Hmbown/CodeWhale · warning · anyhow::Error

Tool could not enter the bounded child toolbox; use…

Error message

Tool {name} could not enter the bounded child toolbox; use tool_search with a narrower query

What it means

The child toolbox is bounded: deferred tools are admitted only up to a capacity (activation.admitted). When a deferred tool's activation attempt cannot fit it into the bounded toolbox, hydrate fails with this error directing the caller to tool_search with a narrower query, so only tools genuinely needed get loaded.

Solutions

Use tool_search with a narrower, more specific query so fewer tools are admitted and the wanted one fits
Stop needing so many tools simultaneously in the child — split the task or end phases that no longer need their tools
Raise or tune the bounded toolbox capacity for this agent type if the workload legitimately needs a wide surface
Call the tool only after confirming its activation message says it was loaded

Example fix

// before: broad search over-admits the toolbox
search("all file and web tools")
// after: narrow query for the needed tool
search("file read tool")

Defensive patterns

Strategy: retry

Validate before calling

if !request_active_names.contains(name) && !child.toolbox_has_capacity() {
    let found = child.tool_search(&format!("{} exact tool", name))?;
    // proceed only if 'found' includes name
}

Try / catch

match child.call_tool(name, input) {
    Err(e) if e.to_string().contains("bounded child toolbox") => {
        child.tool_search(&specific_query_for(name))?;
        child.call_tool(name, input) // retry after narrowing the query
    }
    other => other,
}

Prevention

Use narrow, specific tool_search queries instead of broad ones
Track which tools are admitted and stop activating ones no longer needed
Split tasks so each phase needs only a few tools at a time

When it happens

Trigger: Calling a deferred tool inside a sub-agent (or a tool_search activation) when the bounded child toolbox is full and the requested tool was not among the admitted set — the hydration path cannot make room and refuses.

Common situations: Children with many deferred tools activated at once, broad tool_search queries admitting a large batch that fills the toolbox, then further activation attempts failing; long children accumulating admitted tools over the session.

Related errors

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

Appendix: source

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

            &self.catalog,
            &mut self.active_names,
            &mut self.cache,
        )
        .map(|result| result.content)
        .map_err(|error| anyhow!(error))
    }

    fn hydrate(&mut self, name: &str) -> Result<String> {
        let activation = self.cache.activate(&self.catalog, &[name.to_string()]);
        remove_evicted_cache_activations(&self.catalog, &mut self.active_names, activation.evicted);
        self.active_names
            .extend(activation.admitted.iter().cloned());
        if activation.admitted.iter().any(|admitted| admitted == name) {
            return Ok(format!(
                "Tool `{name}` was deferred and has now been loaded. Retry the call with the newly available schema."
            ));
        }
        Err(anyhow!(
            "Tool {name} could not enter the bounded child toolbox; use tool_search with a narrower query"
        ))
    }
}

/// Role-only approval posture; the registry allow/deny and runtime envelope
/// remain the authoritative per-tool checks.
///
/// `Auto` is safe for every role. `Suggest` requires a write-capable role;
/// `Required` requires the full-shell posture. A Custom worker may describe
/// either posture, but its explicit allowlist and the runtime envelope still
/// narrow what it can execute. Read-only bash operations are classified Auto,
/// so Scouts and Reviewers do not gain general shell authority through this
/// branch.
/// Intersect an explicit parent scope with the child's requested subset.
///
/// A child can narrow an explicit parent scope, never widen it. Omitting the
/// child list inherits the parent's exact scope. A parent with the default

View on GitHub (pinned to 73e0f67d83)