command-code 1.82.5 → 1.84.0

package/dist/bundled/mod-builder/examples/stream-filter.ts

@@ -0,0 +1,70 @@
+// Example mod: filter the model's answer as it streams, and stream a process's output.
+//
+// hooks.transformTextDelta sees every chunk of the answer before it is shown. Return the chunk
+// to show (rewritten or not), or '' to hold it back. When the answer is complete it is called
+// once more with {delta: '', done: true}: return whatever you held back. The transcript keeps
+// exactly what was shown. It must be synchronous and fast: it runs inside the stream.
+//
+// A key can arrive split across chunks ("sk-ab" then "cdef..."), so this filter holds back a
+// tail that might be the start of one and decides when the next chunk (or the end) arrives.
+//
+// cmd.process.spawn runs a command and hands each stdout/stderr chunk to onOutput as it is
+// produced; cmd.exec only answers once the process exits.
+
+import type {ModApi} from '@commandcode/harness';
+
+const KEY_PATTERN = /\bsk-[A-Za-z0-9_-]{16,}/g;
+// A tail that could still grow into a key: "s", "sk", "sk-", "sk-abc...".
+const MAYBE_KEY_TAIL = /(?:\bs|\bsk|\bsk-[A-Za-z0-9_-]*)$/;
+
+function redact(text: string): string {
+	return text.replace(KEY_PATTERN, '[REDACTED]');
+}
+
+export default function (cmd: ModApi): void {
+	// Held-back text, for the stream it belongs to. A retry or a new turn starts a new stream.
+	let held = '';
+	let stream = '';
+
+	cmd.hooks({
+		transformTextDelta: ({delta, done, turnNumber, attempt}) => {
+			const id = `${turnNumber}:${attempt}`;
+			if (id !== stream) {
+				stream = id;
+				held = '';
+			}
+			const text = held + delta;
+			if (done) {
+				held = '';
+				return redact(text);
+			}
+			const tail = MAYBE_KEY_TAIL.exec(text)?.[0] ?? '';
+			held = tail;
+			return redact(text.slice(0, text.length - tail.length));
+		},
+	});
+
+	cmd.addCommand({
+		name: 'stream',
+		description: 'Run a command and show its latest output line as it runs',
+		argumentHint: '<command>',
+		handler: async ({args}) => {
+			if (!args.trim()) return {message: 'usage: /stream <command>'};
+			let lines = 0;
+			cmd.ui.setStatus(`running ${args}`);
+			try {
+				const {code} = await cmd.process.spawn({
+					command: args,
+					onOutput: (chunk, from) => {
+						const last = chunk.trimEnd().split('\n').at(-1) ?? '';
+						lines += chunk.split('\n').length - 1;
+						if (last) cmd.ui.setStatus(`${from}: ${last}`);
+					},
+				});
+				return {message: `${args} exited ${code} after ${lines} lines`};
+			} finally {
+				cmd.ui.setStatus(null);
+			}
+		},
+	});
+}

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

@@ -12,8 +12,15 @@
 | `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` / `setStatus` / `widget` / `refreshWidgets` / `capabilities` |
+| `cmd.ui` | `ModUi` | `notify` / `confirm` / `select` / `input` / `setStatus` / `widget` / `refreshWidgets` / `pane` / `openPane` / `closePane` / `toast` / `copy` / `override` / `setTitle` / `capabilities` |
 | `cmd.sessions` | `ModSessionControls` | `compact` / `tree` / `leafId` / `navigateTree` / `setLabel` |
+| `cmd.state` | `ModStateApi` | `get` / `set` / `subscribe` - session values that survive a hot reload |
+| `cmd.store` | `ModStoreApi` | `get` / `set` / `delete` - values kept across sessions (`~/.commandcode/mods/.store/<mod>.json`) |
+| `cmd.clock` | `ModClockApi` | `every` / `after` - timers cancelled with the mod |
+| `cmd.model` | `ModModelApi` | `complete` - one prompt on the session's model client |
+| `cmd.prompt` | `ModPromptApi` | `submit` - start a turn of its own once the session is idle |
+| `cmd.process` | `ModProcessApi` | `spawn` - run a process and stream its output as it arrives |
+| `cmd.audio` | `ModAudioApi` | `play` / `bell` - sound files shipped with the mod, and the terminal bell |
 
 ## Registration (factory-time; each returns `Disposable`)
 
