Hmbown/CodeWhale · error

Agent session {agent_ref} not found

Error message

Agent session {agent_ref} not found

What it means

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.

Source

Thrown at crates/tui/src/tools/subagent/mod.rs:6747

                .is_none_or(|session_id| self.agent_is_owned_by_session(agent, session_id))
        {
            return Ok(agent.id.clone());
        }

        let matches = self
            .agents
            .values()
            .filter(|agent| agent.session_name == agent_ref)
            .filter(|agent| {
                active_session_id
                    .is_none_or(|session_id| self.agent_is_owned_by_session(agent, session_id))
            })
            .map(|agent| agent.id.clone())
            .collect::<Vec<_>>();

        match matches.as_slice() {
            [id] => Ok(id.clone()),
            [] => Err(anyhow!("Agent session {agent_ref} not found")),
            _ => Err(anyhow!(
                "Agent session name '{agent_ref}' is ambiguous; use an agent_id"
            )),
        }
    }

    fn agent_is_owned_by_session(&self, agent: &SubAgent, active_session_id: &str) -> bool {
        !active_session_id.is_empty() && agent.owner_session_id == active_session_id
    }

    fn agent_id_is_owned_by_session(&self, agent_id: &str, active_session_id: &str) -> bool {
        self.agents
            .get(agent_id)
            .is_some_and(|agent| self.agent_is_owned_by_session(agent, active_session_id))
    }

    /// Resolve a hierarchy mutation target and prove that it is a strict
    /// descendant of the calling agent. Root registries carry no caller id

View on GitHub (pinned to 0c42157ee5)

Solutions

  1. Enumerate valid names first: manager.list() shows each agent's session_name and agent_id
  2. Prefer agent_ids from spawn receipts over human-memorable names for programmatic calls
  3. When scoping by session, ensure the name was created in that same session

Example fix

// before
let receipt = manager.followup_child(&"researcher", text)?;

// after
let live: Vec<(String, String)> = manager.list().into_iter()
    .filter_map(|s| s.session_name.clone().map(|n| (n, s.agent_id)))
    .collect();
let target = live.iter().find(|(n, _)| n == "researcher")
    .map(|(_, id)| id.clone())
    .context("no live agent named 'researcher'; options: {live:?}")?;
let receipt = manager.followup_child(&target, text)?;
Defensive patterns

Strategy: validation

Validate before calling

// Confirm the name exists (and is unambiguous) before the call.
let matches: Vec<String> = manager.list().into_iter()
    .filter(|s| s.session_name.as_deref() == Some(agent_ref.trim()))
    .map(|s| s.agent_id)
    .collect();
anyhow::ensure!(matches.len() == 1,
    "expected exactly one agent named {agent_ref}, found {}", matches.len());

Try / catch

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.

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@0c42157ee5 (2026-08-20). Data as JSON: /api/errors/ce53f9d20de413b8. Report an issue: GitHub.