@wular/coder 0.4.12 → 0.5.0

package/docs/cli/flow.md

@@ -26,7 +26,7 @@ Stop a run with `coder flow stop`.
 - `--max-tasks <max-tasks>` total tasks the run may dispatch (default: CPU count x 10)
 - `--dry-run` print every resolved prompt and gate command without dispatching
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder flow run audit-routes --wait  # run a discovered flow
@@ -44,7 +44,7 @@ within the last 30 minutes. Older runs auto-archive and move to --archived.
 - `--archived` show archived runs (auto-archived or via flow archive)
 - `--limit <limit>` show at most n runs (default all)
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `flow discover [--json] [--cwd <cwd>]`
 
@@ -54,7 +54,7 @@ List every flow discoverable from the current directory: workspace flows in
 .coder/flows/ (walking up to the repo root) and global flows in ~/.coder/flows/.
 
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `flow result [run-id] [--tail <tail>] [--json] [--cwd <cwd>]`
 
@@ -67,7 +67,7 @@ recent run. To watch a run live, prefer `coder flow watch`.
 - `<run-id>` the run (default: the most recent)
 - `--tail <tail>` show the last n step rows (default: all; 0 hides them)
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder flow result --tail 0  # the most recent run's result, no step rows
@@ -89,7 +89,7 @@ following, and `next`: the command that continues them while the run goes on.
 - `--tail <tail>` replay only the last n events first (default: all)
 - `--from <from>` return the events from event n on instead of following them
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder flow watch  # follow the most recent run to completion
@@ -107,7 +107,7 @@ the journal stays ready for `coder flow resume`.
 - `<run-id>` the run (default: the most recent)
 - `--keep-tasks` leave the run's still-running tasks running
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `flow resume [run-id] [--wait] [--args <args>] [--concurrency <concurrency>] [--max-tasks <max-tasks>] [--dry-run] [--json] [--cwd <cwd>]`
 
@@ -124,7 +124,7 @@ Accepts the same flags as flow run.
 - `--max-tasks <max-tasks>` total tasks the run may dispatch (default: CPU count x 10)
 - `--dry-run` print every resolved prompt and gate command without dispatching
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder flow resume  # continue the most recent run
@@ -141,7 +141,7 @@ finished run. A running run must be stopped first.
 - `<run-id>` the run to archive
 - `--all-stopped` archive every stopped (finished) run
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `flow delete [run-id] [--all-archived] [--json] [--cwd <cwd>]`
 
@@ -155,4 +155,4 @@ stopped first.
 - `<run-id>` the run to delete
 - `--all-archived` delete every archived run
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current

package/docs/cli/index.md

@@ -2,7 +2,7 @@
 
 # coder CLI
 
-Delegate a coding task to the best available engine and steer it while it runs.
+Coder turns any model into an agent you own: tasks on this machine, from your code, or always on in Coder Cloud.
 
 - [task](task.md): run, follow and steer coding tasks
 - [flow](flow.md): orchestrate many coder tasks from one TypeScript file
@@ -12,9 +12,9 @@ Delegate a coding task to the best available engine and steer it while it runs.
 - [runner](runner.md): run your server's tasks on this machine
 - [auth](auth.md): sign in to Coder and manage saved server sessions
 - [model](model.md): manage models: built-ins, aliases, custom endpoints
-- [connection](connection.md): platform accounts, API keys and MCP servers tasks use
+- [connection](connection.md): platform accounts and MCP servers tasks use
 
-## `review [--base <base>] [--head <head>] [--pr <pr>] [--since <since>] [--path <path>] [--exclude <exclude>] [--post] [--md] [--engine <engine>] [--model <model>] [--effort <effort>] [--json] [--cwd <cwd>]`
+## `review [--base <base>] [--head <head>] [--pr <pr>] [--since <since>] [--path <path>] [--exclude <exclude>] [--post] [--md] [--model <model>] [--depth <depth>] [--json] [--cwd <cwd>]`
 
 review changed code with a built-in flow
 
@@ -34,17 +34,17 @@ Related: `coder flow watch`, `coder docs review`.
 - `--exclude <exclude>` leave this path out, relative to cwd (repeatable)
 - `--post` post deduplicated inline comments and sticky PR summary
 - `--md` markdown output (the default)