@@ -28,6 +35,8 @@
 | `cmd.addShortcut` | `(keys: string, {description?; handler}) => Disposable` |
 | `cmd.addSkillsPath` | `(path: string) => Disposable` |
 | `cmd.on` | `(event: AgentEventType \| 'session_start' \| 'session_shutdown', handler) => Disposable` |
+| `cmd.addAgent` | `(definition: {name; description; systemPrompt; tools?; disallowedTools?; model?; maxTurns?}) => Disposable` |
+| `cmd.expose` | `(name, fn) => Disposable` |
 
 What each does:
 
@@ -38,6 +47,8 @@ What each does:
 - `cmd.on(event, handler)` - observe any `AgentEvent` plus the host lifecycle events `session_start` / `session_shutdown` (fired when a harness binds the host and when a session switch or dispose replaces it). Handlers are isolated: a throw becomes a `mod_error {hook: 'on:<event>'}` event, never a crash.
 - `cmd.addProvider(providerModule)` - register a model provider through the same `ProviderModule` seam the built-ins use (id, transport, auth hooks, model list). The host appends mod providers to its set - mods extend the provider set, never replace it.
 - `cmd.addRenderer(customType, data => lines)` - a renderer for a custom entry type; returns the lines to print (style them with ansi escapes - picocolors, `@commandcode/tui` helpers, or raw codes). First registration per type wins across mods.
