Hmbown/CodeWhale · error

Sub-agent depth limit reached

Error message

Sub-agent depth limit reached (child depth {}, absolute inherited max {})

What it means

A continuation/fork inherits the source's depth authority: child depth is raised to at least the source's spec/profile spawn depth while max is lowered to the source's max. If the resulting child depth still exceeds the inherited max, spawn is refused with this message.

Solutions

  1. Perform the continued work at a shallower level — let the parent or a fresh depth-1 child take it over.
  2. Raise `max_spawn_depth` in the source spec or `[subagents]` config if deeper nesting is intended.
  3. Reconsider whether this continuation should be a child at all; flatten the chain.

Example fix

// before
[subagents]
max_spawn_depth = 1  # inherited by continuation, child depth 2 fails

// after
[subagents]
max_spawn_depth = 3
Defensive patterns

Strategy: validation

Validate before calling

let child_depth = runtime.spawn_depth
    .max(source.spec.spawn_depth)
    .max(source.spec.runtime_profile.spawn_depth);
let inherited_max = runtime.max_spawn_depth.min(source.spec.max_spawn_depth);
if child_depth > inherited_max { /* flatten or raise limit */ }

Try / catch

match continue_child(source) {
    Err(e) if e.to_string().contains("inherited max") => delegate_from_parent(source.task),
    other => other?,
}

Prevention

When it happens

Trigger: Creating a continuation/fork where `runtime.spawn_depth` (max of current, source.spec.spawn_depth, source.runtime_profile.spawn_depth) exceeds `runtime.max_spawn_depth` (min of current and source.spec.max_spawn_depth).

Common situations: Continuing a child that itself already sits at the inherited absolute depth cap; forks of forks stacking depth; source recorded under a stricter max than the current runtime allows to be inherited.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

AI-assisted analysis of Hmbown/CodeWhale@73e0f67d83 (2026-09-22). Data as JSON: /api/errors/5847942dd5b573c7. Report an issue: GitHub.

Appendix: source

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

                let remaining = source.spec.max_steps.saturating_sub(source.steps_taken);
                if remaining == 0 {
                    return Err(anyhow!(
                        "child step budget exhausted; continuation cannot reset its model-turn allowance"
                    ));
                }
                max_steps = narrow_model_steps(max_steps, remaining);
            }
            // A source's absolute position is part of its authority. A fork
            // requested by root cannot turn a depth-2 leaf into a depth-1
            // worker and thereby regain a generation of delegation.
            runtime.spawn_depth = runtime
                .spawn_depth
                .max(source.spec.spawn_depth)
                .max(source.spec.runtime_profile.spawn_depth);
            runtime.max_spawn_depth = runtime.max_spawn_depth.min(source.spec.max_spawn_depth);
        }
        if runtime.spawn_depth > runtime.max_spawn_depth {
            return Err(anyhow!(
                "Sub-agent depth limit reached (child depth {}, absolute inherited max {})",
                runtime.spawn_depth,
                runtime.max_spawn_depth
            ));
        }
        let wall_time = options
            .wall_time
            .unwrap_or(MAX_CHILD_WALL_TIME)
            .min(self.wall_time.unwrap_or(DEFAULT_CHILD_WALL_TIME))
            .min(
                runtime
                    .worker_profile
                    .wall_time_secs
                    .map(Duration::from_secs)
                    .unwrap_or(MAX_CHILD_WALL_TIME),
            )
            .min(MAX_CHILD_WALL_TIME);
        let now_ms = epoch_millis_now();

View on GitHub (pinned to 73e0f67d83)