@bastani/atomic 0.9.2 → 0.9.3-alpha.1

package/CHANGELOG.md

@@ -2,6 +2,63 @@
 
 ## [Unreleased]
 
+## [0.9.3-alpha.1] - 2026-06-25
+
+### Breaking Changes
+
+- Replaced the previous exact-replacement `edit` input shape with the hashline-only `input` script schema; `path` + `edits[]` and top-level `oldText`/`newText` edit calls are no longer accepted ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Tightened the model-facing `read`, `find`, and `search` schemas to the new builtin contracts: `read` uses path selectors instead of `offset`/`limit`, `find` requires `paths`, and `search` accepts only `pattern`, `paths`, `i`, `case`, `gitignore`, and `skip` ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+
+### Added
+
+- Added one-time first-run onboarding that explains Atomic workflows, uses an onboarding editor placeholder, lets users opt into normal chat with `/chat`, preserves other slash commands, saves a pre-login pasted task in memory only, and hands the first ready ticket/spec/task to the normal coding-agent session with `goal`/`ralph` workflow-routing guidance.
+- Added first-run onboarding routing guidance that raises the parent session to high reasoning when supported, asks the coding agent to first make a text-only scope estimate from tickets/GitHub issues/specs, routes directly when the task is clearly tiny or small with high confidence, and only uses targeted read-only `codebase-locator`/`codebase-analyzer`/`codebase-pattern-finder` probing when referenced context must be read or scope is medium, large, unclear, risky, or not obviously tiny before choosing `goal` or `ralph`.
+- Added a first-class `search` built-in and exposed `find`/`search` in normal coding sessions ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Added hashline snapshot anchors across `read`, `search`, `write`, and successful `edit` results, plus hashline line-range/block/multi-section edit scripts with stale-tag safety checks and snapshot-based recovery for non-overlapping file drift, empty-replace validation, and fresh post-mutation tags for follow-up edits ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Added disabled-by-default `bashInterceptor.enabled` settings support with built-in shell anti-pattern rules, a `/settings` **Bash Interceptor** toggle, and optional `user_bash` extension routing, without changing the default local-execution behavior ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Added Rust-backed native PTY execution for `bash({ "pty": true })`, so local PTY calls run through `@bastani/atomic-natives` `PtySession` with real terminal semantics, streaming output, timeout, abort/kill, cwd, shell, and environment support ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Added native `glob`/`grep` bindings copied from oh-my-pi and wired `find`/`search` to use them when available, matching upstream hidden-file, `.gitignore`, node_modules, result-limit, context, truncation, and timeout behavior without shelling out to host tools ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+
+### Changed
+
+- Updated first-run `goal`/`ralph` workflow handoff guidance so new users see `/workflow status <id>` and `/workflow connect <id>` next steps with the run id, understand connect is where they can watch, attach, and steer, and know they can ask the current chat for status or steering at any point.
+- Removed the unused first-run onboarding scope-probe/routing-assessment subsystem and dead probe-only tests after normal-session prompt handoff became the active onboarding path.
+- Accounted for image content blocks in context-window token accounting and compaction thresholds: image tokens are now estimated through a single shared conservative estimate (1200 tokens per image) used consistently by both the heuristic context-estimate path and the transcript planner, so image-heavy conversations trigger compaction at the correct time. The deletion planner now reports image token share (`remainingImageTokens`, `imageBlockCount`, `imageTokenPercent`) via `context_compaction_budget` and is instructed to prefer deleting stale, superseded, or unrelated image content blocks when images dominate, while preserving task-relevant recent images and user text. Because Verbatim Compaction is deletion-only, compaction never reintroduces image payloads or generates image-bearing summaries ([#1500](https://github.com/bastani-inc/atomic/issues/1500)).
+- Made `context_compaction_budget` image statistics deletion-aware: the `remainingImageTokens`/`imageBlockCount`/`imageTokenPercent` fields are now recomputed from the live deletion-target set on every budget tool call, so they immediately reflect image blocks already deleted within the current compaction run instead of reporting frozen pre-deletion totals ([#1500](https://github.com/bastani-inc/atomic/issues/1500)).
+- Raised the bundled subagent and workflow-stage nesting budget to a hard maximum of five delegated levels, and documented the `0`-to-`5` recursion-guard range.
+- Extracted the schema-aware flattened-argument disambiguation into a shared canonical `unflattenArgumentsWithSchema` helper in `core/flattened-tool-arguments.ts` (exported from `@bastani/atomic`), now reused by both the GitHub Copilot Gemini per-tool normalization and the MCP `callTool` boundary so literal dotted argument keys are preserved unless the tool schema proves they are nested paths. A literal dotted top-level property (e.g. `filter.name`) is preserved verbatim even when the schema also defines a same-head container property (e.g. `filter`) (issue [#1496](https://github.com/bastani-inc/atomic/issues/1496)).
+
+### Fixed
+
+- Fixed the first-run onboarding input placeholder so it uses muted TUI text and still renders a visible cursor while empty, making the startup composer read as an editable field instead of static copy.
+- Fixed `@` file-reference autocomplete in the first-run onboarding editor before the asynchronous `fd` readiness check completes by falling back to the built-in synchronous path completer while preserving `@` prefixes and quoted paths.
+- Fixed workflow config/discovery isolation so `ATOMIC_CODING_AGENT_DIR` prevents home-global workflows from shadowing the bundled first-run onboarding `goal` and `ralph` targets.
+- Fixed first-run onboarding returning-user detection so existing Atomic users with prior changelog state are marked onboarded and do not see the first-run CTA/placeholder when upgrading to a build that includes onboarding, while auth-only fresh installs and unfinished onboarding sessions still see the first-run flow.
+- Fixed first-run onboarding so multiline absolute path seeds with `:line[:column]` plus notes are saved or handed off with the full original text instead of being mistaken for slash commands.
+- Fixed successful `/import <jsonl>` during first-run onboarding so the imported session exits onboarding UI/interception state instead of treating the next normal message as a fresh onboarding seed.
+- Fixed first-run onboarding so a task saved before the session is ready resumes after successful `/model` selection, including the context-window follow-up step when required.
+- Fixed `/new` during first-run onboarding so the replacement session remains in onboarding but drops any previously saved in-memory task seed instead of resuming stale work later.
+- Fixed `context_compaction_budget` `imageTokenPercent` denominator so image share is computed against the remaining (post-deletion) context total rather than the original pre-deletion total. The budget text said “of remaining context” but the value used the original transcript size; deleting non-image text now correctly increases the reported image share while deleting image blocks decreases it ([#1500](https://github.com/bastani-inc/atomic/issues/1500)).
+- Fixed delete-context pruning for old user-pasted image attachments: stale, non-recent user `image` content blocks can now be deleted while preserving user text, old image-only user entries can be deleted when another task-bearing entry remains, multi-image-only user matches are canonicalized to a safe entry deletion during `[image]` grep-delete batches, and recent user images remain protected ([#1500](https://github.com/bastani-inc/atomic/issues/1500)).
+- Fixed `find` and `search` glob entries in `paths`, restored `search.skip` file-page pagination for filesystem and resource-backed matches (including SQLite text primary keys with spaces), surfaced skip pagination hints across multiple pages when filesystem, archive, SQLite, internal, explicit-path, and ranged-selector search pages are full, avoided false continuation hints when later explicit targets do not match, kept `search` line-selector context inside the requested ranges for native and non-native fallback search, searched ranged single-file selectors without dropping matches beyond the internal raw grep cap while preserving backend regex semantics such as inline `(?i)`/`(?m)`/`(?x)`, normalized copied quoted/empty path inputs including `paths: []`, split delimiter-joined glob search/find/resource paths only after preserving exact filesystem paths with spaces or delimiter characters, awaited async internal-resource find resolvers and continued to fallback resolvers when earlier async resolvers returned `undefined`, resolved `local://`/router-backed find paths before filesystem normalization, preserved trailing slashes for directory find matches, stopped exact-file and exact-limit glob find hits from reporting false limit truncation while reporting real truncation when exact files fill the page before later targets, enforced custom find backend result limits without fabricating empty directory matches, made `find.timeout` return a partial timed-out result instead of accepting an ignored option, ensured custom find backends receive/enforce `hidden:false`, and ensured `gitignore:false` plus explicit `node_modules` globs include `node_modules` in native find/search scans ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Fixed copied hashline output passed to `write` by stripping `[PATH#TAG]` headers, directory banners, continuation/truncation footers, and `LINE:` prefixes only for known current-session snapshots, including bounded/truncated read and search snippets, while preserving literal hashline-looking user content and rejecting unknown/stale tags from other snapshot stores; successful hashline edits now return compact refreshed-anchor metadata instead of the full post-edit file, `insert tail` now appends exactly once for trailing-newline, no-final-newline, and empty files, line-anchored edits on empty hashline snapshots no longer silently no-op, and multi-file hashline edits preflight all stale tags before writing any file ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Fixed additional builtin parity gaps by removing the archive selector dependency on host `python3`, bounding oversized archive/internal/URL/SQLite/local-document reads like file reads while preserving oversized-read details for collapsed renderers, truncating resource-backed and SQLite search lines, aligning archive/internal/SQLite resource search regex semantics with filesystem search, avoiding inflation of unrelated zip members for selected reads/searches/writes, routing internal-resource selectors through a session router when available, preserving custom read/find backends that do not map to local files, filtering direct MCP tool allowlists that collide with the new builtin `search`, and expanding supported internal URLs in bash command/cwd/env inputs before execution ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Fixed read/write parity for URL/internal-resource line selectors, `:raw` URL bypasses, archive members named `raw`, `conflicts`, numeric/L-prefixed names, suffix-looking paths such as `raw:notes.txt`, and archive member `:raw`/`:conflicts` suffixes with or without line ranges, reference-context bounded ranges, raw multi-range sorting/merging, invalid open-ended `+` selectors, no-conflict sentinel output, read-registered `conflict://<id>` plus `conflict://*` splicing with `@ours`/`@theirs`/`@base` and fresh resolved-file snapshot headers, read-only conflict side scopes, generated-file overwrite protection, archive directory-write rejection, reader-style HTML/notebook extraction plus `markit-ai` document conversion for PDF/Office/RTF/EPUB formats, SQLite row/search/pagination/schema selectors, SQLite table `{}` default-value inserts, SQLite JSON5 object validation and query-param rejection for writes, JSON5 writes that preserve quoted hex-like strings, non-SQLite `.db` fallback, and conflict-only hashline line numbers; async bash job polling now surfaces stored execution errors, async and headless `pty:true` requests get a real PTY, PTY execution preserves configured shell argv/stdin transport and live writes instead of forcing a login shell, the bash interceptor now checks commands before configured prefixes are prepended, exact absolute `find` targets outside the workspace render as valid relative paths, native grep file searches emit callbacks, and native `find` bypasses stale scan caches after shell/external mutations ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Completed remaining oh-my-pi builtin parity for source-backed `local://` reads/searches/writes with filesystem hashline labels, richer `find`/`search` result details, streaming `find` progress updates, oh-my-pi-shaped `bash` async metadata, write `resolvedPath`/`madeExecutable`/SQLite source metadata, native in-memory resource search usage, expanded direct `grep` native options, reference-shaped edit success headers, `bash` leading-`cd` rewrite/interceptor ordering, and implicit `find` `**/*` directory patterns ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Aligned oh-my-pi SQLite/notebook/metadata parity: SQLite query default limit is 20 with a 500 cap, raw `?q=` rows cap at 1000, table lists cap at 500 and exclude `sqlite_%` system tables; `.ipynb` cells use 0-based `cell:N` IDs; resource-backed search honors `search.contextBefore`/`search.contextAfter` settings; and successful `read` results across filesystem, URL, SQLite, archive, internal-resource, document, and directory paths consistently return `details.meta.source`/`sourcePath` (plus truncation/limits where applicable), matching the referenced `details.meta` contract ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Tightened the final oh-my-pi builtin parity pass by restoring upstream output caps (3,000 shared read lines, 512-character search lines, 64 MiB archive members), preserving plain URL-read truncation metadata from the fetch pipeline, and aligning the oversized URL test expectation with oh-my-pi's truncating URL behavior ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Hardened oh-my-pi parity code paths flagged by GitHub code-quality and advanced-security review by replacing ambiguous regex parsing in `bash`, `edit`, `find`, read selectors, and HTML document extraction with linear parsers and by removing stale local analysis warnings ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Fixed compiled release binary builds by externalizing `mupdf` during Bun compilation so the `markit-ai` document reader can keep its runtime dependency with top-level await in copied `node_modules` instead of being inlined into the executable ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Hardened URL and `local://` resource reads/writes by blocking private/metadata URL fetch targets by default, revalidating manual redirects, and rejecting `local://` paths that escape the workspace root ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Addressed the PR review hardening pass for oh-my-pi parity: built-in bash interception now checks raw, expanded, prefix, and leading-`cd`-normalized commands; hashline edit batches route writes through the vendored patcher with duplicate canonical-path rejection and partial-write reporting; URL reads pin DNS-validated addresses and cap streamed bodies; async bash jobs support cancellation/eviction; native PTY cleanup joins reader threads; native worker panics and poisoned locks are converted to errors; and find/search/native cache paths received additional caps and nonblocking safeguards ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Closed the remaining oh-my-pi parity and PR review gaps for builtin tools: directory reads now use recency-sorted capped trees, comma/semicolon find/search path lists split when at least one path resolves, search pagination exposes `fileLimitReached` details, line-range search renders context around in-range matches, plain writes return compact fresh headers and note copied-hashline stripping, generated-file guards scan a larger header window, notebooks preserve unknown top-level fields, SQLite raw reads match oh-my-pi's readonly raw-query behavior, `bash` leading-`cd` handles `~`, async bash job timeouts render human-readable errors, native/fallback grep count and multiline behavior are aligned, macOS variant-resolved read snapshots can be edited, native Rust grep tests compile through an `rlib`, and selector/URL security hardening now rejects numeric private-IP URL forms plus archive/SQLite/skill/local symlink escapes ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Followed up on the post-push oh-my-pi audit by matching additional SQLite and discovery semantics: SQLite table listings now avoid full table-count scans with bounded row-count probes, raw `?q=` reads stop after 1000 rows while iterating, structured `where=` validation ignores quoted keywords but rejects control clauses such as `INTERSECT`, SQLite writes validate table columns and scalar values before binding, directory reads prune `.git`/`node_modules`, and broad `find` scans keep `node_modules` pruned even with `gitignore:false` unless explicitly requested ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Addressed the follow-up PR review by validating raw SQLite `?q=` selectors as single safe `SELECT` statements, rejecting raw access to `sqlite_%` internals and dangerous statements such as `ATTACH`, bounds-checking zip central-directory/local-entry offsets before reads or inflates, extending URL SSRF guards to NAT64/6to4 private-address forms and documenting `ATOMIC_ALLOW_PRIVATE_URL_READS` as dev-only, wrapping native block/PTY/Cursor HTTP2 entrypoints in panic guards, ensuring PTY error paths still clean up readers/children, documenting generated Rust split wrappers, bounding uncached native grep streaming accumulation, and correcting the direct-`grep` native-cache docs to match the fresh-by-default implementation ([#1483](https://github.com/bastani-inc/atomic/issues/1483)).
+- Fixed cross-platform package test execution by preparing native bindings and LFS fixtures in CI, running the coding-agent Vitest suite under Bun, making self-update/home-directory detection respect live Bun environments, and hardening Windows path/color/process-spawn test coverage ([#1490](https://github.com/bastani-inc/atomic/pull/1490)).
+- Addressed follow-up PR review findings by making hashline snapshot collision handling compare full snapshot text before treating 4-hex tags as identities, extending URL SSRF detection to the full IPv6 link-local `fe80::/10` range plus IPv4-compatible IPv6 forms, re-checking bash interceptor rules after `spawnHook` rewrites, surfacing search pagination collection caps without duplicate continuation banners, preserving truncated async bash output in a recoverable `fullOutputPath`, and passing per-path native search-cache invalidations through to the native binding ([#1490](https://github.com/bastani-inc/atomic/pull/1490)).
+- Addressed the latest PR review hardening pass by counting multi-file search per-file caps by match lines instead of context lines, making native filesystem scan cache insertion generation-aware so in-flight scans cannot repopulate after invalidation, rejecting SQLite raw-query `pragma_*` table-valued functions and double-quoted internal-name splices, and bounds-checking zip central-directory offsets during selective archive writes ([#1490](https://github.com/bastani-inc/atomic/pull/1490)).
+- Addressed the final PR review hardening pass by restoring header-only copied-hashline writes to their snapshot content instead of emptying files, decoding and sanitizing async bash output with a streaming UTF-8 decoder, cleaning up async bash temp output files on eviction/TTL, invalidating native search caches after bash commands, keeping URL protocol validation outside the private-read escape hatch, documenting single-file search skip handling, preserving CR-only hashline edit line endings, rejecting selective zip writes that would drop data descriptors, and exposing `search` in extension `tool_call`/`tool_result` type guards like other builtins ([#1490](https://github.com/bastani-inc/atomic/pull/1490)).
+
 ## [0.9.2] - 2026-06-23
 
 ### Changed

package/README.md

@@ -77,7 +77,7 @@ atomic
 /login  # Then select provider
 ```
 
-Then just talk to Atomic. By default, Atomic gives the model four tools: `read`, `write`, `edit`, and `bash`. The model uses these to fulfill your requests. Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [Atomic packages](#atomic-packages).
+Then just talk to Atomic. By default, Atomic gives the model six coding tools: `read`, `write`, `edit`, `bash`, `find`, and `search`. The model uses these to fulfill your requests. `read`, `search`, `write`, and successful `edit` calls emit session-scoped hashline anchors (`[path#TAG]` plus `LINE:text`) so the model can make stale-safe line edits; see [docs/tools.md](docs/tools.md). Add capabilities via [skills](#skills), [prompt templates](#prompt-templates), [extensions](#extensions), or [Atomic packages](#atomic-packages).
 
 **Platform notes:** [Windows](docs/windows.md) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)
 
@@ -543,7 +543,7 @@ cat README.md | atomic -p "Summarize this text"
 | `--no-builtin-tools`, `-nbt` | Disable built-in tools by default but keep extension/custom tools enabled |
 | `--no-tools`, `-nt` | Disable all tools by default |
 
-Default built-in tools: `read`, `bash`, `edit`, `write`, `ask_user_question`, `todo`. Additional built-in read-only tools are available through tool options: `grep`, `find`, `ls`. Use `--exclude-tools` to disable one or more tools while leaving the rest available.
+Default built-in tools: `read`, `bash`, `edit`, `write`, `find`, `search`, `ask_user_question`, `todo`. `find.paths` accepts directories, files, or glob paths such as `*.ts` and honors `timeout`; `search` accepts `pattern`, `paths`, `i`, `gitignore`, and `skip` for regex content-search pagination. `read`/`search`/`write`/`edit` share session-scoped hashline snapshot tags for stale-safe line edits; copied hashline output is stripped by `write` only when it matches a known current-session snapshot. Archive selectors are Bun-native, and internal-resource selectors use the session router when available. Use `--exclude-tools` to disable one or more tools while leaving the rest available.
 
 ### Project Trust Options
 

package/dist/builtin/cursor/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/cursor",
-  "version": "0.9.2",
+  "version": "0.9.3-alpha.1",
   "private": true,
   "description": "Experimental first-party Atomic extension for Cursor OAuth, model discovery, and streaming provider registration.",
   "contributors": [
@@ -40,7 +40,7 @@
     }
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.2",
+    "@bastani/atomic-natives": "0.9.3-alpha.1",
     "@bufbuild/protobuf": "^2.0.0"
   }
 }

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.2",
+  "version": "0.9.3-alpha.1",
   "private": true,
   "description": "Atomic extension providing a private coordination channel between parent and child agent sessions. Fork of: https://github.com/nicobailon/pi-intercom",
   "contributors": [

package/dist/builtin/mcp/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.3-alpha.1] - 2026-06-25
+
+### Fixed
+
+- `unflattenToolArguments` is now schema-aware and no longer corrupts literal dotted top-level argument keys (issue [#1496](https://github.com/bastani-inc/atomic/issues/1496)). Bracket-indexed keys (`ids[0]`, `files[0].path`) are always reconstructed, but a purely dotted key (`filter.name`) is only split into a nested path when the tool's `inputSchema` proves its head segment is an object/array container property **and** the schema does not declare the full dotted key as a literal top-level property. The latter guard preserves a literal property such as `filter.name` verbatim even when the schema also defines a same-head container (e.g. `filter`). The tool `inputSchema` is now threaded through from both the direct-tool and proxy/gateway `callTool` paths. The schema-aware disambiguation is shared with the host runtime via a new canonical `unflattenArgumentsWithSchema` helper in `@bastani/atomic`, so the two paths cannot drift.
+
 ## [0.9.2] - 2026-06-23
 
 ### Changed

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.1",
   "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,17 @@
 
 ## [Unreleased]
 
+## [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