@bastani/atomic 0.9.2 → 0.9.3-alpha.2

package/dist/builtin/mcp/direct-tools.ts

@@ -12,7 +12,7 @@ import { resourceNameToToolName } from "./resource-tools.ts";
 import { authenticate, supportsOAuth } from "./mcp-auth-flow.ts";
 import { formatAuthRequiredMessage, unflattenToolArguments } from "./utils.ts";
 
-const BUILTIN_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "ls", "mcp"]);
+const BUILTIN_NAMES = new Set(["read", "bash", "edit", "write", "grep", "find", "search", "ls", "mcp"]);
 
 type DirectAutoAuthResult =
   | { status: "skipped" }
@@ -371,7 +371,9 @@ export function createDirectToolExecutor(
         name: spec.originalName,
         // Normalize provider-flattened argument keys (e.g. Gemini's `keywords[0]`)
         // back into arrays/objects before the MCP server validates them.
-        arguments: unflattenToolArguments(params),
+        // Schema-aware: literal dotted property names (e.g. `filter.name`) are
+        // preserved unless the schema proves the head is a container.
+        arguments: unflattenToolArguments(params, spec.inputSchema),
         _meta: uiSession?.requestMeta,
       });
 

package/dist/builtin/mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.9.2",
+  "version": "0.9.3-alpha.2",
   "private": true,
   "description": "Atomic extension that adapts MCP (Model Context Protocol) servers into the coding agent. Fork of: https://github.com/nicobailon/pi-mcp-adapter",
   "contributors": [

package/dist/builtin/mcp/proxy-call.ts

@@ -288,7 +288,9 @@ export async function executeCall(
       name: toolMeta.originalName,
       // Normalize provider-flattened argument keys (e.g. Gemini's `keywords[0]`)
       // back into arrays/objects before the MCP server validates them.
-      arguments: unflattenToolArguments(args),
+      // Schema-aware: literal dotted property names (e.g. `filter.name`) are
+      // preserved unless the schema proves the head is a container.
+      arguments: unflattenToolArguments(args, toolMeta.inputSchema),
       _meta: uiSession?.requestMeta,
     });
 

package/dist/builtin/mcp/utils.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@bastani/atomic";
-import { reconstructFlattenedKeys } from "@bastani/atomic";
+import { unflattenArgumentsWithSchema } from "@bastani/atomic";
 import { homedir, platform } from "node:os";
 import { join } from "node:path";
 import type { McpConfig, ServerEntry } from "./types.ts";
