{"record":{"id":"ce53f9d20de413b8","repo":"Hmbown/CodeWhale","slug":"agent-session-agent-ref-not-found","errorCode":null,"errorMessage":"Agent session {agent_ref} not found","messagePattern":"Agent session (.+?) not found","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/tui/src/tools/subagent/mod.rs","lineNumber":7518,"sourceCode":"                    .is_none_or(|session_id| self.agent_is_owned_by_session(agent, session_id))\n            })\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","sourceCodeStart":7500,"sourceCodeEnd":7536,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/tools/subagent/mod.rs#L7500-L7536","documentation":"The subagent tool resolves an agent reference (`agent_ref`, which may be a name or an agent_id) to exactly one agent session by collecting matching agent IDs. This error is thrown when the reference matches zero sessions, meaning the caller named an agent that does not exist in the current session's agent table.","triggerScenarios":"Calling a subagent coordination tool (e.g. agent send/interrupt/status) with an `agent_ref` string that does not match any live SubAgent id or name, or referencing an agent whose session already terminated and was reaped.","commonSituations":"A typo in the agent name; using a stale agent_id captured before the agent finished; a subagent completing or crashing between listing agents and acting on one; passing a name that was never registered because the spawn failed.","solutions":["Re-list available agents to get a valid agent_id and use that exact id","Check whether the subagent already completed or was cancelled; start a new one if needed","Fix the agent_ref spelling/whitespace and retry","Verify the agent was spawned in the same active session, not a prior session"],"exampleFix":"// before\nlet id = resolve(\"my-agnt\")?; // Err: Agent session my-agnt not found\n// after\nlet agents = list_agents();\nlet id = agents.iter().find(|a| a.id == \"my-agent\").map(|a| a.id.clone()).ok_or_else(|| anyhow!(\"spawn agent first\"))?;","handlingStrategy":"validation","validationCode":"fn ensure_agent_exists(agents: &[AgentInfo], agent_ref: &str) -> Result<&AgentInfo, String> {\n    agents.iter().find(|a| a.id == agent_ref || a.name == agent_ref)\n        .ok_or_else(|| format!(\"agent '{agent_ref}' not found; available: {:?}\", agents.iter().map(|a| a.id.as_str()).collect::<Vec<_>>()))\n}","typeGuard":"fn is_known_agent(agents: &[AgentInfo], agent_ref: &str) -> bool {\n    agents.iter().any(|a| a.id == agent_ref || a.name == agent_ref)\n}","tryCatchPattern":"match resolve_agent_ref(agent_ref) {\n    Ok(id) => proceed(id),\n    Err(e) if e.to_string().contains(\"not found\") => refresh_agent_list_and_retry(),\n    Err(e) => return Err(e),\n}","preventionTips":["Always address subagents by their unique agent_id, not a display name","Capture the agent_id returned at spawn time and reuse it","Re-list agents before acting if time has passed since spawn"],"tags":["subagent","rust","lookup"],"backgroundTag":"entity-not-found","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"}