command-code 1.3.0 → 1.3.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # command-code
 
+## 1.3.1
+
+### Patch Changes
+
+- refactor: improve usage alerts
+
 ## 1.3.0
 
 ### Minor Changes

package/dist/bundled/command-code-knowledge/reference/custom-agents.md

@@ -1,91 +1,325 @@
-<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/core-concepts/custom-agents/page.mdx. Regenerate: pnpm generate:knowledge -->
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/agents/page.mdx. Regenerate: pnpm generate:knowledge -->
 
 # Custom Agents
 
-Custom agents are specialized **subagents** Command Code can delegate to. Each one gets its own context window, **system prompt**, and **tool** set, so you can keep exploration, planning, or niche workflows separate from the main session.
+A subagent is a separate worker Command Code hands a task to. It runs in its own context window with its own tools, system prompt, and (optionally) its own model. Command Code can run several at once, so work like editing three modules can happen in parallel instead of one at a time.
 
-Built-in defaults (**Explore** and **Plan**) are always available. Your definitions live alongside them as Markdown files in **project** `.commandcode/agents/` or **personal** `~/.commandcode/agents/`.
+Three built-in agents are always available: **General**, **Explore**, and **Plan**. You can add your own as Markdown files.
 
 ---
 
-## Open the agents manager
+## Quick start
 
