@bastani/atomic 0.9.21-alpha.1 → 0.9.21

package/docs/models/model-selection.md

@@ -11,21 +11,18 @@ For specific benchmark records, read [Evals](/models/evals). That page is the da
 
 ## Automatic subagent and workflow-stage routing
 
-Subagent and workflow-stage `model: "auto"` routes before execution starts. Atomic sends the router:
+Subagent and workflow-stage `model: "auto"` routes before execution starts, in at most two short requests:
 
-- the final task or stage prompt,
-- the agent or stage name and description,
-- the eligible provider/model and effort choices with catalog capabilities and prices,
-- hard `modelConstraints`, and
-- the factual markdown tables in [Evals](/models/evals).
+1. **Questions about the task, answered by a chat model.** Kind of work, difficulty, mistake cost, image input, very large context, and whether speed matters. The chat model is `routerModel` when that is a chat model, otherwise your current one; a classifier such as Jev never reads the task. A task too large for that model's window is read by the cheapest eligible model that holds it. Anything the caller states in `taskNeeds` is not asked, and when the caller states all six this request is skipped. Computer-use tasks count as needing images unless the caller says otherwise.
+2. **A choice between a shortlist, made by the router without the task.** Atomic narrows the eligible models in code: it drops models that cannot read images when the task needs them and prefers 400k-token windows for long-context tasks, then ranks the rest on the [Evals](/models/evals) results for that kind of work, weighing proven quality against price by how demanding the task is and preferring newer releases. The top six different models form the shortlist; a model's fast route and the same model on another provider share one place. When the caller lists models in `modelConstraints.allowedModels`, those eligible models are the shortlist instead (as many as fit one routing request). Each option carries its own evidence (release date, price tier, image input, and how it was measured on this kind of work and overall), ranked against every model you could route to. With a single option, this request is skipped.
 
