copper-pilot-cli 0.1.9__tar.gz → 0.1.10__tar.gz

{copper_pilot_cli-0.1.9 → copper_pilot_cli-0.1.10}/HISTORY.md

@@ -4,6 +4,165 @@ Changelog
 
 (unreleased)
 ------------
+
+Fix
+~~~
+- Skip the killed-background resume test on Windows. [AdityaNG, Cursor]
+
+  os.killpg is POSIX-only, and that failure was the Windows CI break.
+- Resume the agent when a background shell already exited. [AdityaNG,
+  Cursor]
+
+  The continuation turn only ran while a background command was still alive, so a search that finished during the rest of the turn never woke the agent.
+
+Other
+~~~~~
+- Merge pull request #23 from CopperPilot/feat/acp-image-prompts.
+  [Aditya]
+
+  feat(acp): accept image prompts
+- Feat(acp): accept image prompts. [AdityaNG, Cursor]
+
+  T3 Code refused to start any ACP turn that carried an image because initialize never advertised promptCapabilities.image, and prompt() dropped image blocks anyway. Advertise image support, save each image block under .copperpilot/attachments, pass it as a path-first runtime attachment like the TUI does, and list the saved paths in the query so the agent reads the workspace copy.
+- Merge pull request #22 from CopperPilot/fix/resume-finished-
+  background-shell. [Aditya]
+
+  fix: resume the agent when a background shell already exited
+- Merge pull request #21 from CopperPilot/feat/validate. [Aditya]
+
+  feat: copper-pilot validate, a stage-gated read-only review graph
+- Fix(validate): default reviewers to agent mode and pass Windows CI.
+  [AdityaNG, Cursor]
+
+  Agent mode is the better default for hosted reviewers; the read-only broker still blocks design writes. Windows treated POSIX virtual paths and library URIs as relative, and os.kill(SIGTERM) aborted pytest before it could report.
+- Fix(validate): enforce reviewer.timeout_s and treat SIGTERM like
+  Ctrl-C. [AdityaNG, Claude Fable 5.1]
+
+  A hosted architecture review on a 68-part board outlived an external
+  timeout(1) wrapper; SIGTERM killed the process with no report, and the
+  graph's reviewer.timeout_s had never been applied. Each reviewer slice now
+  runs under asyncio.timeout(reviewer.timeout_s) and times out as an ERROR,
+  and the CLI maps SIGTERM onto the same partial-report path as Ctrl-C.
+- Fix(validate): scope release.repo to the project folder; tolerate
+  markdown escapes in replies. [AdityaNG, Claude Fable 5.1]
+
+  Running validate on a repository that keeps generated boards outside the
+  KiCad project (video/build/tmp_pcbs) counted them as portability failures.
+  The workspace walker now skips the same build/dist/node_modules folders as
+  discover_workspace, and release.repo only scans the project folder.
+
+  A live sch.ratings reviewer wrote '\*' inside JSON strings, which is not a
+  JSON escape and cost a repair turn; invalid escapes are now dropped before
+  the repair path is used.
+- Feat(validate): explain, --context, Python validate() API, and live
+  test. [AdityaNG, Claude Fable 5.1]
+
+  Add copper-pilot validate explain CHECK_ID (config, rendered prompt, input
+  hashes, last result), --context FILE ... (appended to every reviewer prompt
+  under Reference material and folded into the cache key), the
+  copper_pilot_cli.validate.validate()/avalidate() API returning a
+  ValidationReport, and a pytest -m live end-to-end run of validate --until S2
+  on examples/001_esp32.
+- Feat(validate): --json events, --junit, --emit-fix-prompt, MCP
+  validate tool, skill and docs. [AdityaNG, Claude Fable 5.1]
+
+  Stream validate.start/check/result/end events (plus copper.retry pass-through)
+  with --json, write JUnit XML with --junit (FAIL/ERROR -> failure/error,
+  SKIPPED -> skipped naming the blocker, WARN -> system-out), and print a
+  ready fix message for copper-pilot --mode agent with --emit-fix-prompt.
+  Expose validate(workspace?, profile?, gate?, until?, only?, effort?,
+  no_cache?) on the MCP server with per-check progress and the fixed read-only
+  reviewer policy. Add a Validate section to the review skill and plugin,
+  docs/validate.md, and the CLI reference with the exit-code table.
+- Feat(validate): hosted agent reviewers with read-only broker,
+  grounding and consensus. [AdityaNG, Claude Fable 5.1]
+
+  Add the reviewer adapter: each agent check runs CopperPilot in Ask mode
+  against a read-only snapshot of the workspace through a Manual broker whose
+  policy approves reads, scratch-folder writes and non-dangerous shell only.
+  The snapshot is re-hashed after every check; any change outside scratch is
+  an ERROR. Replies must end with a fenced json findings block (two repair
+  turns, then ERROR); findings are grounded against the design index and
+  ungrounded ones can never fail a check. per_part, per_sheet and per_netclass
+  checks fan out in batches, repeat: N takes a majority consensus, and a
+  non-retryable usage-limit block stops scheduling agent checks and exits 4.
+  default.yaml gains the agent checks for S1-S8 and the CLI gains --effort,
+  --concurrency and --repeat.
+- Feat(validate): engine, builtin checks, reports, and validate
+  list|graph|run. [AdityaNG, Claude Fable 5.1]
+
+  Add the copper-pilot validate subcommand: a stage-gated graph of read-only
+  checks loaded from a packaged default.yaml and extended by
+  .copperpilot/validate.yaml. This slice ships the engine (config models and
+  graph validation, design snapshot/hash/index, kicad-cli wrappers, dependency
+  waves, stage/full/strict gating, result cache) with the deterministic builtin
+  checks (intake.tools, intake.project, intake.intent, parts.bom_fields,
+  sch.erc, pcb.parity, pcb.rules, pcb.drc, release.outputs, release.repo) and
+  writes report.json, REPORT.md and next_actions.json under
+  .copperpilot/validate/runs/<id>/ with a latest pointer.
+- Merge pull request #20 from CopperPilot/feat/acp-session-updates.
+  [Aditya]
+
+  feat(acp): usage, plan, subagent, elicitation, and /effort session updates
+- Merge origin/main into feat/acp-session-updates. [AdityaNG, Claude
+  Fable 5.1]
+- Merge pull request #19 from CopperPilot/feat/client-turn-durability.
+  [Aditya]
+
+  feat: make hosted turns durable across transport drops
+- Fix(background): normalize CRLF shell output on Windows. [AdityaNG,
+  Claude Fable 5.1]
+- Feat: make hosted turns durable across transport drops. [AdityaNG,
+  Claude Fable 5.1]
+
+  Port the desktop client's chat-manager resilience into the shared graph
+  node so every front-end (TUI, headless, MCP, ACP) benefits:
+
+  - Retry a dropped stream up to three times with 5/10/20 s backoff and a
+    stitched "Resume where we left off" re-prompt carrying the partial
+    transcript, so the hosted agent continues instead of restarting.
+  - Classify failures like `_categorizeError`: drops, timeouts, 5xx and 429
+    retry; 4xx, invalid/oversized requests, plan refusals and auth fail fast.
+  - Capture the websocket close code and reason in the error message and log,
+    including drops that happen while a tool result is being sent.
+  - Checkpoint partial progress (text, tool calls, results) on a terminal
+    failure or cancellation with a hidden interruption note, so a later
+    manual "continue" has the prior work in context.
+  - Surface retry progress as `copper.retry` events: ACP agent thoughts, TUI
+    status/notification, headless yellow lines, MCP progress.
+  - Honour the desktop foreground-to-background shell contract: commands
+    outliving their timeout keep running, the turn continues, and their
+    output is fed back in a continuation turn after the final frame.
+  - Drop the 300 s idle-frame timeout; websocket keepalive still detects dead
+    peers and long hosted reasoning no longer trips a client limit.
+  - Fix the ACP cancel race where a server close after `session/cancel`
+    surfaced as an error instead of `cancelled`.
+- Fix(acp): read slash commands from the first prompt block. [AdityaNG,
+  Claude Fable 5.1]
+
+  T3 Code appends runtime context as a second text block, so /effort was
+  reaching the hosted agent instead of being answered locally.
+- Fix(acp): elicit option questions, unwrap T3 prompts, bound question
+  waits. [AdityaNG, Claude Fable 5.1]
+
+  T3 Code in Full access auto-selects the first option of a permission prompt,
+  so clarifying questions with options now use form elicitation (enum) when the
+  client supports it. /effort is recognised inside T3's <user_request> envelope.
+  Questions nobody answers within 100 seconds are skipped with a note, because
+  the hosted service drops a turn whose tool result takes longer than two minutes.
+- Feat(acp): usage, plan, subagent, elicitation, and /effort updates.
+  [AdityaNG, Claude Fable 5.1]
+
+  Emit usage_update from hosted token counts so T3 Code's context meter works,
+  project hosted todo_list events and .copperpilot/plans artifacts onto ACP plan
+  entries, render Intelligence survey workers as think tool calls, collect
+  free-text clarifications through ACP form elicitation when the client supports
+  it, and advertise a locally handled /effort command.
+
+
+0.1.9 (2026-10-16)
+------------------
+- Release: version 0.1.9 🚀 [AdityaNG]
 - Merge pull request #18 from CopperPilot/feat/acp-server. [Aditya]
 
   feat: add `copper-pilot acp` Agent Client Protocol server

