{"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":null,"httpStatus":null,"severity":"error","filePath":"crates/tui/src/tools/subagent/mod.rs","lineNumber":6747,"sourceCode":"                .is_none_or(|session_id| self.agent_is_owned_by_session(agent, session_id))\n        {\n            return Ok(agent.id.clone());\n        }\n\n        let matches = self\n            .agents\n            .values()\n            .filter(|agent| agent.session_name == agent_ref)\n            .filter(|agent| {\n                active_session_id\n                    .is_none_or(|session_id| self.agent_is_owned_by_session(agent, session_id))\n            })\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":6729,"sourceCodeEnd":6765,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/0c42157ee52f9d55af2b506d71b46249910f77d3/crates/tui/src/tools/subagent/mod.rs#L6729-L6765","documentation":"Reference resolution fell through to the session-name branch and found zero agents whose session_name equals the given ref (optionally filtered to the active session's owned agents). The ref is neither a live agent_id nor a known session name — a typo, a stale name whose record was pruned, or a name owned by a different session when resolving with a session filter.","triggerScenarios":"resolve_agent_ref (or any ref-taking API like followup_child/interrupt_child) with a misspelled session name; a name whose agent record was archived after completion; resolving a name scoped to an active_session_id that owns a different set of agents than where the name lives.","commonSituations":"The model paraphrasing a session name ('researcher' vs 'research-2'); names reused across sessions colliding with the ownership filter; long-lived chats referencing workers compacted out of the registry.","solutions":["Enumerate valid names first: manager.list() shows each agent's session_name and agent_id","Prefer agent_ids from spawn receipts over human-memorable names for programmatic calls","When scoping by session, ensure the name was created in that same session"],"exampleFix":"// before\nlet receipt = manager.followup_child(&\"researcher\", text)?;\n\n// after\nlet live: Vec<(String, String)> = manager.list().into_iter()\n    .filter_map(|s| s.session_name.clone().map(|n| (n, s.agent_id)))\n    .collect();\nlet target = live.iter().find(|(n, _)| n == \"researcher\")\n    .map(|(_, id)| id.clone())\n    .context(\"no live agent named 'researcher'; options: {live:?}\")?;\nlet receipt = manager.followup_child(&target, text)?;","handlingStrategy":"validation","validationCode":"// Confirm the name exists (and is unambiguous) before the call.\nlet matches: Vec<String> = manager.list().into_iter()\n    .filter(|s| s.session_name.as_deref() == Some(agent_ref.trim()))\n    .map(|s| s.agent_id)\n    .collect();\nanyhow::ensure!(matches.len() == 1,\n    \"expected exactly one agent named {agent_ref}, found {}\", matches.len());","typeGuard":null,"tryCatchPattern":"On 'Agent session ... not found', fall back to enumerating live names (list()) and either correct the typo or use an agent_id; the miss is permanent for that ref, so no retry.","preventionTips":["Validate session names against the live roster before tool calls, especially for model-generated names","Use exact names as returned by spawn receipts; avoid paraphrased role names","Include the available name list in error context fed back to the model so it can self-correct"],"tags":["subagent","rust","name-resolution","agent-not-found","typo"],"backgroundTag":"resource-not-found","analyzedSha":"0c42157ee52f9d55af2b506d71b46249910f77d3","analyzedAt":"2026-08-20T21:50:45.477Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}