{"record":{"id":"7a4881174dcc72c2","repo":"Hmbown/CodeWhale","slug":"agent-session-name-agent-ref-is-ambiguous-use","errorCode":null,"errorMessage":"Agent session name '{agent_ref}' is ambiguous; use an agent_id","messagePattern":"Agent session name '(.+?)' is ambiguous; use an agent_id","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/tui/src/tools/subagent/mod.rs","lineNumber":7519,"sourceCode":"            })\n            .collect::<Vec<_>>();\n        // A reused name shadows settled holders: the live worker wins, and\n        // settled records stay id-addressable (#6313).\n        if matches\n            .iter()\n            .any(|agent| !subagent_status_is_settled(&agent.status))\n        {\n            matches.retain(|agent| !subagent_status_is_settled(&agent.status));\n        }\n        let matches = matches\n            .iter()\n            .map(|agent| agent.id.clone())\n            .collect::<Vec<_>>();\n\n        match matches.as_slice() {\n            [id] => Ok(id.clone()),\n            [] => Err(anyhow!(\"Agent session {agent_ref} not found\")),\n            _ => Err(anyhow!(\n                \"Agent session name '{agent_ref}' is ambiguous; use an agent_id\"\n            )),\n        }\n    }\n\n    fn agent_is_owned_by_session(&self, agent: &SubAgent, active_session_id: &str) -> bool {\n        !active_session_id.is_empty() && agent.owner_session_id == active_session_id\n    }\n\n    fn agent_id_is_owned_by_session(&self, agent_id: &str, active_session_id: &str) -> bool {\n        self.agents\n            .get(agent_id)\n            .is_some_and(|agent| self.agent_is_owned_by_session(agent, active_session_id))\n    }\n\n    /// Resolve a hierarchy mutation target and prove that it is a strict\n    /// descendant of the calling agent. Root registries carry no caller id\n    /// (or the literal `root`) and retain authority over every child. This","sourceCodeStart":7501,"sourceCodeEnd":7537,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/tools/subagent/mod.rs#L7501-L7537","documentation":"When resolving an `agent_ref` by name, more than one agent session matches, so the tool cannot pick one unambiguously. The library refuses to guess and asks the caller to use the unique `agent_id` instead of the human-readable name.","triggerScenarios":"Invoking a subagent coordination tool with a shared agent name (e.g. \"worker\") after spawning multiple subagents with that same name; reusing a default agent name across several spawns.","commonSituations":"Spawning several parallel worker subagents without unique names, then sending a message or command addressed to the shared name.","solutions":["Use the agent's unique agent_id instead of its name in the tool call","Give each subagent a unique name at spawn time","List all agents to see which ids share the name and pick the intended one"],"exampleFix":"// before\nagent_send(\"worker\", \"continue\"); // ambiguous: 3 agents named worker\n// after\nagent_send(\"a1f3-worker-uuid\", \"continue\"); // use agent_id","handlingStrategy":"validation","validationCode":"fn ensure_unique_name(agents: &[AgentInfo], name: &str) -> Result<&AgentInfo, String> {\n    let matches: Vec<_> = agents.iter().filter(|a| a.name == name).collect();\n    match matches.len() { 1 => Ok(matches[0]), 0 => Err(format!(\"no agent named {name}\")), _ => Err(format!(\"{name} is ambiguous; use agent_id\")) }\n}","typeGuard":"fn resolves_uniquely(agents: &[AgentInfo], name: &str) -> bool {\n    agents.iter().filter(|a| a.name == name).count() == 1\n}","tryCatchPattern":"match resolve_agent_ref(name_ref) {\n    Ok(id) => proceed(id),\n    Err(e) if e.to_string().contains(\"ambiguous\") => list_agents().iter().filter(|a| a.name == name_ref).map(|a| a.id.clone()).collect::<Vec<_>>(), // prompt user to pick\n    Err(e) => return Err(e),\n}","preventionTips":["Give each subagent a unique name at spawn time (e.g. suffix with a counter or uuid)","Prefer agent_id over name in all coordination tool calls","Treat names as labels only, never as identifiers"],"tags":["subagent","rust","ambiguity"],"backgroundTag":"ambiguous-identifier","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}