@bastani/atomic 0.9.19-alpha.5 → 0.9.19-alpha.7

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## [Unreleased]
 
+## [0.9.19-alpha.7] - 2026-09-12
+
+### Fixed
+
+- Reduced CPU work in long `/tasks` live transcripts on Windows by reusing unchanged message rendering during streaming, without dropping history or delaying live updates.
+
+## [0.9.19-alpha.6] - 2026-09-11
+
+### Breaking Changes
+
+- `write` no longer silently overwrites a file this session has never seen. Replacing an existing file now requires the session to have already observed exactly the content being replaced, checked under the same per-file mutation queue as the write. A session with no version of its own is refused with `no_prior_observation`; one whose recorded version no longer matches the file on disk is refused with `changed_since_observation` and told which line diverged, what it assumed was there, and what the file holds instead. Both carry the same `FILE_MUTATION_CONFLICT` code and requester identity as an `edit` conflict. Creating a new file, and overwriting one this session read, wrote, or edited, are unaffected ([#2329](https://github.com/bastani-inc/atomic/issues/2329)).
+- `WriteOperations` now requires a `readFile` member, and `writeFile` receives an optional third `WriteFileOptions` argument. `write` reads before every write to refuse generated files, to check that the session has observed what it is replacing, and to decide between creating and overwriting; routing that read through `WriteOperations` is what makes those checks see the filesystem a custom or remote implementation actually writes to, rather than local disk. `readFile` must report absence as `undefined` and reject for anything else, since a path that exists but cannot be read is not a free path. Existing `writeFile` implementations continue to typecheck and may ignore the new options argument, losing only exclusive-create semantics ([#2329](https://github.com/bastani-inc/atomic/issues/2329)).
+- Bundled `code_search` now requires `repoName` in `owner/repo` format alongside `query` and uses DeepWiki MCP for public-repository questions instead of Exa. Add the repository to existing calls. There is no Exa fallback; `web_search` is unchanged, and `maxTokens` remains a best-effort local output bound.
+
+### Changed
+
+- Shell guidance now favors the owner's normal observation budget over routine one-second yields and repeated short polls. Bash and PowerShell share this guidance; explicit budgets, background execution, and execution timeouts are unchanged.
+- Bundled delegation guidance now favors keeping immediately blocking work local and overlapping independent tasks, while preserving specialist and explicitly requested delegation.
+
+### Fixed
+
+- Fixed continuously noisy engines growing interactive diagnostic history without limit. Recent diagnostics retain their order and duplicates without removing normal chat or status messages.
+- Fixed damaged-PDF reads corrupting the fullscreen terminal with MuPDF diagnostics. Bounded diagnostics now appear in the TUI when interactive and use `console.log` otherwise; conversion failures also retain their diagnostic suffix ([#2964](https://github.com/bastani-inc/atomic/issues/2964)).
+- Routed RPC engine stderr through bounded, deferred status messages instead of synchronous filesystem writes or raw terminal output, preserving Unicode characters split across output chunks. Interactive MuPDF and engine diagnostic display neutralizes terminal controls without changing stored diagnostic text. RPC stdout remains JSON-only, and child diagnostics reach the interactive host without changing engine health ([#2964](https://github.com/bastani-inc/atomic/issues/2964)).
+- A rejected `edit` no longer hands back a snapshot tag that authorizes the same edit on retry. Building the rejection recorded the file's current content in the session's snapshot store and reported that tag in the error, so re-sending the identical edit with the reported tag was accepted even though the model had never read the changed file, silently overwriting whatever the other writer had just put there. The rejection now reports the tag without recording it, so the retry is rejected again and the model must re-read first. Drift recovery for tags the session did record is unchanged ([#2329](https://github.com/bastani-inc/atomic/issues/2329)).
+- An `edit` rejected because the file changed after the patch was prepared now reports which line diverged, what the edit assumed was there, what the file holds instead, and how large the target is, instead of a bare "content changed before write". A file deleted in that same window is reported as a missing target rather than a raw filesystem error, and no longer tells the model to re-read a file that is gone. A path that survives but stops being readable, because it was replaced by a directory, locked, or made inaccessible, is now reported as an unreadable target carrying the filesystem error code, instead of escaping as an untyped error. Rejections carry a stable `FILE_MUTATION_CONFLICT` code and the identity of the session, workflow stage, or subagent whose call was refused, so parallel workers editing one file are distinguishable ([#2329](https://github.com/bastani-inc/atomic/issues/2329)).
+- A `write` or hashline `edit` cancelled after its bytes had already reached disk no longer left the change unrecorded, which made the session's own file look like another agent's work on the next overwrite ([#2329](https://github.com/bastani-inc/atomic/issues/2329)).
+- `write` creating a file now claims the path exclusively (`O_EXCL`). A file that appears between `write` observing an absent path and its own write landing is reported as `target_exists`, describing what is there now, instead of being silently truncated ([#2329](https://github.com/bastani-inc/atomic/issues/2329)).
+- Standalone write tools retain their implicit observation store across `local://` writes, so overwriting a file the same tool just created no longer incorrectly fails with `no_prior_observation`.
+- Preserved typed `edit` conflicts when parent-directory permissions change after patch preparation. The rejection retains the original target identity and filesystem error code instead of escaping as a raw permission error ([#2329](https://github.com/bastani-inc/atomic/issues/2329)).
+- Fixed the Gondolin example failing to load after removal of the legacy grep tool API. It now registers only its supported file and shell overrides; the search tool remains on the host, and guest-only content searches use the routed shell ([#2482](https://github.com/bastani-inc/atomic/pull/2482)).
+
 ## [0.9.19-alpha.5] - 2026-09-11
 
 ### Changed

package/README.md

@@ -79,7 +79,7 @@ atomic
 
 Then just talk to Atomic. By default, Atomic gives the model six coding tools: `read`, `write`, `edit`, `bash`, `find`, and `search`. On native Windows, Atomic also enables `powershell` when `pwsh.exe` or `powershell.exe` is available. 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) | [Alpine/musl Linux](docs/index.md#alpine-and-musl-linux-archives) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)
+**Platform notes:** [Windows](docs/windows.md) | [Alpine/musl Linux](docs/getting-started/installation.md#alpine-and-musl-linux-archives) | [Termux (Android)](docs/termux.md) | [tmux](docs/tmux.md) | [Terminal setup](docs/terminal-setup.md) | [Shell aliases](docs/shell-aliases.md)
 
 ---
 
@@ -138,7 +138,7 @@ For each built-in provider, Atomic maintains a list of tool-capable models, upda
 
 See [docs/providers.md](docs/providers.md) for detailed setup instructions.
 
-Atomic's Pi 0.84.1 model/runtime surface includes Claude Opus 5 on Anthropic and Bedrock, model-capability-aware strict JSON-schema and OpenAI Lark/regex tool sampling, ETag-revalidated cached catalogs, persisted llama.cpp models, arbitrary OpenAI-compatible `samplingParams`, opt-in vLLM thinking-token budgets through `compat.supportsThinkingTokenBudget`, and finishless-stream stop inference through `compat.supportsFinishReason`. A populated `ANTHROPIC_AUTH_TOKEN` makes Anthropic models available/selectable while sending header-only bearer auth—with no synthesized API key or `x-api-key`—across chat and summary/compaction requests. Typed RPC model listings expose constrained-sampling flags through optional `ModelInfo.compat`; capability flags are enforcement claims, so unsupported `require` constraints fail instead of being silently weakened. Custom `models.json` is read from the active Atomic agent directory only; it is not merged across `.pi` and `.atomic` paths. See [models](docs/models.md), [providers](docs/providers.md), [RPC](docs/rpc.md#get_available_models), and [extensions](docs/extensions.md#constrained-sampling).
+Atomic's Pi 0.84.1 model/runtime surface includes Claude Opus 5 on Anthropic and Bedrock, model-capability-aware strict JSON-schema and OpenAI Lark/regex tool sampling, ETag-revalidated cached catalogs, persisted llama.cpp models, arbitrary OpenAI-compatible `samplingParams`, opt-in vLLM thinking-token budgets through `compat.supportsThinkingTokenBudget`, and finishless-stream stop inference through `compat.supportsFinishReason`. A populated `ANTHROPIC_AUTH_TOKEN` makes Anthropic models available/selectable while sending header-only bearer auth—with no synthesized API key or `x-api-key`—across chat and summary/compaction requests. Typed RPC model listings expose constrained-sampling flags through optional `ModelInfo.compat`; capability flags are enforcement claims, so unsupported `require` constraints fail instead of being silently weakened. Custom `models.json` is read from the active Atomic agent directory only; it is not merged across `.pi` and `.atomic` paths. See [models](docs/models.md), [providers](docs/providers.md), [RPC](docs/rpc/protocol.md#get_available_models), and [extensions](docs/extensions/authoring.md#constrained-sampling).
 
 **Custom providers & models:** Add providers via the active agent directory's `models.json` (normally `~/.atomic/agent/models.json`; `ATOMIC_CODING_AGENT_DIR`/`PI_CODING_AGENT_DIR` can select another directory) if they speak a supported API (OpenAI, Anthropic, Google). For custom APIs or OAuth, use extensions. See [docs/models.md](docs/models.md) and [docs/custom-provider.md](docs/custom-provider.md).
 

package/dist/builtin/intercom/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to the `pi-intercom` extension will be documented in this fi
 
 ## [Unreleased]
 
+## [0.9.19-alpha.6] - 2026-09-11
+
+### Fixed
+
+- A broker refusal received by an already-registered client now rejects that client's outstanding requests with the broker's own reason instead of being discarded. Previously the refusal was delivered to a listener that `connect()` removes after registration, so pipelined work — notably the session-directory barrier behind workflow route updates — waited out its five-second timer and surfaced `List sessions timeout` or a generic disconnect. Reasons such as `Pending-stage route is not authorized` now reach callers as non-recoverable errors, and the `disconnected` event carries the same cause. Pre-registration rejection, transport-disconnect classification, and explicit shutdown are unchanged.
+
 ## [0.9.19-alpha.4] - 2026-09-10
 
 ### Fixed

package/dist/builtin/intercom/broker/client.ts

@@ -415,7 +415,25 @@ export class IntercomClient extends EventEmitter {
       }
       case "registration_failed": {
         if (typeof brokerMessage.reason !== "string") throw new Error("Invalid registration_failed message");
-        this.emit("_registration_failed", new Error(brokerMessage.reason));
+        const refusal = new Error(brokerMessage.reason);
+        if (this._sessionId === null) {
+          // Still registering: `connect()` owns the failure and its own cleanup.
+          this.emit("_registration_failed", refusal);
+          break;
+        }
+        // The broker reuses this frame to refuse an *established* client's request
+        // (for example a rejected pending-stage route update) and then ends the
+        // socket, deliberately dropping anything already pipelined behind it. By
+        // this point `connect()` has removed its `_registration_failed` listener,
+        // so emitting there would discard the refusal and leave every pipelined
+        // request — notably the `listSessions()` barrier — to expire on its own
+        // five-second timer with an unusable diagnostic. Record the refusal as the
+        // disconnect cause, settle outstanding work with it, and destroy the socket
+        // so no new work is accepted while we wait for the peer FIN. `onClose`
+        // still owns session/socket teardown and the `disconnected` emission.
+        this.disconnectError ??= refusal;
+        this.failPending(this.disconnectError);
+        this.socket?.destroy();
         break;
       }
       case "question_target": {

package/dist/builtin/intercom/index.bundle.mjs

@@ -728,7 +728,14 @@ var init_client = __esm(() => {
         case "registration_failed": {
           if (typeof brokerMessage.reason !== "string")
             throw new Error("Invalid registration_failed message");
-          this.emit("_registration_failed", new Error(brokerMessage.reason));
+          const refusal = new Error(brokerMessage.reason);
+          if (this._sessionId === null) {
+            this.emit("_registration_failed", refusal);
+            break;
+          }
+          this.disconnectError ??= refusal;
+          this.failPending(this.disconnectError);
+          this.socket?.destroy();
           break;
         }
         case "question_target": {

package/dist/builtin/intercom/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/intercom",
-  "version": "0.9.19-alpha.5",
+  "version": "0.9.19-alpha.7",
   "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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/mcp",
-  "version": "0.9.19-alpha.5",
+  "version": "0.9.19-alpha.7",
   "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/subagents/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## [Unreleased]
 
+## [0.9.19-alpha.6] - 2026-09-11
+
+### Changed
+
+- Delegation guidance now favors keeping immediately blocking work local unless specialist expertise, context isolation, or an explicit request warrants a child. Parents are guided to continue independent work and wait on dependencies rather than repeatedly polling. Background launch defaults and explicit foreground waits are unchanged.
+
 ## [0.9.19-alpha.5] - 2026-09-11
 
 ### Changed

package/dist/builtin/subagents/README.md

@@ -176,10 +176,12 @@ Show me the current subagent status.
 
 The agent can choose a mode for each authorized call without asking you merely to select an execution mode:
 
+Keep immediately blocking work local unless specialist expertise, context isolation, or an explicit delegation request makes a child worthwhile. Continue independent work after spawning without duplicating the child's task. Wait when its result becomes a dependency; otherwise rely on completion notices rather than repeated short waits or status polls.
+
 ```ts
 subagent({ agent: "codebase-analyzer", task: "Trace authentication.", wait: { kind: "background" } })
 subagent({ agent: "codebase-analyzer", task: "Trace authentication.", wait: { kind: "foreground", budgetMs: 30000 } })
-subagent({ action: "wait", id: taskId, budgetMs: 1000 })
+subagent({ action: "wait", id: taskId })
 subagent({ action: "status", id: taskId })
 subagent({ action: "kill", id: taskId })
 ```

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

@@ -28,7 +28,7 @@ You research current technical information from authoritative external sources:
 
 Check `research/web/` for a recent cached copy first; fetch only when it is missing or stale. Reuse repositories already under `/tmp/atomic-github-repos/`, and persist reusable high-value fetches to `research/web/`.
 
-For static pages, use the least expensive route that succeeds: `fetch_content <url>`; then the site's `/llms.txt`; then `bash` with `curl <url> -H "Accept: text/markdown"` (inspect `content-type: text/markdown` and `x-markdown-tokens`); then `playwright-cli`. Start with the authoritative source rather than broad search when it is known.
+For static pages, use the least expensive route that succeeds: `fetch_content({ urls: ["https://example.com"] })`; then the site's `/llms.txt`; then `bash` with `curl <url> -H "Accept: text/markdown"` (inspect `content-type: text/markdown` and `x-markdown-tokens`); then `playwright-cli`. Start with the authoritative source rather than broad search when it is known.
 
 Batch independent calls in one turn to reduce round-trips. `fetch_content({ urls: [...] })` fetches three URLs concurrently; independent git/gh commands may use `&` plus `wait`. Tool calls otherwise execute sequentially.
 
@@ -44,7 +44,7 @@ Choose the route that matches the question:
 - **Technical solutions:** search exact errors and terms, official issues/discussions, Stack Overflow or technical forums, and comparable implementations.
 - **Comparisons:** use migration guides, benchmarks, performance evidence, and explicit decision criteria or matrices.
 
-For source repositories, prefer raw GitHub URLs over HTML when reading a known file. For version-specific questions, clone the tagged version with `fetch_content("https://github.com/<owner>/<repo>/tree/v1.0.0")`; resolve a tag SHA with `gh api repos/<owner>/<repo>/git/refs/tags/v1.0.0 --jq '.object.sha'` when needed.
+For source repositories, prefer raw GitHub URLs over HTML when reading a known file. For version-specific questions, clone the tagged version with `fetch_content({ urls: ["https://github.com/<owner>/<repo>/tree/v1.0.0"] })`; resolve a tag SHA with `gh api repos/<owner>/<repo>/git/refs/tags/v1.0.0 --jq '.object.sha'` when needed.
 
 ## Video evidence
 
@@ -53,11 +53,11 @@ For source repositories, prefer raw GitHub URLs over HTML when reading a known f
 Examples of distinct calls:
 
 ```typescript
-fetch_content({ url: "https://youtube.com/watch?v=abc", prompt: "What libraries are imported?" })
-fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41" })
-fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41-25:00", frames: 3 })
-fetch_content({ url: "https://youtube.com/watch?v=abc", frames: 6 })
-fetch_content({ url: "/path/to/demo.mp4", prompt: "What error appears?" })
+fetch_content({ urls: ["https://youtube.com/watch?v=abc"], prompt: "What libraries are imported?" })
+fetch_content({ urls: ["https://youtube.com/watch?v=abc"], timestamp: "23:41" })
+fetch_content({ urls: ["https://youtube.com/watch?v=abc"], timestamp: "23:41-25:00", frames: 3 })
+fetch_content({ urls: ["https://youtube.com/watch?v=abc"], frames: 6 })
+fetch_content({ urls: ["/path/to/demo.mp4"], prompt: "What error appears?" })
 fetch_content({ urls: ["https://youtube.com/watch?v=abc", "https://youtube.com/watch?v=def"], prompt: "What packages are installed?" })
 ```
 

package/dist/builtin/subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/subagents",
-  "version": "0.9.19-alpha.5",
+  "version": "0.9.19-alpha.7",
   "private": true,
   "description": "Atomic extension for delegating tasks to subagents with parallel execution. Fork of: https://github.com/nicobailon/pi-subagents",
   "contributors": [

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

@@ -209,9 +209,11 @@ Concurrent writers conflict. `code-simplifier` and `debugger` change files. Do n
 
 ### Foreground, background, and automatic yielding
 
+Keep immediately blocking work local unless specialist expertise, context isolation, or an explicit user request justifies delegation. Prefer independent tasks you can overlap with useful parent work. Do not spawn a child merely to wait immediately, or duplicate its assigned work while it runs.
+
 Choose the observation mode for each authorized task. No extra user confirmation is needed merely to choose foreground or background. In owner-bound main and workflow-stage sessions, omitted `wait` or `wait: { kind: "background" }` returns after admission. Use `wait: { kind: "foreground", budgetMs: 30000 }` when the result is needed next. If the observation budget expires, the same child keeps running in the background; do not relaunch it. This applies to single and parallel calls.
 
-Use `subagent({ action: "wait", id: taskId, budgetMs: 1000 })` to observe an existing task, `status` to inspect its state, or `kill` to terminally stop it. A yielded receipt is not a terminal result. Background counts stay below the prompt; `/tasks` opens inspection only on command. A shaded completion notification reaches the owning chat without requiring a model reply. A later wait does not extend the owner's lifetime.
+Use `subagent({ action: "wait", id: taskId })` to observe an existing task with the owner's budget, `status` to inspect its state, or `kill` to terminally stop it. Wait when the result becomes a dependency; otherwise rely on completion notices. Avoid repeated short waits or status polls; override the budget only for a concrete responsiveness need. A yielded receipt is not a terminal result. Background counts stay below the prompt; `/tasks` opens inspection only on command. A shaded completion notification reaches the owning chat without requiring a model reply. A later wait does not extend the owner's lifetime.
 
 Intercom `ask` cannot revive a completed, failed, interrupted, or cancelled noninteractive child, even if its retained registration says `idle`. New asks fail immediately, and termination fails an already-admitted ask that has not received a reply. Use a fresh child for follow-up work. Live interactive idle sessions and workflow post-mortem conversations remain separate reply-capable cases; `send` transport behavior is unchanged.
 

package/dist/builtin/subagents/src/extension/index.bundle.mjs

@@ -17148,9 +17148,10 @@ var DEFAULT_PROMPT_GUIDANCE = [
   - Explicit requests such as "quickly", "inline", "do this directly", or "don't use a workflow", and equivalent wording, override that default even for complex tasks. Treat "quickly" as an inline execution choice, not a request for a faster workflow. Do not create or launch a hidden/nested workflow or pressure the user to reapprove the choice. Preserve appropriate testing, review and evidence inline, and unrelated safety and authorization constraints. Apply the preference only to the specified task. Quoted examples and questions about inline code are not execution-mode instructions; neither are descriptions of software that should run quickly.
   - On a switch from an active workflow to inline, notify the controlling session to safely hold/stop the affected run, reconcile completed work and in-flight side effects, then continue inline without duplicate execution. Do not claim completed work was undone.
   - Use a single subagent for a focused specialty or parallel tasks for independent work. Keep substantial-overlap tasks together rather than duplicating investigation across agents.
-  - Delegate noisy or context-heavy command investigation when isolation helps, but run concise commands inline when that is simpler.
+  - Keep immediately blocking work local unless specialist expertise, context isolation, or an explicit user request justifies delegation. Delegate independent work that can usefully overlap your own next steps; do not spawn a child merely to wait immediately. Delegate noisy or context-heavy command investigation when isolation helps, but run concise commands inline when that is simpler.
   - Background subagents are supported in owner-bound sessions: omitted wait or wait:{kind:"background"} yields after admission while the child continues. Use wait:{kind:"foreground",budgetMs:30000} for foreground-first observation. A yielded observation never means the task stopped. Do not duplicate delegated work; observe the existing task or await its completion notice. The UI shows compact status below the prompt, and /tasks opens inspection only when invoked.
   - Choose foreground-first or background observation for each authorized call based on whether the next action needs the result; do not ask the user merely to select a mode. Foreground observation automatically yields on budget expiry while the same task continues. Wait for terminal completion before starting dependent work. Execution mode does not bypass tool permissions, delegation boundaries, or owner lifetime.
+  - Continue useful independent work after spawning without duplicating the child's task. Wait when its result becomes a dependency; otherwise rely on completion notices. Avoid repeated short waits or status polls. Omit the wait budget to use owner policy unless a concrete responsiveness need calls for an override.
   - Use the debugger subagent for actual failures that need reproduction, root-cause diagnosis, and a validated fix; additional debugger or research delegates are optional when they add a distinct useful angle.
   - Let each named agent use its declared model and fallback policy: omit the explicit model argument unless the user requests an exact model or a documented task requirement needs one, and record the reason for any override before launch. Do not choose an ad hoc model merely for diversity.
   - If an agent has no declared model or fallback policy, consult packages/coding-agent/docs/models/model-selection.md for the role's Pareto-efficient recommendations and packages/coding-agent/docs/models/evals.md for the measured per-evaluation scores by task type, then use workflow({ action: "models" }) when available to inspect the configured catalog. Pin only a returned fullId and only append a thinking level listed for that entry. If the catalog tool is unavailable, the catalog is empty, or no recommended model is present, leave the child unpinned and state the limitation rather than inventing a model. Do not inspect credentials or infer why a model is absent.

package/dist/builtin/web-access/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [0.9.19-alpha.7] - 2026-09-12
+
+### Fixed
+
+- `fetch_content` now shows each URL's error and recovery steps when an entire batch fails, instead of hiding the causes behind a generic failure count. Retained partial content is shown as incomplete excerpts rather than incorrectly reported as absent.
+
+## [0.9.19-alpha.6] - 2026-09-11
+
+### Breaking Changes
+
+- `fetch_content` now requires a nonempty `urls` array of nonempty strings for both single and batch requests. Replace `{ url: "..." }` with `{ urls: ["..."] }`. Invalid argument shapes and unrecognized fields are rejected before fetching; the `get_search_content` selectors are unchanged.
+- `code_search` now requires a single `repoName` in `owner/repo` format alongside `query`. It asks DeepWiki about that public GitHub repository instead of searching Exa, with no Exa fallback. Update query-only calls to include the repository. No API key is required; `maxTokens` remains a best-effort local output bound. Unrelated `web_search` providers are unchanged.
+
 ## [0.9.14] - 2026-08-19
 
 Cumulative release of the `0.9.14-alpha.3` – `0.9.14-alpha.4` prereleases. The summary below covers the user-visible outcome of that work; the per-change detail remains in the prerelease sections below.

package/dist/builtin/web-access/README.md

@@ -18,7 +18,7 @@ https://github.com/user-attachments/assets/cac6a17a-1eeb-4dde-9818-cdf85d8ea98f
 
 **Video Understanding** — Point it at a YouTube video or local screen recording and ask questions about what's on screen. Full transcripts, visual descriptions, and frame extraction at exact timestamps.
 
-**Smart Fallbacks** — Every capability has a fallback chain. Search tries Exa, then Perplexity, then Gemini API, then Gemini Web when browser cookies are enabled. YouTube tries Gemini Web when enabled, then API, then Perplexity. Blocked pages retry through Jina Reader and Gemini extraction. Something always works.
+**Smart Fallbacks** — Web search tries Exa, then Perplexity, then Gemini API, then Gemini Web when browser cookies are enabled. YouTube tries Gemini Web when enabled, then API, then Perplexity. Blocked pages retry through Jina Reader and Gemini extraction. Repository-specific `code_search` uses DeepWiki only.
 
 **GitHub Cloning** — GitHub URLs are cloned locally instead of scraped. The agent gets real file contents and a local path to explore, not rendered HTML.
 
@@ -58,16 +58,16 @@ Requires Pi v0.37.3+.
 web_search({ query: "TypeScript best practices 2025" })
 
 // Fetch a page
-fetch_content({ url: "https://docs.example.com/guide" })
+fetch_content({ urls: ["https://docs.example.com/guide"] })
 
 // Clone a GitHub repo
-fetch_content({ url: "https://github.com/owner/repo" })
+fetch_content({ urls: ["https://github.com/owner/repo"] })
 
 // Understand a YouTube video
-fetch_content({ url: "https://youtube.com/watch?v=abc", prompt: "What libraries are shown?" })
+fetch_content({ urls: ["https://youtube.com/watch?v=abc"], prompt: "What libraries are shown?" })
 
 // Analyze a screen recording
-fetch_content({ url: "/path/to/recording.mp4", prompt: "What error appears on screen?" })
+fetch_content({ urls: ["/path/to/recording.mp4"], prompt: "What error appears on screen?" })
 ```
 
 ## Tools
@@ -100,34 +100,41 @@ web_search({ query: "...", includeContent: true })
 
 ### code_search
 
-Search for code examples, documentation, and API references via Exa MCP. No API key required. Uses Exa's code-context MCP tool when available and falls back to code-focused web search when that tool is unavailable.
+Ask questions about code, architecture, and APIs in a public GitHub repository via DeepWiki MCP at `https://mcp.deepwiki.com/mcp`. No API key or local MCP configuration is required. DeepWiki availability and repository indexing determine which questions it can answer.
 
 ```typescript
-code_search({ query: "React useEffect cleanup pattern" })
-code_search({ query: "Express middleware error handling", maxTokens: 10000 })
+code_search({ repoName: "facebook/react", query: "How does useEffect cleanup work?" })
+code_search({ repoName: "expressjs/express", query: "How is middleware error handling implemented?", maxTokens: 10000 })
 ```
 
 | Parameter | Description |
 |-----------|-------------|
-| `query` | Programming question, API, library, or debugging topic |
-| `maxTokens` | Maximum tokens of context to return (default: 5000, max: 50000) |
+| `repoName` | Required single public GitHub repository in `owner/repo` format, not a URL or list |
+| `query` | Required nonempty question about that repository, sent verbatim |
+| `maxTokens` | Optional best-effort output bound, approximately four characters per token, plus a truncation notice (default: 5000, range: 1000–50000) |
+
+Migration: existing `code_search({ query: ... })` calls must now include `repoName`. The query is sent as DeepWiki's `ask_question` question. `maxTokens` limits the returned text locally, not DeepWiki's generation. Requests have a 60-second deadline and honor caller cancellation. Errors and empty responses are reported without falling back to Exa. Use `web_search` for broader discovery or when a repository is unavailable; its providers and settings are unchanged.
 
 ### fetch_content
 
 Fetch URL(s) and extract readable content as markdown. Automatically detects and handles GitHub repos, YouTube videos, PDFs, local video files, and regular web pages.
 
+Use the lowercase `urls` field with a nonempty array of strings, even for one URL. Replace legacy `{ url: "..." }` calls with `{ urls: ["..."] }`. Missing targets, empty arrays, empty strings, object entries, and unrecognized fields are rejected before fetching. Atomic's standard argument normalization can convert a scalar `urls` string into a one-item array, but prompts and integrations should always send the documented array form.
+
+See [Atomic's fetch argument guide](../coding-agent/docs/web-access.md) for examples and validation troubleshooting.
+
 ```typescript
-fetch_content({ url: "https://example.com/article" })
-fetch_content({ urls: ["url1", "url2", "url3"] })
-fetch_content({ url: "https://github.com/owner/repo" })
-fetch_content({ url: "https://youtube.com/watch?v=abc", prompt: "What libraries are shown?" })
-fetch_content({ url: "/path/to/recording.mp4", prompt: "What error appears on screen?" })
-fetch_content({ url: "https://youtube.com/watch?v=abc", timestamp: "23:41-25:00", frames: 4 })
+fetch_content({ urls: ["https://example.com/article"] })
+fetch_content({ urls: ["https://example.com/one", "https://example.com/two"] })
+fetch_content({ urls: ["https://github.com/owner/repo"] })
+fetch_content({ urls: ["https://youtube.com/watch?v=abc"], prompt: "What libraries are shown?" })
+fetch_content({ urls: ["/path/to/recording.mp4"], prompt: "What error appears on screen?" })
+fetch_content({ urls: ["https://youtube.com/watch?v=abc"], timestamp: "23:41-25:00", frames: 4 })
 ```
 
 | Parameter | Description |
 |-----------|-------------|
-| `url` / `urls` | Single URL/path or multiple URLs |
+| `urls` | Required nonempty array of URL/path strings, including for a single target |
 | `prompt` | Question to ask about a YouTube video or local video file |
 | `timestamp` | Extract frame(s) — single (`"23:41"`), range (`"23:41-25:00"`), or seconds (`"85"`) |
 | `frames` | Number of frames to extract (max 12) |
@@ -168,11 +175,11 @@ Fallback: Gemini API (Files API upload) → Gemini Web when browser cookies are
 Use `timestamp` and/or `frames` on any YouTube URL or local video file to extract visual frames as images.
 
 ```typescript
-fetch_content({ url: "...", timestamp: "23:41" })                       // single frame
-fetch_content({ url: "...", timestamp: "23:41-25:00" })                 // range, 6 frames
-fetch_content({ url: "...", timestamp: "23:41-25:00", frames: 3 })      // range, custom count
-fetch_content({ url: "...", timestamp: "23:41", frames: 5 })            // 5 frames at 5s intervals
-fetch_content({ url: "...", frames: 6 })                                // sample whole video
+fetch_content({ urls: ["..."], timestamp: "23:41" })                   // single frame
+fetch_content({ urls: ["..."], timestamp: "23:41-25:00" })             // range, 6 frames
+fetch_content({ urls: ["..."], timestamp: "23:41-25:00", frames: 3 })  // range, custom count
+fetch_content({ urls: ["..."], timestamp: "23:41", frames: 5 })        // 5 frames at 5s intervals
+fetch_content({ urls: ["..."], frames: 6 })                            // sample whole video
 ```
 
 Requires `ffmpeg` (and `yt-dlp` for YouTube). Timestamps accept `H:MM:SS`, `MM:SS`, or bare seconds.
@@ -191,7 +198,7 @@ When Readability fails or returns only a cookie notice, the extension retries vi
 web_search(query)
   → Exa (direct API with key, MCP without) → Perplexity → Gemini API → Gemini Web (if browser cookies enabled)
 
-fetch_content(url)
+fetch_content({ urls: [url] })
   → Video file?  Gemini API (Files API) → Gemini Web (if browser cookies enabled)
   → GitHub URL?  Clone repo, return file contents + local path
   → YouTube URL? Gemini Web (if browser cookies enabled) → Gemini API → Perplexity
@@ -324,7 +331,7 @@ Rate limits: Perplexity is capped at 10 requests/minute (client-side). Content f
 | `curator-server.ts` | Ephemeral HTTP server with SSE streaming and state machine |
 | `summary-review.ts` | Summary prompt construction, model-based draft generation, and deterministic fallback summary |
 | `exa.ts` | Exa.ai search provider — direct API and MCP proxy, budget tracking |
-| `code-search.ts` | Code/docs search via Exa MCP |
+| `code-search.ts` | Repository questions via DeepWiki MCP |
 | `extract.ts` | URL/file path routing, HTTP extraction, fallback orchestration |
 | `gemini-search.ts` | Search routing across Exa, Perplexity, Gemini API, Gemini Web |
 | `gemini-url-context.ts` | Gemini URL Context + Web extraction fallbacks |