-The router returns one primary `{ model, effort }` pair and up to two ordered fallback pairs. It cannot add candidates, bypass constraints, alter the execution prompt, or change the selected chat model. [`routerModel`](/settings#routermodel) chooses the decision model only: an explicit registered classifier or chat language model. Unset and `auto` use the current chat model, regardless of saved classifier credentials. An image-generation model cannot decide.
+Effort follows the task's difficulty, one level lower when speed matters, limited to the levels the chosen model supports. The two fallbacks are the next models in Atomic's ranking. The router cannot add candidates, bypass constraints, alter the execution prompt, or change the selected chat model. [`routerModel`](/settings#routermodel) chooses the decision model only: an explicit registered classifier or chat language model. Unset and `auto` use the current chat model, regardless of saved classifier credentials. An image-generation model cannot decide.
 
 Only chat language models are eligible for execution `auto`, including models that accept image or PDF input. Image-generation and classifier models cannot be execution candidates, even when a classifier makes the routing decision.
 
 In authored workflows, a classifier can make a structured triage decision without executing the stage; an image model can generate an asset inside a durable tool step. See [classifier and image models in `ctx.tool`](/workflows/authoring#classifier-and-image-models-in-ctx-tool).
 
-Long tasks may be excerpted for routing so the decision fits the decision provider's input budget. Execution still receives the full task. The excerpt keeps the beginning and end of the task plus `<keepContext>...</keepContext>` spans, and marks cuts `[... truncated ...]`. Put the role and objective at the start or end, or in a short protected span, and keep bulky reference text in the middle.
+To keep some providers out of routing entirely, set [`modelRouting`](/settings#modelrouting).
 
 ## Benchmarks are evidence, not policy
 
@@ -33,6 +30,8 @@ Benchmark results are measurements under named harnesses, dates, models, efforts
 
 Missing evidence is unknown, not zero. A rounded lead is not proof of significance. A result for one provider, model version, effort, agent, fallback setting, or benchmark harness does not transfer to another identity.
 
+Prefer recency. Each row in [Evals](/models/evals) has a release date. When candidates fit the same role tier and price range, choose the most recently released model over an older one from the same provider or family; a newer release usually supersedes it. Do not let an older model win only because it has no published results: its missing evidence stays unknown, and a recent comparable model with evidence is the safer choice. Recency does not override the role's cost tier or explicit constraints.
+
 ## Role-based thinking effort
 
 Use these starting defaults unless the user requests a level. Higher effort can improve hard reasoning, but it also costs more and can be slower. `max` is an exception, not a default.

package/docs/rpc/examples.md

@@ -9,7 +9,7 @@ description: Additional RPC client implementations.
 
 See [`test/rpc-example.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/test/rpc-example.ts) for a complete interactive example, or [`src/modes/rpc/rpc-client.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/src/modes/rpc/rpc-client.ts) for a typed client implementation.
 
-[`examples/rpc-client.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/rpc-client.ts) uses the exported `RpcClient` to run Atomic in a child process, stream events, and wait for the run to settle. Build the coding-agent package first, then run `npx tsx examples/rpc-client.ts "Explain this repository"` from a repository checkout. `RpcClient` launches the CLI under Bun by default; pass `runtimeExecutable: process.execPath` to run it under Node.
+[`examples/rpc-client.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/rpc-client.ts) uses the exported `RpcClient` to run Atomic in a child process, stream events, and wait for the run to settle. Build the coding-agent package first, then run `node examples/rpc-client.ts "Explain this repository"` from a repository checkout. `RpcClient` launches the CLI under Bun by default; pass `runtimeExecutable: process.execPath` to run it under Node.
 
 For a complete example of handling the extension UI protocol, see [`examples/rpc-extension-ui.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/rpc-extension-ui.ts) which pairs with the [`examples/extensions/rpc-demo.ts`](https://github.com/bastani-inc/atomic/blob/main/packages/coding-agent/examples/extensions/rpc-demo.ts) extension.
 

package/docs/rpc/protocol.md

@@ -39,9 +39,11 @@ If the agent is streaming and no `streamingBehavior` is specified, the command r
 
 Response:
 ```json
-{"id": "req-1", "type": "response", "command": "prompt", "success": true}
+{"id": "req-1", "type": "response", "command": "prompt", "success": true, "data": {"disposition": "started"}}
 ```
 
+`data.disposition` is `"handled"` if an extension command or input handler consumed the prompt, `"queued"` if Atomic queued it during a run or held it because the message queue was paused before its run began, or `"started"` if Atomic started a run for it. This describes the submitted prompt, not independent work started by an extension or a guarantee of completion. If it is `"handled"`, no run started for this prompt, so don't wait for `agent_end` or `agent_settled`.
+
 `success: true` means the prompt was accepted, queued, or handled immediately. `success: false` means the prompt was rejected before acceptance. Failures after acceptance are reported through the normal event and message stream, not as a second `response` for the same request id.
 
 The `images` field is optional. Each image uses `ImageContent` format: `{"type": "image", "data": "base64-encoded-data", "mimeType": "image/png"}`.
@@ -63,9 +65,11 @@ The `images` field is optional. Each image uses `ImageContent` format (same as `
 
 Response:
 ```json
-{"type": "response", "command": "steer", "success": true}
+{"type": "response", "command": "steer", "success": true, "data": {"disposition": "queued"}}
 ```
 
+`data.disposition` is `"handled"` if an input handler consumed this steer, or `"queued"` if Atomic queued it (including after a handler transformed it). It does not guarantee this message remains queued.
+
 See [set_steering_mode](#set_steering_mode) for controlling how steering messages are processed.
 
 #### follow_up
@@ -85,9 +89,11 @@ The `images` field is optional. Each image uses `ImageContent` format (same as `
 
 Response:
 ```json
-{"type": "response", "command": "follow_up", "success": true}
+{"type": "response", "command": "follow_up", "success": true, "data": {"disposition": "queued"}}
 ```
 
+`data.disposition` has the same `"handled"` or `"queued"` meaning as for `steer`, applied to this follow-up.
+
 See [set_follow_up_mode](#set_follow_up_mode) for controlling how follow-up messages are processed.
 
 #### abort

package/docs/sdk/structured-decisions.md

@@ -79,7 +79,7 @@ A registered classifier receives shared state and choice questions through the g
 
 The structured-decision path never trims supplied state. A general structured-output call skips an incompatible classifier candidate and continues with the next fallback. A provider size rejection advances the same way without repeating the rejected request. Supply concise context or select a chat model with enough capacity when needed.
 
-Automatic subagent and workflow-stage model selection uses a [bounded task excerpt](/subagents/reference#automatic-model-selection) for its routing decision. That excerpt preserves protected spans and does not replace the execution prompt. Direct SDK calls do not apply this task-excerpt policy.
+Automatic subagent and workflow-stage model selection has a chat model read the task and sends a classifier only the resulting answers and candidate models; see [automatic model selection](/subagents/reference#automatic-model-selection).
 
 Classifier response bodies are limited by the provider operation. Atomic validates that every question receives a known Choice option. The classify result does not report token usage. Reported model, probabilities, and confidence are advisory and never reject an otherwise valid decision.
 

package/docs/sdk.md

@@ -425,13 +425,13 @@ interface PromptOptions {
   images?: ImageContent[];
   streamingBehavior?: "steer" | "followUp";
   source?: InputSource;
-  preflightResult?: (success: boolean) => void;
+  preflightResult?: (success: boolean, disposition?: "handled" | "queued" | "started") => void;
 }
 ```
 
 `preflightResult` is called once per `prompt()` invocation:
 
-- `true` when the prompt was accepted, queued, or handled immediately
+- `true` when the prompt was accepted, queued, or handled immediately. The second argument says which: `"handled"` if an extension command or input handler consumed it, `"queued"` if it was queued during a run, or `"started"` if it started a run
 - `false` when prompt preflight rejected before acceptance
 
 It fires before `prompt()` resolves. `prompt()` still resolves only after the full accepted run finishes, including retries. Failures after acceptance are reported through the normal event and message stream, not through `preflightResult(false)`.
@@ -469,7 +469,7 @@ await session.steer("New instruction");
 await session.followUp("After you're done, also do this");
 ```
 
-Both `steer()` and `followUp()` expand file-based prompt templates but error on extension commands (extension commands cannot be queued).
+Both `steer()` and `followUp()` expand file-based prompt templates but error on extension commands (extension commands cannot be queued). They return `"queued"` if the input was queued (including after an extension transformed it), or `"handled"` if an extension consumed it.
 
 `pauseQueuedMessages()` synchronously holds existing raw steering/follow-up entries before an abort boundary. Later context-bearing arrivals also stay queued without starting a provider turn. These include trigger-turn custom messages, batches, interrupts, `sendUserMessage()`, and ordinary `prompt()` calls.
 

package/docs/settings.md

@@ -56,6 +56,7 @@ See [Herdr](/herdr) for state aggregation, reporter conflicts, privacy, and Herd
 | `defaultProvider` | string | - | Startup provider, saved automatically when you switch models interactively |
 | `defaultModel` | string | - | Startup model ID, saved automatically when you switch models interactively |
 | `routerModel` | string | `""` | Inference model for workflow-stage and subagent `model: "auto"` selection only. An exact `provider/model` selects a registered chat or classifier model. `auto` and empty use the current chat model. Does not change chat or `structured_output` tool inference. |
+| `modelRouting` | object | `{}` | Provider filters for the models `model: "auto"` may select: `allowedProviders` and `excludedProviders` (provider ID arrays). Does not change `routerModel`. See [modelRouting](#modelrouting). |
 | `defaultThinkingLevel` | string | - | Startup thinking level, saved automatically on interactive model/thinking changes: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`, `"xhigh"`, `"max"`; clamped to the active model's supported levels |
 | `modelThinkingLevels` | object | - | Per-model startup thinking levels keyed by `"provider/modelId"`; updated automatically on interactive model/thinking changes, or configured from `/settings` → Default thinking level per model |
 | `hideThinkingBlock` | boolean | `false` | Hide thinking blocks in output |
@@ -83,16 +84,36 @@ Use `/settings` → **Router model** to change the effective selection. If the p
 
 An explicit ID other than `auto` is resolved through the current model registry: a registered classifier first, otherwise a chat model. Gateway classifier IDs are not registered automatically; configure their classifier models and operations before selecting them. An invalid explicit ID, image-generation model, non-string value, or surrounding whitespace fails the decision instead of silently changing providers. An explicit empty project value overrides a global selection and restores the current chat model.
 
-A failed explicit classifier routing attempt switches to the current chat model when one exists. That includes missing credentials, an unavailable classify operation, a provider size or context rejection, a refusal, and a malformed answer. Transient retries follow the provider operation and retry settings. Chat routing gets an initial attempt plus three corrective retries for invalid output, using the same context. Routing has no built-in wall-clock deadline; cancel the request to stop waiting. Independent provider, credential-preparation, and enclosing tool-request limits still apply. Atomic reports the fallback; it can incur chat-provider charges. Cancellation does not trigger fallback.
+A failed explicit classifier routing attempt switches to the current chat model when one exists. That includes missing credentials, an unavailable classify operation, a provider size or context rejection, a refusal, and a malformed answer. Transient retries follow the provider operation and retry settings. Chat routing gets an initial attempt plus three corrective retries for invalid output, using the same context. Routing has no built-in wall-clock deadline; cancel the request to stop waiting. Independent provider, credential-preparation, and enclosing tool-request limits still apply. The fallback can incur chat-provider charges. Cancellation does not trigger fallback.
 
-Automatic subagent and workflow-stage model selection uses a bounded excerpt for long tasks, keeping the beginning, end, and `<keepContext>...</keepContext>` spans. Only the router's copy is shortened; execution receives the full task and hard model constraints stay enforced. Put essential model-selection requirements in protected spans. Unprotected middle text may be omitted, so excerpts can affect model choice. This does not truncate general structured decisions.
+A classifier `routerModel` such as Jev only chooses between the shortlisted models and never receives the task; a chat model (`routerModel` when it is one, otherwise the current chat model) reads the task to answer the routing questions. If the selected classifier rejects the request, routing switches to the current chat model.
 
-If the selected classifier rejects the request for size or context, routing switches to the current chat model.
+Routing fallbacks are recovered automatically and are not printed to the terminal or added to the conversation. Set `ATOMIC_MODEL_ROUTING_DEBUG=1` to print them while debugging model selection.
 
 This setting selects inference for [workflow-stage `model: "auto"`](/workflows/authoring#automatic-stage-model-selection) and [subagent `model: "auto"`](/subagents/reference#automatic-model-selection). It does not directly select the child execution model or change the selected chat model, `structured_output` tool, or general structured-output inference. The decision provider may be any registered classifier or chat model, never an image-generation model; execution `auto` selects only chat language models, including multimodal-input chat. The selected router provider receives the routing context, so choose a provider permitted to process that data. Authenticate a pinned classifier with that provider's login, such as `/login typesafe` or `TYPESAFE_API_KEY` for TypeSafe Jev. See [Structured decisions](/sdk/structured-decisions) and [TypeSafe Jev](/providers#typesafe-jev).
 
 Remove secrets from routing tasks, inputs, and workflow descriptions/contracts before calling the tool. A routing-context credential error stops before inference or launch. Known configured credentials are screened even when they belong to a provider other than the router. Remove the credential from the supplied context or registered definition, reload a changed definition, then retry explicitly. The guard does not detect every possible secret.
 
+#### modelRouting
+
+```json
+{
+  "modelRouting": {
+    "allowedProviders": ["github-copilot", "openai-codex", "anthropic"],
+    "excludedProviders": ["openrouter"]
+  }
+}
+```
+
+Limits which providers' models workflow stages and subagents with `model: "auto"` can be routed to. It filters the candidates only; the model that makes the decision is still `routerModel`.
+
+- `allowedProviders`: when nonempty, only models from these providers are candidates.
+- `excludedProviders`: models from these providers are never candidates, even if they are also allowed.
+
+Use provider IDs as shown by `/model` or `workflow({ action: "models" })`, such as `github-copilot`, `openai-codex`, `anthropic`, or `openrouter`. For example, to route only to your subscriptions, exclude the API-billed providers you have configured. The Claude subscription and the Anthropic API both use the `anthropic` provider, so this setting cannot separate them.
+
+A project list replaces the global list of the same name; the other list is kept. A subagent call or workflow stage that sets `modelConstraints.allowedProviders` or `excludedProviders`, for example because you asked for a provider, uses its own lists instead of these for that call. Provider lists in an agent definition or inherited from a parent workflow only narrow these settings; they never lift an exclusion. If the filters leave no eligible model, the stage or subagent fails before launch with an error that names this setting. A run resumed after you exclude a provider rejects a recorded selection from that provider instead of using it.
+
 #### thinkingBudgets
 
 ```json

package/docs/subagents/reference.md

@@ -21,11 +21,28 @@ The same value works on individual parallel tasks and in an agent definition's `
 
 Workflow stages also support [prompt-based `model: "auto"`](/workflows/authoring#automatic-stage-model-selection), using the same decision provider and evaluation guidance. Stage model selection is separate from choosing which workflow to launch.
 
-Put requirements that should influence model selection in the task. Atomic supplies `task`, `agent` (name and description), `evals` containing the factual markdown tables from [Evals](/models/evals), and `model_selection_guide`, a fixed policy excerpt from [Model Selection](/models/model-selection) covering benchmarks-as-evidence and the role-based model cost tier and thinking effort table, so exploration and routine implementation lean toward cheaper models while review and verification get frontier ones. Eligible provider-qualified models and efforts, capabilities and prices appear in the choices. There is no separate policy-version field or provider-name filter. You do not need to attach eval records yourself.
+Routing takes at most two short requests, described in [Model Selection](/models/model-selection#automatic-subagent-and-workflow-stage-routing): a chat model answers questions about the task, then the router chooses between a shortlist of models that each carry their own [Evals](/models/evals) results, seeing only those answers and never the task. Effort follows the task's difficulty.
+
+When you launch a subagent, fill in `taskNeeds` with everything you can judge; stated fields are not asked, and stating all six skips the task-reading request. To choose the contenders yourself, list them in `modelConstraints.allowedModels`; the eligible ones become the shortlist:
+
+```typescript
+subagent({
+  agent: "worker",
+  task: "Open Xcode, build the app and verify the settings screen by screenshot",
+  model: "auto",
+  taskNeeds: {
+    work: "computer_use", difficulty: "hard", mistakeCost: "moderate",
+    needsImages: true, longContext: false, latencySensitive: false,
+  },
+  modelConstraints: { allowedModels: ["anthropic/claude-opus-5-5", "openai-codex/gpt-6-astra"] },
+})
+```
+
+`work` is one of `computer_use`, `coding`, `code_review`, `codebase_lookup`, `research`, `business_workflow`, `math_science` or `writing`; `difficulty` is `trivial`, `easy`, `moderate`, `hard` or `very_hard`; `mistakeCost` is `negligible`, `low`, `moderate`, `high` or `severe`; `needsImages`, `longContext` (must hold a very large codebase or document set) and `latencySensitive` (a fast answer matters more than extra reasoning) are true or false. When listing candidates, prefer the user's subscription models over pay-per-token API models unless the user asked for API models or has none. To keep providers out of routing entirely, use the [`modelRouting`](/settings#modelrouting) setting. You do not need to attach eval records yourself.
 
 The agent's system prompt is not routing metadata. For a self-contained agent with no task, it remains the task fallback. The router weighs task-relevant evidence, cost, and latency rather than always choosing a benchmark winner or maximum effort. Benchmark measurement effort does not prescribe execution effort.
 
-Long tasks use a model-selection excerpt of at most 9,000 JSON-encoded UTF-8 bytes (roughly 1,200 words), smaller when many model/effort pairs are eligible. It retains the beginning, end, and `<keepContext>...</keepContext>` spans in source order and marks each cut `[... truncated ...]`. Put the child's role and objective at the start or end of the task, or in a short protected span, and keep bulky reference text in the middle; unprotected middle text may be cut. If the protected spans alone do not fit, the router receives the start and end of the task and the middle is cut, including protected text. This applies to the routing request, not execution: the child still receives its complete task. If a classifier still rejects the request, routing falls back to the current chat model and the warning names the HTTP status and error type. Hard `modelConstraints` are never truncated.
+The chat model reads the complete task; a task too large for its context window is read by the cheapest eligible model whose window holds it. If a classifier rejects the choice request, routing falls back to the current chat model. Fallbacks are silent unless `ATOMIC_MODEL_ROUTING_DEBUG=1`, which prints them with the HTTP status and error type. Hard `modelConstraints` are never truncated.
 
 The shared [`routerModel`](/settings#routermodel) setting chooses the model making the decision, not the child model. Selection follows this order:
 
@@ -38,7 +55,7 @@ Routing has no built-in wall-clock deadline. Slow decisions can finish; cancel t
 
 The result records a primary `{ model, effort }` and up to two ordered `fallbacks`, each with its own model and effort. Atomic ranks three distinct eligible provider/model IDs, or all available IDs when fewer than three qualify. It selects each rank from the remaining models, excluding all efforts of earlier choices. A supported `"off"` is distinct from `null`, which means no configurable reasoning. The catalog reflects configured authentication, not proof of valid credentials, quota, or entitlement.
 
-The child does not start if no candidates are eligible, availability changes, or cancellation occurs. A classifier provider failure, missing credentials, unsupported classify operation, size rejection, or malformed answer triggers a reported switch to the current chat model. Transient provider failures are retried up to three times first. The chat model gets its own output-repair allowance. If routing inference fails completely, the child runs on the current chat model instead of failing, with a reported warning, but only when that model is available and satisfies every routing constraint (such as `allowedModels` and effort, cost, context and input limits). Otherwise the launch fails. Invalid inputs, conflicting constraints, cancellation and stale-catalog failures never trigger fallback. No partial decision can launch a child.
+The child does not start if no candidates are eligible, availability changes, or cancellation occurs. A classifier provider failure, missing credentials, unsupported classify operation, size rejection, or malformed answer switches to the current chat model. Transient provider failures are retried up to three times first. The chat model gets its own output-repair allowance. If routing inference fails completely, or Atomic cannot pick a model itself (the task needs images and no eligible model reads them, `allowedModels` lists more models than one routing request holds (roughly 100), or `evals.md` is missing), the child runs on the current chat model instead of failing, but only when that model is available and satisfies every routing constraint (such as `allowedModels` and effort, cost, context and input limits). Otherwise the launch fails. Invalid inputs, conflicting constraints, cancellation and stale-catalog failures never trigger fallback. No partial decision can launch a child. These switches are silent unless `ATOMIC_MODEL_ROUTING_DEBUG=1` is set.
 
 Router classification is one classify request for the prepared choices. If the provider rejects the request size, routing uses the current chat model. See [structured decision limits](/sdk/structured-decisions#provider-behavior-and-limits).
 
@@ -53,12 +70,13 @@ For automatic routing, optional `modelConstraints` on a call, parallel task, or
 | Field | Meaning |
 | --- | --- |
 | `allowedModels` | Exact provider/model IDs permitted to receive the task |
+| `allowedProviders`, `excludedProviders` | Provider IDs whose models may or may never be used. On a call, setting either replaces the [`modelRouting`](/settings#modelrouting) provider settings for that call, so set them only when the user asks; in an agent definition they only narrow those settings |
 | `maxInputCost`, `maxOutputCost` | Maximum catalog price in USD per million input or output tokens, not a total spending cap |
 | `minContextWindow` | Minimum advertised context window in tokens |
 | `requiredInputs` | Required input types, `"text"` or `"image"` |
 | `allowedEfforts` | Permitted supported effort values, including `null` for non-reasoning models |
 
-Unknown keys and invalid limits fail validation. An empty eligible set stops the launch. These constraints do not turn a concrete model call into an automatic one. The catalog does not establish a latency SLA or a provider's privacy guarantees. Express hard provider restrictions through `allowedModels`; describe softer preferences in the task.
+Unknown keys and invalid limits fail validation. An empty eligible set stops the launch. These constraints do not turn a concrete model call into an automatic one. The catalog does not establish a latency SLA or a provider's privacy guarantees. Express hard provider restrictions through `allowedProviders`, `excludedProviders` or `allowedModels`; describe softer preferences in the task.
 
 For a persistent builtin override, put this in your user or project settings:
 

package/docs/subagents.md

@@ -76,6 +76,8 @@ Runtime-created session contexts bind single launches to their actual session or
 
 Use `subagent({action: "wait", id: taskId})` to observe an existing task in the same owner without restarting it. It uses the owner's observation budget unless explicitly overridden.
 
+When a task has settled, the launch result, `action: "wait"`, and `action: "status"` show its output after the task record: up to 16 KB of text, a `Full output:` path to a private copy of the complete result, and a `Requested output:` line naming the `output` file you asked for (background runs included). The private copies live in a temporary directory readable only by you and are removed when Atomic exits. With `outputMode: "file-only"` the text is only the saved-file reference, and the private copy holds the file's contents. A child that stops to ask a question through `contact_supervisor` settles with the question and a ready-to-run follow-up call in this output.
+
 The agent may choose foreground-first or background observation for each authorized call without asking the user merely to select a mode. When a foreground observation expires, the returned task is still running. Wait for terminal completion before using its result in dependent work. See [Choosing how long to wait](/background-tasks#choose-how-long-to-wait) for shell and subagent defaults and the separate execution-timeout behavior.
 
 User steering or an incoming Intercom ask/send admitted to the waiting parent releases its active subagent observations, including both foreground launches and `action: "wait"`. This applies to main chat and live workflow-stage chat. The parent can handle the queued message and reply without cancelling the child, closing its owner, or interrupting another owner's waits. User input yields with reason `input-needed`; Intercom coordination yields with reason `intercom-coordination`. The original task can be observed again after handling the message.

package/docs/usage.md

@@ -17,7 +17,7 @@ This page covers interactive use: the interactive loop, slash commands, the mess
 
 The interface has four main areas:
 
-- **Startup header** - shortcuts plus named lists of loaded context files, prompt templates, skills, extensions, and themes; use the expand-tools shortcut (Ctrl+O by default) to switch those lists to source paths
+- **Startup header** - shortcuts plus named lists of loaded context files, prompt templates, skills, and extensions; use the expand-tools shortcut (Ctrl+O by default) to switch those lists to source paths
 - **Messages** - user messages, assistant responses, tool calls, tool results, notifications, errors, and extension UI
 - **Editor** - where you type; border color indicates the current thinking level
 - **Footer** - working directory, session name, token/cache usage, cost, context usage, and current model
@@ -28,7 +28,7 @@ The editor can be replaced temporarily by built-in UI such as `/settings` or by
 
 The startup animation shows Atomic's identity. Press any key, including Ctrl+C, to finish it immediately and continue normal input. Quiet startup suppresses it; non-TTY sessions and `ATOMIC_REDUCED_MOTION=1` show the settled identity without animation. `NO_COLOR` removes foreground colors while retaining weight emphasis.
 
-Startup lists loaded context files, skills, prompts, extensions, and themes by name. Duplicate local extension names include path information. Expand the startup disclosure to see source paths.
+Startup lists loaded context files, skills, prompts, and extensions by name. Custom themes are not listed; choose them in `/settings`. Duplicate local extension names include path information. Expand the startup disclosure to see source paths.
 
 While the agent works, `∀` pulses beside a working message. Retry, fallback, compaction, cancellation, and error messages take precedence; approval prompts hide ordinary activity. Set `ATOMIC_REDUCED_MOTION=1` for a static indicator or `NO_COLOR` for activity without foreground colors. Extensions can [customize the indicator](/tui#pattern-4b-working-indicator-customization).
 
@@ -177,7 +177,7 @@ Tasks done without a workflow record `Assistant-workflow: inline`. Each `Assista
 
 ## Exporting and Sharing Sessions
 
-Use `/export [file]` to write a session to HTML.
+Use `/export [file]` to write a session to HTML. In the exported page, press `T` to toggle thinking, `O` to toggle tool output, and `H` to show custom messages that are hidden in the terminal. Hidden messages stay hidden until you toggle them, and selecting one in the sidebar reveals them.
 
 Use `/share` to upload a private GitHub gist with a shareable HTML link.
 

package/docs/workflows/api-reference.md

@@ -546,7 +546,7 @@ Selects the primary stage model. String values can carry the reasoning suffix de
 
 Use `model: "auto"` for prompt-based selection of an execution model and supported effort before session admission. Omission and concrete models keep prior behavior. Shared chain/parallel defaults accept `auto`; each stage receives one decision. The router sees the final supplied prompt, including interpolated inputs and supplied task context, rather than only a stage name.
 
-`modelConstraints?: ModelConstraints` applies hard restrictions to auto selection and execution/compaction fallbacks. Fields are `allowedModels?: string[]`, `allowedEfforts?: (string | null)[]`, `maxInputCost?: number`, `maxOutputCost?: number`, `minContextWindow?: number`, and `requiredInputs?: ("text" | "image")[]`. Model IDs are exact provider/model IDs. Costs are catalog USD per million tokens including pricing tiers, not task budgets. Efforts are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `null` for nonreasoning models. Empty allowlists admit nothing. Inherited and stage restrictions all hold; a task override cannot widen shared restrictions. An authored `thinkingLevel` restricts auto selection to that supported effort.
+`modelConstraints?: ModelConstraints` applies hard restrictions to auto selection and execution/compaction fallbacks. Fields are `allowedModels?: string[]`, `allowedProviders?: string[]`, `excludedProviders?: string[]`, `allowedEfforts?: (string | null)[]`, `maxInputCost?: number`, `maxOutputCost?: number`, `minContextWindow?: number`, and `requiredInputs?: ("text" | "image")[]`. Model IDs are exact provider/model IDs. Costs are catalog USD per million tokens including pricing tiers, not task budgets. Efforts are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, `max`, or `null` for nonreasoning models. Empty allowlists admit nothing. Inherited and stage restrictions all hold; a task override cannot widen shared restrictions. An authored `thinkingLevel` restricts auto selection to that supported effort.
 
 An auto stage has no session until it receives prompt text. Model-dependent operations such as `compact()` or `cycleModel()` before that point report an error; call `prompt()` first or deliberately select a concrete model with `setModel()`. Session operations after admission keep their normal behavior.
 

package/docs/workflows/authoring.md

@@ -60,13 +60,7 @@ const result = await ctx.task("analyze", {
 
 `ctx.stage("analyze", { model: "auto" }).prompt(text)` works too. Set `model: "auto"` in chain or parallel shared options to route each stage separately. The decision uses the actual supplied prompt after input interpolation and chain context expansion, eligible models and efforts, and compact dated evaluation evidence rather than full guides. It ranks up to three distinct models with an effort for each, trying them in order before remaining configured fallbacks and the current chat model. File references remain references, not guessed file contents. See [automatic model selection](/subagents/reference#automatic-model-selection) for ranking and limits.
 
-Long prompts are excerpted for model selection only; the stage still receives the full execution prompt. The router sees the beginning of the prompt, its end, and every `<keepContext>...</keepContext>` span, with each cut marked `[... truncated ...]`. The excerpt is at most about 9 KB (roughly 1,200 words) and can be smaller when many models are eligible. Hard `modelConstraints` remain enforced independently.
-
-Structure `model: "auto"` prompts so the router sees what decides the model:
-
-- Put the stage's role and objective in the first or last lines, or in a short `<keepContext>` span. Text in the unprotected middle may be cut.
-- Put bulky material (issue bodies, artifact reads, prior-stage output) in the middle, or pass it through files and `reads`.
-- Keep `<keepContext>` spans to a few lines of constraints. If the spans alone exceed the excerpt, the router receives only the start and end of the prompt, cutting through the middle of the protected text.
+A chat model reads the complete stage prompt to answer the routing questions; a classifier router such as Jev never sees it. Hard `modelConstraints` remain enforced independently. Set `taskNeeds` in the stage options when you already know the task's kind of work, difficulty, mistake cost, or need for images, a very large context or a fast answer; stating all six skips the chat model's read, and list the contenders in `modelConstraints.allowedModels` to choose them yourself.
 
 ```ts
 const prompt = [

package/docs/workflows/builtins.md

@@ -144,7 +144,7 @@ All six can run by name or as nested definitions. Prefer composition over copyin
 
 Goal keeps the literal objective and immutable acceptance criteria in a durable ledger, delegates implementation, and asks independent reviewers to inspect current changes. Its decision is `complete`, `blocked`, or `needs_human`. Resume retains the run identity and checkpointed progress without repeating completed effects.
 
-Goal reviewers derive checks from the literal objective before consulting implementation receipts, inspect the actual checkout delta, and report commands, observed output, and file:line evidence rather than internal reasoning. Shared contracts cover acceptance-matrix traceability, contract-fidelity risks, end-to-end and QA-video evidence, and independent verification. `stop_review_loop` is the authoritative convergence signal: it remains `false` for P0–P2 findings, any `required_by_objective` finding, or unproven implementation/validation requirements; it becomes `true` only when independent evidence proves the objective and only non-blocking or authorized post-approval work remains. The deterministic reducer consumes that signal without reinterpreting free-form prose.
+Goal reviewers derive checks from the literal objective before consulting implementation receipts, inspect the actual checkout delta, and report commands, observed output, and file:line evidence rather than internal reasoning. Shared contracts cover acceptance-matrix traceability, contract-fidelity risks, end-to-end and QA-video evidence, and independent verification. `stop_review_loop` is the authoritative convergence signal: it remains `false` for P0–P2 findings, any `required_by_objective` finding, or unproven implementation/validation requirements; it becomes `true` only when independent evidence proves the objective and only non-blocking or authorized post-approval work remains. The deterministic reducer consumes that signal without reinterpreting free-form prose, but a `stop_review_loop=true` vote does not count toward the reviewer quorum when the same review reports `overall_correctness: "patch is incorrect"`, `goal_oracle_satisfied: false`, or a blocking finding (P0–P2, or any `required_by_objective` finding). Ralph applies the same check to its reviews.
 Goal and Ralph worker, reviewer and final handoff prompts share [verification and evidence guidance](/workflows/verification): browser, terminal and desktop/simulator routing; environment-aware setup and truthful fallback; qlty initialization or manual offline configuration selected from user/repository priorities; and authorized native GitHub media attachment with hosted-link confirmation. Existing config, read-only tasks and authoritative project checks remain protected. Explicit task-scoped inline/no-workflow steering overrides an existing execution plan and requires safe reconciliation of active work before continuing without duplicate execution.
 Both workflows also share repository-intent mining guidance: implementers and reviewers infer maintainer and requesting-user conventions from repository behavior — git history (including `git log --show-signature`), merged PRs, issues and their comments, review comments, commit subjects and trailers, and CI/branch-protection config — covering norms written docs rarely state, such as commit signing, message style and issue linking, changelog discipline, and review etiquette. The dominant, recent, intentional pattern wins over accidental drift, the requesting user's own activity weighs highest, implementers match the inferred conventions (an unsigned commit in a signed history is a miss, not a preference), and reviewers report deviations as convention findings. Behavioral evidence fills contract gaps; it never overrides the literal objective, acceptance criteria, or explicit `AGENTS.md`/`CLAUDE.md` guidance.
 Goal and Ralph share the same low-confidence finding re-verification and per-round convergence evidence, documented under [`ralph`](/workflows/builtins#ralph).

package/docs/workflows/reliable-design.md

@@ -433,7 +433,7 @@ Do not tag bulk context. Protected lines count against the keep target rather th
 
 Every builtin does this for its own invariants: the steering propagation contract, the literal objective contract, scope discipline, worktree discipline, per-run acceptance criteria, and the research/review role constraints are all protected. See [Compaction](/compaction#keepcontext-tags) for the retention mechanism.
 
-The same tags guide automatic model selection. A `model: "auto"` stage routes on an excerpt of its prompt: the beginning, the end, and every protected span. Short spans that name the role and objective keep that decision grounded. Large spans crowd out the beginning and end, and spans that alone exceed the excerpt are cut through the middle. See [automatic stage model selection](/workflows/authoring#automatic-stage-model-selection).
+For automatic model selection, a chat model reads the whole `model: "auto"` stage prompt; stating `taskNeeds` in the stage options saves that read. See [automatic stage model selection](/workflows/authoring#automatic-stage-model-selection).
 
 #### Tagging is not only for workflow authors
 

package/examples/extensions/custom-provider-gitlab-duo/test.ts

@@ -1,16 +1,16 @@
 /**
  * Test script for GitLab Duo extension
- * Run: npx tsx test.ts [model-id] [--thinking]
+ * Run: node test.ts [model-id] [--thinking]
  *
  * Examples:
- *   npx tsx test.ts                              # Test default (claude-sonnet-4-5-20250929)
- *   npx tsx test.ts gpt-5-codex                  # Test GPT-5 Codex
- *   npx tsx test.ts claude-sonnet-4-5-20250929 --thinking
+ *   node test.ts                              # Test default (claude-sonnet-4-5-20250929)
+ *   node test.ts gpt-5-codex                  # Test GPT-5 Codex
+ *   node test.ts claude-sonnet-4-5-20250929 --thinking
  */
 
+import { getAgentDir } from "@bastani/atomic";
 import { type Api, type Context, type Model, registerApiProvider, streamSimple } from "@bastani/pi-ai/compat";
 import { readFileSync } from "fs";
-import { getAgentDir } from "packages/coding-agent/src/config.js";
 import { join } from "path";
 import { MODELS, streamGitLabDuo } from "./index.ts";
 

package/examples/extensions/gondolin/package.json

@@ -6,7 +6,7 @@
 	"scripts": {
 		"clean": "echo 'nothing to clean'",
 		"build": "echo 'nothing to build'",
-		"check": "tsgo -p ../../../test/tsconfig.remote-examples.json"
+		"check": "tsc -p ../../../test/tsconfig.remote-examples.json"
 	},
 	"dependencies": {
 		"@earendil-works/gondolin": "0.12.0"

package/examples/rpc-client.ts

@@ -2,7 +2,7 @@
  * Run one prompt through an Atomic RPC child process.
  *
  * Build the coding-agent package first, then run:
- * npx tsx examples/rpc-client.ts "Explain this repository"
+ * node examples/rpc-client.ts "Explain this repository"
  *
  * RpcClient launches the CLI under Bun by default; pass
  * `runtimeExecutable: process.execPath` to run it under Node instead.

package/examples/rpc-extension-ui.ts

@@ -5,7 +5,7 @@
  * Demonstrates how to build a custom UI on top of the RPC protocol,
  * including handling extension UI requests (select, confirm, input, editor).
  *
- * Usage: npx tsx examples/rpc-extension-ui.ts
+ * Usage: bun examples/rpc-extension-ui.ts
  *
  * Slash commands:
  *   /select  - demo select dialog