+- `cmd.addAgent(definition)` - a sub-agent type the model can delegate to through the `task` tool, next to the bundled and on-disk agents. `tools` defaults to `'*'`. An agent name that already exists (bundled, project, user, or another mod's) is skipped with a warning. Read live, so a reload's agents show up on the next turn.
+- `cmd.expose(name, fn)` / `cmd.use(mod, name)` - share a function with other mods and call one another mod shared. `use` answers `undefined` until that mod has loaded and exposed the name, so call it from a hook or command, not only at factory time.
 - `cmd.addShortcut(keys, {description, handler})` - a keyboard shortcut in the interactive TUI. `keys` is a `modifier+key` chord that **must include Ctrl or Alt** (`alt+r`, `ctrl+r`); a modifier-less or Shift-only chord (`p`, `enter`, `shift+p`) is rejected with a warning, because it would also type into the prompt, and so is a `Ctrl+Shift` chord whose key reaches the terminal as a bare control byte — letters, digits, Enter, Tab, Backspace (`ctrl+shift+p`, `ctrl+shift+enter`) — where the Shift never arrives (arrow / navigation keys keep their modifiers, so `ctrl+shift+up` is fine). `ctrl+m`, `ctrl+i`, `ctrl+h` and `ctrl+[` are rejected too: terminals send them as Enter, Tab, Backspace and Escape. A chord a built-in already owns (`ctrl+c`, `ctrl+o`, an editor key like `ctrl+k`) is rejected the same way — the host's own bindings run first, so it would never fire — and so are the keys the prompt handles itself (`alt+w`, `ctrl+z`, `ctrl+g`, `ctrl+s`, `ctrl+v`, `alt+v`), which stay taken even when rebound. The handler gets the same `{args, ui, cwd, exec}` context a command handler does and may return the same `{message}` / `{prompt}` result. The host dispatches mod shortcuts AFTER its own bindings, so a mod can add keys but never shadow interrupt, exit, mode cycling, or the transcript toggles; `Esc` stays host-owned. First registration per chord wins across mods; `/hotkeys` lists them under **Mods**. Headless hosts never fire shortcuts.
 - `cmd.addSkillsPath(path)` - an extra skills location (one skill directory, or a directory of skills) for this session's skill discovery. Relative paths resolve against the mod's own file, so a package can point at the `./skills` it ships. Collected at factory time. A package can declare the same thing without code through its manifest - see [What a package ships](./packaging.md#what-a-package-ships).
 
@@ -50,6 +61,7 @@ What each does:
 | `cmd.queueMessage` | `({content, deliverAs?: 'steer' \| 'follow-up'}) => void` |
 | `cmd.sendUserMessage` | `(content, {deliverAs?}) => void` |
 | `cmd.exec` | `({command, args?, cwd?, signal?}) => Promise<{stdout, stderr, code}>` |
+| `cmd.process.spawn` | `({command, args?, cwd?, signal?, onOutput: (chunk, stream) => void}) => Promise<{code}>` |
 | `cmd.setSessionName` / `setModel` / `setEffort` | `(value) => void` (buffered pre-bind) |
 | `cmd.getSessionName` / `getModel` / `getEffort` | `() => value \| undefined` (undefined pre-bind) |
 | `cmd.getContextUsage` | `() => {tokens, contextWindow, percent} \| undefined` |
@@ -59,10 +71,19 @@ What each does:
 | `cmd.getAllTools` / `getActiveTools` | `() => readonly string[]` |
 | `cmd.getToolInfo` | `() => readonly {name, description, readOnly, active}[]` |
 | `cmd.setActiveTools` | `(names: readonly string[]) => void` |
+| `cmd.use` | `(mod, name) => fn \| undefined` |
+| `cmd.state.get` / `set` / `subscribe` | `(key) => T \| undefined` / `(key, value) => void` / `(key, listener) => Disposable` |
+| `cmd.store.get` / `set` / `delete` | `(key) => T \| undefined` / `(key, value) => Promise<void>` / `(key) => Promise<void>` |
+| `cmd.clock.every` / `after` | `(ms, callback) => Disposable` |
+| `cmd.model.complete` | `({prompt, system?, model?, maxOutputTokens?, signal?}) => Promise<ModModelCompleteResult>` |
+| `cmd.prompt.submit` | `(text) => void` |
+| `cmd.ui.copy` | `(text) => Promise<ModCopyResult>` |
+| `cmd.audio.play` | `({file, timeoutMs?}) => Promise<ModAudioResult>` |
+| `cmd.audio.bell` | `() => ModAudioResult` |
 
 Details:
 
-- `cmd.ui` - `notify` (a `notice` feed row), `confirm` / `select` / `input` (the Interaction question modal in the TUI; deterministic defaults headless: false/undefined), `setStatus`, `widget`, `refreshWidgets`, `setTitle`. The full dialog/status/widget contract is in [UI surface](./ui.md#ui-surface).
+- `cmd.ui` - `notify` (a `notice` feed row), `confirm` / `select` / `input` (the Interaction question modal in the TUI; deterministic defaults headless: false/undefined), `setStatus`, `widget`, `refreshWidgets`, `pane` + `openPane(id, {focus?})` / `closePane`, `toast`, `override`, `setTitle`. The full dialog/status/widget/override contract is in [UI surface](./ui.md#ui-surface).
 - `cmd.queueMessage({content, deliverAs})` - `steer` lands after the current tool batch (behind any queued user messages in the same poll), `follow-up` only when the run would stop (ahead of continuation nudges, behind queued user input). Queued messages steer a run that is already going; they never START one.
 - `cmd.sendUserMessage(content, {deliverAs})` - a REAL user message: echoed in the feed like typed input and, when the agent is idle, starting a turn right away. While a run is going, `steer` (default) queues it behind the active turn exactly as typing would, and `follow-up` holds it until the run would stop. Headless there is no submit path, so it falls back to `queueMessage` with the same `deliverAs`.
 - `cmd.getSessionName()` / `getModel()` / `getEffort()` - the live values behind the setters; `undefined` before a session binds.
@@ -75,14 +96,27 @@ Details:
 - `cmd.showEntry(customType, data)` - render a custom entry into the live feed through the renderer registered for that type (unrendered types pretty-print as JSON). The TUI wires the sink; headless runs drop entries. Pair with `cmd.session.appendCustomEntry` when the data should also persist.
 - `cmd.sessions` - live session controls: `compact()`, `tree()` (the session branch tree as stable `{id, label, children}` nodes), `leafId()`, `navigateTree({targetId, summarize?, customInstructions?})`, and `setLabel({targetId, label})`. These read live harness state, so unlike the buffered setters they throw with a clear message when no session is bound yet.
 - `cmd.exec({command, args})` - run a process through the harness Runtime (args are shell-quoted).
+- `cmd.process.spawn({command, args, onOutput})` - the same command line as `cmd.exec`, but every stdout/stderr chunk reaches `onOutput(chunk, stream)` as the process produces it (`stream` is `'stdout'` or `'stderr'`), so a mod can show progress, tail a log, or react to a line without waiting for the exit. Resolves `{code}` when the process exits; aborting `signal` kills the process tree and rejects. A throwing `onOutput` becomes `mod_error {hook: 'on:process'}` and the process keeps running. Output is not buffered for you: keep what you need from the chunks.
 - `cmd.getAllTools()` / `cmd.getActiveTools()` / `cmd.setActiveTools(names)` - a mod-managed tool filter: disabled tools vanish from the model's schemas and refuse execution.
 - `cmd.events` - a tiny cross-mod pub/sub bus (`emit` / `on`).
+- `cmd.state` - values the host holds for the session, namespaced per mod. They survive a hot reload (module variables start over), and `set` repaints every widget and pane, so a drawing that reads state is always current. `subscribe(key, listener)` hears this mod's writes to that key.
+- `cmd.store` - values kept across sessions, one JSON file per mod. `get` is synchronous (the file is read before the factory runs); `set` and `delete` write through.
+- `cmd.clock.every(ms, fn)` / `after(ms, fn)` - timers owned by the mod: cancelled by their `Disposable`, and all of them when the mod reloads. They never hold the process open, and a throwing callback becomes `mod_error` while the timer keeps its schedule.
+- `cmd.model.complete({prompt})` - one text completion on the session's model client, with no transcript and no tools, billed and attributed like the session. It always resolves: `{isAnswered: true, text, model}` or `{isAnswered: false, reason: 'unavailable' | 'error' | 'aborted'}` (unavailable before a session binds).
+- `cmd.prompt.submit(text)` - submit a prompt as if typed: in the TUI it starts a turn once the session is idle and queues behind a running one. Headless, it rides the follow-up queue.
+- `cmd.ui.copy(text)` - write text to the system clipboard with the same helper `/copy` uses. See [Clipboard and sound](./ui.md#clipboard-and-sound).
+- `cmd.audio.play({file})` / `cmd.audio.bell()` - play a sound file shipped with the mod, or ring the terminal bell. See [Clipboard and sound](./ui.md#clipboard-and-sound).
 
 ## `ModHooks` (the mutating lifecycle - all optional, all composable)
 
-`transformContext`, `appendSystemPrompt`, `beforeToolCall`, `afterToolCall`, `onTurnStart`, `onTurnEnd`, `shouldStopAfterTurn`, `prepareNextTurn`, `onRunEnd`, `onStop`, plus the host-level `transformInput`, `onSessionStart`, and `onSessionEnd`.
+`transformContext`, `appendSystemPrompt`, `transformSystemPrompt`, `transformMessage`, `transformTextDelta`, `beforeModelRequest`, `beforeToolCall`, `afterToolCall`, `onTurnStart`, `onTurnEnd`, `shouldStopAfterTurn`, `prepareNextTurn`, `onRunEnd`, `onStop`, plus the host-level `transformInput`, `onPermissionRequest`, `onSessionStart`, and `onSessionEnd`.
 
-- `beforeToolCall` returns `{block?, input?, additionalContext?, terminate?}`.
+- `beforeToolCall` returns `{block?, input?, additionalContext?, terminate?, result?}`. `result` answers the call without running the tool.
+- `beforeModelRequest` returns `{model?}` for one request.
+- `transformSystemPrompt` returns the full system prompt to send.
+- `transformMessage` returns the message the transcript keeps.
+- `transformTextDelta` returns the answer chunk to show (synchronously), or `''` to drop or hold it back.
+- `onPermissionRequest` returns `'allow' | 'deny' | undefined`.
 - `afterToolCall` receives an `isError` param (PostToolUse vs PostToolUseFailure) and returns `{content?, isError?, additionalContext?, terminate?, modState?}`.
 - `onStop` receives `{state, stopReason, turnNumber, lastAssistantText}` and returns `{continue?, reason?}`.
 - `transformInput` returns `{action:'continue'} \| {action:'transform', text} \| {action:'handled', message?}`.
@@ -92,7 +126,8 @@ The per-hook contracts, ordering guarantees, and error policy are in [the hook c
 
 - `transformInput({text})` intercepts typed user prompts before they reach the model (the mods' **UserPromptSubmit** hook): return `{action: 'transform', text}` to rewrite (handlers chain - the next sees the rewrite), `{action: 'handled', message?}` to consume the prompt entirely (an optional info row renders in its place), or `undefined`/`{action: 'continue'}` to pass through. Only real typed input is intercepted - automated turns, meta messages, image-carrying prompts, and slash commands never route through it; a throwing handler is skipped (`mod_error {hook: 'transformInput'}`), never a swallowed prompt. It lives in `hooks` because it MUTATES what the agent sees.
 - `onStop({state, stopReason, turnNumber, lastAssistantText})` is the **Stop** hook - return `{continue: true, reason?}` to force a run that would otherwise finish to keep going (the reason rides an automated turn). Fires only on natural completion, any-mod wins, and the loop caps consecutive continuations.
-- `onSessionStart({source})` / `onSessionEnd({reason})` are the once-per-session **SessionStart** / **SessionEnd** hooks - fired when the host binds to / tears down a session (`source: 'startup' | 'resume'`, `reason: 'shutdown' | 'replaced'`). Act through the mod's captured `cmd`; they run fire-and-forget (a throw becomes `mod_error`), so a session hook never blocks bind/dispose. Pure observation is also available via `cmd.on('session_start' | 'session_shutdown')` - these named hooks add the typed metadata.
+- `onPermissionRequest({toolName, input, description, isSafetyPrompt})` answers a permission prompt before the person sees it. It fires only where the engine would ask a human, so deny rules, plan mode, and dont-ask have already decided everything they cover. Every hook is asked, and **deny wins**: any `'deny'` answers the prompt, and `'allow'` holds only when no hook denies, so a mod that blocks something cannot be overridden by another that allows it. A throwing hook is skipped (`mod_error`). On a safety-forced prompt (`isSafetyPrompt`: a sensitive write, a risky command) `'deny'` works but `'allow'` is ignored and the person is asked.
+- `onSessionStart({source})` / `onSessionEnd({reason})` are the once-per-session **SessionStart** / **SessionEnd** hooks - fired when the host binds to / tears down a session (`source: 'startup' | 'resume' | 'reload'`, `reason: 'shutdown' | 'replaced' | 'reload'`). `reload` is this mod's own hot reload, in the same session: the old code ends with it and the new code starts with it. Act through the mod's captured `cmd`; they run fire-and-forget (a throw becomes `mod_error`), so a session hook never blocks bind/dispose. Pure observation is also available via `cmd.on('session_start' | 'session_shutdown')` - these named hooks add the typed metadata.
 
 ## `on` event types
 

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

@@ -22,9 +22,12 @@ run({state, userInput?, config})
     ◆ onTurnStart (each mod, in order; returns new state)
     → turn_start {turnNumber}
     read live permission mode ONCE - pinned for this round
+    ◆ beforeModelRequest (each mod; later wins) → the model for THIS request; the
+      deferred-tools prompt and tool list below are built for it
     resolve systemPrompt (string | builder({sessionId, state, permissionMode}))
     ◆ appendSystemPrompt (each mod; non-empty returns joined with '\n\n', in
       registration order, and appended AFTER the base prompt)
+    ◆ transformSystemPrompt (each mod; the FULL prompt threaded mod→mod)
     ◆ transformContext (each mod; messages threaded mod→mod; result is EPHEMERAL -
       used for this call only, never written back to state.messages)
     prepareForSend (core wire-validity pass: orphan heal, merge, strip meta)
@@ -33,8 +36,14 @@ run({state, userInput?, config})
     modelClient.complete(...)          (streams → text_delta / thinking_* /
                                         message_update / continuation_recovery /
                                         tool_input_coerced; retry → api_retry)
+      ◆ transformTextDelta on every streamed text chunk (each mod, threaded;
+        sync), BEFORE its → text_delta; a retry starts the chunk log over
     → model_request_end {model, usage, stopReason}
-    → message_end {content}
+    ◆ transformTextDelta {delta: '', done: true} (flush; output → text_delta)
+      assistant text := the rewritten chunks, joined, per text block
+    → message_end {content}               (the rewritten content)
+    ◆ transformMessage on every message before it is committed
+      (user input, assistant reply, tool results, steering, follow-ups)
     working += assistant message       (provider-executed blocks filtered out)
     if client tool calls:
       runTools(...)                    (see tool-dispatch order below)
@@ -73,6 +82,7 @@ phase 2 - execution (sequential, or parallel when config.toolExecution='parallel
       execution uses the LAST mod's input; a mod may also set `terminate`)
       block ⇒ → tool_hook_blocked {hookOutput}; the block reason becomes the
       tool_result text; NO tool_running / tool_completed / tool_errored fires
+      result ⇒ the tool does NOT run; the answer is its (successful) output
   → tool_running {toolCallId, toolName, description}
   toolRunner.execute({toolName, input: <possibly rewritten>, signal, onUpdate})
   ◆ afterToolCall (each mod, in order; sees current content, may replace it,
@@ -124,6 +134,32 @@ Fires per tool call, after the permission check passed, before execution.
 - `terminate: true` - stops the run after this tool batch finishes. ANY-semantics (one hook, on one call, in one batch, is enough). Combines with `block` on the same return value.
 - `undefined` - no opinion.
 
+- `result` - answer the call WITHOUT running the tool: this content is the tool's successful output (unlike `block`, which is an error). Later mods' `beforeToolCall` for this call do not run; `afterToolCall` still does, so a post-hook sees the answer like any real result. `block` wins when both are set.
+
+### `beforeModelRequest({state, turnNumber, model}, ctx?) → {model?} | undefined`
+
+Fires once per model request, at the start of the round, before the round's prompt, context, and tools are built. The tool list and the deferred-tools prompt are then built for the model the request goes to, so a model that cannot load deferred tools gets every tool inline, the same as picking it with `/model`. A returned `model` sends **this request only** to that model; the next request goes back to the run's model (use `prepareNextTurn` to switch for the rest of the run). Later mods win. A swapped request drops the run's explicit BYOK route, which belongs to the run's model. `model_request_start` / `model_request_end` report the model the request actually went to.
+
+The other hooks of the round have not run yet, so a value one of them stores is from the previous round. To route on context size, measure `state.messages` inside `beforeModelRequest` itself.
+
+### `transformSystemPrompt({system, state}, ctx?) → string`
+
+Fires once per round, after `appendSystemPrompt`: receives the round's **full** system prompt (base + every append) and returns the prompt to send, so a mod can replace, edit, or drop parts of it. Threaded mod to mod. Returning the input unchanged keeps the structured, cache-friendly sections; any change sends one flat string, so keep the result byte-stable across rounds or the prompt-prefix cache misses every turn.
+
+### `transformMessage({message, state}, ctx?) → AgentMessage`
+
+Fires for every message the loop commits: the person's input, each model reply, each tool-result batch, steering and follow-up messages. The returned message is what the transcript stores **and** what every later request sends, which makes it the place for secret redaction and PII masking. Threaded mod to mod. The role and every `tool_use` / `tool_result` id must survive: a rewrite that changes them is rejected with `mod_error {hook: 'transformMessage'}` and the previous message is kept. Live streaming events (`text_delta`, `message_end`) still show the model's raw output; the transcript holds the rewrite. To change what is shown as well, use `transformTextDelta`.
+
+### `transformTextDelta({delta, done, turnNumber, attempt, state}, ctx?) → string`
+
+Fires for every chunk of the model's answer text as it streams, **before** the `text_delta` event for it goes out. Return the chunk to show (rewritten or as is), or `''` to drop it. Threaded mod to mod; a dropped chunk stops there, so later mods never see it. What the feed shows and what the transcript keeps are the same text: the committed assistant message (and `message_end`, and the live `message_update`) carries exactly the rewritten chunks, joined, each in the text block it streamed into. Thinking and tool calls are untouched.
+
+- **Synchronous and fast.** It runs inside the model stream. A hook that throws, or returns a promise or a non-string, is skipped for that chunk with `mod_error {hook: 'transformTextDelta'}`, and the chunk passes on as the previous mod handed it.
+- **The final flush.** When the response is complete, every mod is called once more with `{delta: '', done: true}`. Return anything you held back (the start of a key split across two chunks) and it streams as one last `text_delta` and lands at the end of the last text block.
+- **Retries.** `attempt` counts this request's attempts from 0. A mid-stream retry throws the abandoned attempt's chunks away (the feed marks the seam with `stream_restart`), so a mod that keeps state across chunks should start over when `turnNumber` or `attempt` changes.
+- **Non-streaming clients.** A response that arrived with no text deltas still goes through the hook, one chunk per text block, with no `text_delta` events invented for it.
+- Runs **before** `transformMessage`, which still sees the (rewritten) assistant message on commit.
+
 ### `afterToolCall({toolCallId, toolName, input, result, isError, state}, ctx?) → {content?, terminate?, additionalContext?, isError?, modState?} | undefined`
 
 Fires per tool call after execution (also after an execution error - `result` is then the error text content). `input` is the FINAL input the tool actually ran with (after any `beforeToolCall` rewrites).

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

@@ -4,7 +4,7 @@
 
 > **Experimental.** The `ModApi` is new and still taking shape. Surfaces and signatures can change as we learn from how mods get built - so pin what you ship, and tell us what's missing. Your feedback is what stabilizes it.
 
-Mods are TypeScript packages that let you modify almost any behavior of Command Code. They're far more powerful than the plugin or extension APIs you'll find in other agents - though you can absolutely use one to build a plugin or an extension. Each mod is written against the `ModApi`: a plain TypeScript file that Command Code discovers on disk, loads at startup, and compiles onto its agent loop. One file can add tools the model calls, slash commands, mutating lifecycle hooks, event observers, typed-input interception, custom feed rendering, configurable flags, and model providers. Command Code's own built-in features - providers, session titling, the update notice - are built as mods against this very same API. If Command Code can do it, a mod can change it.
+Mods are TypeScript packages that let you modify almost any behavior of Command Code. They're far more powerful than the plugin or extension APIs you'll find in other agents - though you can absolutely use one to build a plugin or an extension. Each mod is written against the `ModApi`: a plain TypeScript file that Command Code discovers on disk, loads at startup, and compiles onto its agent loop. One file can add tools the model calls, slash commands, mutating lifecycle hooks, event observers, typed-input interception, permission answers, transcript redaction, per-request model routing, panes and widgets with buttons, toasts, sub-agent types, configurable flags, and model providers. Mods hot-reload when you save them. Command Code's own built-in features - providers, session titling, the update notice - are built as mods against this very same API. If Command Code can do it, a mod can change it.
 
 A loadable mod IS an `AgentMod` once loaded; the mod host just builds it from a factory file instead of a code import:
 
@@ -27,6 +27,10 @@ hooks.transformInput ──►  typed-prompt
 addProvider          ──►  ProviderModule
 addRenderer          ──►  custom feed entries
 queueMessage         ──►  steering drains
+ui.widget / ui.pane  ──►  bands, panes, buttons
+                          (element tree, any host)
+addAgent             ──►  task tool agent types
+prompt.submit        ──►  a turn of its own
 ```
 
 The factory receives the API bound as `cmd`. Registration verbs are all `add*` and each returns a `Disposable` - call `.dispose()` to undo exactly that one registration.
@@ -169,11 +173,13 @@ Dot-entries and `node_modules` are never scanned (the package registry lives und
 {"mods": {"disabled": ["review-guard"]}}
 ```
 
+Turn off every installed mod at once with `{"mods": {"disableAll": true}}` (any settings file; a disable wins), or for one session with `cmd --safe-mode`. Both still load the built-in mods, which are Command Code itself; safe mode also skips `--mod` paths.
+
 ---
 
 ## The one rule: hooks mutate, `on` observes
 
-- **`cmd.hooks({...})`** is the only place that can change behavior - block a tool (`beforeToolCall`), rewrite a result (`afterToolCall`), add to the prompt (`appendSystemPrompt`), rewrite typed input (`transformInput`), force a finished run to keep going (`onStop`), react to session start/end (`onSessionStart`/`onSessionEnd`), or run post-turn work (`onRunEnd`). Multiple `hooks()` calls compose in registration order.
+- **`cmd.hooks({...})`** is the only place that can change behavior - block, rewrite, or answer a tool call (`beforeToolCall`), rewrite a result (`afterToolCall`), add to or edit the system prompt (`appendSystemPrompt`, `transformSystemPrompt`), redact what the transcript keeps (`transformMessage`), rewrite the answer as it streams (`transformTextDelta`), send one request to another model (`beforeModelRequest`), answer a permission prompt (`onPermissionRequest`), rewrite typed input (`transformInput`), force a finished run to keep going (`onStop`), react to session start/end (`onSessionStart`/`onSessionEnd`), or run post-turn work (`onRunEnd`). Multiple `hooks()` calls compose in registration order.
 - **`cmd.on(event, ...)`** only observes - it cannot block or rewrite. Handlers are isolated (a throw becomes a `mod_error` event, never a crash).
 
 If you find yourself wanting an `on` handler to stop a tool, you want a hook instead. The full mutating surface is in [Hooks and events](./hooks-and-events.md#hooks-and-events); the full registration/live surface is the [ModApi reference](./api.md#mod-api-reference).
@@ -222,6 +228,13 @@ Ask for any of these by name or by what you want:
 | `custom-entry-renderer.ts` | `addRenderer` + `showEntry` - styled feed rows |
 | `flags-and-options.ts` | `addFlag` / `getFlag` + `--mod-option` |
 | `lifecycle-hooks.ts` | `hooks.onStop` (Stop) + `onSessionStart`/`onSessionEnd` + `afterToolCall` `isError` + `on('subagent_start'/'subagent_stop')` |
+| `pane-and-buttons.ts` | `ui.pane` + `ui.widget` + buttons + `cmd.state` + `ui.toast` |
+| `pane-form.ts` | a focused form pane: `input` + `select` + `markdown` elements, `openPane(id, {focus: true})` |
+| `spinner-count.ts` | `ui.override` - a tool-call count beside the spinner, compact shell rows |
+| `redact-secrets.ts` | `hooks.transformMessage` - mask keys before the transcript keeps them |
+| `permission-policy.ts` | `hooks.onPermissionRequest` - answer prompts with a team policy |
+| `model-router.ts` | `hooks.beforeModelRequest` + `cmd.model.complete` |
+| `stream-filter.ts` | `hooks.transformTextDelta` - redact keys as the answer streams + `cmd.process.spawn` |
 | `kitchen-sink.ts` | every capability in one annotated file |
 
 ---
@@ -232,8 +245,10 @@ Ask for any of these by name or by what you want:
 - **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, and `cmd.ui.capabilities.status` is false). 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.
+- **Rendering is data, not components.** Widgets, panes, and feed renderers return strings or a small element tree (text, row, box, button, progress, divider, input, select, markdown) that each host draws; mods never mount React components. That keeps a mod host-agnostic, and a crashing render degrades to a one-line warning, never a broken screen.
+- **Mods hot-reload on save.** In the interactive TUI every file-backed mod is watched: saving it re-imports the file and swaps the mod in place. The old code gets `onSessionEnd` with `reason: 'reload'` and every registration it made is disposed, except tools added with `addTool`, which keep the old code until the next session. `cmd.state` is kept, and the new code's `onSessionStart` fires with `source: 'reload'`. A save that throws while loading keeps the old code running, and the feed says why. `/mods reload [name]` does the same on demand; `COMMANDCODE_MODS_HOT_RELOAD=0` turns the watcher off. Tools a mod adds take effect on the next session, because the tool set is fixed per session. Built-in mods never reload.
+- **Mods restyle rows, never the permission prompt.** `cmd.ui.override` covers the spinner, tool rows, user messages, and command output. What a person is asked to approve is always drawn by Command Code, so the permission prompt (and every other approval dialog) is not on the list and never will be.
+- **Permission answers stop at the prompt.** `onPermissionRequest` only sees prompts the engine was about to show you: deny rules, plan mode, and dont-ask always win, and a safety-forced prompt can be denied by a mod but never allowed. In a headless run, where the prompt would otherwise be auto-answered, the mod's answer is used too.
 - **Session controls stop at the harness surface.** `cmd.sessions` covers what the live harness owns (compact, tree, navigate, labels); creating/switching/forking sessions is host lifecycle, not harness state, and stays with the host UI.
 
 Embedders wire the same machinery directly: `createModHost` + `loadMods` + `createHarness({modHost})` (or `createNodeHarnessSession({modHost})`), all exported from `@commandcode/harness`.

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

@@ -19,6 +19,7 @@ cmd mods remove fun-stuff                   # by the name `mods list` prints
 cmd mods enable <name>                      # enable a mod; -g for user level
 cmd mods disable <name>                     # disable a mod; -g for user level
 cmd mods open                               # open the mods dir (project); --user for ~
+cmd mods inspect ./some-mod                 # what it hooks, registers, and reaches (never runs it)
 ```
 
 `cmd mods list` prints one line per mod - name, scope, origin - project mods first, then user, then package-provided:
@@ -146,7 +147,19 @@ A disable in `settings.local.json` has to be removed by hand; no command writes
 
 ## Trust and safety
 
-- **There is no sandbox** - a mod is arbitrary code; install packages you trust.
+- **There is no sandbox** - a mod is arbitrary code that runs with your permissions; install packages you trust.
+- **Inspect before you trust** - `cmd mods inspect <path>` reads a mod's source (it never imports it) and lists the hooks it registers, what it adds, and what it can reach: processes, the network, the filesystem, the environment, permission answers, transcript rewrites. It is a lexical scan, so code a mod imports or names it builds at runtime can reach further, and the report says so.
+
+```bash
+$ cmd mods inspect ./permission-policy.ts
+files:     1
+hooks:     onPermissionRequest
+registers: none
+reaches:   answers permission prompts (onPermissionRequest)
+imports:   none
+```
+
+- **Kill switches** - `cmd --safe-mode` loads built-in mods only for one session (no installed mods, no `--mod`); `{"mods": {"disableAll": true}}` in any settings file does the same for every session until removed.
 - **Project mods are trust-gated** like project skills: they load only after the workspace trust prompt. User-scope and `--mod` mods always load.
 - **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.** 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).