@wular/coder 0.4.11 → 0.4.13

package/docs/cli/task.md

@@ -0,0 +1,273 @@
+<!-- Generated by contextjsx from definitions. Edit the source, not this file. -->
+
+# task
+
+run, follow and steer coding tasks
+
+## `task run [prompt] [--output-schema <output-schema>] [--name <name>] [--agent <agent>] [--append-system <append-system>] [--wait] [--engine <engine>] [--model <model>] [--effort <effort>] [--permissions <permissions>] [--mcp <mcp>] [--connections <connections>] [--add-dir <add-dir>] [--server <server>] [--workspace <workspace>] [--yes] [--background] [--repo <repo>] [--runner <runner>] [--json] [--cwd <cwd>]`
+
+run a task (background; --wait blocks)
+
+Dispatch a coding task to the configured engine. Backgrounds by default and
+prints a task id; --wait runs in the foreground and prints the answer.
+Shortcut: `coder run "<text>"`.
+
+Writing a task: one task per focused goal, independent goals as parallel runs.
+The worker starts with nothing but the text, so include the goal, file paths,
+constraints and any context only you have. Delegate rather than doing the work
+yourself first, however small it looks.
+
+Waiting: run `coder task result <task-id> --wait` in its own background shell, one
+per task. Never wait on several tasks in one call, or their approvals and answers
+never reach you one by one.
+
+Use luna or sonnet for mechanical work; sol or opus is the default.
+Use astra or fable for the hardest work; they cost the most.
+
+- `<prompt>` the task text
+- `--output-schema <output-schema>` JSON Schema for the task answer
+- `--name <name>` label the task (shown in list/result)
+- `--agent <agent>` run as that agent: its system.md, engine settings, MCP servers and flows; flags override them
+- `--append-system <append-system>` standing instructions appended to Coder's system prompt (kept out of prompt previews)
+- `--wait` run in the foreground and block until the answer is ready
+- `--engine <engine>` engine to use; custom runs your configured custom models (default: first in the chain)
+- `--model <model>` luna/sol/astra (codex) · sonnet/opus/fable (claude) · a custom model (coder model list)
+- `--effort <effort>` reasoning effort
+- `--permissions <permissions>` read-only · workspace-write · auto (default: auto)
+- `--mcp <mcp>` attach MCP servers from `mcp` in .coder/config.json by name (or all), or an inline JSON array [{"name","command","args","env","tools"}]; none by default, all adds your engine's own MCP servers
+- `--connections <connections>` use only these connections (coder connection list), within the agent's
+- `--add-dir <add-dir>` give the task another directory beyond --cwd (repeatable); read-only can only read it, other modes can also write
+- `--server <server>` run the task on your Coder server and follow it here (--background prints its id)
+- `--workspace <workspace>` with --server: the workspace to run in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--background` with --server: print the task id instead of following it
+- `--repo <repo>` with --server: check out a repo from the workspace's installs
+- `--runner <runner>` with --server: where it runs (a runner kind or a registered runner)
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+Exit codes:
+
+- `0` The task started, or --wait printed a successful answer.
+- `1` Dispatch or the task failed.
+- `3` No engine could start; follow fallback.instructions in the JSON payload.
+- `4` An approval is pending; answer it, then run result --wait again.
+- `130` The foreground wait was detached and the task is still running.
+
+```sh
+coder run "add a /health endpoint"  # dispatch in the background, print a task id
+coder result <task-id> --wait  # then block until it finishes and print the answer
+coder run --wait "fix the failing test"  # or block on the run itself
+coder task run --model luna --append-system "tests live in test/, don't touch anything outside of it" "rename foo to bar"  # pick an engine via its model alias; --append-system adds standing instructions
+coder task run --agent reviewer "review the last commit"  # run a repo agent from .coder/agents/reviewer
+coder run --add-dir ../api --add-dir ../shared "update the client for the new endpoint"  # let the task reach sibling repos too
+```
+
+## `task list [--running] [--stopped] [--archived] [--limit <limit>] [--cursor <cursor>] [--dir <dir>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+list recent tasks (by default running + just stopped)
+
+List recent tasks across all workspaces, most recent first: running tasks plus
+ones stopped within the last 30 minutes. Older stopped tasks auto-archive and
+move to --archived. Shortcut: `coder list`.
+
+- `--running` show only running tasks
+- `--stopped` show only recently stopped tasks (not yet archived)
+- `--archived` show only archived tasks (auto-archived or via task archive)
+- `--limit <limit>` tasks per page (default: 50; all for every task)
+- `--cursor <cursor>` continue from the previous page cursor
+- `--dir <dir>` only tasks launched in that workspace
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `task result [task-id] [--wait] [--turns] [--tail <tail>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+status + final answer (--wait blocks)
+
+Show a task's status and its final answer (result pending while it runs), plus
+any pending approvals. --wait blocks until it finishes, then prints. --tail <n>
+includes the last n progress-log steps (--tail all for the whole transcript).
+Defaults to the most recent task. Shortcut: `coder result`.
+
+JSON and MCP return a summary and the complete answer, without engine diagnostics
+or raw diffs. Use --tail for progress; answers are never truncated.
+
+Run each --wait in its own background shell, one per task. Never wait on several
+tasks in one call, or their approvals and answers never reach you one by one.
+
+- `<task-id>` the task (default: the most recent)
+- `--wait` block until the task finishes or needs an approval, then print
+- `--turns` every turn's answer (a steered task accretes turns)
+- `--tail <tail>` include the last n progress-log steps (default: 0, final result only)
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+Exit codes:
+
+- `0` The task completed successfully.
+- `1` The task failed or was cancelled.
+- `4` An approval is pending; answer it, then run --wait again.
+
+```sh
+coder result <task-id> --wait  # block until the task finishes, print the answer
+coder result <task-id> --turns  # every turn's answer for a steered task
+```
+
+## `task watch [task-id] [--tail <tail>] [--trim <trim>] [--from <from>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+stream a task's live transcript
+
+Stream a running task's transcript live (for you/debugging), then print its
+final answer. Replays the last line first so the current step is visible;
+--tail <n> replays the last n lines (--tail all for the whole transcript).
+Blocks until it finishes; exits 0 on success, 1 otherwise. For the answer
+alone, prefer `coder result`. Alias: stream.
+
+With --from <n>, or as a tool, it returns the log from event n on without
+following, and `next`: the command that continues it while the task runs.
+
+- `<task-id>` the task (default: the most recent)
+- `--tail <tail>` replay the last n log lines first (default: 1)
+- `--trim <trim>` budget for tool output and thinking (default: 1200 chars, 12 lines)
+- `--from <from>` return the log from event n on instead of following it
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder task watch  # follow the most recent task to completion
+coder task watch <task-id> --from 0 --json  # the log so far, and the command that continues it
+```
+
+## `task steer [task-id] [text] [--wait] [--model <model>] [--effort <effort>] [--permissions <permissions>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+continue a task's thread
+
+Continue a task's thread with new instructions. They are injected into a live Codex or
+Claude turn at its next tool boundary and queued across a startup or completion race.
+A stopped, finished, or archived task resumes on the same task id. It reuses the
+task's engine, model, and permissions unless overridden.
+
+- `<task-id>` the task to continue
+- `<text>` the follow-up instructions
+- `--wait` run in the foreground and block until the answer is ready
+- `--model <model>` override the task's model for this follow-up
+- `--effort <effort>` override the task's reasoning effort
+- `--permissions <permissions>` read-only · workspace-write · auto
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder task steer task-abc "now add tests"  # continue that task with a follow-up
+```
+
+## `task ask [task-id] [question] [--model <model>] [--effort <effort>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+ask about a task without interrupting it
+
+Answer a question ABOUT a task without touching it: a read-only sidecar reads
+the task's progress log, result, and workspace and answers; the task never
+sees the question and its thread is not steered. Works whether the task is
+running or stopped. To change what the task does, use `coder task steer`.
+
+- `<task-id>` the task to ask about
+- `<question>` the question
+- `--model <model>` sidecar model (default: the task's own)
+- `--effort <effort>` sidecar reasoning effort
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+```sh
+coder task ask task-abc "what approach did you take and why?"  # probe a decision without derailing the task
+```
+
+## `task stop [task-id] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+interrupt a running task
+
+Interrupt a running task and mark it cancelled.
+
+- `<task-id>` the task to stop
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `task archive [task-id] [--all-stopped] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+archive a session (or --all-stopped)
+
+Archive a task session so it drops out of the default list (see it again with
+`coder task list --archived [--limit N]`). Pass --all-stopped to archive every
+finished task. A running task keeps running; steering an archived task
+brings it back.
+
+- `<task-id>` the task to archive
+- `--all-stopped` archive every stopped (finished) task
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `task delete [task-id] [--all-archived] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+delete a session (or --all-archived)
+
+Delete a task's session from disk. This is permanent. Pass --all-archived to
+delete every archived task at once. A running task must be stopped first.
+
+- `<task-id>` the task to delete
+- `--all-archived` delete every archived task
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `task approvals [task-id] [--denied] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+pending approvals (all tasks, or one)
+
+List pending approvals across all tasks, --denied the denied ones (still answerable), or every approval of one task.
+
+- `<task-id>` one task (default: approvals of every task)
+- `--denied` denied approvals instead of pending ones
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current
+
+## `task approve [task-id] [approval-id] [--deny] [--reason <reason>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+
+answer an escalation
+
+Answer an escalation the task raised. Accepts by default; --deny rejects it, --reason says why.
+Works any time, also after a deny: the task gets the decision as a message.
+Approval ids are unique, so the task id is optional.
+
+- `<task-id>` the task, or the approval id alone
+- `<approval-id>` the approval to answer
+- `--deny` reject the request instead of accepting
+- `--reason <reason>` why it is denied; the task reads it
+- `--server <server>` act on your Coder server
+- `--workspace <workspace>` with --server: the workspace to act in (default: the saved one)
+- `--yes` with --server: connect to a server used for the first time without asking
+- `--json` JSON output
+- `--cwd <cwd>` workspace directory; default current

package/docs/config.md

@@ -33,7 +33,6 @@ coder config set engines.codex.model sol
     "astra": { "disabled": true }
   },
   "approvals": {
-    "escalationTimeoutMs": 120000,
     "allowedNetworkHosts": ["localhost", "127.0.0.1", "registry.npmjs.org"]
   },
   "agents": {
@@ -53,10 +52,6 @@ coder config set engines.codex.model sol
 
 Fallback order. When an engine can't start (missing binary, auth, quota), the task automatically retries on the next entry. Default `["codex", "claude"]`.
 
-## `conversationCompactTokens`
-
-Context size in tokens at which a platform conversation's task, such as a Slack thread or a pull request, continues from a summary plus its recent messages. Default `70000`.
-
 ## `engines`
 
 Per-engine defaults, used when a dispatch doesn't override them:
@@ -67,7 +62,7 @@ Per-engine defaults, used when a dispatch doesn't override them:
 | `effort`      | `low`, `medium`, `high`                                                                                                                       |
 | `permissions` | `read-only`, `workspace-write`, `auto`                                                                                                        |
 
-Permission modes are one surface across all engines: read-only can't modify anything, workspace-write stays inside the repo, and auto enables Codex network access plus policy-answered escalations; `engines.codex.network` overrides network access for every mode when set.
+Permission modes are one surface across all engines: read-only can't modify anything, workspace-write stays inside the repo, and auto lets the engine's own reviewer decide actions outside the sandbox (see [approvals](#approvals)); `engines.codex.network` overrides network access for every mode when set.
 
 A task reaches only its workspace unless you give it more. Pass `--add-dir <dir>` to `coder run` once for each sibling repo or shared folder the task needs. Relative paths resolve against the workspace and each one must already exist. Read-only tasks can read these directories but never write them, while workspace-write and auto tasks can write them just like the workspace. Claude receives them as `--add-dir` and `permissions.additionalDirectories`, so its OS sandbox follows the same rules. Codex already reads everywhere in read-only, and in the other modes it receives them as extra writable roots in the turn's sandbox policy. The directories are saved on the task, `coder result` lists them, and steering keeps them.
 
@@ -85,16 +80,11 @@ Every shape also accepts `"disabled": true` to park the entry without deleting i
 
 ## `approvals`
 
-Tunes the `auto` permission mode; ignored by `read-only` and `workspace-write`.
-
-| Key                   | Meaning                                                                                                                |
-| --------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `escalationTimeoutMs` | How long an escalated approval waits for an answer before auto-denying and letting the task move on. Default `120000`. |
-| `allowedNetworkHosts` | Hosts (and their subdomains) coders may reach without an approval when network sandboxing is active. Default `[]`.     |
-
-`allowedNetworkHosts` is pre-allowed in the Claude sandbox and auto-accepted by the Codex approval policy when `engines.codex.network` is `false`. A bare hostname covers its subdomains; anything else escalates as usual. Listing `localhost`, `127.0.0.1` or `::1` also lets sandboxed Claude commands serve on local ports (macOS), so a task can run a dev server. On `vercel-sandbox` they also open the firewall of tasks below `auto`.
+| Key                   | Meaning                                                                                                           |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `allowedNetworkHosts` | Hosts (and their subdomains) tasks reach without review. Default `[]`. Also in the dashboard, Settings → Engines. |
 
-Allowlist only hosts you trust: the check is by name, not by the address the name resolves to.
+How tasks ask for more: [Access and approvals](access.md).
 
 ## `agents`
 

package/docs/flows.md

@@ -59,7 +59,7 @@ const r = await task('Explain the auth module', {
 r.output; // final message text
 ```
 
-Options are the same as the `coder run` flags (`engine`, `model`, `effort`, `permissions`, `name`, `system`, `cwd`, and `addDirs` for `--add-dir` - see `coder run --help`), plus one of its own:
+Options are the same as the `coder run` flags (`engine`, `model`, `effort`, `permissions`, `name`, `appendSystem`, `cwd`, and `addDirs` for `--add-dir` - see `coder run --help`), plus one of its own:
 
 - `returns` - a zod schema for structured output instead of prose. The runtime passes the schema natively, validates the reply (one corrective retry on mismatch), and the parsed value lands on `r.data`:
 
@@ -212,12 +212,6 @@ Coder ships a few flows of its own; they resolve after the directories above, so
 
 - `review`: the `coder review` code review. Args: `pr` (number or GitHub URL), `post` (comment on the PR), `base`/`head`/`since` (as the CLI flags), `engine`/`model`/`effort`. Returns `{ findings, summary }`. `coder flow run review --args '{"pr":42,"post":true}'`
 
-### Flows run by an agent
-
-An [agent](agents/index.md) runs a flow like any script: `coder flow run <name>` from its shell, inside its sandbox. It can run any flow, including one it writes during the task.
-
-The tasks a flow starts can't exceed the agent's `permissions` (`read-only` < `workspace-write` < `auto`). A task without permissions inherits the agent's, and one asking for more fails before it starts. Platform actions, like the `review` flow's comments, run outside the sandbox, so no token enters it.
-
 ## CLI
 
 ```bash

package/docs/mcp.md

@@ -1,6 +1,6 @@
 # MCP
 
-Give tasks tools of your own: an MCP server is a [connection](agents/index.md#connections), or an entry under `mcp` in a config file you edit, attached to a task by name. Nothing from a config file attaches unless asked, so the default run stays lean. `--mcp all` also loads your engine's own MCP servers and connectors.
+Give tasks tools of your own: an MCP server is a [connection](agents/index.md#connections), or an entry under `mcp` in a config file you edit, attached to a task by name. Nothing from a config file attaches unless asked, so the default run stays lean. `--mcp all` also loads your engine's own MCP servers and connectors. To use Coder itself as an MCP server in your host, see [In your local harness](../README.md#in-your-local-harness).
 
 ```sh
 coder connection add docs --access write -- npx -y docs-mcp           # stdio server: the command after --
@@ -32,12 +32,12 @@ Entries in `.coder/config.json`, `~/.coder/config.json` and an agent's `agent.js
 }
 ```
 
-| Key                      | Purpose                                                             |
-| ------------------------ | ------------------------------------------------------------------- |
-| `command`, `args`, `env` | Stdio server to spawn                                               |
-| `url`, `headers`, `type` | Remote server; `type` is `http` (streamable HTTP, default) or `sse` |
-| `tools`                  | Allowlist of tool names; omit for every tool the server offers      |
-| `description`            | What the server is for                                              |
+| Key                      | Purpose                                                        |
+| ------------------------ | -------------------------------------------------------------- |
+| `command`, `args`, `env` | Stdio server to spawn                                          |
+| `url`, `headers`         | Remote server, streamable HTTP                                 |
+| `tools`                  | Allowlist of tool names; omit for every tool the server offers |
+| `description`            | What the server is for                                         |
 
 Repository servers need local approval with `coder connection approve <name>`; `coder connection list` shows which are approved. `${VAR}` and `${VAR:-default}` expand from the environment, except in a repository remote entry's URL and headers, where they stay literal; use a connection for credentials.
 
@@ -51,4 +51,4 @@ coder run --mcp all "..."
 coder run --mcp '[{"name":"tmp","command":"node","args":["server.js"]}]' "..."
 ```
 
-Claude gets the servers through `--mcp-config` with the allowlist as `mcp__<name>__<tool>`, and finds their tools with its tool search. Codex gets one `coder` server whose `find_tools` and `call_tool` reach every server on demand; a server starts on its first use. Agents attach their integration tools the same way, so an agent never needs an entry here.
+A server's `tools` list limits what a task can call; read-only tasks get only the tools a server marks read-only. Agents attach their integration tools the same way, so an agent never needs an entry here.

package/docs/models.md

@@ -14,12 +14,13 @@ coder model add kimi --base-url https://openrouter.ai/api/v1 --env-key OPENROUTE
 
 `model add` saves the entry, probes the endpoint, and reports anything missing (unreachable URL, unset key env var, no codex). Change one later with `coder model update <name>`, drop it with `coder model remove <name>`. Flags:
 
-| Flag               | Meaning                                                                                  |
-| ------------------ | ---------------------------------------------------------------------------------------- |
-| `--base-url <url>` | OpenAI-compatible API base (e.g. `http://localhost:11434/v1`)                            |
-| `--model <id>`     | the provider's model id (e.g. `qwen2.5-coder:32b`)                                       |
-| `--env-key <VAR>`  | env var holding the API key; omit for keyless local endpoints                            |
-| `--workspace`      | write to `<repo>/.coder/config.json` instead of the user file                            |
+| Flag               | Meaning                                                       |
+| ------------------ | ------------------------------------------------------------- |
+| `--base-url <url>` | OpenAI-compatible API base (e.g. `http://localhost:11434/v1`) |
+| `--model <id>`     | the provider's model id (e.g. `qwen2.5-coder:32b`)            |
+| `--env-key <VAR>`  | env var holding the API key; omit for keyless local endpoints |
+| `--context-window <tokens>` | the model's context window, filled when the provider reports it; Codex compacts at 90% of it |
+| `--workspace`      | write to `<repo>/.coder/config.json` instead of the user file |
 
 ## Use it
 

package/docs/review.md

@@ -39,3 +39,7 @@ Changed submodules are reviewed file by file under their path. Uninitialized one
 ## Exit codes
 
 The command exits `0` when the review completes, even with findings, `1` when the diff, review, or posting fails, `3` when no engine starts, and `4` while a task awaits approval.
+
+## From a task
+
+Every task has a `review` tool. It reviews the task's uncommitted changes in the background, or those since `base`, and sends the findings to the task as a message. One review runs at a time, at most 5 per task.

package/docs/sdk.md

@@ -21,36 +21,36 @@ SDK functions never print and never call `process.exit`; results come back as ty
 
 ## CLI to SDK mapping
 
-| CLI                                                                                    | SDK                                                                                                                                                                                                                                                   |
-| -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `coder run "<text>"`                                                                   | `task.run(prompt, opts?)`; `connections` narrows the task's connections                                                                                                                                                                              |
-| `coder list`                                                                           | `task.list(opts?)`                                                                                                                                                                                                                                    |
-| `coder result [id] [--wait] [--tail N] [--turns]`                                      | `task.result(id?, { wait?, tail? })` - returns `turns` (one entry per finished turn) alongside `result`                                                                                                                                               |
-| `coder task steer <id> "<text>"`                                                       | `task.steer(id, text, { model?, effort?, permissions?, wait? })` - live, or resumes a finished or archived task on the same id                                                                                                                        |
-| `coder task ask <id> "<question>"`                                                     | `task.ask(id, question, { model?, effort? })` - read-only sidecar answer; the task's thread is never touched                                                                                                                                          |
-| `coder task stop <id>`                                                                 | `task.stop(id)`                                                                                                                                                                                                                                       |
-| `coder task watch [id] [--tail N]`                                                     | `task.stream(id?, { tail? })` - async iterable of progress events                                                                                                                                                                                     |
-| `coder task approvals [id]`                                                            | `task.approvals(id?)`                                                                                                                                                                                                                                 |
-| `coder task approve <id> <appr>`                                                       | `task.approve(id, approvalId, { deny? })`                                                                                                                                                                                                             |
-| `coder task archive / delete <id>`                                                     | `task.archive(id)` / `task.delete(id)`                                                                                                                                                                                                                |
-| `coder flow run / list / discover / result / watch / stop / resume / archive / delete` | the matching `flow.*` function; `flow.run(nameOrPath, { args?, concurrency?, maxTasks? })`, `flow.stream(id?)` for `watch`                                                                                                                            |
-| `coder model add / update / remove / list / alias / unalias / disable / enable`        | the matching `model.*` function                                                                                                                                                                                                                       |
-| `coder config get / set`                                                               | `config.get(key?)` / `config.set(key, value)`                                                                                                                                                                                                         |
+| CLI                                                                                    | SDK                                                                                                                                                                                                                                                                                                           |
+| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `coder run "<text>"`                                                                   | `task.run(prompt, opts?)`; `connections` narrows the task's connections                                                                                                                                                                                                                                       |
+| `coder list`                                                                           | `task.list(opts?)` - one page, `{ items, next? }`; pass `next` as `cursor`                                                                                                                                                                                                                                    |
+| `coder result [id] [--wait] [--tail N] [--turns]`                                      | `task.result(id?, { wait?, tail? })` - returns `turns` (one entry per finished turn) alongside `result`                                                                                                                                                                                                       |
+| `coder task steer <id> "<text>"`                                                       | `task.steer(id, text, { model?, effort?, permissions?, wait? })` - live, or resumes a finished or archived task on the same id                                                                                                                                                                                |
+| `coder task ask <id> "<question>"`                                                     | `task.ask(id, question, { model?, effort? })` - read-only sidecar answer; the task's thread is never touched                                                                                                                                                                                                  |
+| `coder task stop <id>`                                                                 | `task.stop(id)`                                                                                                                                                                                                                                                                                               |
+| `coder task watch [id] [--tail N]`                                                     | `task.stream(id?, { tail? })` - async iterable of progress events                                                                                                                                                                                                                                             |
+| `coder task approvals [id]`                                                            | `task.approvals(id?)`                                                                                                                                                                                                                                                                                         |
+| `coder task approve <id> <appr>`                                                       | `task.approve(id, approvalId, { deny? })`                                                                                                                                                                                                                                                                     |
+| `coder task archive / delete <id>`                                                     | `task.archive(id)` / `task.delete(id)`                                                                                                                                                                                                                                                                        |
+| `coder flow run / list / discover / result / watch / stop / resume / archive / delete` | the matching `flow.*` function; `flow.run(nameOrPath, { args?, concurrency?, maxTasks? })`, `flow.stream(id?)` for `watch`                                                                                                                                                                                    |
+| `coder model add / update / remove / list / alias / unalias / disable / enable`        | the matching `model.*` function                                                                                                                                                                                                                                                                               |
+| `coder config get / set`                                                               | `config.get(key?)` / `config.set(key, value)`                                                                                                                                                                                                                                                                 |
 | `coder connection add / list / rm / reconnect / approve`                               | `connection.add(name, { env?, url?, command?, key?, askKey?, header?, access?, me?, credential?, onAuthorize?, server? })` / `connection.list()` / `connection.remove(name)` / `connection.reconnect(name, { key?, askKey?, onAuthorize? })` / `connection.approve(name, { agent? })`, all with `{ server? }` |
-| `coder setup-host [hosts...]`                                                          | `setupHost(hosts?)`                                                                                                                                                                                                                                   |
-| `coder upgrade`                                                                        | `upgrade({ cliOnly?, pluginsOnly? })`                                                                                                                                                                                                                 |
-| `coder docs [topic]`                                                                   | `docs(topic?)`                                                                                                                                                                                                                                        |
-| `coder review [--base] [--head] [--pr] [--since] [--post]`                             | `review.run({ base?, head?, pr?, since?, post?, engine?, model?, effort? })` - returns `{ findings, summary, runId }`                                                                                                                                 |
-| `coder auth login [--server] [--workspace] [--device] [--yes]`                         | `auth.login({ server?, organization?, device?, yes?, onCode?, open?, save? })` - the same Wular Auth sign-in; `open` gets the browser URL, `device` switches to the code flow; pass the workspace slug as `organization` when the account has several |
-| `coder auth logout / status`                                                           | `auth.logout({ server? })` / `auth.status()` - the saved sessions, never their tokens                                                                                                                                                                 |
-| `coder task <verb> --server [url]`                                                     | every `task.*` above with `{ server: true \| url, organization?, token?, yes? }` - acts on your server's tasks instead of local tasks                                                                                                                 |
-| `coder agent list / show <id> / init [id] / push [id]`                                 | `agent.list({ server? })` / `agent.show(id, { server? })` / `agent.init(id)` / `agent.push(id?, { cwd?, server? })`                                                                                                                                  |
-| `coder agent integrations list / show <id>`                                            | `agent.integrations.list()` / `agent.integrations.show(id)`                                                                                                                                                                                           |
-| `coder agent run <agent> <event.json> [--server]`                                      | `agent.run(agent, event, { server?, wait?, flow?, cwd? })` - local, tools off; with `server`, a real task                                                                                                                                             |
-| `coder agent run --task <id>`                                                          | `agent.runTask(id, options?)` - the runner form, not for application code                                                                                                                                                                             |
-| `coder credentials list / add / remove`                                                | `credentials.list()` / `.add({ env, value?, workspace?, noCheck? })` / `.remove(name, { workspace? })`, all with `{ server? }`                                                                                                                       |
-| `coder agent usage [--since] [--by]`                                                   | `agent.usage({ since?, by?, server?, cwd? })`                                                                                                                                                                                                         |
-| `coder server serve / rotate-key`                                                                        | `server.serve(options?)` / `server.rotateKey(options?)`; `server.handler(env)` for serverless hosts, see [Self-hosting](self-host.md#deploy)                                                                                                                                                                                                                 |
+| `coder setup-host [hosts...]`                                                          | `setupHost(hosts?)`                                                                                                                                                                                                                                                                                           |
+| `coder upgrade`                                                                        | `upgrade({ cliOnly?, pluginsOnly? })`                                                                                                                                                                                                                                                                         |
+| `coder docs [topic]`                                                                   | `docs(topic?)`                                                                                                                                                                                                                                                                                                |
+| `coder review [--base] [--head] [--pr] [--since] [--post]`                             | `review.run({ base?, head?, pr?, since?, post?, engine?, model?, effort? })` - returns `{ findings, summary, runId }`                                                                                                                                                                                         |
+| `coder auth login [--server] [--workspace] [--device] [--yes]`                         | `auth.login({ server?, organization?, device?, yes?, onCode?, open?, save? })` - the same Wular Auth sign-in; `open` gets the browser URL, `device` switches to the code flow; pass the workspace slug as `organization` when the account has several                                                         |
+| `coder auth logout / status`                                                           | `auth.logout({ server? })` / `auth.status()` - the saved sessions, never their tokens                                                                                                                                                                                                                         |
+| `coder task <verb> --server [url]`                                                     | every `task.*` above with `{ server: true \| url, organization?, token?, yes? }` - acts on your server's tasks instead of local tasks                                                                                                                                                                         |
+| `coder agent list / show <id> / init [id] / push [id]`                                 | `agent.list({ server? })` / `agent.show(id, { server? })` / `agent.init(id)` / `agent.push(id?, { cwd?, server? })`                                                                                                                                                                                           |
+| `coder agent integrations list / show <id>`                                            | `agent.integrations.list()` / `agent.integrations.show(id)`                                                                                                                                                                                                                                                   |
+| `coder agent run <agent> <event.json> [--server]`                                      | `agent.run(agent, event, { server?, wait?, flow?, cwd? })` - local, tools off; with `server`, a real task                                                                                                                                                                                                     |
+| `coder agent run --task <id>`                                                          | `agent.runTask(id, options?)` - the runner form, not for application code                                                                                                                                                                                                                                     |
+| `coder credentials list / add / remove`                                                | `credentials.list()` / `.add({ env, value?, workspace?, noCheck? })` / `.remove(name, { workspace? })`, all with `{ server? }`                                                                                                                                                                                |
+| `coder agent usage [--since] [--by]`                                                   | `agent.usage({ since?, by?, server?, cwd? })`                                                                                                                                                                                                                                                                 |
+| `coder server serve / rotate-key`                                                      | `server.serve(options?)` / `server.rotateKey(options?)`; `server.handler(env)` for serverless hosts, see [Self-hosting](self-host.md#deploy)                                                                                                                                                                  |
 
 Options objects take the same names as the CLI flags, camelCased (`--max-tasks` becomes `maxTasks`, `--server` becomes `server`). Every server option accepts `organization`, the `--workspace` flag's slug, which overrides the saved workspace for that call. `server` falls back to `CODER_SERVER`, then the hosted service; authentication comes from `auth.login()`, or from `token` when supplied; `yes: true` acknowledges the first use of a new server origin in non-interactive code.