docs(skill): tell orchestrators to report spawn display name, not the id#2593
Conversation
… the id The CLI output fix alone only helps a human directly reading raw terminal output. An orchestrator agent already knows the name it just typed via --name, so echoing it back doesn't teach the agent anything new -- but orchestrators tend to relay ao spawn's raw confirmation string verbatim into their own prose rather than translate it, so shaping that string (this PR) does most of the practical work by habit. This adds an explicit instruction as a second, independent safeguard that doesn't rely on that habit holding.
mukesher4
force-pushed
the
ao/agent-orchestrator-15/spawn-confirmation-name-fork
branch
from
d72c22c to
8514e6b
Compare
mukesher4
changed the title
…name Session names aren't permanent (ao session rename), unlike the id which is fixed for the session's lifetime. Preferring the name over the id when reporting to the user (added in the prior commit) is only correct if the name is actually current -- an orchestrator agent has no automatic way to learn about a rename that happened after it last observed the session, so it would otherwise confidently repeat a stale name. This belongs in the general Conventions section (not spawn.md) since it applies whenever a session is referenced, not just at spawn time.
|
Thanks for contributing to Agent Orchestrator. This PR is being picked up by the current external contributor on-call pair: If someone is already working on this, please continue as usual. You are also welcome to join the AO Discord community. We do daily Discord calls at 10 PM IST, except Saturday. Join the session here: Come by if you want to see what is being built, ask questions, or just hang around with the community. |
3 participants
Fixes #2592
Summary
Originally this PR also changed
ao spawn's CLI confirmation output to echo the display name. That code change has been dropped after reconsidering the actual problem: an orchestrator agent already knows the name it just passed via--namein that same tool call, so echoing it back in the CLI's output doesn't give the agent new information. The "CLI output shapes what gets relayed" argument doesn't hold up either — an agent careless enough to ignore an explicit reporting instruction is also careless enough to not faithfully transcribe a specific CLI line; these aren't independent failure modes.The actual fix is a documentation change only:
backend/internal/skillassets/using-ao/commands/spawn.mdnow explicitly tells orchestrator agents to report a spawned session by its--name, not its generated id, when summarizing for the user. This targets the real problem directly (what the orchestrator chooses to say) instead of indirectly (hoping a reshaped CLI string gets copied faithfully).A second bug this surfaced: stale names after rename
Preferring the display name over the id introduces a new failure mode: a session's display name is not permanent — it can be changed after spawn via
ao session rename <id> <name>, unlike the id, which is fixed for the session's lifetime. An orchestrator agent has no automatic way to learn that a rename happened after it last observed a session — its only "knowledge" of the name is whatever is still in its own conversation memory (from spawning it, or a prior query), which is never invalidated or refreshed automatically. So without a further caveat, the "report by name" instruction could make an orchestrator confidently repeat a stale, now-wrong name — arguably worse than reporting the id, which never goes stale.This was caught live during review: a worker session's display name changed from
investigate-glyphstoglyphssometime after it was spawned, and the orchestrator only noticed because it happened to re-query the session's current state rather than trust its own memory — it would otherwise have kept reporting the original, now-incorrect name indefinitely.Fix: added a note to
SKILL.md's general Conventions section (notspawn.md, since staleness applies whenever a session is referenced, not just at spawn time) telling orchestrator agents to re-confirm a session's current name viaao session get/ao session lsrather than relying on memory, whenever accuracy matters (long conversations, or after any renaming activity).ao spawn's CLI output itself remains as it was onmain— this is a docs-only PR.Test plan
N/A — documentation-only change, no code touched.