-- `--engine <engine>` codex, claude, or custom
-- `--model <model>` model for the review task
-- `--effort <effort>` reasoning effort and review depth (default: medium depth)
+- `--model <model>` model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high) for the review task (default: reviewModel)
+- `--depth <depth>` what to report: low only critical and major, high nits too (default: medium)
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder review  # review the branch plus uncommitted work
 coder review --base main  # review everything since main locally
 coder review --path src --exclude src/gen  # review src without generated code
 coder review --pr 42 --post  # review and post to pull request 42
+coder review --depth high  # report nits too
 ```
 
 ## `config [action] [key] [value] [--workspace] [--json] [--cwd <cwd>]`
@@ -52,19 +52,21 @@ coder review --pr 42 --post  # review and post to pull request 42
 read or write config
 
 Read or write configuration. `list` prints the effective config; get/set/unset
-target a dotted key (e.g. engines.codex.model). Writes go to ~/.coder/config.json.
+target a dotted key (e.g. chain); migrate rewrites the file at this Coder's config
+version. Writes go to ~/.coder/config.json.
 
-- `<action>` list, get, set or unset
-- `<key>` a dotted key, such as engines.codex.model
+- `<action>` list, get, set, unset or migrate
+- `<key>` a dotted key, such as chain or reviewModel
 - `<value>` with set: the value; JSON, or a comma list
 - `--workspace` target <repo>/.coder/config.json instead of the user file
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder config list  # print the effective config
-coder config set chain codex,claude  # set the engine fallback chain
-coder config get engines.codex.model  # read one value
+coder config set chain codex/sol,claude/opus  # the default model, then its fallbacks
+coder config get reviewModel  # read one value
+coder config migrate --workspace  # rewrite the repo file at config version 1
 ```
 
 ## `setup-host [hosts] [--json] [--cwd <cwd>]`