-In [interactive mode](https://commandcode.ai/docs/core-concepts/interactive-mode), run:
+The fastest way to make a subagent is to ask for one:
+
+```text
+create a code-reviewer subagent that reviews diffs for bugs and security issues
+```
+
+Command Code writes the agent file for you. From then on it delegates to that agent when the task matches.
+
+To manage agents yourself, run:
 
 ```text
 /agents
 ```
 
-This opens the agents screen: your custom agents (if any), **Create new agent**, and the default agents list.
+That's it for getting started. The rest of this page covers making agents by hand, how delegation works, and the full file reference.
+
+---
+
+## Built-in agents
+
+These ship with Command Code and are always available. They're read-only - you can't edit or delete them.
+
+| **Agent** | **When it runs** | **Tools** |
+| --------- | ---------------- | --------- |
+| **General** | The default when no other agent fits. Research and multi-step tasks. | All tools |
+| **Explore** | Codebase search and understanding that touches many files. | Read-only: `read_file`, `read_directory`, `read_multiple_files`, `grep` |
+| **Plan** | Designing an approach and weighing trade-offs. | `read_file`, `read_multiple_files` |
+
+When Command Code delegates without naming an agent, the task goes to **General**.
 
 ---
 
-## Create a new agent
+## Creating an agent
+
+### Ask Command Code (recommended)
+
+Describe the agent in plain language, as shown in [Quick start](#quick-start). Command Code drafts the name, description, system prompt, and a sensible tool set, then saves the file. You review and adjust.
+
+Choosing **Create agents with Command Code** in the `/agents` menu shows the same thing - it points you back to just asking:
+
+```text
+ Create agents with Command Code
+
+ Ask Command Code to create or update subagents for you, e.g.
+
+   ‣ "create a code-reviewer subagent that reviews diffs for bugs"
+   ‣ "make a changelog agent that uses a fast model"
+
+ Or edit the files directly:
+
+   • .commandcode/agents/    (this project)
+   • ~/.commandcode/agents/  (all projects)
+
+ Docs: https://commandcode.ai/docs/core-concepts/custom-agents
+
+ Press Enter to go back and just ask
+```
+
+### The /agents manager
+
+Run `/agents` to open the manager. It lists two create actions, your custom agents grouped by scope, and the read-only defaults.
+
+```text
+ Agents (2 agents)
+
+   1. Create agents with Command Code (recommended)
+   2. Create manually
+
+   User agents
+ > changelog-writer
+   release-notes
 
-Choose **Create new agent**, then walk through the wizard.
+   Project agents
+   code-reviewer
 
-### 1. Choose where it lives
+   Default agents (read-only)
+   General
+   Explore
+   Plan
 
-| **Scope** | **Path** | **When to use** |
-| --------- | -------- | --------------- |
-| **Project** | `.commandcode/agents/` in the current repo | Shared with the team; commit in Git. |
-| **Personal** | `~/.commandcode/agents/` | Available in every project on your machine. |
+ ↑↓ navigate · Enter to select · Esc to close
 
-### 2. Choose how to build it
+ Agents live in .commandcode/agents/ (project) and
+ ~/.commandcode/agents/ (all projects) - edit the files directly anytime.
+ Docs: https://commandcode.ai/docs/core-concepts/custom-agents
+```
+
+Sections only appear when they have agents. With no custom agents, the title reads `Agents (No custom agents)`.
+
+### The manual wizard
 
-| **Option** | **Description** |
-| ---------- | --------------- |
-| **Generate with Command Code (recommended)** | Describe the agent’s role and when to use it; Command Code drafts configuration for you. |
-| **Manual configuration** | Set the identifier, system prompt, “when to use” description, and tools yourself. |
+Pick **Create manually** to fill in every field yourself. The steps are: location → identifier → system prompt → description → tools → model → confirm.
 
-### 3. Generate: write a thorough description
+**Choose where it lives:**
 
-If you chose **Generate with Command Code**, you’ll see a prompt like the one below. The more specific you are about responsibilities, boundaries, and when delegation should happen, the better the result.
+```text
+ Create new agent
+ Choose location
 
-Command Code will automatically generate:
+ > 1. Project (.commandcode/agents/)
+   2. Personal (~/.commandcode/agents/)
+```
 
-- **Agent name**
-- **Description** (when to use it)
-- **System prompt**
+Project agents are committed with the repo and shared with your team. Personal agents live in your home directory and work in every project.
 
-You only need to review them, choose which **tools** the agent should have access to, and pick which **model** it runs on (or keep the default of inheriting the session model).
+**Name it, prompt it, describe when to use it.** Three steps set the identifier (must be unique, not a reserved name), the system prompt, and the description Command Code matches against to decide when to delegate.
 
-After generation, you’ll confirm tools and save. Manual creation follows the same tool-selection and confirmation steps, but you’ll enter the **name**, **description**, and **system prompt** yourself.
+```text
+ Create new agent
+ Agent type (identifier)
+
+ Enter a unique identifier for your agent:
+
+ > code-reviewer_
+   e.g. code-reviewer, unit-tester
+
+ Enter to continue · Esc to cancel
+```
+
+**Select tools.** Categories toggle groups; **Show advanced options** lists individual tools. The first row saves your choice.
+
+```text
+ Create new agent
+ Select tools
+
+ > [ Continue ]
+   ────────────────────────────────
+   [x] Read-only tools
+   [x] Edit tools
+   [ ] Execution tools
+   [x] Search tools
+   [ Show advanced options ]
+
+ 3 tools selected
+```
+
+**Select model.** Keep the session model, or pin one this agent always uses.
+
+```text
+ Create new agent
+ Select model
 
+ > 1. Inherit from session (default)
+   2. Pick a specific model
+```
+
+**Confirm.** A summary shows every field before the file is written:
+
+```text
+ Create new agent
+ Confirm and save
+
+ Name:        code-reviewer
+ Location:    .commandcode/agents/ (project)
+ Tools:       Read-only, Edit, Search
+ Model:       Inherit from session
+
+ Description (Tells Command Code when to use this agent):
+   Use this agent when you are done writing code and want a
+   diff reviewed for bugs and security issues.
+
+ System Prompt:
+   You are a meticulous code reviewer. Prioritize correctness,
+   security, and clear feedback. Cite file paths and lines.
+
+ Press Enter to save · Esc to cancel
+```
+
+Agents you add or edit are picked up on the next turn - no restart.
+
+### Edit the file directly
+
+An agent is a Markdown file. The front matter configures it; the body is the system prompt.
+
+```markdown
+---
+name: code-reviewer
+description: Use after writing code to review a diff for bugs and security issues.
+tools: read_file, read_multiple_files, grep, glob
+model: claude-sonnet-5
 ---
 
-## Agent files (manual editing)
+You are a meticulous code reviewer. Prioritize correctness, security, and clear
+feedback. Cite file paths and line numbers. Be concise.
+```
+
+Drop the file in `.commandcode/agents/` (project) or `~/.commandcode/agents/` (personal) and it loads on the next turn. Full field list is in the [Reference](#reference).
+
+---
+
+## How it works
+
+You don't call a subagent yourself. You describe what you want, and Command Code decides when to delegate by calling its built-in `agent` tool. The subagent runs in its own loop, does the work, and returns one result.
+
+- **Parallel runs.** Command Code starts independent subagents at the same time by making several `agent` calls in one turn. Five explorers, or three agents each editing a different module, run together instead of in sequence.
+- **Isolated context.** A subagent's file reads and reasoning stay in its own context window, so a long exploration doesn't fill up the main conversation.
+- **Own model.** An agent can pin its own model, so a slow planner and a fast implementer keep separate prompt caches.
+- **One level deep.** Subagents can't start their own subagents - the `agent` tool is removed from their tool set.
+
+### Background runs
 
-Each agent is a **Markdown file** with YAML front matter and a body that becomes the **system prompt**.
+A run can be detached. When it's started in the background (or the agent sets `background: true`), the `agent` tool returns right away with an `agent_id` and the main session keeps going. The result is collected later with the `agent_output` tool, which can `wait` for it, check `status`, or `kill` the run.
 
-- **`name`** - Identifier and filename (e.g. `security-review.md` → agent `security-review`).
-- **`description`** - Tells Command Code **when** to use this agent.
-- **`tools`** - Comma-separated tool list, **`"*"`** for all tools, or a restriction such as read-only style lists.
-- **`model`** - Optional model this agent always runs on (any `/model` id, e.g. `deepseek/deepseek-v4-pro` or `claude-sonnet-5`). Omit it or set `model: inherit` to follow the session's current model. Per-agent models let you pin deep-reasoning models to architect/planner agents while implementation or docs agents ride faster, cheaper ones - each keeps its own prompt cache.
+### Where agents load from
 
-Do not use reserved names for custom agents: `explore`, `plan`, `review`, and `general`. Those names are reserved for built-in or internal behavior; custom files with those names are ignored.
+| **Source** | **Path** | **Notes** |
+| ---------- | -------- | --------- |
+| Bundled | (built-in) | General, Explore, Plan - always present, read-only |
+| Personal | `~/.commandcode/agents/` | Every project on your machine |
+| Project | `.commandcode/agents/` | Committed with the repo; shared with the team |
 
-Example shape:
+They load in that order and the **first** definition of a name wins. Files are re-scanned each turn, so adds, edits, and deletes take effect right away.
 
-**Example agent file**
+Reserved names (`explore`, `plan`, `review`, `general`) are used by built-in behavior. A custom file with one of these names is ignored.
+
+---
+
+## Reference
+
+### Frontmatter fields
+
+Only these keys are read; anything else is ignored. All except `name` are optional.
+
+    The agent's id, the name Command Code delegates to. Defaults to the filename without `.md` (`code-reviewer.md` → `code-reviewer`). Characters outside `a-z A-Z 0-9 _ -` become `_`. Can't be a reserved name.
+    When to use the agent. This is the text Command Code matches against, so be specific. Defaults to empty.
+    Tools the agent may use. `"*"` grants all; otherwise a comma- or space-separated list (or a YAML array). Omit it and the agent gets no tools.
+    Deny list applied after `tools`. Deny beats allow, so pair it with `tools: "*"` to mean "everything except these". Same format as `tools`.
+    Model this agent always runs on: any `/model` id. See [Available models](https://commandcode.ai/docs/reference/cli/models) for the full list, or run `cmd --list-models`. Omit it (or set `model: inherit`) to follow the session model.
+    Caps the agent's loop. Default `100`.
+    Overrides the session's permission mode for this agent. One of `default`, `auto-accept`, `bypass`, `plan`, `dont-ask`. A session already in `plan` or `bypass` wins. Defaults to inheriting the session.
+    When `true`, every run detaches: the `agent` tool returns an `agent_id` and results come from `agent_output`.
+    When `true`, the agent's final message is shown verbatim in the feed instead of a short "done" line. The model still receives it as the result.
+
+### Tools
+
+Tool ids are the same names shown in the `/agents` wizard's advanced list. How `tools` is read:
+
+- `tools: "*"` - every tool, including connected MCP tools.
+- `tools: read_file, grep, glob` - an allowlist. Comma- or space-separated; a YAML array also works.
+- Omitted - no tools.
+
+Common ids by category:
+
+| **Category** | **Tool ids** |
+| ------------ | ------------ |
+| Read-only | `read_file`, `read_directory`, `read_multiple_files`, `grep` |
+| Edit | `edit_file`, `write_file` |
+| Execution | `shell_command`, `run_command`, `kill_shell` |
+| Search | `web_search`, `web_fetch` |
+| Other | `glob`, `todo_write`, `task_create`, `task_update`, `task_list`, `task_get`, `task_output`, `task_stop`, `cron_create`, `cron_list`, `cron_delete`, `get_diagnostics`, `get_command_code_knowledge`, `taste`, `ask_user_question`, `sleep`, `config`, `enter_plan_mode`, `exit_plan_mode`, `enter_worktree`, `exit_worktree` |
+
+MCP tools go in by their raw name, e.g. `mcp__github__get_me`. The `agent` and `agent_output` tools can't be granted - that's what keeps delegation one level deep.
+
+### Models
+
+The `model` field takes any id you'd pass to `/model`. To find one:
+
+- See [Available models](https://commandcode.ai/docs/reference/cli/models) for the full list,
+- open the `/model` picker, or
+- run `cmd --list-models` in the shell.
+
+Use ids exactly as `--list-models` prints them. Examples: `claude-opus-4-8`, `claude-sonnet-5`, `claude-haiku-4-5`, `moonshotai/kimi-k2.6`, `zai-org/glm-5.2`.
+
+Omitting `model` is the same as `model: inherit` - the agent follows the session's `/model`. Pinning a model gives the agent its own prompt cache, so a slow planner and a fast implementer don't thrash each other's.
+
+### Full example
+
+Every field, with valid values. Copy it and delete what you don't need.
+
+**.commandcode/agents/report-writer.md**
 ```markdown
 ---
-name: "security-review"
-description: "Use for dependency and secret-scanning review before release."
-tools: "glob, grep, read_file, think"
-model: "claude-sonnet-5"
+name: report-writer
+description: "Writes a structured research report from the current repo. Delegate long-form summarization and analysis tasks here."
+tools: "*"                                  # grant everything…
+disallowedTools: shell_command, write_file  # …except shells and file writes
+model: claude-opus-4-8                       # any /model id, or omit to inherit
+maxTurns: 40                                 # cap the loop (default 100)
+permissionMode: plan                         # default|auto-accept|bypass|plan|dont-ask
+background: true                             # detach; collect via agent_output
+showOutput: true                             # render the final report in the feed
 ---
 
-You are a security-focused reviewer. Prioritize dependency risks, secrets in code,
-and unsafe patterns. Be concise; cite file paths and lines.
+You are a research report writer. You receive one self-contained task and
+produce a complete, well-structured Markdown report as your final message.
+
+- Gather only the files and facts the task requires.
+- Work on your own - you can't ask follow-up questions.
+- Your final message is the deliverable; make it complete.
 ```
 
-You can edit files directly in `.commandcode/agents/` or `~/.commandcode/agents/`, or recreate them through `/agents`.
+Quick lookup:
+
+| **Field** | **Type** | **Values** | **Default** |
+| --------- | -------- | ---------- | ----------- |
+| `name` | string | id, sanitized to `a-z A-Z 0-9 _ -`; not reserved | filename |
+| `description` | string | any text | `""` |
+| `tools` | string \| list | `"*"`, or comma/space-separated ids, or a YAML list | none |
+| `disallowedTools` | string \| list | same format as `tools`; applied after it | - |
+| `model` | string | any `/model` id, or `inherit` | inherit |
+| `maxTurns` | integer | positive integer | `100` |
+| `permissionMode` | string | `default`, `auto-accept`, `bypass`, `plan`, `dont-ask` | inherit |
+| `background` | boolean | `true` / `false` | `false` |
+| `showOutput` | boolean | `true` / `false` | `false` |
 
 ---
 
 ## Next steps
 
 - [Interactive mode](https://commandcode.ai/docs/core-concepts/interactive-mode) - slash commands and session controls
+- [Background tasks](https://commandcode.ai/docs/core-concepts/background-tasks) - detached, long-running work
 - [Memory](./memory.md) - project and user instructions in `AGENTS.md`
 - [Skills](./skills.md) - reusable skill packages vs. full subagents

package/dist/bundled/mod-builder/reference/api.md

@@ -12,7 +12,7 @@
 | `cmd.cwd` | `string` | workspace root |
 | `cmd.session` | `ModSessionApi \| undefined` | persistence seam; undefined until bound |
 | `cmd.events` | `ModEventBus` | `emit(channel, data?)` / `on(channel, handler)` cross-mod bus |
-| `cmd.ui` | `ModUi` | `notify` / `confirm` / `select` / `input` (each with `{timeoutMs, timeoutValue}`) / `setStatus` / `widget` / `refreshWidgets` |
+| `cmd.ui` | `ModUi` | `notify` / `confirm` / `select` / `input` / `setStatus` / `widget` / `refreshWidgets` |
 | `cmd.sessions` | `ModSessionControls` | `compact` / `tree` / `leafId` / `navigateTree` / `setLabel` |
 
 ## Registration (factory-time; each returns `Disposable`)
@@ -78,4 +78,4 @@ The per-hook contracts, ordering guarantees, and error policy are in [the hook c
 
 ## `on` event types
 
-Any `AgentEvent['type']` - including `run_start`, `run_end`, `turn_start`, `turn_end`, `model_request_start`, `model_request_end`, `tool_running`, `tool_completed`, `tool_errored`, `subagent_start`, `subagent_stop`, `compaction_start`, `compaction_done`, `notice`, `session_titled`, `mod_error` - plus the two host lifecycle events `session_start` / `session_shutdown`. (`subagent_start`/`subagent_stop` are SubagentStart/Stop; `compaction_start`/`compaction_done` are Pre/PostCompact; `notice` is Notification.) The full payload catalog is in [the AgentEvent catalog](./hooks-and-events.md#agent-event-catalog).
+Any `AgentEvent['type']` - including `run_start`, `run_end`, `turn_start`, `turn_end`, `model_request_start`, `model_request_end`, `tool_running`, `tool_completed`, `tool_errored`, `subagent_start`, `subagent_stop`, `subagent_progress`, `compaction_start`, `compaction_done`, `notice`, `session_titled`, `permission_mode_changed`, `config_setting_changed`, `mod_error` - plus the two host lifecycle events `session_start` / `session_shutdown`. (`subagent_start`/`subagent_stop` are SubagentStart/Stop; `compaction_start`/`compaction_done` are Pre/PostCompact; `notice` is Notification.) The full payload catalog is in [the AgentEvent catalog](./hooks-and-events.md#agent-event-catalog).

package/dist/bundled/mod-builder/reference/hooks-and-events.md

@@ -224,12 +224,15 @@ One sync sink, fan out with `createEventBus`. Payloads are snapshots - never liv
 | `tool_update` | streaming tool progress | `partial` content |
 | `tool_completed` / `tool_errored` | after afterToolCall | post-hook `result` / `error` text; `afterToolCall`'s `isError` can select which one fires |
 | `tool_hooks` | emitted by the user-hooks mod, before the phase's terminal tool event | `phase: 'pre'\|'post'`, `lines`, `outcome` |
-| `subagent_start` / `subagent_stop` | the `task` tool brackets a nested sub-agent run | `toolCallId`, `subagentType`; stop adds `tokensUsed` |
+| `subagent_start` / `subagent_stop` | the `agent` tool brackets a nested sub-agent run | `toolCallId`, `subagentType`; stop adds `tokensUsed` |
+| `subagent_progress` | per child tool call inside a running sub-agent | `toolCallId`, `subagentType`, `toolName`, `toolInput`, `tokensUsed` |
 | `api_retry` | retry loop, after 3 silent attempts | `attempt`, `error`, `delayMs` |
 | `compaction_start` / `compaction_done` | compaction mod | `tokensSaved` (done, only when > 0) |
 | `notice` | user-facing info/warning | `level`, `message` |
 | `skill_loaded` | a skill was activated by an explicit user `/name` invocation | `name` |
 | `session_titled` | the auto-generated session title was persisted | `title` |
+| `permission_mode_changed` | the effective permission mode changed (shift+tab, `/plan`, enter/exit plan tools) | `mode` |
+| `config_setting_changed` | a setting changed through the `config` tool | `setting`, `value`, `previousValue?` |
 | `continuation_recovery` | a turn was auto-continued (pause/empty/length/intent) | `kind`, `attempt`, `maxAttempts` |
 | `tool_input_coerced` | ModelClient rescued malformed (array/null) tool input | `rawType`, `recovered` |
 | `tool_input_repaired` | repair layer healed tool input pre-execution | `rulesFired`, `hintCount`, `receivedKeys` |

package/dist/bundled/mod-builder/reference/overview.md

@@ -209,7 +209,7 @@ Runnable, single-file example mods ship with Command Code inside the bundled `mo
 
 - **Hooks mutate, `on` observes.** Event handlers cannot block tools or rewrite context; that is what `cmd.hooks` is for.
 - **Project mods are trust-gated** like project skills: they load only after the workspace trust prompt, because a mod is arbitrary code. User-scope and `--mod` mods always load. There is no sandbox - install packages you trust. Package installs run npm with `--ignore-scripts` (mods are jiti-loaded TypeScript; they need no build step, so lifecycle scripts are pure attack surface).
-- **Print mode loads user-scope and `--mod` mods only**, with the ui bridge degraded to headless defaults (confirm → false, select/input → undefined - never auto-approved; `setStatus`/`widget` render nowhere; timed dialogs resolve `timeoutValue` immediately). Project mods stay out of headless runs because print never shows a trust prompt; pass `--dangerously-skip-permissions` to opt a repo's own mods into a headless run (CI).
+- **Print mode loads user-scope and `--mod` mods only**, with the ui bridge degraded to headless defaults (confirm → false, select/input → undefined - never auto-approved; `setStatus`/`widget` render nowhere). Project mods stay out of headless runs because print never shows a trust prompt; pass `--dangerously-skip-permissions` to opt a repo's own mods into a headless run (CI).
 - **Mod-queued messages don't echo in the feed** the way typed input does - they land in the transcript and steer the model, but the visible record is the model's response.
 - **Rendering is line-based, not component-based.** `cmd.addRenderer` returns styled text lines the host prints as feed rows; mods do not mount React components into the TUI. That keeps renderers host-agnostic (the same mod renders in any future host) and a crashing renderer degrades to a warning notice, never a broken screen.
 - **Reload is the `/reload` path.** Mods load once per process; `/reload` restarts the process, which re-discovers and re-imports every mod (jiti caches nothing between loads). There is no in-place hot swap.
@@ -225,6 +225,6 @@ The rest of this page is the complete reference, in order:
 
 - [ModApi reference](./api.md#mod-api-reference) — every field, registration verb, and live method.
 - [Hooks and events](./hooks-and-events.md#hooks-and-events) — the mutating lifecycle, the `AgentEvent` catalog.
-- [UI surface](./ui.md#ui-surface) — dialogs, timed dialogs, footer status, editor widgets, custom feed rendering.
+- [UI surface](./ui.md#ui-surface) — dialogs, footer status, editor widgets, custom feed rendering.
 - [Packaging and install](./packaging.md#packaging-and-install) — `cmd mods add`, manifests, filtering, scopes.
 - [Verify a mod](./verify.md#verify-a-mod) — load it, list it, test it, ship it.

package/dist/bundled/mod-builder/reference/ui.md

@@ -7,19 +7,7 @@ Everything a mod can put on screen rides `cmd.ui`, `cmd.addRenderer`, and `cmd.s
 ## Notifications and dialogs
 
 - `cmd.ui.notify(message)` - a `notice` feed row.
-- `cmd.ui.confirm({title})` / `cmd.ui.select({title, options})` / `cmd.ui.input({title})` - the Interaction question modal in the TUI. Headless, each resolves its deterministic default: confirm → `false`, select/input → `undefined` - never auto-approved.
-
-### Timed dialogs
-
-Each dialog accepts `{timeoutMs, timeoutValue}`: after `timeoutMs` the dialog auto-resolves `timeoutValue` (default: the dialog's headless default). The TUI shows a visible countdown and dismisses the modal at the deadline; on a TIMED dialog a dismissal without an answer (auto-dismiss or Esc) also resolves `timeoutValue`. Headless, a timed dialog resolves `timeoutValue` immediately - it never blocks a print run.
-
-```ts
-const proceed = await cmd.ui.confirm({
-	title: 'Deploy to staging?',
-	timeoutMs: 15_000,
-	timeoutValue: true, // no answer in 15s = go ahead
-});
-```
+- `cmd.ui.confirm({title, message?})` / `cmd.ui.select({title, options})` / `cmd.ui.input({title, placeholder?})` - the Interaction question modal in the TUI. Headless, each resolves its deterministic default: confirm → `false`, select/input → `undefined` - never auto-approved.
 
 ## Footer status segments and editor widgets
 
@@ -55,7 +43,6 @@ Rendering is deliberately **line-based, not component-based**: mods return style
 | `notify` | notice feed row | printed notice |
 | `confirm` | modal | resolves `false` |
 | `select` / `input` | modal | resolves `undefined` |
-| timed dialog | countdown, auto-resolve at deadline | resolves `timeoutValue` immediately |
 | `setStatus` | no-op (wire-up pending) | no-op |
 | `widget` | no-op (wire-up pending) | no-op |
 | `showEntry` | rendered feed row | dropped |

package/dist/bundled/mod-builder/reference/verify.md

@@ -26,7 +26,7 @@ Your mod must appear, with no load warnings. If it does not appear, the warning
 - **Tool** - ask the model to use it by name ("call count_todos"). The tool call renders in the feed like any built-in.
 - **Hook** - trigger the behavior it guards (for a `beforeToolCall` blocker, ask for the blocked action and watch the block reason land as the tool result).
 - **Input interception** - type the pattern `transformInput` matches and confirm the rewrite/consume happened.
-- **Status / widget** - the footer segment appears under the input panel; the widget renders around the editor.
+- **Status / widget** - `cmd.ui.setStatus` / `cmd.ui.widget` / `cmd.ui.refreshWidgets` must return without throwing and hand back a `Disposable`. They render **nothing** today (TUI wire-up pending - see the [UI surface](./ui.md#ui-surface) note), so don't expect a footer segment or editor widget to appear yet; only verify the calls are safe.
 - **Renderer** - `cmd.showEntry` rows render styled; an unregistered type pretty-prints as JSON.
 
 ### Test: block-dangerous-commands guards rm -rf
@@ -51,7 +51,7 @@ Mods load once per process. After editing the file, run `/reload` - it restarts
 cmd -p "exercise the mod" --mod ./your-mod.ts
 ```
 
-Print mode loads user-scope and `--mod` mods with the UI bridge degraded to deterministic defaults (confirm → false, select/input → undefined; timed dialogs resolve `timeoutValue` immediately). A mod that must work in CI should behave sensibly under those defaults.
+Print mode loads user-scope and `--mod` mods with the UI bridge degraded to deterministic defaults (confirm → false, select/input → undefined). A mod that must work in CI should behave sensibly under those defaults.
 
 ## Working from the bundled examples