Sub-agent session name '{name}' is already in use by agent_i

Error message

Sub-agent session name '{name}' is already in use by agent_id '{}' (status: {}, started {since}). Wait for its completion event, or open a new agent with a different name.

What it means

Assigning a session_name that another registered agent already holds fails with this error, which names the conflicting agent_id, its current status, and how long ago it started (added so parents can tell a live worker from a stale earlier spawn). Session names must be unique across the manager's registry — the matching does not filter by status, so even a finished agent blocks reuse while its record lives.

Source

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

        if let Some(name) = options
            .name
            .as_deref()
            .map(str::trim)
            .filter(|name| !name.is_empty())
        {
            if let Some(existing) = self
                .agents
                .values()
                .find(|existing| existing.session_name == name)
            {
                // #3020: Include elapsed time so the parent can distinguish a
                // live worker from a stale/failed earlier spawn (#2656).
                let elapsed = existing.started_at.elapsed();
                let since = format!(
                    "{} ago",
                    crate::elapsed::format_elapsed_secs(elapsed.as_secs())
                );
                return Err(anyhow!(
                    "Sub-agent session name '{name}' is already in use by agent_id '{}' \
                     (status: {}, started {since}). \
                     Wait for its completion event, or open a new agent with a different name.",
                    existing.id,
                    subagent_status_name(&existing.status)
                ));
            }
            agent.session_name = name.to_string();
        }
        agent.fork_context = options.fork_context;
        let agent_id = agent.id.clone();
        let started_at = agent.started_at;
        let tool_profile = match tools.clone() {
            Some(tools) => AgentWorkerToolProfile::Explicit(tools),
            None => AgentWorkerToolProfile::Inherited,
        };
        let runtime_profile = match options.preserve_runtime_profile.clone() {
            Some(preserved) => {

View on GitHub (pinned to 0c42157ee5)

Solutions

Make names unique per spawn: suffix with a counter, timestamp, or task id ('writer-3', 'researcher-2026-08-20-2')
Check the existing agent's status first — if it is live, wait for its completion event; if it is stale, it will no longer block once its record is pruned
Reference agents by agent_id from the spawn receipt instead of relying on memorable names

Example fix

// before
let opts = SubAgentSpawnOptions { name: Some("researcher".into()), /* ... */ };

// after
let name = format!("researcher-{}", uuid::Uuid::new_v4().simple());
let opts = SubAgentSpawnOptions { name: Some(name), /* ... */ };

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight name uniqueness before spawn.
let taken: Vec<String> = manager.list().into_iter()
    .filter_map(|s| s.session_name)
    .collect();
anyhow::ensure!(!taken.contains(&name),
    "session name {name} already taken by a live or recorded agent");

Try / catch

On 'already in use', read the embedded agent_id/status/elapsed: if the holder is live, wait for its completion event before reusing the name; otherwise generate a suffixed unique name and retry the spawn once.

Prevention

Generate names as role + unique suffix (counter/uuid/timestamp) at the spawn site
Carry agent_ids from spawn receipts as the canonical reference; treat names as display labels only
In retry logic, never respawn with the identical session_name

When it happens

Trigger: Spawning an agent with options.session_name equal to an existing agent's name (e.g., a fixed 'researcher' name in a loop); retry logic re-spawning with the same name after an ambiguous earlier failure; templates that derive names from the task type only, colliding on the second instance.

Common situations: Retry/re-spawn loops reusing fixed names; multi-phase workflows naming workers by role ('writer', 'reviewer') where two phases overlap; the earlier stale-spawn ambiguity (#2656) that motivated including elapsed time (#3020) in this message.

Related errors

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