@bastani/atomic 0.9.43 → 0.9.44-alpha.2

package/docs/settings.md

@@ -412,7 +412,7 @@ Older settings with a boolean `websockets` value are migrated to `transport`: `t
 |---------|------|---------|-------------|
 | `terminal.showImages` | boolean | `true` | Show images in terminal (if supported) |
 | `terminal.imageWidthCells` | number | `60` | Preferred inline image width in terminal cells |
-| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker) |
+| `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker). When unset, `ATOMIC_CLEAR_ON_SHRINK=1` enables it |
 | `terminal.showTerminalProgress` | boolean | `false` | Show OSC 9;4 progress indicators in the terminal tab bar |
 | `images.autoResize` | boolean | `true` | Resize oversized images to a 2000x2000 maximum. Applies to `@file` attachments, `read`, and images returned by tools |
 | `images.blockImages` | boolean | `false` | Block all images from being sent to LLM |
@@ -604,7 +604,7 @@ Local worker pools are disabled unless `workflows.localWorkers` is set. With the
 
 `startupTimeoutMs` is how long, in milliseconds, each worker process may take to become ready. It defaults to `30000`. The pool runs children once any worker is ready and fails only when no worker starts. This value is not saved with the root, so changing it does not block a resume. Each worker's standard error is written to `worker-logs/<root run ID>/<worker ID>.log` in the workflow journal's directory, and worker failure messages name that file. See [Worker startup and failures](/workflows/operations#worker-startup-and-failures).
 
-`leaseMs` is how long, in milliseconds, a worker that is still running but has stopped responding keeps its child before the child is replayed on another worker. It defaults to `30000` and must be at least `2000`. A worker that exits is replaced immediately, and a worker that is still responding keeps its child even when the root itself is briefly too busy to process its heartbeats. Like `startupTimeoutMs`, this value is not saved with the root.
+`leaseMs` is how long, in milliseconds, a worker that is still running but has stopped responding keeps its child before the child is replayed on another worker. It defaults to `30000` and must be at least `2000`. A worker that exits is replaced immediately, and a worker that is still responding keeps its child even when the pool is briefly too busy to process its heartbeats. Like `startupTimeoutMs`, this value is not saved with the root.
 
 `limits` caps agent sessions and managed tool processes for one root. Session permits cover creation through disposal, including fallback and delegated sessions. Process permits last until confirmed cleanup; yielding an observation wait does not free one. Processes outside Atomic's managed tools are not counted. `host` load and memory thresholds gate launches but do not impose hard OS limits.
 

package/docs/skills.md

@@ -117,9 +117,9 @@ Offline, `qlty metrics` and `qlty smells` still work through built-in static ana
 
 Load `/skill:agent-browser` first for anything it covers: websites and web apps in Chrome/Chromium, Mobile Safari in the iOS Simulator (`agent-browser -p ios`), Electron and other apps that expose a CDP port, Slack, and cloud browsers. Its text snapshots cost far fewer tokens than screenshot-driven CUA. For everything else, including native desktop apps, native iOS apps in the Simulator, Android emulators, OS dialogs, and desktop Safari or other non-Chromium browsers, load `/skill:cua-driver` and drive the exact window with one-shot `cua-driver call <tool>` commands; when a custom workflow's TypeScript owns the scenario, use the `@trycua/cua-driver` SDK inside `ctx.tool` instead. See [what agent-browser covers](/computer-use#what-agent-browser-covers) for the full split, and [Computer use](/computer-use#desktop-automation-with-cua-driver) for installing the Cua Driver executable, turning telemetry off, readiness, and permissions. For terminal automation/testing, prefer `/skill:herdr` on macOS, Linux and Windows. Install Herdr if missing when network access and permissions permit; fall back to `/skill:tmux` or native Windows psmux when installation or use is not possible. Preserve the upstream skill's explicit-request and managed-pane requirements. These are separate interfaces, not interchangeable command names. See [verification and desktop safety](/workflows/verification) for installation, permissions, dedicated sessions and evidence.
 
-The bundled [Cua Driver skill](https://github.com/trycua/cua/tree/cua-driver-rs-v0.36.0/libs/cua-driver/rust/Skills/cua-driver) is upstream's `libs/cua-driver/rust/Skills/cua-driver` at tag `cua-driver-rs-v0.36.0`, vendored verbatim with all three platform guides (`MACOS.md`, `WINDOWS.md`, `LINUX.md`) plus `WORKFLOW.md`, `RUNTIME.md`, `VISUAL.md`, `BROWSER.md`, `RECORDING.md`, and `EMBEDDING.md`; only the `SKILL.md` frontmatter is Atomic-owned. MIT licensed, © 2025 Cua AI, Inc. Its core guide routes to focused references for authorization, exact targets, observation, and outcome verification. It does not install the `cua-driver` executable, grant permissions, or turn telemetry off, and Atomic never runs `cua-driver skills install`. Chromium browsers, Mobile Safari, and CDP-exposing apps stay with `agent-browser` even though the vendored `BROWSER.md` describes upstream's browser route; that route applies only to browsers agent-browser cannot reach, such as desktop Safari or Firefox.
+The bundled [Cua Driver skill](https://github.com/trycua/cua/tree/cua-driver-rs-v0.38.0/libs/cua-driver/rust/Skills/cua-driver) is upstream's `libs/cua-driver/rust/Skills/cua-driver` at tag `cua-driver-rs-v0.38.0`, vendored with all three platform guides (`MACOS.md`, `WINDOWS.md`, `LINUX.md`) plus `WORKFLOW.md`, `RUNTIME.md`, `VISUAL.md`, `BROWSER.md`, `RECORDING.md`, and `EMBEDDING.md`; Atomic owns the `SKILL.md` frontmatter and adapts the macOS permission-approval guidance described below. MIT licensed, © 2025 Cua AI, Inc. Its core guide routes to focused references for authorization, exact targets, observation, and outcome verification. It does not install the `cua-driver` executable or turn telemetry off, and Atomic never runs `cua-driver skills install`. Other permission prompts stay with you. The one exception, on by default: the agent approves Cua Driver's own macOS Accessibility and Screen Recording prompts itself over the host's VNC or Screen Sharing when credentials for it are available, and reports each approval. It never approves any other permission or another app's dialog. Set `ATOMIC_CUA_AUTO_APPROVE=0` to turn this off and have the agent ask you instead. Chromium browsers, Mobile Safari, and CDP-exposing apps stay with `agent-browser` even though the vendored `BROWSER.md` describes upstream's browser route; that route applies only to browsers agent-browser cannot reach, such as desktop Safari or Firefox.
 
-The bundled [Herdr skill](https://github.com/herdrdev/herdr/blob/v0.9.0/skills/herdr/SKILL.md) requires an explicit Herdr mention or request and `HERDR_ENV=1`; it stops outside a Herdr-managed pane. It does not install Herdr or authorize control of unrelated panes. Use returned pane IDs, and check completion separately from command submission.
+The bundled [Herdr skill](https://github.com/herdrdev/herdr/blob/v0.9.5/skills/herdr/SKILL.md) requires an explicit Herdr mention or request and `HERDR_ENV=1`; it stops outside a Herdr-managed pane. It does not install Herdr or authorize control of unrelated panes. Use returned pane IDs, and check completion separately from command submission.
 
 ### Report feedback
 

package/docs/subagents.md

@@ -98,7 +98,15 @@ In a parallel run, `intercom.ask`, `contact_supervisor({ reason: "need_decision"
 
 `intercom.send` and `contact_supervisor` progress updates return after delivery without waiting for a reply. An exact-child Intercom handshake can release the parallel call's foreground observations so the supervisor can handle the message. This is not execution cancellation: active siblings keep running, queued siblings start once capacity is available, and worktrees stay owned until their children exit. Background calls use the same communication path without needing to release an observation.
 
-To update a working child, use ordinary Intercom `send` or `ask` with its exact connected name or full session ID from `intercom list`. An admitted child registers with Intercom when its session starts, so it is listed and reachable while it works even if it never calls Intercom itself. Foreground and background children treat it as a priority interrupt: the child's current model call or cancellable tool is cancelled and the message is handled next in the same child execution, without relaunching its task or repeating the original prompt. Tools that ignore cancellation finish first, and completed side effects are kept. Multiple updates stay in arrival order. A reply to an incoming ask uses ordinary `intercom.reply`; this does not change the single-child parent-targeted handoff described below.
+To update a working child, use ordinary Intercom `send` or `ask` with its exact connected name or full session ID from `intercom list`. An admitted child registers with Intercom when its session starts, so it is listed and reachable while it works even if it never calls Intercom itself. Foreground and background children handle it in the same child execution, without relaunching the task or repeating the original prompt, according to the sender's `delivery` option. Messages from sibling children, the supervisor, and you all work the same way:
+
+| `delivery` | When a busy recipient gets it | Use it for |
+|---|---|---|
+| `"steer"` (default) | After its current tool calls finish. Its work is never cancelled. | Ordinary coordination, findings, and updates |
+| `"followUp"` | Only after it finishes and stops | Low-priority notes, or anything meant for "after you're done" |
+| `"interrupt"` | Immediately. Its current model call or cancellable tool call is cancelled, then the message is handled next. | An urgent correction or a stop order |
+
+The sender chooses `delivery` for each message; override the default by urgency. It applies to every sender, including peers, the supervisor, and you. With `"interrupt"`, tools that ignore cancellation finish first, and completed side effects are kept. Multiple updates stay in arrival order. A reply to an incoming ask uses ordinary `intercom.reply`; this does not change the single-child parent-targeted handoff described below.
 
 [Run control](#run-control) (`pause`, `quit`) stops only the selected child, and it stays resumable. Explicit batch cancellation and workflow-stage closure stop the intended owned children for good, including pending reply waits. Closing or switching away from a session also stops its children, but they stay resumable, as described next. A late or duplicate reply cannot revive a terminal child. Ordinary Intercom group restrictions and the authorized cross-group `contact_supervisor` route are unchanged.
 
@@ -108,9 +116,38 @@ Completed, failed, interrupted, and cancelled noninteractive children cannot ans
 
 ### Peer coordination
 
-Children do not have to route everything through the supervisor. Children launched in one parallel set, or with the same explicit `group`, share an Intercom group, and children launched by a workflow stage inherit that stage's invocation group. A child can run `intercom({ action: "list" })` to see live siblings and use ordinary `send` or `ask` with them directly: a locator hands file paths to the analyzer, two writers agree who owns which files or who runs the shared test suite, a debugger reuses a sibling's verified reproduction, or one reviewer challenges another's finding with evidence before each returns its own verdict. `contact_supervisor` stays reserved for supervisor decisions, and ordinary Intercom group restrictions still apply.
+Peer-to-peer (swarm) coordination is the default. There are no limits on communication between agents; it is encouraged whenever you need to. The supervisor is not a message relay: relaying adds latency, loses detail, and fills the supervisor's context, while children that talk directly converge faster. Children launched in one parallel set, or with the same explicit `group`, share an Intercom group, and children launched by a workflow stage inherit that stage's invocation group. A child can run `intercom({ action: "list" })` to see live siblings and use ordinary `send` or `ask` with them directly: a locator hands file paths to the analyzer, two writers agree who owns which files or who runs the shared test suite, a debugger reuses a sibling's verified reproduction, or one reviewer challenges another's finding with evidence before each returns its own verdict. `contact_supervisor` stays reserved for supervisor decisions, and ordinary Intercom group restrictions still apply.
+
+Children coordinate spontaneously: they discover peers with `list`, broadcast findings, claim shared files or expensive steps, ask and answer each other, hand work along a chain, and debate as much as is useful, then each returns its own complete result rather than deferring to a sibling. Explicit user approval gates and authorization for destructive or external actions still apply. Peer asks and one blocking supervisor request can wait concurrently in the same child; mutual asks work as long as both children process inbound work. The `intercom` skill (`/skill:intercom`) has copy-paste peer patterns.
+
+For example, three reviewers launched as one parallel set work as a swarm, and the parent reads their three final results:
+
+```typescript
+const peerRules =
+  "Your siblings review the same diff. Run intercom list to find them, share every confirmed finding, " +
+  "ask them whatever you need, and debate disagreements with evidence. Then return your own structured verdict.";
+
+subagent({
+  tasks: [
+    { agent: "reviewer", task: `Review correctness of the auth changes. ${peerRules}` },
+    { agent: "reviewer", task: `Review security of the auth changes. ${peerRules}` },
+    { agent: "reviewer", task: `Review test coverage of the auth changes. ${peerRules}` },
+  ],
+});
+```
+
+### Scaling a swarm
+
+Swarm size scales with the task. For very complex work, or when you ask for heavy parallelism, the agent can run hundreds or thousands of agents. They organize themselves into teams and coordinate peer-to-peer, like an organization, and useful behavior emerges from their exchanges rather than from one central plan.
+
+These are the limits that apply:
+
+- **Children per parallel set.** One set holds up to `parallel.maxTasks` children (default 1000, no hard cap). `parallel.concurrency` and `parallel.runningCapacity` (each default 1000) bound how many run at once per parent. For more than 1000, raise all three, as shown in [Context and execution modes](#context-and-execution-modes).
+- **Nesting.** Subagent delegation is one level deep and cannot be configured: a child cannot call `subagent`. To nest teams, start them from workflow stages. Each stage can launch its own parallel set, and `ctx.workflow(...)` nests child workflows up to the workflow `maxDepth` (default 3, configurable).
+- **Workflow fan-out.** `ctx.parallel(...)` has no task-count limit. The workflow `defaultConcurrency` setting (default 1000) or a per-call `concurrency` bounds how many stages run at once. Set `workflows.localWorkers` to run first-level child workflows in a pool of worker processes. See [Workflow configuration](/workflows/operations#workflow-configuration) and [Local workflow workers](/workflows/operations#local-workflow-workers).
+- **Teams.** Intercom groups have no member limit. Give each team its own `group` so its members coordinate internally. Team members reach their lead with `contact_supervisor`, the lead steers them, and the leads, as stages of one workflow, talk to each other in the invocation group.
 
-Peers do not coordinate spontaneously. When related work runs in parallel, name the peers and the expected exchange in each task prompt, keep it bounded, and require each child to return its own complete result rather than deferring to a sibling. Scope, product, and architecture decisions still go to the supervisor. Peer asks and one blocking supervisor request can wait concurrently in the same child; mutual asks work as long as both children process inbound work. The `intercom` skill (`/skill:intercom`) has copy-paste peer patterns.
+For example, 20 parallel workflow stages that each launch 50 children form a swarm of 1,000 agents. The workflow and subagent defaults already run them all at once: up to 1000 stages and 1000 running children per parent. Lower `defaultConcurrency` or a per-call `concurrency` to run fewer stages at a time. Beyond these settings, the practical ceiling is your provider rate limits, machine memory, and any workflow admission limits you set.
 
 ### Single-child handoff
 
@@ -289,18 +326,18 @@ Fresh children inherit the invoking session's SDK configuration, resource-discov
 
 Top-level parallel calls apply these settings from `~/.atomic/agent/extensions/subagent/config.json` after expanding each task's optional `count`:
 
-- `parallel.maxTasks` defaults to 50 and limits the number of tasks in a parallel set. There is no hard upper cap; raise or lower it as needed.
-- `parallel.concurrency` defaults to 3 and limits how many children are dispatched at once. Per-call `concurrency` takes precedence.
-- `parallel.runningCapacity` defaults to 4 and limits simultaneously running child turns per parent.
+- `parallel.maxTasks` defaults to 1000 and limits the number of tasks in a parallel set. There is no hard upper cap; raise or lower it as needed.
+- `parallel.concurrency` defaults to 1000 and limits how many children are dispatched at once. Per-call `concurrency` takes precedence.
+- `parallel.runningCapacity` defaults to 1000 and limits simultaneously running child turns per parent.
 
-To run up to 100 children at once, raise both concurrency and running capacity as well as the task limit:
+To run more than 1000 children at once, raise concurrency and running capacity as well as the task limit:
 
 ```json
 {
   "parallel": {
-    "maxTasks": 100,
-    "concurrency": 100,
-    "runningCapacity": 100
+    "maxTasks": 2000,
+    "concurrency": 2000,
+    "runningCapacity": 2000
   }
 }
 ```

package/docs/workflows/api-reference.md

@@ -802,7 +802,7 @@ readonly concurrency?: number;
 readonly failFast?: boolean;
 ```
 
-`WorkflowParallelOptions` uses `concurrency` to bound active tasks in an authored `ctx.parallel(...)`. When omitted, the runtime uses the workflow's `defaultConcurrency` setting, which defaults to `3`; explicit configuration and per-call concurrency remain honored. Parallel execution is fail-fast unless `failFast` is explicitly `false`.
+`WorkflowParallelOptions` uses `concurrency` to bound active tasks in an authored `ctx.parallel(...)`. When omitted, the runtime uses the workflow's `defaultConcurrency` setting, which defaults to `1000`; explicit configuration and per-call concurrency remain honored. Parallel execution is fail-fast unless `failFast` is explicitly `false`.
 
 With `failFast: false`, every step settles before the call rejects. When any step failed, the rejection is usually an `AggregateError` whose `errors` hold the step failures and whose `partialResults` holds one entry per step, in step order: the task result for each step that completed, and `undefined` for a step that failed or did not run. Two rejections are not wrapped and have no `partialResults`: a workflow exit, and a `WorkflowBudgetExceededError` when every failed step exhausted a budget. Check for `partialResults` and rethrow anything else unchanged:
 

package/docs/workflows/authoring.md

@@ -1000,7 +1000,7 @@ A child exposes only outputs declared in `outputs` and returned from `run` or su
 
 Missing required outputs, schema type mismatches, and non-JSON-serializable returned values fail normal child completion before the parent continues; child `ctx.exit({ outputs })` allows missing required outputs but still validates every provided key and sets `child.exited === true` so parent code must handle the partial shape.
 
-Pass only imported workflow definitions to `ctx.workflow(...)`, not registry names or paths. Missing modules or invalid exports fail discovery. Nested children count against `maxDepth`, default `4` total workflow levels.
+Pass only imported workflow definitions to `ctx.workflow(...)`, not registry names or paths. Missing modules or invalid exports fail discovery. Nested children count against `maxDepth`, default `3` total workflow levels.
 
 A missing, empty, or invalid child graph retains a boundary summary rather than displaying unrelated nodes. Failed or skipped boundaries also retain summaries. Use `stageName` for a concise custom boundary label.
 

package/docs/workflows/operations.md

@@ -814,8 +814,8 @@ Example config:
     "team": { "path": "./workflows/team.ts" },
     "shared": { "path": "/shared/team/workflows" }
   },
-  "defaultConcurrency": 3,
-  "maxDepth": 4,
+  "defaultConcurrency": 1000,
+  "maxDepth": 3,
   "budget": { "maxDurationMs": 0, "maxTokens": 0, "maxCost": 0, "warnAtPercent": 80 },
   "persistRuns": true,
   "statusFile": false,
@@ -834,8 +834,8 @@ Runtime config defaults:
 
 | Key | Default | Purpose |
 |-----|---------|---------|
-| `defaultConcurrency` | `3` | Default stage concurrency and concurrency for authored `ctx.parallel(...)` execution |
-| `maxDepth` | `4` | Maximum workflow nesting depth |
+| `defaultConcurrency` | `1000` | Default stage concurrency and concurrency for authored `ctx.parallel(...)` execution |
+| `maxDepth` | `3` | Maximum workflow nesting depth |
 | `budget` | `{ maxDurationMs: 0, maxTokens: 0, maxCost: 0, warnAtPercent: 80 }` | Default per-run budget declaration; `0` disables a dimension; warnings default to `80` percent |
 | `persistRuns` | `true` | Persist run metadata for status/resume/history |
 | `statusFile` | `false` | Write a derived status file; defaults under `.atomic/workflows/status.json` when enabled |
@@ -873,7 +873,7 @@ Local workers are opt-in. With no `localWorkers` setting or `RunOpts.localWorker
 }
 ```
 
-The root workflow remains in its original process and owns the run graph, run controls, journal writes and Intercom routes. It can be an inline closure. Only an entire first-level `ctx.workflow(child)` subtree can move to a local worker. Nested workflows stay on that worker. Independent stage placement is not supported. Register every worker-eligible child definition by its module path and export name. The worker loads the module again in its own process, so the definition must be importable rather than a closure. Missing or incompatible definitions fail the run; Atomic does not fall back to local execution.
+The root workflow remains in its original process and owns the run graph, run controls and the root's journal writes. It can be an inline closure. The pool adds one coordinator process per root, and the worker processes run under it: the coordinator handles worker messages and heartbeats, pool journal writes, and the Intercom routes of pooled children, so a busy pool does not slow down the interactive TUI. Only an entire first-level `ctx.workflow(child)` subtree can move to a local worker. Nested workflows stay on that worker. Independent stage placement is not supported. Register every worker-eligible child definition by its module path and export name. The worker loads the module again in its own process, so the definition must be importable rather than a closure. Missing or incompatible definitions fail the run; Atomic does not fall back to local execution.
 
 Worker definitions are loaded in the SDK with `loadWorkerWorkflow(absolutePath, exportName)`, then passed to `ctx.workflow(...)`. The SDK also accepts `RunOpts.localWorkers`; the settings form applies to CLI launches. Paths in worker settings resolve against the invocation working directory. `RunOpts.localWorkers` paths resolve against `cwd` (or the current working directory when omitted). On resume, Atomic checks the saved worker options (`count` and `definitions`) and definition entry-module digests. A changed definition or worker configuration is refused. The digest covers the entry file, not its imported dependency graph.
 
@@ -887,10 +887,12 @@ The root's existing `/workflow status`, `/workflow stages`, steering, pause, qui
 
 Each worker process must report that it is ready within `localWorkers.startupTimeoutMs` milliseconds, 30000 by default. When a pool starts, it runs children as soon as one worker is ready. A worker that exits or times out during that startup is left out of the pool, and the run fails only when no worker starts. A replacement worker that cannot start fails the run. `startupTimeoutMs` is not saved with the root, so you can change it before resuming.
 
-A worker that exits is detected immediately, and its child is replayed from its last committed checkpoint on a replacement worker. A worker that is still running keeps its child as long as it keeps responding, even when the root is briefly too busy to process its heartbeats. Only a running worker that has not responded for `localWorkers.leaseMs` milliseconds (30000 by default) is stopped and its child replayed. When a root is resumed after its process crashed, children that were held by the crashed process's workers are replayed on the new workers right away.
+A worker that exits is detected immediately, and its child is replayed from its last committed checkpoint on a replacement worker. A worker that is still running keeps its child as long as it keeps responding, even when the pool is briefly too busy to process its heartbeats. Only a running worker that has not responded for `localWorkers.leaseMs` milliseconds (30000 by default) is stopped and its child replayed. When a root is resumed after its process crashed, children that were held by the crashed process's workers are replayed on the new workers right away.
 
 A worker that exits or is killed while it runs a child does not stop the root. The root fences that worker's attempt and replays the child from its last committed checkpoint on a replacement worker, up to three attempts per child.
 
+If the root process exits, even when it is killed, the pool's coordinator and workers exit with it. Resume the root to continue its children. If the coordinator process itself dies, its workers exit with it, and each pooled child the root is waiting on fails with the retryable `worker_lost` fault and the message `Local worker pool coordinator exited (…)`.
+
 Each worker writes its standard error to `worker-logs/<root run ID>/<worker ID>.log` in the directory that holds the workflow journal. With the default journal, that is `~/.atomic/workflows/worker-logs/`. Characters in the root run ID that are unsafe in a file name are percent-encoded. The errors `Local worker exited before readiness`, `Local worker startup timed out after … ms`, and `Local worker retry limit` name the log file and include the end of the worker's output. Atomic keeps the logs of workers that fail. It deletes the logs of workers that are still running when the pool shuts down normally.
 
 ### Worker resource limits

package/docs/workflows/reliable-design.md

@@ -1325,14 +1325,32 @@ Constructive quorum relies on existing Intercom mechanics: every workflow invoca
 
 #### Peer coordination between stages
 
-Quorum is one instance of a general capability: stages in the same invocation are peers, not only targets for the supervisor to steer. A live stage can `intercom({ action: "list" })` its siblings and `send`/`ask` them directly to debate a finding with evidence, hand off file paths and reproductions, claim shared files or an expensive suite or build, or learn what a sibling already verified. A `send` to a known pending sibling queues until that stage starts, and an `ask` to a completed sibling that retains a valid conversation reopens it for a post-mortem turn. Delegated subagents inside a stage inherit the same group, so a stage's children can talk to each other and to sibling stages. Named subgroups (`group: "name"` or `group: true`) isolate their members from sibling subgroups while the invocation context keeps directional control over them.
+Quorum is one instance of a general capability, and peer-to-peer (swarm) exchange is the default. There are no limits on communication between agents; it is encouraged whenever you need to. The supervisor is not a message relay: relaying adds latency, loses detail, and fills its context, while stages that exchange evidence directly converge faster. Stages in the same invocation are peers, not only targets for the supervisor to steer. A live stage can `intercom({ action: "list" })` its siblings and `send`/`ask` them directly to debate a finding with evidence, hand off file paths and reproductions, claim shared files or an expensive suite or build, or learn what a sibling already verified. A `send` to a known pending sibling queues until that stage starts, and an `ask` to a completed sibling that retains a valid conversation reopens it for a post-mortem turn. Delegated subagents inside a stage inherit the same group, so a stage's children can talk to each other and to sibling stages. Named subgroups (`group: "name"` or `group: true`) isolate their members from sibling subgroups while the invocation context keeps directional control over them.
 
-Design peer exchange the way you design any other handoff:
+How stages work as a swarm:
 
-- Stages do not coordinate spontaneously. Say in each prompt who the peers are (or the `list` pattern that finds them) and what they exchange.
-- Bound it: one evidence round, one ownership claim per shared step, one ask per fact. An unbounded conversation between parallel stages burns budget and blurs who decided what.
+- Stages coordinate spontaneously. They discover peers with `list` and broadcast findings, claim shared files or an expensive step, ask and answer each other, hand work along a chain, and debate for as long as it is useful.
 - Keep every stage's output its own. A peer's claim is evidence to inspect, not a verdict to copy; each stage still returns its own structured result to the reducer or downstream stage.
-- Peer messages are activity inside already-running stages, not graph edges. They never replace `previous`, artifacts, or declared outputs for durable handoffs, and scope or acceptance decisions stay with a supervisor or a `ctx.ui` gate.
+- Peer messages are activity inside already-running stages, not graph edges. They never replace `previous`, artifacts, or declared outputs for durable handoffs. Explicit user approval gates and authorization for destructive or external actions still apply.
+
+A minimal swarm: three parallel investigators share findings directly, and the workflow collects each stage's own result.
+
+```typescript
+const swarm = [
+  "Your sibling stages investigate other angles of the same failure.",
+  "Run intercom list to find them and talk to them as much as you need: share findings,",
+  "claim any shared suite before running it, ask instead of guessing, and debate disagreements.",
+  "Then return your own findings.",
+].join("\n");
+
+const results = await ctx.parallel([
+  { name: "logs", prompt: `Trace the timeout through the service logs.\n${swarm}` },
+  { name: "code", prompt: `Trace the timeout through the retry code.\n${swarm}` },
+  { name: "repro", prompt: `Build a minimal reproduction of the timeout.\n${swarm}` },
+]);
+```
+
+Swarm size scales with the task. For very complex work, or when the user asks for heavy parallelism, fan out to hundreds or thousands of agents: wide `ctx.parallel(...)` stages, a subagent parallel set inside each stage, and child workflows via `ctx.workflow(...)` (optionally on `workflows.localWorkers`). Give each team a named subgroup so its members coordinate internally while the team leads, as sibling stages, coordinate in the invocation group. Up to 1000 stages run at once by default; lower `defaultConcurrency` or pass `concurrency` to run fewer; `maxDepth` (default 3) bounds child-workflow nesting, and subagent children cannot delegate further. See [Scaling a swarm](/subagents#scaling-a-swarm) for every limit.
 
 #### Pattern diagrams
 

package/examples/extensions/custom-provider-anthropic/index.ts

@@ -19,7 +19,7 @@ import {
 	type TextContent,
 	type ThinkingContent,
 	type Tool,
-	type ToolCall,
+	ToolCallArgumentsStream,
 	type ToolResultMessage,
 	type TranscriptContext,
 } from "@bastani/pi-ai/compat";
@@ -378,8 +378,11 @@ function streamCustomAnthropic(
 			}
 			const anthropicStream = client.messages.stream({ ...params }, { signal: options?.signal });
 			stream.push({ type: "start", partial: output });
-			type Block = (ThinkingContent | TextContent | (ToolCall & { partialJson: string })) & { index: number };
-			const blocks = output.content as Block[];
+
+			// Stream state per Anthropic block index, kept off the content blocks so it never reaches partial messages.
+			// ToolCallArgumentsStream reads each argument delta once and shows the arguments parsed so far.
+			const openBlocks = new Map<number, { contentIndex: number; arguments?: ToolCallArgumentsStream }>();
+
 			for await (const event of anthropicStream) {
 				if (event.type === "message_start") {
 					output.usage.input = event.message.usage.input_tokens || 0;
@@ -391,15 +394,12 @@ function streamCustomAnthropic(
 					calculateCost(model, output.usage);
 				} else if (event.type === "content_block_start") {
 					if (event.content_block.type === "text") {
-						output.content.push({ type: "text", text: "", index: event.index } as any);
+						output.content.push({ type: "text", text: "" });
+						openBlocks.set(event.index, { contentIndex: output.content.length - 1 });
 						stream.push({ type: "text_start", contentIndex: output.content.length - 1, partial: output });
 					} else if (event.content_block.type === "thinking") {
-						output.content.push({
-							type: "thinking",
-							thinking: "",
-							thinkingSignature: "",
-							index: event.index,
-						} as any);
+						output.content.push({ type: "thinking", thinking: "", thinkingSignature: "" });
+						openBlocks.set(event.index, { contentIndex: output.content.length - 1 });
 						stream.push({ type: "thinking_start", contentIndex: output.content.length - 1, partial: output });
 					} else if (event.content_block.type === "tool_use") {
 						output.content.push({
@@ -409,15 +409,19 @@ function streamCustomAnthropic(
 								? fromClaudeCodeName(event.content_block.name, context.tools)
 								: event.content_block.name,
 							arguments: {},
-							partialJson: "",
-							index: event.index,
-						} as any);
+						});
+						openBlocks.set(event.index, {
+							contentIndex: output.content.length - 1,
+							arguments: new ToolCallArgumentsStream(),
+						});
 						stream.push({ type: "toolcall_start", contentIndex: output.content.length - 1, partial: output });
 					}
 				} else if (event.type === "content_block_delta") {
-					const index = blocks.findIndex((b) => b.index === event.index);
-					const block = blocks[index];
-					if (!block) continue;
+					const open = openBlocks.get(event.index);
+					if (!open) continue;
+					const index = open.contentIndex;
+					const block = output.content[index]!;
+
 					if (event.delta.type === "text_delta" && block.type === "text") {
 						block.text += event.delta.text;
 						stream.push({ type: "text_delta", contentIndex: index, delta: event.delta.text, partial: output });
@@ -429,11 +433,8 @@ function streamCustomAnthropic(
 							delta: event.delta.thinking,
 							partial: output,
 						});
-					} else if (event.delta.type === "input_json_delta" && block.type === "toolCall") {
-						(block as any).partialJson += event.delta.partial_json;
-						try {
-							block.arguments = JSON.parse((block as any).partialJson);
-						} catch {}
+					} else if (event.delta.type === "input_json_delta" && block.type === "toolCall" && open.arguments) {
+						block.arguments = open.arguments.append(event.delta.partial_json);
 						stream.push({
 							type: "toolcall_delta",
 							contentIndex: index,
@@ -444,19 +445,19 @@ function streamCustomAnthropic(
 						block.thinkingSignature = (block.thinkingSignature || "") + (event.delta as any).signature;
 					}
 				} else if (event.type === "content_block_stop") {
-					const index = blocks.findIndex((b) => b.index === event.index);
-					const block = blocks[index];
-					if (!block) continue;
-					delete (block as any).index;
+					const open = openBlocks.get(event.index);
+					if (!open) continue;
+					openBlocks.delete(event.index);
+					const index = open.contentIndex;
+					const block = output.content[index]!;
+
 					if (block.type === "text") {
 						stream.push({ type: "text_end", contentIndex: index, content: block.text, partial: output });
 					} else if (block.type === "thinking") {
 						stream.push({ type: "thinking_end", contentIndex: index, content: block.thinking, partial: output });
-					} else if (block.type === "toolCall") {
-						try {
-							block.arguments = JSON.parse((block as any).partialJson);
-						} catch {}
-						delete (block as any).partialJson;
+					} else if (block.type === "toolCall" && open.arguments) {
+						// One full parse of the complete text; malformed arguments are reported in `argumentsError`.
+						Object.assign(block, open.arguments.finish());
 						stream.push({ type: "toolcall_end", contentIndex: index, toolCall: block, partial: output });
 					}
 				} else if (event.type === "message_delta") {
@@ -478,7 +479,6 @@ function streamCustomAnthropic(
 			stream.push({ type: "done", reason: output.stopReason as "stop" | "length" | "toolUse", message: output });
 			stream.end();
 		} catch (error) {
-			for (const block of output.content) delete (block as any).index;
 			output.stopReason = options?.signal?.aborted ? "aborted" : "error";
 			output.errorMessage = error instanceof Error ? error.message : JSON.stringify(error);
 			stream.push({ type: "error", reason: output.stopReason, error: output });

package/examples/extensions/todo.ts

@@ -275,6 +275,13 @@ export default function (pi: ExtensionAPI) {
 
 				case "clear":
 					return new Text(theme.fg("success", "✓ ") + theme.fg("muted", "Cleared all todos"), 0, 0);
+
+				default:
+					return new Text(
+						result.content[0]?.type === "text" ? theme.fg("error", result.content[0].text) : "",
+						0,
+						0,
+					);
 			}
 		},
 	});

package/npm-shrinkwrap.json

@@ -1,16 +1,16 @@
 {
 	"name": "@bastani/atomic",
-	"version": "0.9.43",
+	"version": "0.9.44-alpha.2",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@bastani/atomic",
-			"version": "0.9.43",
+			"version": "0.9.44-alpha.2",
 			"license": "MIT",
 			"dependencies": {
-				"@bastani/atomic-natives": "0.9.43",
-				"@bastani/pi-ai": "0.9.43",
+				"@bastani/atomic-natives": "0.9.44-alpha.2",
+				"@bastani/pi-ai": "0.9.44-alpha.2",
 				"@earendil-works/pi-agent-core": "1.4.0",
 				"@earendil-works/pi-codemode": "1.4.0",
 				"@earendil-works/pi-tui": "1.4.0",
@@ -427,18 +427,18 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives": {
-			"version": "0.9.43",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.43.tgz",
+			"version": "0.9.44-alpha.2",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives/-/atomic-natives-0.9.44-alpha.2.tgz",
 			"license": "MIT",
 			"optionalDependencies": {
-				"@bastani/atomic-natives-darwin-arm64": "0.9.43",
-				"@bastani/atomic-natives-darwin-x64": "0.9.43",
-				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.43",
-				"@bastani/atomic-natives-linux-arm64-musl": "0.9.43",
-				"@bastani/atomic-natives-linux-x64-gnu": "0.9.43",
-				"@bastani/atomic-natives-linux-x64-musl": "0.9.43",
-				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.43",
-				"@bastani/atomic-natives-win32-x64-msvc": "0.9.43"
+				"@bastani/atomic-natives-darwin-arm64": "0.9.44-alpha.2",
+				"@bastani/atomic-natives-darwin-x64": "0.9.44-alpha.2",
+				"@bastani/atomic-natives-linux-arm64-gnu": "0.9.44-alpha.2",
+				"@bastani/atomic-natives-linux-arm64-musl": "0.9.44-alpha.2",
+				"@bastani/atomic-natives-linux-x64-gnu": "0.9.44-alpha.2",
+				"@bastani/atomic-natives-linux-x64-musl": "0.9.44-alpha.2",
+				"@bastani/atomic-natives-win32-arm64-msvc": "0.9.44-alpha.2",
+				"@bastani/atomic-natives-win32-x64-msvc": "0.9.44-alpha.2"
 			},
 			"engines": {
 				"bun": ">=1.4.2",
@@ -446,8 +446,8 @@
 			}
 		},
 		"node_modules/@bastani/atomic-natives-darwin-arm64": {
-			"version": "0.9.43",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.43.tgz",
+			"version": "0.9.44-alpha.2",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-arm64/-/atomic-natives-darwin-arm64-0.9.44-alpha.2.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -458,8 +458,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-darwin-x64": {
-			"version": "0.9.43",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.43.tgz",
+			"version": "0.9.44-alpha.2",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-darwin-x64/-/atomic-natives-darwin-x64-0.9.44-alpha.2.tgz",
 			"license": "MIT",
 			"os": [
 				"darwin"
@@ -470,8 +470,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-gnu": {
-			"version": "0.9.43",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.43.tgz",
+			"version": "0.9.44-alpha.2",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-gnu/-/atomic-natives-linux-arm64-gnu-0.9.44-alpha.2.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -485,8 +485,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-arm64-musl": {
-			"version": "0.9.43",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-musl/-/atomic-natives-linux-arm64-musl-0.9.43.tgz",
+			"version": "0.9.44-alpha.2",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-arm64-musl/-/atomic-natives-linux-arm64-musl-0.9.44-alpha.2.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -500,8 +500,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-gnu": {
-			"version": "0.9.43",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.43.tgz",
+			"version": "0.9.44-alpha.2",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-gnu/-/atomic-natives-linux-x64-gnu-0.9.44-alpha.2.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -515,8 +515,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-linux-x64-musl": {
-			"version": "0.9.43",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-musl/-/atomic-natives-linux-x64-musl-0.9.43.tgz",
+			"version": "0.9.44-alpha.2",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-linux-x64-musl/-/atomic-natives-linux-x64-musl-0.9.44-alpha.2.tgz",
 			"license": "MIT",
 			"os": [
 				"linux"
@@ -530,8 +530,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-arm64-msvc": {
-			"version": "0.9.43",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.43.tgz",
+			"version": "0.9.44-alpha.2",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-arm64-msvc/-/atomic-natives-win32-arm64-msvc-0.9.44-alpha.2.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -542,8 +542,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/atomic-natives-win32-x64-msvc": {
-			"version": "0.9.43",
-			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.43.tgz",
+			"version": "0.9.44-alpha.2",
+			"resolved": "https://registry.npmjs.org/@bastani/atomic-natives-win32-x64-msvc/-/atomic-natives-win32-x64-msvc-0.9.44-alpha.2.tgz",
 			"license": "MIT",
 			"os": [
 				"win32"
@@ -554,8 +554,8 @@
 			"optional": true
 		},
 		"node_modules/@bastani/pi-ai": {
-			"version": "0.9.43",
-			"resolved": "https://registry.npmjs.org/@bastani/pi-ai/-/pi-ai-0.9.43.tgz",
+			"version": "0.9.44-alpha.2",
+			"resolved": "https://registry.npmjs.org/@bastani/pi-ai/-/pi-ai-0.9.44-alpha.2.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.129.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.9.43",
+  "version": "0.9.44-alpha.2",
   "description": "Atomic coding agent CLI with read, bash, edit, write tools and session management",
   "type": "module",
   "atomicConfig": {
@@ -89,8 +89,8 @@
     "prepublishOnly": "bun run clean && bun run build && bun run shrinkwrap"
   },
   "dependencies": {
-    "@bastani/atomic-natives": "0.9.43",
-    "@bastani/pi-ai": "0.9.43",
+    "@bastani/atomic-natives": "0.9.44-alpha.2",
+    "@bastani/pi-ai": "0.9.44-alpha.2",
     "@earendil-works/pi-agent-core": "1.4.0",
     "@earendil-works/pi-codemode": "1.4.0",
     "@earendil-works/pi-tui": "1.4.0",