Agent Identity

This doc explains how Scout turns a human-friendly handle like @hudson into one exact agent identity. 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 in Scout has a name. When there is only one 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 agent unambiguously addressable while still letting humans type the shortest useful name.

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 Five Dimensions

An agent identity combines up to five dimensions:

The canonical form strings them together with dots:

@<definitionId>[.<workspaceQualifier>][.profile:<profile>][.harness:<harness>][.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 in user-facing text. Internal systems can omit it.
• 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:, node:) may appear in any order during input. Scout normalizes them to canonical order on storage.
• 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. 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