Agent Identity

This doc explains how Scout turns a human-friendly handle like @hudson into one exact Scout address for routing. Read it after quickstart.md when you want to understand what an agent name represents, why short names sometimes work, and when Scout needs more qualifiers.

Every agent Scout can address has a name. When there is only one matching agent on one machine, the name is simple — @arc or @hudson. But agents multiply. The same project might run on two machines. The same workspace might have a main branch and a feature branch, each with its own agent. A project might use Claude for one task and Codex for another.

The identity grammar exists to keep every target unambiguously addressable while still letting humans type the shortest useful name. The default target is the base project/workspace identity. Harness, model, node, and session details describe the concrete instance Scout routes to; they are not a different base agent unless the caller intentionally chooses a specialized profile.

Base Agent Vs Instance

A base agent is the vanilla project/workspace identity that agents should use when they do not care about a specific runtime. In practice this is the thing represented by a project path, such as ../talkie, or by a short handle, such as @talkie.

An agent instance is the concrete attachment Scout routes to for that base identity: a Claude or Codex harness, a model choice, a machine/node, and possibly a sticky session/thread. Asking for a specific instance should refine the route, not create the impression that talkie#codex and talkie#claude are separate base agents.

Default rule: if the project is known but the exact agent/session is not, use project routing and let Scout pick or create the concrete instance:

scout ask --project ../talkie "Review this."

ask({ projectPath: "../talkie", body: "Review this." })

Specialized profiles may become first-class over time. For example, @scout.profile:investigator could name a profile with a dedicated tool set and instructions. That is a specialization layered onto the project identity, not the default routing model.

Three Layers

Scout separates identity into three layers, each serving a different audience:

• Canonical identity is exact, stable, and system-owned. It includes every dimension needed to distinguish one agent from all others. Humans rarely type it, but the broker always stores it.

• Minimal unique identity is the shortest address that still resolves to exactly one agent. Scout computes it automatically from the current set of online agents. When there is only one hudson, @hudson is enough. When two exist on different machines, @hudson.node:mini disambiguates.

• Alias is a human-owned shortcut. @huddy maps to one specific identity. If the mapping becomes ambiguous, the alias is invalid until repaired.

The Six Dimensions

An agent identity combines up to six dimensions:

The canonical form strings them together with dots:

@<definitionId>[.<workspaceQualifier>][.profile:<profile>][.harness:<harness>][.model:<model>][.node:<node>]

In practice, most of these dimensions are omitted. You only include what is needed to resolve unambiguously.

Examples

From shortest to most qualified:

Parsing and Normalization

• @ is required for body-mention compatibility in user-facing text. Internal systems can omit it, and Scout-aware composers may use the >> route operator instead, such as /scout:ask >> hudson Review this.
• One positional qualifier (without a type prefix) is allowed after the definition ID — it is always treated as the workspace qualifier.
• Typed qualifiers (profile:, harness:, model:, node:) may appear in any order during input. Scout normalizes them to canonical order on storage.
• Shorthand #<harness> maps to harness:<harness>, and ?<model> maps to model:<model>.
• Segments are lowercased and kebab-cased: Super Refactor becomes super-refactor, Mini.local becomes mini-local. Dots are reserved as separators.

These aliases are accepted during parsing and map to canonical dimensions:

Resolution

When you type @hudson, Scout resolves it against all known agents:

1. Check for an exact alias match first.
2. Match the parsed identity against registered candidates.
3. If exactly one candidate matches, resolve to it.
4. If zero or more than one match, return nothing — the name is either unknown or ambiguous.

This keeps short names fast and ergonomic while requiring precision only when the situation demands it.

Minimal Unique Identity

Given a specific agent and its peers, Scout prefers the shortest address that uniquely identifies it. Dimensions are dropped in this order until removing the next one would create ambiguity:

1. workspaceQualifier
2. profile
3. harness
4. model
5. node

If a configured alias is shorter than the minimal canonical form and resolves uniquely, Scout prefers it.

Example:

• Canonical: @hudson.hudson-main-8012ac.node:arachs-mac-mini-local
• Minimal unique: @hudson (if only one hudson is online)
• Alias: @huddy