@@ -140,15 +140,26 @@ export function extractToolUiStreamMode(toolMeta: Record<string, unknown> | unde
  *
  * This normalizer runs at the MCP `callTool` boundary so arguments are correct
  * regardless of how the model/provider serialized them. It is provider-agnostic
- * and **self-gating**: it is a no-op unless at least one bracket-indexed key
- * (`name[<digit>]`) is present, so well-formed arguments pass through untouched
- * (including arguments already normalized upstream by the host runtime).
+ * and schema-aware:
+ *
+ * - Bracket-indexed keys (`ids[0]`, `files[0].path`) are **always**
+ *   reconstructed — they are unambiguous.
+ * - Purely dotted keys (`parent.child`) are reconstructed only when the tool's
+ *   `inputSchema` proves their head segment is an object/array container
+ *   property. The presence of a bracket-indexed sibling does NOT force a pure
+ *   dotted key to split, so a literal property name such as `filter.name`
+ *   survives intact even when a sibling like `ids[0]` is present (issue #1496).
+ * - Otherwise dotted keys are preserved verbatim — so a literal property name
+ *   such as `filter.name` (a legitimate top-level schema property) is no longer
+ *   silently split into `{ filter: { name } }`.
+ *
+ * When no schema is supplied (the legacy call shape), bracket-indexed payloads
+ * are still reconstructed while pure dotted keys are preserved verbatim.
  */
 export function unflattenToolArguments(
   args: Record<string, unknown> | null | undefined,
+  inputSchema?: unknown,
 ): Record<string, unknown> {
   if (args === null || args === undefined) return {};
-  const keys = Object.keys(args);
-  if (!keys.some((key) => /\[\d+\]/.test(key))) return args;
-  return reconstructFlattenedKeys(args, () => true);
+  return unflattenArgumentsWithSchema(args, inputSchema);
 }

package/dist/builtin/subagents/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 ## [Unreleased]
 
+## [0.9.3-alpha.2] - 2026-06-27
+
+### Fixed
+
+- Prevented the async subagent status widget from briefly unmounting during reset-and-hydrate cycles when active background runs are still present, including Atomic host updates that deliver fresh UI context wrappers for the same logical session ([#1517](https://github.com/bastani-inc/atomic/issues/1517)).
+- Fixed live subagent result animation cleanup to register a host-row disposer, so terminal workflow cleanup evicts animation registry entries instead of only clearing intervals ([#1518](https://github.com/bastani-inc/atomic/issues/1518)).
+- Synced recent upstream subagent hardening so compact delegated tool-call summaries are preserved, fanout children keep their live nested subagent call/result history, duplicate concurrent subagent dispatches are rejected, provider-hostile chain schema conditionals are removed, and failed foreground runs include captured child output for diagnostics ([#1527](https://github.com/bastani-inc/atomic/issues/1527)).
+- Eliminated the foreground subagent widget flicker that appeared once a running subagent panel grew tall enough to reach or exceed the terminal viewport. The live compact result no longer animates its spinner on an 80ms wall-clock timer; instead it shows an activity "pulse" glyph that advances exactly once per real progress update. Because the panel renders into chat scrollback, a timer-driven spinner cell that scrolled above pi-tui's viewport fold forced a destructive full-screen + scrollback clear on every tick — driving the indicator off genuine updates keeps line diffs tied to content that actually changed, so the differential renderer repaints only when progress does and never strobes.
+
+## [0.9.3-alpha.1] - 2026-06-25
+
+### Changed
+
+- Raised the default and hard maximum subagent nesting budget to five delegated levels, clamping environment, config, and frontmatter values above `5` and extending nested-run observability to the same depth.
+
+### Fixed
+
+- Filtered direct MCP child-agent allowlists against the builtin `search` tool name so unprefixed MCP tools named `search` do not collide with Atomic's builtin search tool ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Updated bundled subagent definitions and docs to use the builtin `search`/`find` tools instead of the legacy `grep` helper ([#1490](https://github.com/bastani-inc/atomic/pull/1490)).
+
 ## [0.9.2] - 2026-06-23
 
 ### Changed

package/dist/builtin/subagents/README.md

@@ -425,7 +425,7 @@ name: scout
 # Optional: registers this as code-analysis.scout while preserving name: scout
 package: code-analysis
 description: Fast codebase recon
-tools: read, grep, find, ls, bash, mcp:chrome-devtools
+tools: read, search, find, ls, bash, mcp:chrome-devtools
 extensions:
 model: claude-haiku-4-5
 fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4
@@ -910,7 +910,7 @@ Session directory precedence is: `params.sessionDir`, then `config.defaultSessio
 { "maxSubagentDepth": 1 }
 ```
 
-Controls nested delegation when no inherited `PI_SUBAGENT_MAX_DEPTH` is already in effect. Per-agent `maxSubagentDepth` can tighten the limit for that agent’s child runs, but cannot relax an inherited stricter limit.
+Controls nested delegation when no inherited `ATOMIC_SUBAGENT_MAX_DEPTH` (or legacy `PI_SUBAGENT_MAX_DEPTH`) is already in effect. Accepted values are `0` through `5`; higher values are clamped to the hard ceiling. Per-agent `maxSubagentDepth` can tighten the limit for that agent’s child runs, but cannot relax an inherited stricter limit.
 
 ### `intercomBridge`
 
@@ -1022,17 +1022,17 @@ This is disabled by default. Session data may contain source code, paths, enviro
 
 Subagents can call `subagent`, which can get expensive and hard to observe. A depth guard prevents unbounded nesting.
 
-By default, nesting is limited to two levels: main session → subagent → sub-subagent. Deeper calls are blocked with guidance to complete the current task directly.
+By default, nesting is capped at five delegated subagent levels below the main session. Deeper calls are blocked with guidance to complete the current task directly.
 
-Configure the limit with:
+Configure a lower or equal limit with:
 
-1. `ATOMIC_SUBAGENT_MAX_DEPTH` (or legacy `PI_SUBAGENT_MAX_DEPTH`) before starting Atomic
+1. `ATOMIC_SUBAGENT_MAX_DEPTH` (or legacy `PI_SUBAGENT_MAX_DEPTH`) before starting Atomic; values above `5` are clamped to `5`
 2. `config.maxSubagentDepth`
 3. `maxSubagentDepth` in agent frontmatter, which can only tighten the inherited limit
 
 ```bash
+export ATOMIC_SUBAGENT_MAX_DEPTH=5
 export ATOMIC_SUBAGENT_MAX_DEPTH=3
-export ATOMIC_SUBAGENT_MAX_DEPTH=1
 export ATOMIC_SUBAGENT_MAX_DEPTH=0
 ```
 

package/dist/builtin/subagents/agents/code-simplifier.md

@@ -7,9 +7,10 @@ description: |
   - Cleanup right after implementing a feature ("clean up the payment module").
   - Production-quality refinement of a working draft ("ugly but working CSV parser").
   - Code that has gotten messy after several iterations.
-tools: read, edit, write, grep, find, ls, bash
-model: openai/gpt-5.5:low
-fallbackModels: openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, anthropic/claude-opus-4-8:low, github-copilot/claude-opus-4.7:low
+tools: read, edit, write, search, find, ls, bash, todo
+model: zai/glm-5.2:medium
+fallbackModels: zai-coding-cn/glm-5.2:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, github-copilot/gemini-3.5-flash (1m):medium, google/gemini-3.5-flash:medium, google-vertex/gemini-3.5-flash:medium, github-copilot/gemini-3.1-pro-preview (1m):medium, google/gemini-3.1-pro-preview:medium, google-vertex/gemini-3.1-pro-preview:medium
+skills: tdd, playwright-cli, tmux
 ---
 
 You are an expert code refinement specialist with deep experience in software craftsmanship, refactoring patterns (Fowler, Beck), clean code principles, and language-idiomatic style across major ecosystems. Your mission is to simplify and refine code for clarity, consistency, and maintainability while strictly preserving all existing functionality and observable behavior.
@@ -37,11 +38,11 @@ These five principles are the heart of how you read code before you touch it. Th
 
 ## Interior versus boundary: what you change, what you surface
 
-Before touching any name or type, decide which side of a door you are on. Use `grep`/`find` to locate every caller; check the language's visibility markers (`export`, `pub`, `public`, `__all__`, module/package privacy) and whether the symbol is reachable outside its module or package.
+Before touching any name or type, decide which side of a door you are on. Use `search`/`find` to locate every caller; check the language's visibility markers (`export`, `pub`, `public`, `__all__`, module/package privacy) and whether the symbol is reachable outside its module or package.
 
 - **Interior (mechanism).** Locals, private helpers, module-internal functions and types, dead code, and the bodies of everything. No external caller depends on its shape. Here the doors lens turns directly into edits: rename tool→joint, split a fused helper into honest ones, collapse needless intermediates, tighten types until illegal states are unrepresentable, flatten nesting with guard clauses. Your only constraint is behavior.
 - **Just-introduced boundary.** Helpers you created in this same change and nothing else yet depends on — treat as interior.
-- **Public door (contract).** Exported functions, public methods, HTTP routes, RPC methods, published types — anything `grep` shows is reached from outside the module/package, or that is part of a documented API surface. **You do not rename, retype, or reshape these.** A public door's name is a contract with every caller; changing it is a behavior change by another name. When a public door is tool-named, dishonest, primitive-obsessed, or scatters danger, write it up as a **deferred suggestion** carrying the exact rubric finding — never an edit.
+- **Public door (contract).** Exported functions, public methods, HTTP routes, RPC methods, published types — anything `search` shows is reached from outside the module/package, or that is part of a documented API surface. **You do not rename, retype, or reshape these.** A public door's name is a contract with every caller; changing it is a behavior change by another name. When a public door is tool-named, dishonest, primitive-obsessed, or scatters danger, write it up as a **deferred suggestion** carrying the exact rubric finding — never an edit.
 
 When you cannot tell whether a symbol is public, treat it as public: surface it as a suggestion or ask. Err toward preserving contracts.
 
@@ -63,7 +64,7 @@ When you cannot tell whether a symbol is public, treat it as public: surface it
 ## Methodology
 
 1. **Identify scope**: Determine exactly which files/regions are recently modified. State this scope explicitly before making changes.
-2. **Map the doors**: Before editing, `read` the target code AND its callers/consumers to understand the contracts you must preserve. Use `grep` to find every caller before touching any symbol, and use that to classify each touched entrypoint as **interior** or **public** (see the section above). Check `AGENTS.md` / `CLAUDE.md` and existing style conventions.
+2. **Map the doors**: Before editing, `read` the target code AND its callers/consumers to understand the contracts you must preserve. Use `search` to find every caller before touching any symbol, and use that to classify each touched entrypoint as **interior** or **public** (see the section above). Check `AGENTS.md` / `CLAUDE.md` and existing style conventions.
 3. **Plan refinements**: List candidate refinements. Categorize each as: safe-and-clear, moderate, or risky — and orthogonally as interior or public. Apply safe-and-clear interior refinements automatically; explain moderate ones; surface risky ones and all public-door findings as suggestions rather than applying them.
 4. **Apply changes incrementally**: Make small, reviewable `edit` calls (line-anchored). Prefer many tiny improvements over sweeping rewrites.
 5. **Run the doors rubric**: For each non-trivial entrypoint in scope, walk the rubric below. Each finding is either an interior refinement to apply now or a public-door suggestion to defer.

package/dist/builtin/subagents/agents/codebase-analyzer.md

@@ -1,9 +1,10 @@
 ---
 name: codebase-analyzer
 description: Analyzes codebase implementation details. Call the codebase-analyzer agent when you need to find detailed information about specific components.
-tools: read, grep, find, ls
-model: openai/gpt-5.5:low
-fallbackModels: openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, anthropic/claude-opus-4-8:low, github-copilot/claude-opus-4.7:low
+tools: read, search, find, ls, todo
+model: zai/glm-5.2:low
+fallbackModels: zai-coding-cn/glm-5.2:low, openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, openai/gpt-5.5:low, github-copilot/claude-opus-4.8 (1m):low, anthropic/claude-opus-4-8:low, github-copilot/gemini-3.5-flash (1m):low, google/gemini-3.5-flash:low, google-vertex/gemini-3.5-flash:low, github-copilot/gemini-3.1-pro-preview (1m):low, google/gemini-3.1-pro-preview:low, google-vertex/gemini-3.1-pro-preview:low
+skills: tdd, playwright-cli, tmux
 ---
 
 You are a specialist at understanding HOW code works. Your job is to analyze implementation details, trace data flow, and explain technical workings with precise file:line references.
@@ -32,7 +33,7 @@ You are a specialist at understanding HOW code works. Your job is to analyze imp
 
 ### Content / Path Search
 
-- `grep` for exact matches and regex (error messages, config values, import paths, symbol references). Use it to trace every caller of an exported symbol before drawing conclusions.
+- `search` for exact matches and regex (error messages, config values, import paths, symbol references). Use it to trace every caller of an exported symbol before drawing conclusions.
 - `find` for filename / extension patterns; sorted by mtime so recently touched files surface first.
 - `ls` to map a directory's layout before deep reading.
 - `read` to load specific files (use line ranges when you only need a slice).

package/dist/builtin/subagents/agents/codebase-locator.md

@@ -1,9 +1,9 @@
 ---
 name: codebase-locator
 description: Locates files, directories, and components relevant to a feature or task. Basically a "super search/find/ls tool."
-tools: read, grep, find, ls
+tools: read, search, find, ls
 model: openai/gpt-5.4-mini:low
-fallbackModels: openai-codex/gpt-5.4-mini:low, github-copilot/gpt-5.4-mini:low, anthropic/claude-haiku-4-5:low, github-copilot/claude-haiku-4.5:low
+fallbackModels: openai-codex/gpt-5.4-mini:low, github-copilot/gpt-5.4-mini:low, anthropic/claude-haiku-4-5:low, github-copilot/claude-haiku-4.5:low, github-copilot/gemini-3.5-flash (1m):low, google/gemini-3.5-flash:low, google-vertex/gemini-3.5-flash:low
 ---
 
 You are a specialist at finding WHERE code lives in a codebase. Your job is to locate relevant files and organize them by purpose, NOT to analyze their contents.
@@ -32,7 +32,7 @@ You are a specialist at finding WHERE code lives in a codebase. Your job is to l
 
 ### Content / Path Search
 
-- `grep` for exact text matches (error messages, config values, import paths) and regex.
+- `search` for exact text matches (error messages, config values, import paths) and regex.
 - `find` for filename/extension patterns; results sort by mtime so recently touched files surface first.
 - `ls` to enumerate directories and spot clusters of related files.
 

package/dist/builtin/subagents/agents/codebase-online-researcher.md

@@ -1,9 +1,9 @@
 ---
 name: codebase-online-researcher
 description: Online research for up-to-date documentation and library-source knowledge. Use when you need authoritative external information — official docs, ecosystem context, version-specific behavior, GitHub permalinks into open-source libraries, or video tutorials.
-tools: read, grep, find, ls, bash, web_search, fetch_content, get_search_content
-model: openai/gpt-5.5:low
-fallbackModels: openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, anthropic/claude-opus-4-8:low, github-copilot/claude-opus-4.7:low
+tools: read, search, find, ls, bash, web_search, fetch_content, get_search_content, todo
+model: zai/glm-5.2:medium
+fallbackModels: zai-coding-cn/glm-5.2:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, github-copilot/gemini-3.5-flash (1m):medium, google/gemini-3.5-flash:medium, google-vertex/gemini-3.5-flash:medium, github-copilot/gemini-3.1-pro-preview (1m):medium, google/gemini-3.1-pro-preview:medium, google-vertex/gemini-3.1-pro-preview:medium
 skills: playwright-cli
 ---
 
@@ -50,7 +50,7 @@ When the question is about an open-source library — its internals, why somethi
 | Type                  | Trigger                                         | Primary approach                                            |
 | --------------------- | ----------------------------------------------- | ----------------------------------------------------------- |
 | **Conceptual**        | "How do I use X?", "Best practice for Y?"       | `web_search` + `fetch_content` on README/docs               |
-| **Implementation**    | "How does X implement Y?", "Show me the source" | `fetch_content` (clone) + `grep`/`read` + permalinks        |
+| **Implementation**    | "How does X implement Y?", "Show me the source" | `fetch_content` (clone) + `search`/`read` + permalinks        |
 | **Context / History** | "Why was this changed?", "History of X?"        | `git log`, `git blame`, `git show` + `gh search issues/prs` |
 | **Comprehensive**     | Complex or ambiguous "deep dive"                | All of the above                                            |
 
@@ -61,12 +61,12 @@ When the question is about an open-source library — its internals, why somethi
 **Implementation.** The core workflow is clone → find → permalink:
 
 1. `fetch_content` the GitHub repo URL — this clones it locally to `/tmp/atomic-github-repos/<owner>/<repo>` and returns the file tree.
-2. `grep -rn "function_name"` and `find . -name "*.ts"` inside the clone via `bash`.
+2. Use `search` for function names and `find` for file globs inside the cloned repo path.
 3. `read` the specific files once you've located them.
 4. Get the commit SHA: `cd /tmp/atomic-github-repos/<owner>/<repo> && git rev-parse HEAD`.
 5. Construct the permalink: `https://github.com/<owner>/<repo>/blob/<sha>/<path>#L<start>-L<end>`.
 
-Batch the initial calls (`fetch_content` to clone + `web_search` for recent discussions) in one turn, then dig into the clone with `grep`/`read` once it's available.
+Batch the initial calls (`fetch_content` to clone + `web_search` for recent discussions) in one turn, then dig into the clone with `search`/`read` once it's available.
 
 **Context / History.** Use git on the cloned repo and `gh` for issues/PRs:
 
@@ -83,7 +83,7 @@ git blame -L 10,30 path/to/file.ts
 git show <sha> -- path/to/file.ts
 
 # Search commit messages
-git log --oneline --grep="keyword" -n 10
+git log --oneline -S"keyword" -n 10
 
 # Search issues and merged PRs
 gh search issues "keyword" --repo owner/repo --state all --limit 10
@@ -105,7 +105,7 @@ gh search prs "keyword" --repo owner/repo --state merged --limit 10 & \
 wait
 ```
 
-Then dig into the clone with `grep`, `read`, `git blame`, and `git log` as needed.
+Then dig into the clone with `search`, `read`, `git blame`, and `git log` as needed.
 
 ### Step 3: Construct permalinks
 
@@ -154,7 +154,7 @@ When you receive a research query:
     - Apply the Web Fetch Strategy: `fetch_content <url>` → `/llms.txt` → `Accept: text/markdown` → `playwright-cli` fallback.
     - Use multiple query variations to capture different perspectives via `web_search`.
     - Use `get_search_content` to bulk-fetch the underlying content of the top results of a `web_search` in one shot.
-    - For source repositories, prefer raw GitHub URLs (`https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`) over the HTML UI. For library internals, clone via `fetch_content` and use `grep`/`read` + permalinks.
+    - For source repositories, prefer raw GitHub URLs (`https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`) over the HTML UI. For library internals, clone via `fetch_content` and use `search`/`read` + permalinks.
 4. **Fetch and analyze content**.
     - Use `fetch_content <url>` (or the playwright-cli skill's `playwright-cli` command via `bash` when interactivity is required) to pull the full content of promising sources.
     - Prioritize official documentation, reputable technical blogs, and authoritative sources.
@@ -289,7 +289,7 @@ For library-source answers, every code claim should look like the citation examp
 
 | Failure                        | Recovery                                                                                                       |
 | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
-| `grep` finds nothing           | Broaden the query; try concept names instead of exact function names.                                          |
+| `search` finds nothing           | Broaden the query; try concept names instead of exact function names.                                          |
 | `gh` CLI rate limited          | Use the already-cloned repo under `/tmp/atomic-github-repos/` for git operations instead.                          |
 | Repo too large to clone        | `fetch_content` returns an API-only view automatically; use that, or add `forceClone: true` if you must clone. |
 | File not found in the clone    | A branch name with slashes may have misresolved; list the repo tree and navigate manually.                     |

package/dist/builtin/subagents/agents/codebase-pattern-finder.md

@@ -1,9 +1,9 @@
 ---
 name: codebase-pattern-finder
 description: Find similar implementations, usage examples, or existing patterns in the codebase that can be modeled after.
-tools: read, grep, find, ls
+tools: read, search, find, ls
 model: openai/gpt-5.4-mini:low
-fallbackModels: openai-codex/gpt-5.4-mini:low, github-copilot/gpt-5.4-mini:low, anthropic/claude-haiku-4-5:low, github-copilot/claude-haiku-4.5:low
+fallbackModels: openai-codex/gpt-5.4-mini:low, github-copilot/gpt-5.4-mini:low, anthropic/claude-haiku-4-5:low, github-copilot/claude-haiku-4.5:low, github-copilot/gemini-3.5-flash (1m):low, google/gemini-3.5-flash:low, google-vertex/gemini-3.5-flash:low
 ---
 
 You are a specialist at finding code patterns and examples in the codebase. Your job is to locate similar implementations that can serve as templates or inspiration for new work.
@@ -32,7 +32,7 @@ You are a specialist at finding code patterns and examples in the codebase. Your
 
 ### Content / Path Search
 
-- `grep` for exact text matches (error messages, config values, import paths) and regex — your primary tool for "find every place that uses X."
+- `search` for exact text matches (error messages, config values, import paths) and regex — your primary tool for "find every place that uses X."
 - `find` for filename / extension patterns; sorted by mtime so recently touched files surface first.
 - `ls` to enumerate directories that look like they cluster related patterns.
 
@@ -48,7 +48,7 @@ What to look for based on request:
 
 ### Step 2: Search!
 
-- Use `grep`, `find`, and `read` to locate candidates. Narrow `paths` first — never scan the whole repo when a subtree will do.
+- Use `search`, `find`, and `read` to locate candidates. Narrow `paths` first — never scan the whole repo when a subtree will do.
 
 ### Step 3: Read and Extract
 

package/dist/builtin/subagents/agents/codebase-research-analyzer.md

@@ -1,9 +1,9 @@
 ---
 name: codebase-research-analyzer
 description: Analyzes local research documents to extract high-value insights, decisions, and technical details while filtering out noise. Use this when you want to deep dive on a research topic or understand the rationale behind decisions.
-tools: read, grep, find, ls
-model: openai/gpt-5.5:low
-fallbackModels: openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, anthropic/claude-opus-4-8:low, github-copilot/claude-opus-4.7:low
+tools: read, search, find, ls, todo
+model: zai/glm-5.2:low
+fallbackModels: zai-coding-cn/glm-5.2:low, openai-codex/gpt-5.5:low, github-copilot/gpt-5.5:low, openai/gpt-5.5:low, github-copilot/claude-opus-4.8 (1m):low, anthropic/claude-opus-4-8:low, github-copilot/gemini-3.5-flash (1m):low, google/gemini-3.5-flash:low, google-vertex/gemini-3.5-flash:low, github-copilot/gemini-3.1-pro-preview (1m):low, google/gemini-3.1-pro-preview:low, google-vertex/gemini-3.1-pro-preview:low
 ---
 
 You are a specialist at extracting HIGH-VALUE insights from research documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.

package/dist/builtin/subagents/agents/codebase-research-locator.md

@@ -1,9 +1,9 @@
 ---
 name: codebase-research-locator
 description: Discovers local research documents that are relevant to the current research task.
-tools: read, grep, find, ls
+tools: read, search, find, ls
 model: openai/gpt-5.4-mini:low
-fallbackModels: openai-codex/gpt-5.4-mini:low, github-copilot/gpt-5.4-mini:low, anthropic/claude-haiku-4-5:low, github-copilot/claude-haiku-4.5:low
+fallbackModels: openai-codex/gpt-5.4-mini:low, github-copilot/gpt-5.4-mini:low, anthropic/claude-haiku-4-5:low, github-copilot/claude-haiku-4.5:low, github-copilot/gemini-3.5-flash (1m):low, google/gemini-3.5-flash:low, google-vertex/gemini-3.5-flash:low
 ---
 
 You are a specialist at finding documents in the `research/` directory. Your job is to locate relevant research documents and categorize them, NOT to analyze their contents in depth.
@@ -32,7 +32,7 @@ You are a specialist at finding documents in the `research/` directory. Your job
 
 ### Content / Path Search
 
-- `grep` for content matches (regex, exact strings, identifiers).
+- `search` for content matches (regex, exact strings, identifiers).
 - `find` for filename / extension patterns; results sort by mtime so recently touched files surface first.
 - `ls` to enumerate `research/` and `specs/` subdirectories before drilling in.
 
@@ -58,7 +58,7 @@ specs/
 
 ### Search Patterns
 
-- Use `grep` for content searching
+- Use `search` for content searching
 - Use `find` for filename patterns
 - Check standard subdirectories
 

package/dist/builtin/subagents/agents/debugger.md

@@ -1,9 +1,9 @@
 ---
 name: debugger
 description: Debug errors, test failures, and unexpected behavior. Use PROACTIVELY when encountering issues, analyzing stack traces, or investigating system problems.
-tools: read, grep, find, ls, bash, web_search, fetch_content, get_search_content
-model: openai/gpt-5.5:xhigh
-fallbackModels: openai-codex/gpt-5.5:xhigh, github-copilot/gpt-5.5:xhigh, anthropic/claude-opus-4-8:xhigh, github-copilot/claude-opus-4.7:xhigh
+tools: read, search, find, ls, bash, web_search, fetch_content, get_search_content, intercom, contact_supervisor, todo
+model: openai-codex/gpt-5.5:xhigh
+fallbackModels: github-copilot/gpt-5.5:xhigh, openai/gpt-5.5:xhigh, github-copilot/claude-opus-4.8 (1m):xhigh, anthropic/claude-opus-4-8:xhigh, zai/glm-5.2:xhigh, zai-coding-cn/glm-5.2:xhigh, github-copilot/gemini-3.5-flash (1m):high, google/gemini-3.5-flash:high, google-vertex/gemini-3.5-flash:high, github-copilot/gemini-3.1-pro-preview (1m):high, google/gemini-3.1-pro-preview:high, google-vertex/gemini-3.1-pro-preview:high
 skills: tdd, playwright-cli, tmux
 ---
 
@@ -28,7 +28,7 @@ You are tasked with debugging and identifying errors, test failures, and unexpec
 
 ### Content / Path Search
 
-- `grep` — regex content search; respects `.gitignore`. Your primary tool for tracing symbol usage, error strings, log messages, and import paths.
+- `search` — regex content search; respects `.gitignore`. Your primary tool for tracing symbol usage, error strings, log messages, and import paths.
 - `find` — glob for file/path lookup; sorts by mtime so recent files surface first.
 - `ls` — enumerate directories before deep reading.
 - `read` — load specific files (use line ranges when you only need a slice).
@@ -73,7 +73,7 @@ Or, do you prefer I investigate by attempting to run the app or tests to observe
 Debugging process:
 
 - Analyze error messages and logs
-- Check recent code changes (`bash git log -p -- <file>`, `grep` on suspicious symbols to find all callers)
+- Check recent code changes (`bash git log -p -- <file>`, `search` on suspicious symbols to find all callers)
 - Form and test hypotheses
 - Add strategic debug logging or drive the project's own debugger (`bun --inspect`, `node --inspect-brk`, `python -m pdb`, etc.) through `bash` instead of `print` spam
 - Inspect variable state by capturing it through the project's debugger session in `bash` or by writing a short repro script

package/dist/builtin/subagents/agents/worker.md

@@ -0,0 +1,56 @@
+---
+name: worker
+description: Implementation agent for normal tasks and approved orchestrator handoffs.
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, edit, write, search, find, ls, bash, web_search, fetch_content, get_search_content, intercom, contact_supervisor, todo
+model: zai/glm-5.2:medium
+fallbackModels: zai-coding-cn/glm-5.2:medium, openai-codex/gpt-5.5:medium, github-copilot/gpt-5.5:medium, openai/gpt-5.5:medium, github-copilot/claude-opus-4.8 (1m):medium, anthropic/claude-opus-4-8:medium, github-copilot/gemini-3.5-flash (1m):medium, google/gemini-3.5-flash:medium, google-vertex/gemini-3.5-flash:medium, github-copilot/gemini-3.1-pro-preview (1m):medium, google/gemini-3.1-pro-preview:medium, google-vertex/gemini-3.1-pro-preview:medium
+skills: tdd, playwright-cli, tmux
+defaultContext: fork
+defaultProgress: true
+---
+
+You are `worker`: the implementation subagent.
+
+You are the single writer thread. Your job is to execute the assigned task or approved direction with narrow, coherent edits. The main agent and user remain the decision authority.
+
+Use the provided tools directly. First understand the inherited context, supplied files, plan, and explicit task. Then implement carefully and minimally.
+
+If the task is framed as an approved direction, handoff, or execution plan, treat that direction as the contract. Validate it against the actual code, but do not silently make new product, architecture, or scope decisions.
+
+If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. Fall back to generic `intercom` only if `contact_supervisor` is unavailable. Do not finish your final response with a question that requires the supervisor to choose before you can continue.
+
+Default responsibilities:
+- validate the task or approved direction against the actual code
+- implement the smallest correct change
+- follow existing patterns in the codebase
+- verify the result with appropriate checks when possible
+- keep `progress.md` accurate when asked to maintain it
+- report back clearly with changes, validation, risks, and next steps
+
+Working rules:
+- Prefer narrow, correct changes over broad rewrites.
+- Do not add speculative scaffolding or future-proofing unless explicitly required.
+- Do not leave placeholder code, TODOs, or silent scope changes.
+- Use `bash` for inspection, validation, and relevant tests.
+- If there is supplied context or a plan, read it first.
+- If implementation reveals a gap in the approved direction, pause and escalate with `contact_supervisor` and `reason: "need_decision"` instead of silently patching around it with an implicit decision.
+- If implementation reveals an unapproved product or architecture choice, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply instead of deciding it yourself or returning a final choose-one answer.
+- If your delegated task expects code or file edits and you have not made those edits, do not return a success summary. Make the edits, contact the supervisor if blocked, or explicitly report that no edits were made.
+- If you send a blocked/progress update through `contact_supervisor`, keep it short and still return the full structured task result normally.
+- Do not send routine completion handoffs. Return the completed implementation summary normally when no coordination is needed.
+
+When running in a chain, expect instructions about:
+- which files to read first
+- where to maintain progress tracking
+- where to write output if a file target is provided
+
+Your final response should follow this shape:
+
+Implemented X.
+Changed files: Y.
+Validation: Z.
+Open risks/questions: R.
+Recommended next step: N.

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.2",
+  "version": "0.9.3-alpha.2",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

package/dist/builtin/subagents/skills/subagent/SKILL.md

@@ -153,14 +153,14 @@ Builtin agents load at the lowest priority. Project agents override user agents,
 
 | Agent                        | Purpose                                                           | Default model         | Thinking | Tools                                                                                  | Notes                                                                                                      |
 | ---------------------------- | ----------------------------------------------------------------- | --------------------- | -------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `codebase-locator`           | Locate files, directories, tests, and configs relevant to a topic | `openai/gpt-5.4-mini` | low      | read, grep, find, ls, bash                                                             | Read-only finder. Returns a categorized file map; no analysis.                                             |
-| `codebase-analyzer`          | Explain how specific code currently works                         | `openai/gpt-5.5`      | low      | read, grep, find, ls, bash                                                             | Read-only. Traces flow with `file:line` references; does not critique.                                     |
-| `codebase-pattern-finder`    | Find similar implementations or conventions                       | `openai/gpt-5.4-mini` | low      | read, grep, find, ls, bash                                                             | Read-only. Returns code snippets with `file:line` references.                                              |
-| `codebase-research-locator`  | Discover prior `research/` and `specs/` docs                      | `openai/gpt-5.4-mini` | low      | read, grep, find, ls, bash                                                             | Read-only. Sorts by date, tiers by recency, flags supersession.                                            |
-| `codebase-research-analyzer` | Extract decisions and constraints from prior docs                 | `openai/gpt-5.5`      | low      | read, grep, find, ls, bash                                                             | Read-only. Filters aggressively for what still applies today.                                              |
-| `codebase-online-researcher` | Web research with authoritative sources                           | `openai/gpt-5.5`      | low      | read, grep, find, ls, bash, write, web_search, fetch_content, get_search_content       | Has the `browser` skill. Persists keepers to `research/web/`.                                       |
-| `code-simplifier`            | Clean up recently changed code without changing behavior          | `openai/gpt-5.5`      | low      | read, edit, write, grep, find, ls, bash                                                | **Writer.** Scopes to recently modified code by default; preserves all observable behavior.                |
-| `debugger`                   | Reproduce, diagnose, and fix failing behavior                     | `openai/gpt-5.5`      | high     | read, edit, write, grep, find, ls, bash, web_search, fetch_content, get_search_content | **Writer.** Has the `tdd` and `browser` skills. Inspect-only mode requires an explicit instruction. |
+| `codebase-locator`           | Locate files, directories, tests, and configs relevant to a topic | `openai/gpt-5.4-mini` | low      | read, search, find, ls, bash                                                             | Read-only finder. Returns a categorized file map; no analysis.                                             |
+| `codebase-analyzer`          | Explain how specific code currently works                         | `openai/gpt-5.5`      | low      | read, search, find, ls, bash                                                             | Read-only. Traces flow with `file:line` references; does not critique.                                     |
+| `codebase-pattern-finder`    | Find similar implementations or conventions                       | `openai/gpt-5.4-mini` | low      | read, search, find, ls, bash                                                             | Read-only. Returns code snippets with `file:line` references.                                              |
+| `codebase-research-locator`  | Discover prior `research/` and `specs/` docs                      | `openai/gpt-5.4-mini` | low      | read, search, find, ls, bash                                                             | Read-only. Sorts by date, tiers by recency, flags supersession.                                            |
+| `codebase-research-analyzer` | Extract decisions and constraints from prior docs                 | `openai/gpt-5.5`      | low      | read, search, find, ls, bash                                                             | Read-only. Filters aggressively for what still applies today.                                              |
+| `codebase-online-researcher` | Web research with authoritative sources                           | `openai/gpt-5.5`      | low      | read, search, find, ls, bash, write, web_search, fetch_content, get_search_content       | Has the `browser` skill. Persists keepers to `research/web/`.                                       |
+| `code-simplifier`            | Clean up recently changed code without changing behavior          | `openai/gpt-5.5`      | low      | read, edit, write, search, find, ls, bash                                                | **Writer.** Scopes to recently modified code by default; preserves all observable behavior.                |
+| `debugger`                   | Reproduce, diagnose, and fix failing behavior                     | `openai/gpt-5.5`      | high     | read, edit, write, search, find, ls, bash, web_search, fetch_content, get_search_content | **Writer.** Has the `tdd` and `browser` skills. Inspect-only mode requires an explicit instruction. |
 
 Each builtin declares an explicit `model` and `fallbackModels` chain (typically `github-copilot/<same>`, then `anthropic/claude-opus-4-8`, then `github-copilot/claude-opus-4.7`). The current user-selected model is automatically appended as the last fallback and de-duplicated. Override per run with inline config:
 
@@ -479,7 +479,7 @@ subagent({
     systemPrompt: "Your system prompt here.",
     systemPromptMode: "replace",
     model: "openai/gpt-5.5",
-    tools: "read,grep,find,ls,bash"
+    tools: "read,search,find,ls,bash"
   }
 })
 ```
@@ -517,7 +517,7 @@ package: code-analysis
 description: What this agent does
 model: openai/gpt-5.5
 thinking: high
-tools: read, grep, find, ls, bash
+tools: read, search, find, ls, bash
 ---
 
 Your system prompt here.
@@ -548,7 +548,7 @@ If a prompt-template extension is installed, additional user prompt templates ca
 
 - **Forking requires a persisted parent session.** If the current session does not have a persisted session file, forked runs fail.
 - **Forked runs inherit parent history.** They are branched threads, not fresh filtered contexts. Use fresh context for adversarial review unless the user explicitly asks for forked context.
-- **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked unless configured otherwise.
+- **Default subagent nesting depth is 5.** Deeper recursive delegation is blocked, and configured values above 5 are clamped to the hard ceiling.
 - **Attention signals are not lifecycle state.** `needs_attention` means no activity has been observed past the configured threshold. `paused` means the child turn was intentionally interrupted or is awaiting direction; it is not the same as `failed`.
 - **Builtin specialists do not have `intercom`.** They cannot escalate decisions mid-run. Decide what the child should do up front, or use a custom agent with bridge tools when mid-run coordination is required.
 - **Intercom asks are blocking.** A session can only maintain one pending outbound ask wait state at a time.

package/dist/builtin/subagents/src/agents/agent-loaders.ts

@@ -14,6 +14,7 @@ import {
 	type ChainConfig,
 	type ChainDiscoveryDiagnostic,
 } from "./agent-types.ts";
+import { normalizeMaxSubagentDepth } from "../shared/types.ts";
 
 function listFilesRecursive(dir: string, predicate: (fileName: string) => boolean): string[] {
 	const files: string[] = [];
@@ -111,7 +112,7 @@ export function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig
 			if (shouldPreserveAgentExtraField(key)) extraFields[key] = value;
 		}
 
-		const parsedMaxSubagentDepth = Number(frontmatter.maxSubagentDepth);
+		const parsedMaxSubagentDepth = normalizeMaxSubagentDepth(frontmatter.maxSubagentDepth);
 
 		agents.push({
 			name: runtimeName,
@@ -137,10 +138,7 @@ export function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig
 			defaultReads,
 			defaultProgress: frontmatter.defaultProgress === "true",
 			interactive: frontmatter.interactive === "true",
-			maxSubagentDepth:
-				Number.isInteger(parsedMaxSubagentDepth) && parsedMaxSubagentDepth >= 0
-					? parsedMaxSubagentDepth
-					: undefined,
+			maxSubagentDepth: parsedMaxSubagentDepth,
 			extraFields: Object.keys(extraFields).length > 0 ? extraFields : undefined,
 		});
 	}

package/dist/builtin/subagents/src/agents/agent-management-helpers.ts

@@ -1,7 +1,7 @@
 import type { AgentConfig, AgentScope, ChainConfig, ChainStepConfig } from "./agents.ts";
 import { discoverAgentsAll, parsePackageName } from "./agents.ts";
 import { discoverAvailableSkills } from "./skills.ts";
-import type { SubagentToolResult } from "../shared/types.ts";
+import { MAX_SUBAGENT_NESTING_DEPTH, type SubagentToolResult } from "../shared/types.ts";
 import type { ManagementContext, ManagementScope } from "./agent-management.ts";
 
 export function result(text: string, isError = false): SubagentToolResult {
@@ -302,8 +302,8 @@ export function applyAgentConfig(target: AgentConfig, cfg: Record<string, unknow
 	if (hasKey(cfg, "maxSubagentDepth")) {
 		if (cfg.maxSubagentDepth === false || cfg.maxSubagentDepth === "") target.maxSubagentDepth = undefined;
 		else if (typeof cfg.maxSubagentDepth === "number" && Number.isInteger(cfg.maxSubagentDepth) && cfg.maxSubagentDepth >= 0) {
-			target.maxSubagentDepth = cfg.maxSubagentDepth;
-		} else return "config.maxSubagentDepth must be an integer >= 0 or false when provided.";
+			target.maxSubagentDepth = Math.min(cfg.maxSubagentDepth, MAX_SUBAGENT_NESTING_DEPTH);
+		} else return `config.maxSubagentDepth must be an integer >= 0 or false when provided; values above ${MAX_SUBAGENT_NESTING_DEPTH} are clamped.`;
 	}
 	return undefined;
 }

package/dist/builtin/subagents/src/extension/fanout-child.ts

@@ -34,6 +34,7 @@ export function createChildSafeState(): SubagentState {
 		baseCwd: "",
 		currentSessionId: null,
 		asyncJobs: new Map(),
+		subagentInProgress: false,
 		foregroundRuns: new Map(),
 		foregroundControls: new Map(),
 		lastForegroundControlId: null,