{"record":{"id":"c94459be8ccd4389","repo":"Hmbown/CodeWhale","slug":"tool-name-could-not-enter-the-bounded-child-tool","errorCode":null,"errorMessage":"Tool {name} could not enter the bounded child toolbox; use tool_search with a narrower query","messagePattern":"Tool (.+?) could not enter the bounded child toolbox; use tool_search with a narrower query","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"warning","filePath":"crates/tui/src/tools/subagent/mod.rs","lineNumber":16637,"sourceCode":"            &self.catalog,\n            &mut self.active_names,\n            &mut self.cache,\n        )\n        .map(|result| result.content)\n        .map_err(|error| anyhow!(error))\n    }\n\n    fn hydrate(&mut self, name: &str) -> Result<String> {\n        let activation = self.cache.activate(&self.catalog, &[name.to_string()]);\n        remove_evicted_cache_activations(&self.catalog, &mut self.active_names, activation.evicted);\n        self.active_names\n            .extend(activation.admitted.iter().cloned());\n        if activation.admitted.iter().any(|admitted| admitted == name) {\n            return Ok(format!(\n                \"Tool `{name}` was deferred and has now been loaded. Retry the call with the newly available schema.\"\n            ));\n        }\n        Err(anyhow!(\n            \"Tool {name} could not enter the bounded child toolbox; use tool_search with a narrower query\"\n        ))\n    }\n}\n\n/// Role-only approval posture; the registry allow/deny and runtime envelope\n/// remain the authoritative per-tool checks.\n///\n/// `Auto` is safe for every role. `Suggest` requires a write-capable role;\n/// `Required` requires the full-shell posture. A Custom worker may describe\n/// either posture, but its explicit allowlist and the runtime envelope still\n/// narrow what it can execute. Read-only bash operations are classified Auto,\n/// so Scouts and Reviewers do not gain general shell authority through this\n/// branch.\n/// Intersect an explicit parent scope with the child's requested subset.\n///\n/// A child can narrow an explicit parent scope, never widen it. Omitting the\n/// child list inherits the parent's exact scope. A parent with the default","sourceCodeStart":16619,"sourceCodeEnd":16655,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/tools/subagent/mod.rs#L16619-L16655","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before: broad search over-admits the toolbox\nsearch(\"all file and web tools\")\n// after: narrow query for the needed tool\nsearch(\"file read tool\")","handlingStrategy":"retry","validationCode":"if !request_active_names.contains(name) && !child.toolbox_has_capacity() {\n    let found = child.tool_search(&format!(\"{} exact tool\", name))?;\n    // proceed only if 'found' includes name\n}","typeGuard":null,"tryCatchPattern":"match child.call_tool(name, input) {\n    Err(e) if e.to_string().contains(\"bounded child toolbox\") => {\n        child.tool_search(&specific_query_for(name))?;\n        child.call_tool(name, input) // retry after narrowing the query\n    }\n    other => other,\n}","preventionTips":["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"],"tags":["subagent","tools","toolbox","capacity"],"backgroundTag":"operation-not-supported","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}