@@ -84,7 +86,7 @@ add coder -- coder mcp, or for Cursor "coder": { "command": "coder", "args":
 
 - `<hosts>` claude, agents, codex, cursor (one or more)
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder setup-host claude  # install the Claude Code plugin
@@ -131,7 +133,7 @@ serve Coder's commands as MCP tools over stdio
 
 Serve Coder's commands as MCP tools over stdio, so a harness can run them.
 
-Commands return their JSON payloads and next steps. Load guides with load_skill;
+Commands return their JSON payloads and next steps. Load docs with load_skill;
 blocking commands keep their CLI flags and behavior, subject to the client's tool timeout.
 
 ```sh

package/docs/cli/model.md

@@ -7,37 +7,38 @@ manage models: built-ins, aliases, custom endpoints
 Manage the models coder can dispatch to. `add` connects any OpenAI-compatible
 endpoint (Ollama, vLLM, OpenRouter, ...) as the custom engine, alongside the
 built-in codex/claude models. Name your own shortcuts with `alias`
-(e.g. fast -> codex:luna); disable/enable turns any model off and on.
+(e.g. fast -> codex/luna); disable/enable turns any model off and on.
 
-## `model list [--json] [--cwd <cwd>]`
+## `model list [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
 list built-ins, custom models, and aliases
 
 List built-in aliases, configured custom models, and user aliases. Only custom
-models are probed.
-
-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.
+models on this machine are probed; --server lists the workspace's.
 
+- `--server <server>` act on the 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)
+- `--cwd <cwd>` workspace directory; default current
 
-## `model add [name] [--base-url <base-url>] [--model <model>] [--env-key <env-key>] [--workspace] [--json] [--cwd <cwd>]`
+## `model add [name] [--base-url <base-url>] [--model <model>] [--env-key <env-key>] [--context-window <context-window>] [--workspace] [--json] [--cwd <cwd>]`
 
 connect a model
 
 Connect a custom model behind an OpenAI-compatible endpoint (Ollama, LM Studio,
 vLLM, OpenRouter, ...). It currently runs on the codex engine pointed at your
-URL and is usable anywhere a model is: --model <name>, --engine custom, or as an
+URL and is usable anywhere a model is: --model <name> or --model custom/<name>, or as an
 agent default in config. Alias: `coder model setup`.
 
 - `<name>` the name to dispatch it by
 - `--base-url <base-url>` OpenAI-compatible API base (e.g. http://localhost:11434/v1)
 - `--model <model>` the provider's model id (e.g. qwen2.5-coder:32b)
 - `--env-key <env-key>` env var holding the API key (omit for keyless local endpoints)
+- `--context-window <context-window>` the model's context window in tokens; filled from the provider when it reports one
 - `--workspace` write to <repo>/.coder/config.json instead of the user file
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder model add qwen --base-url http://localhost:11434/v1 --model qwen2.5-coder:32b  # local Ollama model, no key
@@ -45,7 +46,7 @@ coder model add kimi --base-url https://openrouter.ai/api/v1 --model moonshotai/
 coder run --model qwen "explain this repo"  # dispatch a task on it
 ```
 
-## `model update [name] [--base-url <base-url>] [--model <model>] [--env-key <env-key>] [--workspace] [--json] [--cwd <cwd>]`
+## `model update [name] [--base-url <base-url>] [--model <model>] [--env-key <env-key>] [--context-window <context-window>] [--workspace] [--json] [--cwd <cwd>]`
 
 change a model in place
 
@@ -56,9 +57,10 @@ is re-probed and the wire protocol re-detected.
 - `--base-url <base-url>` new API base
 - `--model <model>` new provider model id
 - `--env-key <env-key>` new API-key env var
+- `--context-window <context-window>` the model's context window in tokens; filled from the provider when it reports one
 - `--workspace` write to <repo>/.coder/config.json instead of the user file
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `model remove [name] [--workspace] [--json] [--cwd <cwd>]`
 
@@ -69,7 +71,7 @@ Remove a configured custom model.
 - `<name>` the custom model
 - `--workspace` target <repo>/.coder/config.json instead of the user file
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `model disable [name] [--workspace] [--json] [--cwd <cwd>]`
 
@@ -80,7 +82,7 @@ Disable a model - built-in, custom, or alias. Requests for it fail until re-enab
 - `<name>` a built-in, custom model, or alias
 - `--workspace` target <repo>/.coder/config.json instead of the user file
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `model enable [name] [--workspace] [--json] [--cwd <cwd>]`
 
@@ -89,20 +91,20 @@ re-enable a disabled model
 - `<name>` a built-in, custom model, or alias
 - `--workspace` target <repo>/.coder/config.json instead of the user file
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `model alias [name] [spec] [--workspace] [--json] [--cwd <cwd>]`
 
-name a spec, e.g. fast codex:luna
+name a spec, e.g. fast codex/luna
 
-Save an alias for an engine spec, e.g. fast -> codex:luna. An alias may reuse a
-built-in name to override it.
+Save an alias for an engine spec, e.g. fast -> codex/luna. An alias may reuse a
+built-in name to override it; an engine name sets what that bare engine runs.
 
 - `<name>` the alias
-- `<spec>` the engine spec, such as codex:luna
+- `<spec>` the engine spec, such as codex/luna
 - `--workspace` target <repo>/.coder/config.json instead of the user file
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `model unalias [name] [--workspace] [--json] [--cwd <cwd>]`
 
@@ -113,4 +115,4 @@ Remove a user-defined alias.
 - `<name>` the alias
 - `--workspace` target <repo>/.coder/config.json instead of the user file
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current

package/docs/cli/runner.md

@@ -57,7 +57,7 @@ Run tasks on this machine with its own claude and codex logins. Expose the port
 - `--server <server>` act on your Coder server, in the saved workspace
 - `--yes` connect to a server used for the first time without asking
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 cloudflared tunnel --url http://localhost:4100  # expose the port in one terminal

package/docs/cli/server.md

@@ -17,7 +17,7 @@ Run the Coder server on Bun: the address platforms deliver events to, the dashbo
 - `--memory` a throwaway test server: everything in memory, no sign-in, admin token only
 - `--runner <runner>` local, local-docker, vercel-sandbox, github-actions, or http
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 Environment:
 
@@ -31,7 +31,7 @@ Environment:
 - `MAX_TASKS, TASK_TIMEOUT, TASK_STALL, TASK_ATTEMPTS` runner capacity and lifecycle limits
 - `ADMIN_TOKEN` local and memory servers: the dashboard and CLI key; minted and shown when unset
 - `CODER_CACHE_HOME` archived tasks, flows and usage (default OS cache directory/wular-coder)
-- `WORK_DIR` where tasks check out repositories
+- `WORK_DIR` where the local runner keeps task work folders
 - `SERVER_NAME` what the dashboard calls this server (default Coder)
 
 ```sh

package/docs/cli/task.md

@@ -4,12 +4,12 @@
 
 run, follow and steer coding tasks
 
-## `task run [prompt] [--output-schema <output-schema>] [--name <name>] [--agent <agent>] [--system <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>] [--simulate-approval] [--json] [--cwd <cwd>]`
+## `task run [prompt] [--output-schema <output-schema>] [--name <name>] [--agent <agent>] [--append-system <append-system>] [--wait] [--model <model>] [--access <access>] [--mcp <mcp>] [--connections <connections>] [--add-dir <add-dir>] [--server <server>] [--workspace <workspace>] [--yes] [--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.
+prints a task id locally or with --server; --wait follows it to the answer.
 Shortcut: `coder run "<text>"`.
 
 Writing a task: one task per focused goal, independent goals as parallel runs.
@@ -21,31 +21,30 @@ Waiting: run `coder task result <task-id> --wait` in its own background shell, o
 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.
+Recommended, unless the user prefers otherwise or a model is unavailable:
+- sol or opus by default
+- luna or sonnet for mechanical work
+- opus for public APIs, SDKs and UI design
+- 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
-- `--system <system>` standing instructions prepended to the task (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)
+- `--append-system <append-system>` standing instructions appended to Coder's system prompt (kept out of prompt previews)
+- `--wait` follow the task until the answer is ready
+- `--model <model>` model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high)
+- `--access <access>` read-only also restricts platforms and connections; auto lets the engine review what leaves the sandbox (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)
+- `--add-dir <add-dir>` give the task another directory beyond --cwd (repeatable); read-only can only read it, auto can also write
+- `--server <server>` run the task on your Coder server and print its id (--wait follows it)
 - `--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)
-- `--simulate-approval` test only: raise a fake approval request
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 Exit codes:
 
@@ -59,7 +58,7 @@ Exit codes:
 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 --system "tests live in test/, don't touch anything outside of it" "rename foo to bar"  # pick an engine via its model alias; --system adds standing instructions
+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
 ```
@@ -78,11 +77,11 @@ move to --archived. Shortcut: `coder list`.
 - `--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
+- `--server <server>` act on the 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)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `task result [task-id] [--wait] [--turns] [--tail <tail>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
@@ -103,11 +102,11 @@ tasks in one call, or their approvals and answers never reach you one by one.
 - `--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
+- `--server <server>` act on the 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)
+- `--cwd <cwd>` workspace directory; default current
 
 Exit codes:
 
@@ -137,43 +136,42 @@ following, and `next`: the command that continues it while the task runs.
 - `--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
+- `--server <server>` act on the 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)
+- `--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>]`
+## `task steer [task-id] [text] [--wait] [--model <model>] [--access <access>] [--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's engine, model, and access 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
+- `--model <model>` model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high) for this follow-up
+- `--access <access>` lower the task's access for this follow-up
+- `--server <server>` act on the 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)
+- `--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>]`
+## `task ask [task-id] [question] [--model <model>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
 ask about a task without interrupting it
 