{copper_pilot_cli-0.1.9 → copper_pilot_cli-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: copper-pilot-cli
-Version: 0.1.9
+Version: 0.1.10
 Summary: CopperPilot hosted agent for the terminal and LangChain
 Project-URL: Homepage, https://copperpilot.ai
 Project-URL: Repository, https://github.com/CopperPilot/copper-pilot-cli
@@ -122,6 +122,22 @@ Balanced effort is the default. Paid-plan users can select Intelligence with
 server-owned survey subagents and shows their lifecycle through the existing
 Deep Agents task rows; Intelligence Plan turns survey before writing a plan.
 
+## Validate
+
+```console
+copper-pilot validate ./my-board
+```
+
+Runs a stage-gated graph of read-only reviewers over the KiCad workspace:
+`kicad-cli` checks (ERC, DRC, schematic parity, board rules, Gerbers) plus
+hosted Agent-mode reviewers, each scoped to one concern, in the order a hardware
+engineer reviews a board. It never edits design files. The verdict, a
+`REPORT.md`, and `next_actions.json` (only the earliest failing stage, worst
+first) land in `.copperpilot/validate/latest/`; `--emit-fix-prompt` prints a
+ready message for `copper-pilot --mode agent`. Exit codes: 0 pass, 1 fail,
+2 config error, 3 incomplete, 4 not logged in or usage limit. See
+[docs/validate.md](docs/validate.md).
+
 ## Use from Claude Code, Cursor, or Codex
 
 CopperPilot stays the electronics agent. Copy
@@ -139,7 +155,8 @@ Claude Code can also install the in-repo plugin:
 /plugin install copper-pilot
 ```
 
-That plugin starts `copper-pilot mcp` and adds `@copper-pilot` plus
+That plugin starts `copper-pilot mcp` (tools `status`, `ask`, `plan`, `run`,
+`resume`, `threads_list`, `validate`) and adds `@copper-pilot` plus
 `/copper-pilot-review`. Editors that speak the Agent Client Protocol, such as
 Zed, can run `copper-pilot acp` after `pip install "copper-pilot-cli[acp]"`.
 Setup for Cursor, Codex, Zed, and approvals: [docs/harness.md](docs/harness.md).

{copper_pilot_cli-0.1.9 → copper_pilot_cli-0.1.10}/README.md

@@ -68,6 +68,22 @@ Balanced effort is the default. Paid-plan users can select Intelligence with
 server-owned survey subagents and shows their lifecycle through the existing
 Deep Agents task rows; Intelligence Plan turns survey before writing a plan.
 
+## Validate
+
+```console
+copper-pilot validate ./my-board
+```
+
+Runs a stage-gated graph of read-only reviewers over the KiCad workspace:
+`kicad-cli` checks (ERC, DRC, schematic parity, board rules, Gerbers) plus
+hosted Agent-mode reviewers, each scoped to one concern, in the order a hardware
+engineer reviews a board. It never edits design files. The verdict, a
+`REPORT.md`, and `next_actions.json` (only the earliest failing stage, worst
+first) land in `.copperpilot/validate/latest/`; `--emit-fix-prompt` prints a
+ready message for `copper-pilot --mode agent`. Exit codes: 0 pass, 1 fail,
+2 config error, 3 incomplete, 4 not logged in or usage limit. See
+[docs/validate.md](docs/validate.md).
+
 ## Use from Claude Code, Cursor, or Codex
 
 CopperPilot stays the electronics agent. Copy
@@ -85,7 +101,8 @@ Claude Code can also install the in-repo plugin:
 /plugin install copper-pilot
 ```
 
-That plugin starts `copper-pilot mcp` and adds `@copper-pilot` plus
+That plugin starts `copper-pilot mcp` (tools `status`, `ask`, `plan`, `run`,
+`resume`, `threads_list`, `validate`) and adds `@copper-pilot` plus
 `/copper-pilot-review`. Editors that speak the Agent Client Protocol, such as
 Zed, can run `copper-pilot acp` after `pip install "copper-pilot-cli[acp]"`.
 Setup for Cursor, Codex, Zed, and approvals: [docs/harness.md](docs/harness.md).

copper_pilot_cli-0.1.10/VERSION

@@ -0,0 +1 @@
+0.1.10

{copper_pilot_cli-0.1.9 → copper_pilot_cli-0.1.10}/docs/cli.md

@@ -8,6 +8,7 @@ copper-pilot auth --help
 copper-pilot threads --help
 copper-pilot mcp --help
 copper-pilot acp --help
+copper-pilot validate --help
 ```
 
 Python 3.11 or newer is required. Install with `pip install copper-pilot-cli`.
@@ -50,6 +51,39 @@ Headless mode is also used when `--message` is set and stdout is not a TTY.
 With `--json --no-stream`, the document includes `thread_id` so a later run can
 pass `--resume`.
 
+## Validate
+
+```console
+copper-pilot validate [workspace] [--profile dev|release] [--gate stage|full|strict]
+                      [--until STAGE] [--only ID,...] [--skip ID,...] [--json] [--junit PATH]
+copper-pilot validate list|graph [workspace]
+copper-pilot validate explain CHECK_ID [workspace]
+```
+
+Runs a stage-gated graph of read-only reviewers: `kicad-cli` checks (ERC,
+DRC, parity, rules, Gerbers) and hosted Agent-mode reviewers scoped to one
+concern each, in the order a hardware engineer reviews (intake, architecture,
+parts, schematic, netlist-to-layout, placement, routing, DFM/DFA, release).
+It never modifies design files. Outputs land in `.copperpilot/validate/latest/`:
+`report.json`, `REPORT.md`, and `next_actions.json` (only the earliest failing
+stage, worst first). Uses the stored credential; never opens a browser.
+
+| Code | Meaning |
+|------|---------|
+| 0 | PASS: every selected check is PASS or WARN |
+| 1 | FAIL: at least one blocking FAIL or ERROR |
+| 2 | Usage or config error: bad flags, invalid YAML, a dependency cycle |
+| 3 | INCOMPLETE: no failures, but checks were SKIPPED because of `--gate`, `--until` or `--only` |
+| 4 | Environment: not logged in, or a usage-limit block |
+
+```console
+copper-pilot validate ./my-board --json --gate stage
+copper-pilot validate ./my-board --until S3 --emit-fix-prompt
+copper-pilot validate ./my-board --profile release --gate full --junit validate.xml
+```
+
+Flags, config, the default graph and the fix loop: [validate.md](validate.md).
+
 ## MCP
 
 ```console
@@ -68,6 +102,7 @@ write to stdout; the protocol owns it.
 | `run` | `--mode agent`. Optional `effort`; `approval` is `auto` (default) or `yolo`. |
 | `resume` | Continue `thread_id`. Optional `mode`, `effort`, and the same approval as `run`. |
 | `threads_list` | List threads for this workspace (`limit`, `all_workspaces`). |
+| `validate` | Read-only stage-gated review; returns `verdict`, `exit_code`, `report_path`, `next_actions`. |
 
 Workspace is the tool argument, else `CLAUDE_PROJECT_DIR`, else the process
 current directory. Manual approval is TUI-only. See [harness.md](harness.md).
@@ -93,12 +128,23 @@ advertises a terminal auth method that runs `copper-pilot auth login`.
 | Config options | `mode` and `effort` (`balanced` default, `intelligence` paid) |
 | `session/load` | Resumes an existing thread id and replays its history |
 | `session/request_permission` | Auto approval; non-routine writes and shell prompt the editor |
+| `elicitation/create` | Clarifying questions (options or free text) when the client advertises form elicitation |
 | `session/cancel` | Cancels the hosted turn and local tools |
+| `usage_update` | Prompt tokens of the latest hosted turn; window size is unknown (0) |
+| `plan` | Hosted todo list events and `.copperpilot/plans/*.plan.md` todos |
+| `available_commands_update` | `/effort balanced\|intelligence`, answered locally |
 
 "Allow all for this session" switches that session to YOLO until the server
-exits; it is never saved. Clarifying questions with options are shown as
-permission choices plus Skip; free-text questions are declined with a message
-to continue in the TUI. See [harness.md](harness.md).
+exits; it is never saved. Clarifying questions use ACP form elicitation when
+the client supports it (T3 Code does): options become an enum, free text a
+string field. Without form elicitation, option questions are shown as
+permission choices plus Skip and free-text questions are declined with a
+message to continue in the TUI. A question nobody answers within 100 seconds
+is skipped with a note asking the model to repeat it in its reply, because the
+hosted service drops a turn whose tool result takes longer than two minutes.
+Intelligence survey workers appear as `think` tool calls named
+`Survey: <task>` whose status and output track the worker.
+See [harness.md](harness.md).
 
 ## Effort and Intelligence
 
@@ -167,6 +213,38 @@ searches run freely. Writes, edits, deletes, and shell commands are gated:
 
 `--yolo` wins over `--auto-approve`. Saved preferences never enable YOLO.
 
+## Turn durability
+
+Every front-end (TUI, headless, MCP, ACP) runs a hosted turn through the same
+checkpointed graph node, which mirrors the desktop client's chat manager:
+
+- A stream that drops before the final frame (socket close, timeout, 5xx, 429)
+  is retried up to three times with 5 s, 10 s, and 20 s backoff. The retry
+  re-prompts the hosted agent with the partial transcript and
+  `Resume where we left off: <original message>` so it continues rather than
+  restarting. Deterministic failures (4xx other than 429, invalid or oversized
+  requests, plan refusals, auth) fail immediately.
+- Retry progress is visible: the TUI status bar and a notification, a yellow
+  line in headless text mode, MCP progress, and ACP agent thoughts
+  (`Retrying (1/2) in 5s: …`). `--json` emits `copper.retry` events.
+- The websocket close code and reason are carried into the error message
+  (`close code 1011 received: …`) and the log file.
+- Whatever a failed turn produced before the error (assistant text, tool calls
+  and results) is still checkpointed with a hidden
+  `[Turn interrupted before completion: …]` note, so a later "continue" has the
+  prior work in context.
+- There is no idle timeout between frames once a turn is streaming; websocket
+  keepalive still detects dead peers, and long hosted reasoning or subagent
+  runs no longer trip a client-side limit. The first frame must still arrive
+  within 60 s.
+- Shell commands run in the foreground for the requested timeout (default
+  25 s) and then move to the background unless the request sets
+  `kill_on_timeout` or `background: false`. After the final frame the client
+  resumes the agent with their output. Commands still running are awaited
+  first. Commands that already exited while the model was still working are
+  delivered too, so a search that finishes mid-turn is not dropped. Output is
+  capped at 5 MB and the whole process tree is killed on cancel.
+
 ## Usage limits
 
 The hosted service owns weekly and window usage. The CLI does not show raw

{copper_pilot_cli-0.1.9 → copper_pilot_cli-0.1.10}/docs/development.md

@@ -6,7 +6,7 @@ How to build, test, and release this package. Contributor workflow lives in
 ## Layout
 
 ```
-src/copper_pilot_cli/   Python package
+src/copper_pilot_cli/   Python package (validate/ holds the review graph engine)
 tests/                  pytest suite
 examples/               Runnable examples
 docs/                   User and developer docs
@@ -53,6 +53,9 @@ unreleased Python.
   credential is stored.
 - ESP32 example helpers are covered in `tests/test_esp32_example.py`. Running
   `python examples/001_esp32/main.py` needs KiCad 10 and a live account.
+- `tests/test_validate.py` covers the validate engine with a fake `kicad-cli`
+  and fake hosted turns; `tests/test_validate_live.py` runs
+  `validate --until S2` on `examples/001_esp32` under `pytest -m live`.
 
 Do not commit credentials, `.venv/`, or `dist/`.
 
@@ -82,6 +85,16 @@ A WebSocket `error` frame keeps `code`, `status`, `block_reason`,
 `error` string use `public_message`; `--json` and the MCP event digest keep
 the object.
 
+`classify_error` in `copper_protocol.py` ports the desktop client's error
+categories (`timeout`, `connection`, `server`, `rate_limit`, `usage_limit`,
+`authentication`, `invalid_request`, `payload_too_large`, `protocol`,
+`network`, `aborted`, `unknown`) with a `retryable` flag. The graph node in
+`copper_graph.py` owns the retry loop, the stitched "Resume where we left off"
+re-prompt, partial-progress checkpointing, and the background shell wait;
+`copper_background.py` owns the foreground-to-background shell contract.
+Transport-level failures before the first frame are retried once inside
+`HostedChatClient.stream`; everything after that is the node's job.
+
 Device login and the WebSocket `User-Agent` (`CopperPilot CLI/<version>`)
 read the installed package version. That version comes from `VERSION`.
 

{copper_pilot_cli-0.1.9 → copper_pilot_cli-0.1.10}/docs/harness.md

@@ -35,6 +35,10 @@ Use `--mode plan` for a plan, `--mode agent -y` for Auto local writes, and
 `--yolo` only when the user asked to skip local approval. Add
 `--effort intelligence` for a paid Intelligence turn; Balanced is the default.
 
+For sign-off, run `copper-pilot validate --json`, read
+`.copperpilot/validate/latest/next_actions.json`, fix with `--mode agent -y`
+citing the finding IDs, and re-run. See [validate.md](validate.md).
+
 ## Option 2: MCP conductor (`copper-pilot mcp`)
 
 The same process as the CLI, same stored credential. Stdio JSON-RPC; do not
@@ -88,6 +92,7 @@ Point the host at `copper-pilot mcp` on stdio. Tools:
 | `run` | Mutating agent turn (`--mode agent`); optional `effort` |
 | `resume` | Continue `thread_id` (`mode` defaults to `agent`; optional `effort`) |
 | `threads_list` | List threads for this workspace |
+| `validate` | Read-only stage-gated review graph (`copper-pilot validate`); returns `next_actions` |
 
 Workspace is the tool `workspace` argument, else `CLAUDE_PROJECT_DIR`, else the
 process current directory.
@@ -136,11 +141,36 @@ Launch `copper-pilot acp` on stdio. The server implements `initialize`,
 `copper-pilot auth login`; clients that append it to the agent command, such as
 T3 Code, get `copper-pilot acp auth login`, which the CLI treats the same way.
 
+`initialize` advertises `promptCapabilities.image`. Each `image` prompt block
+is written to `.copperpilot/attachments/` in the workspace and passed to the
+hosted agent as a path-first attachment, the same way the TUI sends pasted
+images. The query also lists the saved paths, because clients such as T3 Code
+mention their own copy outside the workspace. A prompt with images but no text
+asks the agent to analyze them.
+
 Hosted text, reasoning, and status arrive as agent message and thought chunks;
 hosted tool requests and results arrive as `tool_call` and `tool_call_update`.
 A hosted error ends the prompt with a JSON-RPC error whose `details` carry the
 public message.
 
+Further session updates:
+
+- `usage_update` after each hosted usage report. `used` is the prompt tokens
+  of the latest turn and `size` is `0`, because the hosted service does not
+  report the model's context window; the raw hosted counts are in `_meta`.
+  T3 Code shows the count alone when the size is unknown.
+- `plan` whenever the hosted agent updates its todo list (`todo_list` status
+  events) or writes a `.copperpilot/plans/<name>.plan.md` artifact. Plan todos
+  map `open`, `running`, and `done` onto `pending`, `in_progress`, and
+  `completed`, the same statuses the Electron client's plan card uses.
+- Intelligence survey workers are `think` tool calls titled `Survey: <task>`
+  with `in_progress`, `completed`, or `failed` status and the worker's output
+  or error as content, mirroring the Electron client's subagent card.
+- `available_commands_update` once per session advertising `/effort`. A prompt
+  of `/effort balanced` or `/effort intelligence` is answered locally with a
+  `config_option_update` and a confirmation; `/effort` alone reports the
+  current value.
+
 ## Approval
 
 | Mode | Where | Behavior |
@@ -155,9 +185,17 @@ always use Auto. `run` and `resume` default to Auto.
 ACP sessions start in Auto. Anything Auto would have prompted for in the TUI
 is sent to the editor as `session/request_permission` with Allow, Allow all
 for this session, and Reject. Choosing "Allow all" puts that session in YOLO
-until the server exits. Hosted clarifying questions that offer options are
-presented the same way, with a Skip choice; free-text questions are declined
-with a pointer to the TUI.
+until the server exits. Hosted clarifying questions use ACP form elicitation
+(`elicitation/create`) when the client advertised
+`clientCapabilities.elicitation.form`: options become an enum field and free
+text a string field, and a declined or cancelled form counts as Skip. This
+matters for hands-off clients: T3 Code in Full access auto-selects the first
+option of a permission prompt, but always shows a form to the user. Clients
+without form elicitation get option questions as permission choices plus Skip
+and a rejection pointing to the TUI for free text. Either way, a question that
+is still unanswered after 100 seconds is skipped with a note telling the model
+to ask again in its reply, because the hosted service closes a turn whose tool
+result takes longer than two minutes.
 
 `effort` is `balanced` (default) or `intelligence`. Intelligence requires a
 paid plan. It may run server-owned survey subagents; Plan turns survey before