Hmbown/CodeWhale · error

Agent session name '{agent_ref}' is ambiguous; use an agent_

Error message

Agent session name '{agent_ref}' is ambiguous; use an agent_id

What it means

Session-name resolution found two or more agents sharing the referenced session_name (within the active session's owned agents, when a filter is applied), so it refuses to guess and demands the unique agent_id. Duplicate names across the registry arise when name uniqueness was only enforced within one scope — e.g., the same name registered in different sessions and resolved globally, or legacy/imported state predating the duplicate check.

Source

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

        {
            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
    /// (or the literal `root`) and retain authority over every child. This

View on GitHub (pinned to 0c42157ee5)

Solutions

1. Pass the explicit agent_id (from the spawn receipt or manager.list()) instead of the ambiguous name
2. Narrow the resolution scope: use the *_for_session variants so only the active session's agents match
3. Adopt unique name generation (role + counter/uuid) so collisions cannot occur even across sessions

Example fix

// before
let id = manager.followup_child(&"writer", text)?; // ambiguous

// after
let matches: Vec<String> = manager.list().into_iter()
    .filter(|s| s.session_name.as_deref() == Some("writer"))
    .map(|s| s.agent_id)
    .collect();
anyhow::ensure!(matches.len() == 1,
    "name 'writer' matches {} agents; pass an explicit agent_id", matches.len());
let receipt = manager.followup_child(&matches[0], text)?;

// Count matches up front and disambiguate explicitly.
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();
if matches.len() > 1 {
    return Err(anyhow::!(
        "name {agent_ref} is ambiguous across {} agents; pass one of {matches:?}",
        matches.len()
    ));
}

Catch 'is ambiguous; use an agent_id', enumerate the candidates from list() (id + status + owner session), and re-issue the call with the explicit id — often after asking the user/model to pick based on status.

When it happens

Trigger: resolve_agent_ref on a name that matches multiple agents (global resolution with no active_session_id); two sessions each owning a 'writer' agent and resolution running without a session filter; state restored from older versions that permitted duplicate names.

Common situations: Role-based naming ('writer', 'reviewer') reused across parallel sessions; cross-session resume or imported history creating registry overlap; global tool calls that predate session-scoped routing.

Related errors

• Agent session {agent_ref} not found
• Ambiguous task prefix '{}': matches {} tasks
• Cannot follow up agent {agent_id}: status is {} and the chil
• Cannot continue agent {agent_id}: no runtime is available to
• Cannot continue agent {agent_id}: status is {} and the child

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