@@ -184,13 +182,12 @@ 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
+- `--model <model>` model name[/effort] or engine/model[/effort] (sol/low, claude/opus, codex/gpt-6.1-sol/high) for the sidecar (default: the task's own)
+- `--server <server>` act on the 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)
+- `--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
@@ -203,11 +200,11 @@ 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
+- `--server <server>` act on the 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)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `task archive [task-id] [--all-stopped] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
@@ -220,11 +217,11 @@ brings it back.
 
 - `<task-id>` the task to archive
 - `--all-stopped` archive every stopped (finished) task
-- `--server <server>` act on your Coder server
+- `--server <server>` act on the 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)
+- `--cwd <cwd>` workspace directory; default current
 
 ## `task delete [task-id] [--all-archived] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
@@ -235,37 +232,40 @@ 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
+- `--server <server>` act on the 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)
+- `--cwd <cwd>` workspace directory; default current
 
-## `task approvals [task-id] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+## `task approvals [task-id] [--denied] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
 pending approvals (all tasks, or one)
 
-List only pending approvals across all tasks, or for one task. Answered approvals stay in the task log.
+List pending approvals across all tasks, --denied the denied ones (still answerable), or every approval of one task.
 
-- `<task-id>` one task (default: pending approvals of every task)
-- `--server <server>` act on your Coder server
+- `<task-id>` one task (default: approvals of every task)
+- `--denied` denied approvals instead of pending ones
+- `--server <server>` act on the 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)
+- `--cwd <cwd>` workspace directory; default current
 
-## `task approve [task-id] [approval-id] [--deny] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
+## `task approve [task-id] [approval-id] [--deny] [--reason <reason>] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
-answer an escalated permission
+answer an escalation
 
-Answer an escalated permission request. Accepts by default; --deny rejects it.
+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
-- `--server <server>` act on your Coder server
+- `--reason <reason>` why it is denied; the task reads it
+- `--server <server>` act on the 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)
+- `--cwd <cwd>` workspace directory; default current