@wular/coder 0.4.12 → 0.4.13

package/docs/agents/index.md

@@ -61,7 +61,7 @@ Only pushes to the agents repo's configured branch are imported, and each change
 | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `name`, `description`       | Text                                                                                                                                                                                                    | App name and handle; the description is added to the prompt                                                                                                                                                                |
 | `engine`, `model`, `effort` | As in `coder task run`                                                                                                                                                                                  | Engine defaults                                                                                                                                                                                                            |
-| `permissions`               | `auto` (default), `workspace-write`, `read-only`                                                                                                                                                        | Sandbox mode inside the checkout, also for the tasks its [flows](../flows.md) start                                                                                                                                        |
+| `permissions`               | `auto` (default), `workspace-write`, `read-only`                                                                                                                                                        | Sandbox mode inside the checkout, also for the tasks its [flows](../flows.md) start; only `auto` asks a person ([escalations](../access.md#escalations))                                                                   |
 | `integrations.<id>.events`  | Event names from the [integration](#integrations): a list, or a map of event → `true`, a flow name (repo `.coder/flows` or built-in such as `review`), or `{ "flow", "match", "permissions", "actAs" }` | A list or `true` runs the agent, a flow name runs that flow, `match` is a regex the event text must pass, `permissions` overrides the agent's for this event, `"actAs": "requester"` uses the requester's own GitHub token |
 | `access`                    | `read` (Read-only) or `write` (Read-write, default)                                                                                                                                                     | What it may do on its platforms and connections; also its apps' permissions                                                                                                                                                |
 | `mcp`                       | A map of MCP servers in the `.mcp.json` entry shape, as in [MCP](../mcp.md)                                                                                                                             | Servers every task of the agent attaches                                                                                                                                                                                   |

package/docs/cli/agent.md

@@ -16,7 +16,7 @@ Without --server, one row per built-in and workspace agent. With --server, list
 - `--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
 
 ## `agent show [id] [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
@@ -29,7 +29,7 @@ Describe one agent as it will run here, or its active version on a server: its s
 - `--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 agent show coder  # what the built-in agent listens to and may do
@@ -51,7 +51,7 @@ Create .coder/agents/<id>/ with an agent.json built from the integration catalog
 - `--match <match>` start tasks only for event text matching a regex, as event=regex pairs
 - `--yes` skip the questions and take the defaults
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder agent init  # answer the questions, id included
@@ -69,7 +69,7 @@ Upload one workspace agent, or every agent in .coder/agents when no id is given.
 - `--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 agent push helper  # upload helper
@@ -90,7 +90,7 @@ Run a recorded platform event (AgentEvent JSON) through an agent. With --server
 - `--flow <flow>` override the matched flow
 - `--task <task>` a runner's form: run that server task here
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder agent run helper sample-slack-mention.json  # offline: print what the agent would reply
@@ -107,7 +107,7 @@ aggregate usage by agent, installation, or engine
 - `--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
 
 ## agent integrations
 

package/docs/cli/connection.md

@@ -27,7 +27,7 @@ Connect a platform account by its name (OAuth in the browser), an API key that t
 - `--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
 GROQ_API_KEY=gsk_... coder connection add groq --env GROQ_API_KEY  # an API key from this shell
@@ -45,7 +45,7 @@ Your connections, and the MCP servers this repository and its agents declare wit
 - `--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
 
 ## `connection rm <name> [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
@@ -58,7 +58,7 @@ Remove a connection. The credential an API key connection reads stays.
 - `--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
 
 ## `connection reconnect <name> [--server <server>] [--workspace <workspace>] [--yes] [--json] [--cwd <cwd>]`
 
@@ -71,7 +71,7 @@ Give a key connection its new key, read from stdin or a prompt, or sign in to an
 - `--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
 pbpaste | coder connection reconnect groq  # the new key from the clipboard
@@ -86,4 +86,4 @@ Approve an MCP server this repository or one of its agents declares, on this mac
 - `<name>` the MCP server
 - `--agent <agent>` select the agent when names have different definitions
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current

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

@@ -38,7 +38,7 @@ Related: `coder flow watch`, `coder docs review`.
 - `--model <model>` model for the review task
 - `--effort <effort>` reasoning effort and review depth (default: medium depth)
 - `--json` JSON output
-- `--cwd <cwd>` workspace directory (default: current)
+- `--cwd <cwd>` workspace directory; default current
 
 ```sh
 coder review  # review the branch plus uncommitted work
@@ -59,7 +59,7 @@ target a dotted key (e.g. engines.codex.model). Writes go to ~/.coder/config.jso
 - `<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
@@ -84,7 +84,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

package/docs/cli/model.md

@@ -20,9 +20,9 @@ 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.
 
 - `--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
 
@@ -35,9 +35,10 @@ agent default in config. Alias: `coder model setup`.
 - `--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,7 +91,7 @@ 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>]`
 
@@ -102,7 +104,7 @@ built-in name to override it.
 - `<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,7 +4,7 @@
 
 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] [--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)
 
@@ -28,7 +28,7 @@ Use astra or fable for the hardest work; they cost the most.
 - `--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)
+- `--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)
@@ -43,9 +43,8 @@ Use astra or fable for the hardest work; they cost the most.
 - `--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
 ```
@@ -82,7 +81,7 @@ move to --archived. Shortcut: `coder list`.
 - `--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>]`
 
@@ -107,7 +106,7 @@ tasks in one call, or their approvals and answers never reach you one by one.
 - `--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:
 
@@ -141,7 +140,7 @@ following, and `next`: the command that continues it while the task runs.
 - `--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
@@ -167,7 +166,7 @@ task's engine, model, and permissions unless overridden.
 - `--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
@@ -190,7 +189,7 @@ running or stopped. To change what the task does, use `coder task steer`.
 - `--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
@@ -207,7 +206,7 @@ Interrupt a running task and mark it cancelled.
 - `--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>]`
 
@@ -224,7 +223,7 @@ brings it back.
 - `--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>]`
 
@@ -239,33 +238,36 @@ delete every archived task at once. A running task must be stopped first.
 - `--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)
+- `<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)
+- `--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
+- `--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)
+- `--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`:
 

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