Hmbown/CodeWhale · error

Agent not found in the active session

Error message

Agent not found in the active session

What it means

Session-scoped reference resolution (resolve_agent_ref_for_session) maps every failure — unknown id, unknown name, ambiguous name, or an id owned by a different session — to this single deliberately vague message. The manager intentionally does not distinguish 'foreign agent' from 'missing agent' so user- and model-facing callers cannot probe which agents exist in other sessions (an existence-oracle hardening measure documented at the get_result_for_session seam).

Source

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

                    .worker_records
                    .get(&agent.id)
                    .is_none_or(|record| record.spec.parent_run_id.is_none())
                && !delivered_ids.contains(&agent.id)
        })
    }

    /// Resolve either a durable agent id or a model-facing session name.
    fn resolve_agent_ref(&self, agent_ref: &str) -> Result<String> {
        self.resolve_agent_ref_inner(agent_ref, None)
    }

    fn resolve_agent_ref_for_session(
        &self,
        active_session_id: &str,
        agent_ref: &str,
    ) -> Result<String> {
        self.resolve_agent_ref_inner(agent_ref, Some(active_session_id))
            .map_err(|_| anyhow!("Agent not found in the active session"))
    }

    fn resolve_agent_ref_inner(
        &self,
        agent_ref: &str,
        active_session_id: Option<&str>,
    ) -> Result<String> {
        let agent_ref = agent_ref.trim();
        if let Some(agent) = self.agents.get(agent_ref)
            && active_session_id
                .is_none_or(|session_id| self.agent_is_owned_by_session(agent, session_id))
        {
            return Ok(agent.id.clone());
        }

        let matches = self
            .agents
            .values()

View on GitHub (pinned to 0c42157ee5)

Solutions

1. List the active session's agents (manager.list() filtered to the session) and use one of those ids
2. Only pass refs that came from spawn receipts issued in the same active session
3. If the agent truly belongs to another session, switch the active session or re-spawn the work there instead of cross-referencing

Example fix

// before
let id = manager.resolve_for_session(&active_session, &agent_ref)?; // opaque miss

// after
let owned: Vec<String> = manager.list().into_iter()
    .filter(|s| s.owner_session_id == active_session)
    .map(|s| s.agent_id)
    .collect();
ensure!(owned.contains(&agent_ref), "ref not owned by this session; pick from list()");

// Restrict refs to those the active session actually owns.
let owned: Vec<String> = manager.list().into_iter()
    .filter(|s| s.owner_session_id == active_session_id)
    .map(|s| s.agent_id)
    .collect();
anyhow::ensure!(owned.contains(&agent_ref.trim()),
    "ref not owned by the active session; valid ids: {owned:?}");

Handle 'Agent not found in the active session' as a hard stop for that ref: do not probe variants or other sessions (the vague message is intentional anti-probing); re-derive the ref from the session's own roster or respawn.

When it happens

Trigger: Calling a *_for_session API with an agent_id whose owner_session_id differs from the active session; passing a name that resolves in another session only; refs left over after switching the active root session; ids from restored state belonging to the old boot.

Common situations: Multi-session TUI usage where the model reuses an agent_id learned in a previous conversation; session switching mid-orchestration; copied prompts carrying agent ids between chats.

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

• Agent session {agent_ref} not found
• sub-agent transcript artifact is not a regular file: {}
• sub-agent state path must stay within state root: {}
• sub-agent state path must not traverse symlinks: {}
• sub-agent state path must be a regular file: {}

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