Cannot resume agent {agent_id}: sub-agent depth limit reache

Error message

Cannot resume agent {agent_id}: sub-agent depth limit reached (current {}, max {})

What it means

Resuming an interrupted child counts as a new spawn at child depth, and the manager fails closed when runtime.would_exceed_depth() is true — the parent's spawn_depth is already at max_spawn_depth. The check runs on the parent runtime before deriving the background runtime, mirroring the fresh-spawn seam so an infinite chain of nested resumes is impossible. The message reports both current and maximum depth.

Source

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

            (
                agent.agent_type.clone(),
                build_resume_prompt(&agent.prompt, checkpoint, followup_text),
                agent.assignment.clone(),
                agent.allowed_tools.clone(),
                agent.model.clone(),
                agent.fork_context,
                agent.workspace.clone(),
                claim,
                preserved_profile,
                child_route,
            )
        };
        // Resume runs at child depth with a detached cancellation token, the
        // same seam a fresh spawn uses; fail closed on the depth ceiling.
        // Checked on the parent runtime before derivation, matching the
        // fresh-spawn order (would_exceed_depth at the spawn seam).
        if runtime.would_exceed_depth() {
            return Err(anyhow!(
                "Cannot resume agent {agent_id}: sub-agent depth limit reached (current {}, max {})",
                runtime.spawn_depth,
                runtime.max_spawn_depth
            ));
        }
        let runtime = runtime.background_runtime();
        // Resume in the interrupted child's workspace, not the caller's
        // (worktree/cwd children must not resume in the parent directory).
        let mut runtime = runtime;
        runtime.context.workspace = workspace;
        let options = SubAgentSpawnOptions {
            name: None, // the old session name stays owned by the terminal record
            model: Some(model),
            model_route: None,
            child_route,
            nickname: None,
            fork_context,
            write_claim: claim.as_ref().map(|(claim, _)| claim.clone()),

View on GitHub (pinned to 0c42157ee5)

Solutions

Flatten the orchestration: move the resumed work to a shallower/top-level agent instead of resuming the deepest child
Raise the configured maximum sub-agent spawn depth if the nesting is legitimate
Spawn a fresh top-level agent that receives the interrupted child's checkpoint content as prompt context

Example fix

// before
let resumed = manager.resume_from_checkpoint_with_policy(
    handle, runtime, &deep_child_id, &text, policy)?;

// after
if runtime.would_exceed_depth() {
    // resume would exceed the ceiling: relay the work at top level instead
    return spawn_top_level_with_context(manager, &deep_child_id, &text).await;
}
let resumed = manager.resume_from_checkpoint_with_policy(
    handle, runtime, &deep_child_id, &text, policy)?;

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast before the resume seam when the ceiling is already hit.
if runtime.would_exceed_depth() {
    return plan_shallow_resume(&agent_id); // relay work at a shallower level
}

Type guard

fn resume_within_depth(runtime: &SubAgentRuntime) -> bool {
    !runtime.would_exceed_depth()
}

Try / catch

Catch 'sub-agent depth limit reached' and do not retry at the same depth: either raise the configured max depth or relay the checkpoint content into a fresh top-level agent.

Prevention

Track spawn depth in your orchestration bookkeeping and refuse to queue resumes that would exceed the ceiling
Flatten deep agent trees during design; resume at the shallowest level that has the needed context
Size max_spawn_depth to the workflow's real nesting before running deep fan-outs

When it happens

Trigger: Resuming the deepest agent in a nested tree (child of child of child) when the chain already sits at the maximum spawn depth; orchestration where a resumed agent itself resumes another agent, walking depth upward each time; low max_spawn_depth configured for the session.

Common situations: Recursive/deeply nested agent workflows (agent spawns researcher which spawns sub-researcher) followed by a resume of the leaf; tight depth ceilings set to prevent runaway nesting; resumes issued from within already-deep continuation chains.

Related errors

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