@bastani/atomic 0.9.25-alpha.2 → 0.9.25-alpha.4

package/docs/mcp-servers.md

@@ -1,111 +1,232 @@
 ---
 title: "MCP Servers"
-description: "Configure MCP servers, discover tools, and authenticate connections."
+description: "Configure MCP servers, discover tools and resources, and authenticate connections."
 ---
 
 # MCP Servers
 
-Atomic includes MCP support in both npm and binary installations. No separate extension install is needed. Use `/mcp` to inspect servers or `/mcp setup` to configure them.
+Atomic includes [Model Context Protocol](https://modelcontextprotocol.io) support in npm and binary installations. It connects to servers over stdio or streamable HTTP. No separate extension install is needed.
 
-## Configure a server
+## Quick setup
 
-Put shared project configuration in `.mcp.json` at your project root:
+Add a local server, check the connection, then start Atomic:
+
+```sh
+atomic mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
+atomic mcp list
+atomic
+```
+
+For a remote server:
+
+```sh
+atomic mcp add docs --url https://example.com/mcp --bearer-token-env-var DOCS_TOKEN
+```
+
+Commands write user-level configuration by default. Add `--local` or `-l` to write `.atomic/mcp.json` in the current project instead. Start Atomic and grant project trust before using project servers.
+
+Use `/mcp` to inspect connections and manage servers. After changing configuration outside the session, run `/reload` or restart Atomic.
+
+## Configure servers
+
+Atomic reads user-level servers from `~/.atomic/agent/mcp.json` and project servers from `.atomic/mcp.json`. Project configuration is read only after [project trust](/security) is granted. A project entry replaces a user-level entry with the same name.
+
+Both files use a top-level `mcpServers` object. Keep personal servers and credentials in the user-level file. `ATOMIC_CODING_AGENT_DIR` relocates the Atomic agent directory.
+
+Stdio servers use `command`, `args`, `env`, and `cwd`. `command` is one executable, not a shell command string. Relative `cwd` values resolve against the session directory.
+
+HTTP servers use `url`, optional `headers`, and optional `oauth`. For bearer authentication:
 
 ```json
 {
   "mcpServers": {
-    "my-server": {
-      "command": "path/to/mcp-server",
-      "args": []
+    "docs": {
+      "url": "https://example.com/mcp",
+      "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" },
+      "description": "Search and read the product documentation"
     }
   }
 }
 ```
 
-Replace `command` and `args` with your server's launch instructions. For a remote HTTP server, use `url` instead:
+URLs support `${NAME}` and `$env:NAME` environment references. Atomic resolves them in memory before validating the URL, without rewriting configuration files. `env`, `headers`, and `oauth.clientSecret` support `${NAME}` environment references and whole-value `!command` expressions, for example `"Authorization": "!echo Bearer $(gh auth token)"`. Only use commands from configuration you trust.
+
+Both transports support:
+
+- `timeout`: per-request inactivity timeout in seconds, default 60. Progress notifications reset it; it is not a total execution deadline.
+- `enabled: false`: keep a server listed without connecting to it.
+- `exposure` and `toolExposure`: control how tools reach the model.
+- `description`: a short server summary for the system prompt, tool search, and `describeNamespace()`. Without it, Atomic uses the first line of server instructions once connected.
+
+Server names may contain letters, digits, `_`, and `-`. Names that differ only in `-` and `_` identify the same namespace. Invalid entries are reported and skipped without preventing other servers from connecting.
+
+`type` is optional: `command` selects stdio and `url` selects streamable HTTP. If present, it must be `stdio`, `http`, or `streamable-http`. SSE is not supported; use the server's streamable HTTP endpoint, commonly `/mcp` rather than `/sse`.
+
+### Servers from packages and extensions
+
+Installed [packages](/packages/authoring#mcp-servers) and extensions can contribute servers with the same configuration shape. File-configured servers take precedence over contributions with the same normalized name. Project packages load only after the project is trusted.
+
+`/mcp` shows each server's source. Enabled-state and exposure changes for file-configured servers are saved without replacing unrelated configuration. Changes to extension-contributed servers apply to the current session.
+
+## Manage servers
+
+`/mcp` opens a server manager with connection state, tool count, exposure, and source. Select a server to inspect tools and connection details, sign in or out, reconnect, enable or disable it, or change exposure. Servers that need attention appear first.
+
+| Command | Action |
+| --- | --- |
+| `/mcp` | Open the manager in the TUI, or show status outside it. |
+| `/mcp login [server]` | Sign in with OAuth. |
+| `/mcp logout [server]` | Remove stored OAuth credentials. |
+| `/mcp reconnect [server]` | Reconnect a server and refresh its tools. |
+
+Command completion suggests actions and eligible server names. When a server name is omitted, Atomic selects an eligible server when the choice is unambiguous; otherwise it asks you to choose. Session login requires an interactive UI. Shell login opens the browser without starting a session; authenticate before unattended work.
+
+Enabled servers connect in the background when a session starts. The first prompt waits up to 10 seconds for servers with `direct` tools. Codemode, tool search, and resource calls wait for the servers they need. A dropped connection reconnects on the next call. Changes announced by a server update the available tools; withdrawn tools become unreachable.
+
+### Shell commands
+
+Shell commands use file-configured servers and do not load extensions:
+
+```sh
+atomic mcp add <server> [options] -- <command> [args...]
+atomic mcp add <server> [options] --url <url>
+atomic mcp remove <server> [-l]
+atomic mcp list [--json]
+atomic mcp login <server> [--timeout <seconds>]
+atomic mcp logout <server>
+```
+
+`add` replaces an existing entry of the same name. `add` and `remove` accept `--local` (`-l`) for the project file. For stdio, use repeatable `--env KEY=VALUE` and `--cwd`. For HTTP, use repeatable `--header KEY=VALUE`, `--bearer-token-env-var NAME`, and `--oauth-client-id`, `--oauth-client-secret`, `--oauth-callback-port`, or `--oauth-client-name`. Both transports accept `--exposure` and `--description`. Run `atomic mcp --help` for usage.
+
+`list` connects to enabled servers and reports state, tools, and errors; it exits with status 1 for invalid configuration or an enabled server that is not connected. `--json` produces a machine-readable report. Login waits up to 300 seconds by default; `--timeout` changes that browser-login budget, not the server request timeout. A running session uses new credentials on its next turn.
+
+## Find and call tools
+
+Tools are named `mcp__<server>__<tool>`, with punctuation replaced by `_`. Names that collide after normalization receive deterministic hash suffixes. Use names returned by discovery rather than constructing them yourself.
+
+### Control tool exposure
+
+| Exposure | Behavior |
+| --- | --- |
+| `codemode`, the default | Callable from codemode scripts, but not declared to the model or listed in the codemode description. Discover with `searchTools()`, `describeTool()`, or `ALL_TOOLS`. |
+| `deferred` | Not declared until `tool_search` loads a matching tool for the next model call. |
+| `direct` | Declared like a built-in tool and also callable from codemode. |
+| `hidden` | Unreachable. |
+
+`codemode-deferred` is accepted as an alias for `codemode`. Atomic activates `codemode` for codemode servers and `tool_search` for deferred servers. Set `"autoEnableCodemode": false` beside `mcpServers` to prevent automatic codemode activation. A project value overrides a user-level value.
+
+`toolExposure` overrides individual tools. Keys are original server tool names or patterns where `*` matches any characters. Exact names win; among patterns, the first match wins:
 
 ```json
 {
   "mcpServers": {
-    "my-server": {
-      "url": "https://example.com/mcp"
+    "github": {
+      "url": "https://api.githubcopilot.com/mcp/",
+      "exposure": "deferred",
+      "toolExposure": {
+        "search_code": "direct",
+        "get_*": "codemode",
+        "delete_*": "hidden"
+      }
     }
   }
 }
 ```
 
-Remote `url` values support `${VAR}` and `$env:VAR` environment variable interpolation in both project and user configuration. For example, commit this server entry and set `MY_SERVICE_URL` and `MY_SERVICE_TOKEN` in the environment that launches Atomic:
+Codemode and deferred tools can be reached through either indirect mechanism. Server summaries appear in the `mcp_servers` system prompt section. Scripts can read instructions and tool names with `describeNamespace("mcp__github")`.
 
-```json
-{ "url": "${MY_SERVICE_URL}/mcp", "auth": "bearer", "bearerTokenEnv": "MY_SERVICE_TOKEN" }
-```
+Codemode receives the complete MCP result, including `content`, `structuredContent`, and `isError`. Text over 20 KB is shortened for the model, with the complete text saved to a temporary file named in the result. Every MCP call passes through Atomic's tool pipeline, including permission hooks.
 
-With `MY_SERVICE_URL=https://example.com`, the endpoint is `https://example.com/mcp`. Unset variables become empty strings.
+## Use resources
 
-The resolved endpoint must be a non-empty HTTP(S) URL. If Atomic reports a configuration error before connecting, check the variables in its environment and the URL suffix. Restart Atomic after changing its environment.
+When a connected server offers resources, Atomic registers:
 
-Atomic reads configuration in this order, with later files overriding earlier settings:
+- `list_mcp_resources`, to list resources. Use `server` for one server and `cursor` for its next page; without `server`, it lists resources across servers.
+- `list_mcp_resource_templates`, to list URI templates.
+- `read_mcp_resource`, to read by `server` and `uri`. Text and images reach the model directly; other binary content is saved to a temporary file.
 
-1. `~/.config/mcp/mcp.json`, shared user-global configuration.
-2. `~/.atomic/agent/mcp.json`, Atomic user-global overrides.
-3. `.mcp.json`, shared project configuration.
-4. `.atomic/mcp.json`, Atomic project overrides.
+These tools reach enabled, non-hidden resource servers. Their exposure is the widest exposure among those servers. Resource links in tool results identify the server and `read_mcp_resource`.
 
-The Atomic agent directory can be relocated with `ATOMIC_CODING_AGENT_DIR`. Use `/mcp setup` to inspect detected configuration and preview imports from other hosts before writing changes.
+MCP Apps resources (`ui://` URIs or `text/html;profile=mcp-app`) are omitted because Atomic does not render them.
 
-Servers connect lazily by default. Adding a server does not require an immediate connection at startup.
+## Authentication
+
+For a remote OAuth server, configure its URL and run `/mcp login my-server`, or select **Sign in** in `/mcp`. Atomic opens the authorization page and displays a clickable URL. If the browser runs on another machine, paste the complete URL it was redirected to into the sign-in prompt. Treat authorization and redirect URLs as sensitive.
 
-## Servers from packages and extensions
+Atomic registers OAuth clients as `atomic`, stores credentials in `~/.atomic/agent/mcp-auth.json`, and refreshes tokens when they expire or are rejected. A successful sign-in reconnects the server. If additional scope is required, sign in again. `/mcp logout my-server` or `atomic mcp logout my-server` deletes stored credentials. Old adapter credential files are not imported; sign in through the native client.
 
-Installed [packages](/packages/authoring#mcp-servers) and extensions can contribute MCP servers. Contributed servers sit below all four configuration files: a server with the same name in any of them replaces the contributed entry completely. To turn a contributed server off, give its name an entry with only `disabled`:
+OAuth applies to HTTP servers without an `Authorization` header or provider-token configuration. For a pre-registered client:
 
 ```json
 {
   "mcpServers": {
-    "acme-search": { "disabled": true }
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauth": {
+        "clientId": "my-client",
+        "clientSecret": "${EXAMPLE_SECRET}",
+        "callbackPort": 8765,
+        "scope": "read write"
+      }
+    }
   }
 }
 ```
 
-`"disabled": true` removes any server from the effective configuration, contributed or not.
+`clientSecret` is optional. `callbackPort` uses `http://127.0.0.1:<port>/callback`. For another registered redirect URI, set `callbackUrl`; it must use HTTP on `localhost`, `127.0.0.1`, or `[::1]`. Atomic sends it as written. If it has no port, Atomic adds `callbackPort` or a free port. The URI must match the client's registration.
 
-`/mcp` shows where each contributed server came from next to its name: `(package npm:@acme/tools)` for a package manifest, `(extension from package npm:@acme/tools)` for a package's extension, or `(extension /path/to/extension.ts)` for a local extension. Connection errors name the same source. Turning on direct tools for a contributed server in `/mcp` copies its definition into `~/.atomic/agent/mcp.json`, where it then overrides the contributed version.
+Use `oauth.clientName` when a server requires a known registration name. Sign out before signing in again to register with a changed name. Use `oauth.scope` for servers that do not advertise their required scopes; later scope requests are added to it.
 
-To choose which servers one package contributes, add `mcpServers` patterns to its [package filter](/packages/reference#package-filtering). Project packages contribute servers only after the project is trusted. Workflow stages see the same contributed servers as the session that starts them.
+### Override OAuth authorization server discovery
 
-## Find and call tools
+If a server advertises the wrong authorization server or none, set `oauth.authServerMetadataUrl` to a trusted RFC 8414 or OpenID Connect metadata document:
+
+```json
+{
+  "mcpServers": {
+    "example": {
+      "url": "https://mcp.example.com/mcp",
+      "oauth": { "authServerMetadataUrl": "https://example.okta.com/.well-known/openid-configuration" }
+    }
+  }
+}
+```
+
+Atomic uses the document instead of authorization server discovery and trusts its issuer as configured. Point it only at a document you trust. The URL must use HTTPS, except for HTTP on `localhost`, `127.0.0.1`, or `[::1]`.
+
+Atomic rejects authorization responses whose `iss` names another issuer, before exchanging the code. If the server promises the RFC 9207 issuer parameter, the response must include it. Empty or null optional token and registration fields count as absent. An empty refresh token does not replace a previously stored one, and `expires_in: null` does not immediately expire the access token.
 
-The `mcp` gateway discovers tools without adding every server's full tool definitions to the session:
+### Authenticate with a provider login
 
-```js
-mcp({ server: "my-server" })
-mcp({ search: "search" })
-mcp({ describe: "my_server_search" })
-mcp({ tool: "my_server_search", args: '{"query":"example"}' })
+An HTTP server can use your current provider login token instead of MCP OAuth:
+
+```json
+{ "mcpServers": { "radius": { "url": "https://radius.example/mcp", "auth": { "provider": "radius" } } } }
 ```
 
-Use the tool names returned by discovery. `args` is a JSON string, not an object. Search may connect configured servers when their metadata has not yet been cached.
+Atomic reads the current token for every request and does not copy it into MCP credential storage. If the token is missing or rejected, run `/login <provider>` and retry the MCP call.
 
-To expose a server's tools directly in the agent's tool list, add `"directTools": true` to that server's configuration. To expose only selected tools, set `directTools` to an array of the original MCP tool names. The default is gateway-only access.
+Because the credential goes to the configured server, provider-token authentication has these limits:
 
-In a headless SDK session, cached direct tools are available at startup, but discovery does not connect uncached lazy servers. Call the `mcp` gateway when you need them. Set the server's `lifecycle` to `"eager"` or `"keep-alive"` if it must connect during startup.
+- It is accepted only from global configuration and extension registrations, not project configuration or package manifests.
+- The URL must use HTTPS, except for HTTP on `localhost`, `127.0.0.1`, or `[::1]`.
+- Tokens are sent only to the server's origin. Only same-origin `307` and `308` redirects are followed.
 
-## Authentication
+## Native configuration only
 
-For an OAuth server, run `/mcp-auth my-server` in an interactive session. You can also select the server in `/mcp` and press Enter or `Ctrl+A`. Run `/mcp logout my-server` to remove stored OAuth credentials and disconnect.
+The old adapter has been replaced by the native client. Only `~/.atomic/agent/mcp.json` and trusted `.atomic/mcp.json` files are read; shared configuration files and client imports are not supported. Use the native fields documented above. Old adapter fields are not translated, and old OAuth credential files are not imported.
 
-Automatic OAuth is opt-in through `settings.autoAuth`. Browser-based authorization requires an interactive session; authenticate before running unattended work.
+Tools use `mcp__<server>__<tool>` names and default to `codemode` exposure. The old gateway tool, configurable prefixes, lazy/idle lifecycle settings, metadata cache, SSE transport, MCP Apps rendering, and setup command are not available. All enabled servers connect in the background.
 
 ## Troubleshooting
 
-- Run `/mcp` to check server status and `/mcp tools` to list available tools.
-- After editing configuration manually, restart Atomic to load it. Use `/mcp reconnect my-server` to reconnect a configured server and refresh its tools.
-- If Atomic cannot open the authorization browser, use the complete URL it displays for manual login. **Treat it as sensitive**: it includes all paths, parameters, and any credentials. Login instructions are not redacted; transport and RPC error diagnostics are.
-  Browser-launch failure cancels the pending attempt, so its callback cannot complete authentication. Check your default browser and retry `/mcp-auth my-server`.
-- If a local server cannot start, check its executable, arguments, working directory, and required environment variables. Server configuration supports `cwd` and `env`.
-- If authorization fails, run `/mcp-auth my-server` again. Check the remote server's URL and authentication requirements.
-- For slow tools, a server's `timeoutMs` controls the inactivity timeout. Progress notifications reset it; it is not a total execution deadline.
+- Run `/mcp` to inspect connection errors, server tools, and the tail of a failed stdio server's stderr.
+- After editing configuration, run `/reload` or restart Atomic. Use `/mcp reconnect my-server` to retry a connection and refresh tools.
+- For a missing tool, check server and per-tool exposure. `hidden` tools cannot be called; codemode or deferred tools need an active discovery tool.
+- For OAuth redirect failures, check `callbackPort` and `callbackUrl` against the registered URI. Over SSH, paste the complete redirected URL into the waiting sign-in prompt.
+- For an issuer mismatch, check the authorization server's metadata and callback configuration before retrying. Do not disable issuer checks to accept an unexpected response.
+- For slow calls, adjust `timeout` in seconds. Progress resets this inactivity timer.
 
 ## Local documentation
 
-This guide is available at `docs/mcp-servers.md` under Atomic's installation root in both npm and binary installations. The session's documentation instructions provide the absolute docs directory. Read this guide there rather than looking inside the bundled extension directory.
+This guide is available at `docs/mcp-servers.md` under Atomic's installation root in npm and binary installations. The session's documentation instructions provide the absolute docs directory.

package/docs/packages/authoring.md

@@ -41,14 +41,14 @@ A package can contribute [MCP servers](/mcp-servers) with `mcpServers`. Point it
 {
   "atomic": {
     "mcpServers": {
-      "acme-search": { "url": "https://mcp.acme.dev", "auth": "bearer", "bearerTokenEnv": "ACME_TOKEN" },
+      "acme-search": { "url": "https://mcp.acme.dev", "headers": { "Authorization": "Bearer ${ACME_TOKEN}" } },
       "acme-local": { "command": "node", "args": ["./dist/server.js"], "cwd": "." }
     }
   }
 }
 ```
 
-Entries use the same schema as `mcp.json`, including `${VAR}` interpolation, `lifecycle`, and `timeoutMs`. A relative `cwd` is resolved against the package root, so `"cwd": "."` lets a stdio server run files shipped in the package. MCP servers are only read from the manifest, never from a convention directory.
+Entries use the same schema as `mcp.json`, including URL environment-variable interpolation, tool `exposure`, per-tool `toolExposure`, and request `timeout` in seconds. A relative `cwd` is resolved against the package root, so `"cwd": "."` lets a stdio server run files shipped in the package. MCP servers are only read from the manifest, never from a convention directory. Package manifests cannot select provider login credentials with `auth.provider`.
 
 Contributed servers have the lowest precedence: users can replace or disable one by name in their own MCP configuration, and filter them with `mcpServers` patterns in settings. Project packages contribute servers only in trusted projects. For a server whose configuration is computed at runtime, call [`pi.registerMcpServer()`](/extensions/api-reference#pi-registermcpserver-name-config) from an extension.
 

package/docs/providers.md

@@ -124,12 +124,20 @@ Anthropic fast mode delivers up to 2.5x higher output tokens per second at twice
 
 Anthropic subscription auth is active for Claude Pro/Max accounts. Third-party harness usage draws from [extra usage](https://claude.ai/settings/usage) and is billed per token, not against Claude plan limits.
 
+Run `/login anthropic` and choose subscription authentication. **Browser login (default)** uses a local callback and still accepts a pasted redirect URL. Choose **Copy code login (headless)** when your browser runs on another machine: complete sign-in in that browser, then paste the `code#state` value Anthropic displays into Atomic. This method does not need a reachable local callback.
+
 For gateway-issued Anthropic bearer credentials, set `ANTHROPIC_AUTH_TOKEN` without `ANTHROPIC_API_KEY` or `ANTHROPIC_OAUTH_TOKEN`. A populated bearer token counts as configured Anthropic authentication, so `/model`, saved/default selection, cycling, RPC catalogs, and isolated model pickers keep Anthropic models available. Atomic sends it as `Authorization: Bearer …` for normal turns, branch summaries, and Verbatim Compaction without replacing caller-supplied custom headers.
 
 Claude Opus 5 is available from the bundled/dynamic Anthropic and Amazon Bedrock catalogs. With bearer-only Anthropic auth, select the exact `anthropic/claude-opus-5-*` entry through `/model`; Bedrock uses its catalog-advertised inference profile. `xhigh` appears only when the chosen entry advertises it. Bedrock requests retain adaptive thinking, prompt caching, and AWS validation/error details from the provider runtime.
 
 `ANTHROPIC_AUTH_TOKEN` is specifically for Anthropic-compatible gateways that require a bearer header. It does not synthesize an API key or `x-api-key`, and callers may still add independent custom headers/base URLs through `models.json` or an extension. Empty environment variables do not count as configured. If token and API-key sources are both configured, normal credential resolution rules apply; avoid setting both accidentally.
 
+### Anthropic workload identity federation
+
+With no Anthropic key, bearer token, or login configured, Atomic uses workload identity federation when `ANTHROPIC_FEDERATION_RULE_ID`, `ANTHROPIC_ORGANIZATION_ID`, and `ANTHROPIC_IDENTITY_TOKEN_FILE` are all set. The Anthropic SDK exchanges the identity token for a short-lived access token and refreshes it, re-reading the token file each time, so keep that file fresh in long sessions. `ANTHROPIC_SERVICE_ACCOUNT_ID` and `ANTHROPIC_WORKSPACE_ID` are sent when set.
+
+Keys, `ANTHROPIC_AUTH_TOKEN`, and custom authorization headers take precedence. Federation applies only to the `anthropic` provider, not to other Anthropic-compatible providers.
+
 ### GitHub Copilot
 
 - Press Enter for github.com, or enter your GitHub Enterprise Server domain

package/docs/sdk/reference.md

@@ -849,6 +849,22 @@ type EditDiffResult
 SessionManager
 SettingsManager
 
+// Workflow run control (session.workflows)
+type SessionWorkflows
+type WorkflowRunSummary
+type WorkflowRunDetail
+type WorkflowRunControlOutcome
+type WorkflowRunControlFailedRun
+WorkflowRunControlError
+WorkflowRunNotFoundError
+WorkflowRunOwnershipError
+WorkflowRunNotResumableError
+WorkflowStageNotFoundError
+WorkflowStageAmbiguousError
+WorkflowStageResumeUnsupportedError
+WorkflowRunDatabaseError
+WorkflowRunControlUnavailableError
+
 // Tool factories
 createCodingTools
 createReadOnlyTools

package/docs/sdk.md

@@ -210,7 +210,7 @@ To continue a saved run in another session:
 
 1. Keep its definition and durable storage available.
 2. Bind the new host.
-3. Use `/workflow resume <run-id>` or the workflow tool's `resume` action.
+3. Use `session.workflows.resume(runId)` ([Workflow run control](#workflow-run-control)), `/workflow resume <run-id>`, or the workflow tool's `resume` action.
 
 Rebinding alone does not reopen a saved run. See [workflow operations](/workflows/operations) for inspection, graceful quit, and resume.
 
@@ -226,6 +226,69 @@ Rebinding host callbacks preserves pending MCP OAuth ownership. Authorization st
 
 Web provider configuration caches are session-local. Configuration discovery and environment keys are unchanged; create a new session to pick up changed cached settings. GitHub extraction returns the owned clone path for use with file tools, so callers need not predict its directory.
 
+### Workflow run control
+
+`session.workflows` manages the workflow runs that this session owns, without slash commands or the model-facing `workflow` tool. It uses the same run-control service as the tool, so ownership and durability rules are identical: a run owned by another session, or executing in another live Atomic process, stays read-only here.
+
+```typescript
+interface SessionWorkflows {
+  listRuns(filter?: { status?: WorkflowRunFilterStatus }): Promise<readonly WorkflowRunSummary[]>;
+  getRun(runId: string): Promise<WorkflowRunDetail>;
+  getStages(runId: string, filter?: { status?: WorkflowStageStatus }): Promise<readonly WorkflowRunStageSummary[]>;
+  pause(runId: string, options?: { stageId?: string }): Promise<WorkflowRunControlOutcome>;
+  pause(target: { all: true }): Promise<WorkflowRunControlOutcome>;
+  quit(target: string | { all: true }): Promise<WorkflowRunControlOutcome>;
+  resume(runId: string, options?: { stageId?: string; message?: string }): Promise<WorkflowRunControlOutcome>;
+}
+```
+
+`listRuns()` returns the same per-run data as `workflow status`: id, workflow name, status, active stages, and unanswered prompts (`awaitingInput`). Run IDs accept the full UUID or a unique 8-character prefix. `getRun()`, `getStages()`, `pause()` and `quit()` resolve a prefix against the runs this session holds and reject it at once when none matches, so pass the full UUID for a run recorded by an earlier process. `pause`, `quit` and `resume` resolve with the tool's acknowledged outcome: `action`, `runId` (`--all` for a batch), a `status` of `ok`, `running`, `paused`, `partial`, `noop` or `cancelled`, and a human-readable `message`. A `noop` means the request was understood and found nothing to change, such as pausing a run that already ended. A `partial` outcome means part of the request took effect. For `pause({ all: true })` and `quit({ all: true })`, `partial` means this call stopped at least one run and others are still active: `failedRuns` lists each run that is still active with its `runId`, a `reason` (for example `pause_failed` or `no_active_stages`) and a `message`, so check `outcome.status === "partial"` before treating a batch stop as complete. If active runs could not be stopped and this call stopped none, the call rejects with `WorkflowRunControlError` (`WORKFLOW_RUN_CONTROL_FAILED`) whose `failedRuns` carries the same list, even when other runs were already paused. Runs that are already paused or already ended are not failures, and a batch with no active run left to stop resolves as a `noop`. Call `getRun()` before retrying.
+
+Pausing a run doesn't park a stage that is waiting on a prompt. Such a run reports `paused` and counts as already paused, because nothing in it advances on its own. If your host then answers that prompt, the stage can continue its turn before you call `resume`. To keep a paused run fully stopped, hold prompt answers until you resume it.
+
+Requests that cannot be carried out reject with a subclass of `WorkflowRunControlError`. Branch on `code` or use `instanceof`:
+
+| Class | `code` | Meaning |
+| --- | --- | --- |
+| `WorkflowRunNotFoundError` | `WORKFLOW_RUN_NOT_FOUND` | The run ID is unknown or malformed, or a prefix is ambiguous or matches no run in this session. |
+| `WorkflowRunOwnershipError` | `WORKFLOW_RUN_OWNED_ELSEWHERE` | The run belongs to another session, or is running in another live Atomic process. Control it from its owner. |
+| `WorkflowRunNotResumableError` | `WORKFLOW_RUN_NOT_RESUMABLE` | The run completed, was killed, or has no durable progress to resume. |
+| `WorkflowStageNotFoundError` | `WORKFLOW_STAGE_NOT_FOUND` | `stageId` matches no stage of the run, or the stage has no control to pause. |
+| `WorkflowStageAmbiguousError` | `WORKFLOW_STAGE_AMBIGUOUS` | `stageId` matches more than one stage; pass a more specific identifier. |
+| `WorkflowStageResumeUnsupportedError` | `WORKFLOW_STAGE_RESUME_UNSUPPORTED` | A durable run resumes as a whole; call `resume()` without `stageId`. |
+| `WorkflowRunDatabaseError` | `WORKFLOW_RUN_DATABASE` | Workflow durability is unavailable, including when the database cannot be inspected to check a run's owner during `pause()` or `quit()`. Restore the database, then inspect the run before retrying. |
+| `WorkflowRunControlError` | `WORKFLOW_RUN_CONTROL_FAILED` | Another failure; `message` explains it. |
+| `WorkflowRunControlUnavailableError` | `WORKFLOW_RUN_CONTROL_UNAVAILABLE` | The workflows package is disabled, or the session was disposed. |
+
+Each error carries the `runId` when one applies. A refused batch also carries `failedRuns`.
+
+A host with a stop button can pause its session's runs and resume the same runs later:
+
+```typescript
+import { createAgentSession, WorkflowRunControlError } from "@bastani/atomic";
+
+const { session } = await createAgentSession();
+
+async function onStopClicked() {
+  const outcome = await session.workflows.pause({ all: true });
+  showStatus(outcome.message);
+}
+
+async function onResumeClicked() {
+  for (const run of await session.workflows.listRuns({ status: "paused" })) {
+    try {
+      const outcome = await session.workflows.resume(run.runId);
+      showStatus(`${run.name}: ${outcome.message}`);
+    } catch (error) {
+      if (!(error instanceof WorkflowRunControlError)) throw error;
+      showStatus(`${run.name}: ${error.code}: ${error.message}`);
+    }
+  }
+}
+```
+
+`pause` holds the live run and keeps it resumable in this process; `quit` retires the executor at a durability boundary so a later process can resume it. After `quit`, or when resuming a run from a previous process, `resume` follows the durable resume path: keep the workflow definition and durable storage available. See [pausing, quitting, and resuming](/workflows/operations#pausing-quitting-and-resuming) for what each action guarantees. To watch runs change instead of polling `listRuns()`, use the observation contract in [Workflow activity and lifecycle hooks](/extensions/events#workflow-activity-and-lifecycle-hooks).
+
 ### Workflow and subagent children
 
 Children inherit the invoking session's model/auth runtime, settings, agent directory, human-input callbacks, and diagnostic sink. Choosing a child model or fallback does not switch to global credentials.
@@ -275,6 +338,9 @@ interface AgentSession {
   sessionFile: string | undefined;
   sessionId: string;
 
+  // Typed control of the workflow runs this session owns
+  readonly workflows: SessionWorkflows;
+
   // Model and thinking control
   setModel(model: Model): Promise<void>;
   setThinkingLevel(level: ThinkingLevel): void;

package/docs/settings.md

@@ -476,6 +476,8 @@ A list containing only modifiers starts from Atomic's standard defaults. Modifie
 
 Plain names establish a replacement list before its modifiers apply. A project list of only modifiers layers over the global selection. A project list with plain names, or an empty list, replaces the global selection. For example, global `["read", "bash"]` plus project `["-bash", "+ls"]` resolves to `["read", "ls"]`.
 
+`/reload` enables tools newly added to `defaultTools`. It does not disable removed tools or re-enable unchanged tools you turned off during the session. Explicit `--tools`, `--no-tools`, and `--no-builtin-tools` choices override the setting on reload too; excluded tools remain excluded.
+
 `codemode` and `tool_search` are built-in extension tools registered inactive. Add `"+codemode"` or `"+tool_search"` to `defaultTools` to activate them alongside ordinary defaults. See [codemode](/tools#codemode) and [tool search](/tools#tool_search) for usage and safety boundaries.
 
 ### Sessions

package/docs/tools.md

@@ -41,16 +41,22 @@ Use `text(value)`, `image(dataUrlOrImageContent)`, `console.log(...)`, or a top-
 return await tools.read({ path: "README.md" });
 ```
 
+`image()` accepts base64 PNG, JPEG, GIF, or WebP data URLs and MCP image content. It detects the MIME type from the data, ignores an incorrect supplied type, and rejects malformed base64 or unsupported formats before returning an image. Remote HTTP image URLs are not supported; fetch the image through a permitted tool first.
+
 There is no default deadline. Text output defaults to 10,000 estimated tokens; longer output keeps its start and end and, when saving succeeds, names a temporary file containing the full text. Failed scripts retain partial output and report the error. Unawaited calls are cancelled when a script ends; await work you need to finish.
 
 Tools with `outputSchema` return their `structuredContent` to scripts, including structured error results. Other tools return text and throw on errors. Completed `bash` calls provide structured output as described in the [SDK reference](/sdk/reference#bash-tool-behavior).
 
 `ALL_TOOLS`, `searchTools(query, { limit, namespace })`, and `describeTool(name)` discover the currently permitted tools. `store(key, value)` and `load(key)` preserve JSON values across successful calls on the current session branch, including after resume. Failed scripts discard store writes, not tool side effects. `models.getModelsOfType`, `getAvailableOfType`, and `getModelOfType` expose public catalog metadata; `models.classify(model, context)` calls a registered classifier with host-resolved credentials, at most four concurrently. Reported classifier usage contributes to the script's session cost.
 
+Use `await describeNamespace(name)` to retrieve a callable tool namespace's `{ name, description?, instructions?, tools }`, or `undefined` when it is unavailable. Namespace instructions are returned on request rather than included in inline listings. `searchTools()` also searches those instructions; pass `{ namespace: name }` to restrict the search.
+
 Set [codemode settings](/settings#tools) to control inline declaration size and whether ordinary direct tool declarations remain visible. Atomic's existing [MCP host](/mcp-servers) remains the only MCP connection/configuration owner: codemode calls the permitted gateway or direct tools, not a second MCP host. Use MCP discovery for server tools not yet registered in the session.
 
 ## `tool_search`
 
+Deferred tools and their namespaces are omitted from codemode's inline catalog. Discover them with `searchTools()`, `describeNamespace()`, or `ALL_TOOLS`; `tool_search` can load matching registered tools for direct calls.
+
 `tool_search` is inactive by default. Enable it with `"defaultTools": ["+tool_search"]` or include it in `--tools`. It ranks currently registered `codemode` and `deferred` tools by their metadata and activates matching tools for the next model call. It does not bypass session tool restrictions or replace MCP server discovery.
 
 ## `code_search`

package/docs/workflows/operations.md

@@ -372,6 +372,8 @@ This reopens only the conversation. The workflow DAG and terminal stage snapshot
 
 Workflow stages and their subagent transcripts are excluded from ordinary `/resume`, `atomic -r`, `--continue`, and global history. Use workflow inspection and resume commands for stages; terminal subagents remain transcript artifacts, not resumable children. An explicit `--session` file path can still open a stage transcript. Older unmarked workflow sessions may remain in ordinary history.
 
+Embedding hosts can run the same pause, quit, and resume actions programmatically with `session.workflows`; see [Workflow run control](/sdk#workflow-run-control).
+
 ## Workflow activity for extensions
 
 Extensions can subscribe with `ctx.observeWorkflowActivity(observer)` and use the typed `workflow_lifecycle`, `workflow_activity_changed`, `workflow_stage_completed`, and `workflow_heartbeat` hooks. See [Workflow activity and lifecycle hooks](/extensions/events#workflow-activity-and-lifecycle-hooks) for the public types and subscription example.
@@ -470,7 +472,7 @@ If a resume continuation reports `cleanup skipped: database admission unavailabl
 
 While root registration is pending, status shows `pending` with phase `starting`, not healthy execution. Status listing and exact-run detail include `phase`, `phaseAgeMs`, `dependencyError`, and `lastProgressAt`. Last progress records admission or a tracked node starting/settling, not polling or a heartbeat. Database failures report `blocked_dependency`; a paused run still reports `paused`. Starting and dependency-blocked runs do not emit "still running" heartbeats.
 
-For an admitted live executor with no active stage or tool, pause installs a local barrier immediately and acknowledges within 500ms of starting database settlement. The acknowledgement and status distinguish `observed` from `durable` control persistence. If confirmation is still pending at acknowledgement, settlement continues in the background for up to 10 seconds total. Status becomes `durable` on success; only a settlement failure or deadline reports `blocked_dependency`. `observed` is not proof of a saved pause and does not guarantee cross-process resume. During registration, pause acknowledges immediately while database settlement continues in the background. After registration, resume allows up to 10 seconds for database confirmation before releasing the barrier. A failed resume leaves the executor paused; restore database availability and retry the same run. These limits do not cover stage cancellation or arbitrary external I/O.
+For an admitted live executor with no active stage or tool, pause installs a local barrier immediately and acknowledges within 500ms of starting database settlement. The acknowledgement and status distinguish `observed` from `durable` control persistence. If confirmation is still pending at acknowledgement, settlement continues in the background for up to 10 seconds total. Status becomes `durable` on success; only a settlement failure or deadline reports `blocked_dependency`. `observed` is not proof of a saved pause and does not guarantee cross-process resume. During registration, pause acknowledges immediately while database settlement continues in the background. After registration, resume allows up to 10 seconds for database confirmation before releasing the barrier, and a resume requested while the pause's confirmation is still pending waits for it within that same 10 seconds instead of cancelling it. A failed resume leaves the executor paused; restore database availability and retry the same run. These limits do not cover stage cancellation or arbitrary external I/O.
 
 If registration times out or reports an unavailable database while the run is paused, restore the existing database without resetting data, then resume that same run in the same Atomic process. Resume retries registration with the original identity and releases the existing executor once; repeated concurrent resume requests share the retry and do not start another executor. If the run was not paused, admission failure ends the attempt. A non-retryable admission rejection, such as a permission error, is reported on resume instead of retrying the live executor. Retain the full run ID and inspect it before retrying. Completed checkpoints remain reusable, but an external side effect whose checkpoint was never confirmed can still repeat after a crash; make such operations idempotent.
 

package/examples/extensions/built-in-tool-renderer.ts

@@ -12,8 +12,8 @@
  *
  * How it works:
  * - registerTool() with the same name as a built-in replaces it entirely
- * - We create instances of the original tools via createReadTool(), etc.
- *   and delegate execute() to them
+ * - We create the original definitions via createReadToolDefinition(), etc.
+ *   and override only their renderers
  * - renderCall() controls what's shown when the tool is invoked
  * - renderResult() controls what's shown after execution completes
  * - renderShell: "self" lets a tool render its own outer shell instead of
@@ -26,23 +26,21 @@
  */
 
 import type { BashToolDetails, EditToolDetails, ExtensionAPI, ReadToolDetails } from "@bastani/atomic";
-import { createBashTool, createEditTool, createReadTool, createWriteTool } from "@bastani/atomic";
+import {
+	createBashToolDefinition,
+	createEditToolDefinition,
+	createReadToolDefinition,
+	createWriteToolDefinition,
+} from "@bastani/atomic";
 import { Text } from "@earendil-works/pi-tui";
 
 export default function (pi: ExtensionAPI) {
 	const cwd = process.cwd();
 
 	// --- Read tool: show path and line count ---
-	const originalRead = createReadTool(cwd);
+	const originalRead = createReadToolDefinition(cwd);
 	pi.registerTool({
-		name: "read",
-		label: "read",
-		description: originalRead.description,
-		parameters: originalRead.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate) {
-			return originalRead.execute(toolCallId, params, signal, onUpdate);
-		},
+		...originalRead,
 
 		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("read "));
@@ -92,16 +90,9 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	// --- Bash tool: show command and exit code ---
-	const originalBash = createBashTool(cwd);
+	const originalBash = createBashToolDefinition(cwd);
 	pi.registerTool({
-		name: "bash",
-		label: "bash",
-		description: originalBash.description,
-		parameters: originalBash.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate) {
-			return originalBash.execute(toolCallId, params, signal, onUpdate);
-		},
+		...originalBash,
 
 		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("$ "));
@@ -151,17 +142,9 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	// --- Edit tool: show path and diff stats ---
-	const originalEdit = createEditTool(cwd);
+	const originalEdit = createEditToolDefinition(cwd);
 	pi.registerTool({
-		name: "edit",
-		label: "edit",
-		description: originalEdit.description,
-		parameters: originalEdit.parameters,
-		renderShell: "self",
-
-		async execute(toolCallId, params, signal, onUpdate) {
-			return originalEdit.execute(toolCallId, params, signal, onUpdate);
-		},
+		...originalEdit,
 
 		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("edit "));
@@ -216,16 +199,9 @@ export default function (pi: ExtensionAPI) {
 	});
 
 	// --- Write tool: show path and size ---
-	const originalWrite = createWriteTool(cwd);
+	const originalWrite = createWriteToolDefinition(cwd);
 	pi.registerTool({
-		name: "write",
-		label: "write",
-		description: originalWrite.description,
-		parameters: originalWrite.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate) {
-			return originalWrite.execute(toolCallId, params, signal, onUpdate);
-		},
+		...originalWrite,
 
 		renderCall(args, theme, _context) {
 			let text = theme.fg("toolTitle", theme.bold("write "));