command-code 0.52.5 → 1.0.0

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

@@ -0,0 +1,308 @@
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/mods/page.mdx. Regenerate: pnpm generate:knowledge -->
+
+# Hooks and events
+
+The harness's extension seam. A **mod** is a plain object of lifecycle hooks that mutates agent state or changes loop decisions. Pure observers (UI, telemetry, loggers) are **not** mods — they subscribe to the `AgentEvent` stream. Hooks change behavior; subscribers watch it. In a loadable mod, `cmd.hooks({...})` registers the hooks and `cmd.on(event, ...)` subscribes to events.
+
+A mod may also contribute **tools**, and every hook receives a **`ModContext`** (`{emit, signal, cwd, session?}`) as an extra last argument, so a mod can raise its own events and persist durable state without extra plumbing.
+
+## Lifecycle — where each hook fires
+
+One `run()` = one user turn → many model turns ("rounds"). The loop below is the agent loop, verbatim in ordering; mod hooks are marked `◆`, events `→`.
+
+```bash
+run({state, userInput?, config})
+  fork AbortController; working := state (+ user message when userInput given)
+  ctx := {emit, signal, cwd, session}              — built ONCE per run,
+                                    passed as the LAST argument to every ◆ hook below
+  → run_start {sessionId}
+  poll getSteeringMessages once                      (catch pre-run queued input)
+  loop:
+    abort check ──────────────────────────────────► stop: interrupted (→ interrupted)
+    ◆ onTurnStart (each mod, in order; returns new state)
+    → turn_start {turnNumber}
+    read live permission mode ONCE — pinned for this round
+    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)
+    ◆ 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)
+    → message_start
+    → model_request_start {model}
+    modelClient.complete(...)          (streams → text_delta / thinking_* /
+                                        message_update / continuation_recovery /
+                                        tool_input_coerced; retry → api_retry)
+    → model_request_end {model, usage, stopReason}
+    → message_end {content}
+    working += assistant message       (provider-executed blocks filtered out)
+    if client tool calls:
+      runTools(...)                    (see tool-dispatch order below)
+      working += tool-results user message
+      working := setModState(...) for every afterToolCall `modState`
+        contribution across the batch (BEFORE onTurnEnd runs)
+      any deny ────────────────────────► pendingStop: permission_denied
+      any terminate ───────────────────► pendingStop: terminate
+      else poll getSteeringMessages → append (source 'steering')
+    ◆ onTurnEnd (each mod; receives THIS turn's usage; returns new state)
+    → turn_end {turnNumber, hadToolCalls, usage}
+    onCommit(working)                  ← the durability boundary
+    pendingStop? ──────────────────────► stop
+    ◆ shouldStopAfterTurn (any true) ──► stop: stop_hook
+    turnNumber ≥ maxTurns ─────────────► stop: max_turns
+    if no tool calls:
+      no follow-up wanted ─────────────► ◆ onStop (any continue → keep going)
+                                         else stop: end_turn
+    ◆ prepareNextTurn (merged; later mods win) → may swap model / effort
+  ◆ onRunEnd (each mod, awaited)
+  → run_end {result}
+```
+
+### Tool-dispatch order
+
+```bash
+for each tool_use:  → tool_queued {toolCallId, toolName, input}   ← ALWAYS the original input
+phase 1 — permissions (always sequential):
+  permissions.generateDescription (5s timeout → null)
+  permissions.check({toolName, input, description, permissionMode})
+    throw ⇒ deny (fail closed)
+  deny → tool_denied; batch aborted: every call gets a tool_result,
+    run stops with permission_denied AFTER the turn commits
+phase 2 — execution (sequential, or parallel when config.toolExecution='parallel'):
+  ◆ beforeToolCall (each mod, in order; `input` rewrites CHAIN mod→mod;
+      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
+  → tool_running {toolCallId, toolName, description}
+  toolRunner.execute({toolName, input: <possibly rewritten>, signal, onUpdate})
+  ◆ afterToolCall (each mod, in order; sees current content, may replace it,
+      append `additionalContext`, flip `isError`, set `terminate`, or persist
+      `modState`)
+  beforeToolCall additionalContext strings appended to the final content
+  → tool_completed {result}   (or → tool_errored {error})
+```
+
+### Ordering guarantees mod authors can rely on
+
+- Every hook receives `ModContext` (`{emit, signal, cwd, session?}`) as its LAST argument. It's declared optional on every hook signature, so a hook that only declares the params object keeps compiling and running unchanged; the core always supplies a real object at runtime.
+- `beforeToolCall` completes (for every mod) **before** `tool_running` is emitted. Its `input` rewrites chain across mods, but the `tool_queued` event fired with the ORIGINAL input before any hook ran and is never re-emitted — display always shows what the model asked for, only execution sees the rewrite.
+- `afterToolCall` completes **before** `tool_completed` / `tool_errored` is emitted — the terminal event carries the post-hook content, and its `isError` (when set) decides which of the two fires, independent of whether execution itself threw.
+- `afterToolCall`'s `modState` is committed right after the batch's tool-result message is appended — BEFORE `onTurnEnd` runs, so `onTurnEnd` sees it.
+- `onTurnStart` precedes `turn_start`; `onTurnEnd` precedes `turn_end` and `onCommit`.
+- `onCommit` fires once per completed turn with the full serializable state.
+- `shouldStopAfterTurn` is evaluated **after** the turn commits, so a stop_hook never loses the turn that triggered it.
+- `prepareNextTurn` runs only when the loop actually continues (never on a stopping turn).
+- `onRunEnd` is **awaited** before the `run_end` event — it is the place for must-complete work (flush, trigger learning); event subscribers must never be.
+- Mods run in **registration order** in every phase; the built-ins come first and caller mods last (they see post-compaction context and post-hook tool results).
+- Hooks **never throw** upward: the runner catches per-mod, per-hook. A failing `transformContext` leaves messages unchanged; a failing `onTurnStart`/`onTurnEnd` keeps the prior state; a failing `shouldStopAfterTurn` means "don't stop"; failing tool hooks are skipped. Every catch site ALSO emits a `mod_error {modId, hook, error}` event before falling back to its no-crash default — the decision the loop makes is unchanged, but the degradation is never silent.
+
+## The hook contracts
+
+### `transformContext({messages, state, signal?}, ctx?) → messages`
+
+Fires once per round, after `appendSystemPrompt`, before `prepareForSend`. Messages are threaded through every mod in order — each receives the previous mod's output. **The result is used for this model call only and never written back to `state.messages`**: the durable log is untouched (compaction relies on this — the recorded transcript stays complete). Return the input array unchanged (same reference) to signal "no change".
+
+### `shouldStopAfterTurn({state, turnNumber}, ctx?) → boolean`
+
+Fires after the turn commits. **Any** mod returning `true` ends the run with `stopReason: 'stop_hook'` — first true short-circuits. This is *early stop* (goal budget spent); it is the opposite of the Stop hook forcing continuation.
+
+### `prepareNextTurn({state, turnNumber}, ctx?) → {model?, effort?} | undefined`
+
+Fires at the bottom of a continuing round. Results are merged across mods — later mods override earlier ones per field. A returned `model`/`effort` applies from the **next** model call onward (`config` is never mutated).
+
+### `appendSystemPrompt({state}, ctx?) → string | undefined`
+
+Fires once per round, right after the round's base `systemPrompt` resolves and before `transformContext`. Every mod's non-empty return is joined with `'\n\n'`, in registration order, and appended AFTER the base prompt. May return a plain string OR a Promise. **Must be byte-stable across rounds for the same durable inputs** — the provider's prompt-prefix cache keys off the system prompt's bytes, so a value that changes turn-to-turn without a corresponding `state`/`modState` change busts the cache every round. Compute once, store in `modState`, read it back.
+
+### `beforeToolCall({toolCallId, toolName, input, state}, ctx?) → {block?, additionalContext?, input?, terminate?} | undefined`
+
+Fires per tool call, after the permission check passed, before execution.
+
+- `block: true` — the tool does not run. The core emits `tool_hook_blocked` with `hookOutput` = your `additionalContext` (or `'Blocked by a pre-tool hook.'`), and that same text becomes the tool_result the model sees. Later mods' `beforeToolCall` for this call do not run. No `tool_running`/`tool_completed`/`tool_errored` is emitted for a blocked call.
+- `additionalContext` (without `block`) — collected across mods and appended as extra text blocks to the tool_result **after** execution and after `afterToolCall` overrides.
+- `input` — rewrites the input the tool actually executes with. **Chained across mods**: the next mod's `input` param is YOUR rewrite, not the original.
+- `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.
+
+### `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).
+
+- `isError` (param) — whether the tool's OWN execution failed, read before any hook override and threaded across mods like `result`. This is the **PostToolUse vs PostToolUseFailure** distinction: a hook can branch on `isError` to react only to failures. It is the INPUT signal; the returned `isError` field below is the OUTPUT override that selects the terminal event.
+- `content` **replaces** the tool result the model will see (threaded mod→mod).
+- `terminate: true` ends the run with `stopReason: 'terminate'` **after the whole batch finishes**.
+- `additionalContext` — appended as a SEPARATE text block after `content` (and after any `beforeToolCall` additionalContext strings).
+- `isError` — overrides whether the terminal event is `tool_completed` or `tool_errored`, independent of whether execution itself threw.
+- `modState` — a `Record<string, unknown>` merged into `state.modState[mod.id]` right after the tool-result message commits — a full replace of that mod's slot, exactly like `setModState`. The durable-state channel for tool hooks: neither tool hook can return a whole `AgentState` the way `onTurnStart`/`onTurnEnd` can.
+
+### `onTurnStart({state, turnNumber}, ctx?) → AgentState` / `onTurnEnd({state, turnNumber, hadToolCalls, usage}, ctx?) → AgentState`
+
+The only hooks that can **persist state changes** unconditionally — they return the new `AgentState` (typically via `setModState`), which the loop threads onward and commits. `onTurnEnd`'s `usage` is *this turn's* token usage. Both fire every round, including the round that stops.
+
+### `onRunEnd({state, result}, ctx?) → void`
+
+Fires once, awaited, after the loop exits and before the `run_end` event. `state` is the final state; `result` carries `finalText`, `stopReason`, `turnCount`, accumulated `usage`. Cannot alter the result. This is the "must-complete work" hook (learning, flushes).
+
+### `onStop({state, stopReason, turnNumber, lastAssistantText}, ctx?) → {continue?, reason?} | undefined`
+
+The **Stop hook** — the mods' force-continue channel. Fires when a turn WOULD end the run **naturally** — the model returned no tool calls and no follow-up provider wants to continue. Returning `{continue: true}` keeps the run going: `reason` (or a neutral default) is appended as an automated `source: 'stop_hook'` user turn, so the model is told why it must keep working.
+
+- **ANY** mod returning `continue` wins (first wins, short-circuits).
+- Does **NOT** fire for hard stops (`max_turns`, `terminate`, `permission_denied`, `interrupted`).
+- A follow-up provider (e.g. the continuation nudger) gets first say; `onStop` is consulted only when the provider declines.
+- The loop caps consecutive stop-hook continuations at **8** — a hook that always says `continue` can't loop forever.
+- Distinct from `shouldStopAfterTurn` (force EARLY stop) and `onRunEnd` (observe the stop): only `onStop` can push a finished run onward.
+
+```ts
+const persistUntilTestsPass = {
+	id: 'until-green',
+	onStop: async ({lastAssistantText}) => {
+		if (/all tests pass/i.test(lastAssistantText)) return {continue: false};
+		return {continue: true, reason: 'Tests are not green yet — keep going.'};
+	},
+};
+```
+
+## `ModContext.session` — the mods' persistence surface
+
+The harness's tree-format session store gives mods a durable, per-entry seam onto the SAME append-only file the transcript lives in. Available in a loadable mod as `cmd.session` and inside hooks as `ctx.session`. Two entry kinds:
+
+- **`appendCustomEntry({customType, data?})`** — a `custom` tree entry. Mod-private data; **never** sent to the LLM, never rendered. Use it for durable bookkeeping a mod wants to survive resume (counters, cursors, cached decisions).
+- **`appendCustomMessageEntry({customType, content, display, details?})`** — a `custom_message` tree entry. Content the model SHOULD see: it is projected as an ordinary `user` message on the NEXT turn (`display: true` also renders it in the TUI with distinct styling; `display: false` is context-only). The call returns `{entryId, message}` — a mod MUST fold `message` onto the `AgentState` it hands back from its hook for the model to see it that turn.
+- **`getCustomEntries({customType})`** — reads back every `custom` entry this mod itself wrote (filtered by `customType`), in file order, over the ACTIVE branch's full entry list. The standard reload pattern: a mod with in-memory state seeds it from `getCustomEntries` at first `onTurnStart`.
+
+```ts
+const MOD_ID = 'turn-counter';
+const CUSTOM_TYPE = 'turn-counter/count';
+
+const mod = {
+	id: MOD_ID,
+	onTurnStart: async ({state}, ctx) => {
+		if (!ctx?.session) return state; // a bare unit-test config without a store
+		const priorCount = ctx.session.getCustomEntries({
+			customType: CUSTOM_TYPE,
+		}).length;
+		ctx.session.appendCustomEntry({customType: CUSTOM_TYPE, data: {count: priorCount + 1}});
+		return state;
+	},
+};
+```
+
+`session` is absent (not merely empty) only for a bare unit-test config built without a durable store — every hook must treat `ctx.session` as possibly `undefined` and no-op gracefully. A `--no-session` run DOES populate `session` — entries still append and are readable for the lifetime of the process, they simply never touch disk.
+
+## `modState` conventions
+
+`AgentState.modState` is a `Readonly<Record<string, unknown>>` — one slot per mod, keyed by the mod's `id`:
+
+```ts
+const value = getModState<MyShape>({state, modId: 'my-mod'});     // undefined when unset
+const next  = setModState({state, modId: 'my-mod', value: {...}}); // fresh AgentState
+```
+
+- **Namespacing is by convention**: write only your own `id`'s slot.
+- Values must be **JSON-serializable** — `modState` is persisted with the session and survives resume. Run-scoped/volatile data (budgets, locks, in-flight promises) belongs in the mod factory's closure instead.
+- `onTurnStart`/`onTurnEnd` return the whole `AgentState` (typically via `setModState`). `afterToolCall` can also persist state via its `modState` return field. `beforeToolCall` has no state channel; a before-hook that needs to accumulate data stores it in the closure and flushes it via `afterToolCall`'s `modState` or `onTurnEnd`.
+- Custom data never goes into `state.messages`: the message union is closed wire types. When a mod must put something in front of the model, it emits real messages via `transformContext` (or `appendCustomMessageEntry`).
+
+## `AgentEvent` catalog
+
+One sync sink, fan out with `createEventBus`. Payloads are snapshots — never live references.
+
+| Event | Fires | Payload highlights |
+|---|---|---|
+| `run_start` / `run_end` | run boundaries | `sessionId` / `result` |
+| `turn_start` / `turn_end` | round boundaries (after onTurnStart / onTurnEnd) | `turnNumber`; end adds `hadToolCalls`, this turn's `usage` |
+| `message_start` | before each model call | — |
+| `text_delta`, `thinking_start/delta/end` | streaming | deltas; `thinking_end` carries full text |
+| `message_update` | streaming (ModelClient-accumulated) | whole partial assistant message incl. partial tool JSON |
+| `message_end` | response complete | full assistant content |
+| `model_request_start/end` | bracket the inference call | `model`; end adds `usage`, raw-preferred `stopReason` |
+| `tool_queued` | per call, before permission checks | `input` — the ORIGINAL input, never the rewritten one |
+| `tool_denied` | permission denied | — (batch then aborts) |
+| `tool_hook_blocked` | a mod's beforeToolCall blocked | `hookOutput` — **terminal for that call**: no tool_running/completed/errored follows |
+| `tool_running` | execution begins (after beforeToolCall) | `description` from permissions.generateDescription |
+| `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` |
+| `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` |
+| `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` |
+| `mod_error` | a mod hook threw (any phase), or a mod tool collided with an existing tool | `modId`, `hook`, `error` |
+| `interrupted` | abort observed | — |
+| `run_error` | non-retryable failure | the raw `Error` |
+
+## Worked example — a write-quota mod
+
+Blocks writes outside an allowlist, counts tool activity durably in modState, and reports at run end. Exercises the block channel, the closure-vs-modState split, and `onRunEnd`.
+
+```ts
+import type {AgentMod, AgentState} from '@commandcode/harness';
+import {getModState, setModState} from '@commandcode/harness';
+
+const MOD_ID = 'write-quota';
+
+interface WriteQuotaState {
+	readonly writesThisSession: number; // durable — survives resume
+}
+
+export function createWriteQuotaMod(options: {
+	readonly allowedRoot: string;
+	readonly maxWrites: number;
+	readonly report: (summary: string) => void;
+}): AgentMod {
+	// Run-scoped tally lives in the closure; flushed into modState at turn end
+	// (beforeToolCall cannot return state — see modState conventions).
+	let writesThisTurn = 0;
+
+	return {
+		id: MOD_ID,
+
+		beforeToolCall: async ({toolName, input, state}) => {
+			if (toolName !== 'write_file' && toolName !== 'edit_file') return undefined;
+			const path = typeof input.file_path === 'string' ? input.file_path : '';
+			if (!path.startsWith(options.allowedRoot)) {
+				// Block: this text becomes the tool_result the model sees, and the
+				// core emits tool_hook_blocked. The run continues — the model adapts.
+				return {
+					block: true,
+					additionalContext: `Writes outside ${options.allowedRoot} are not allowed.`,
+				};
+			}
+			const durable = getModState<WriteQuotaState>({state, modId: MOD_ID});
+			if ((durable?.writesThisSession ?? 0) + writesThisTurn >= options.maxWrites) {
+				return {block: true, additionalContext: 'Write quota exhausted for this session.'};
+			}
+			writesThisTurn += 1;
+			return undefined;
+		},
+
+		onTurnEnd: async ({state}) => {
+			if (writesThisTurn === 0) return state;
+			const durable = getModState<WriteQuotaState>({state, modId: MOD_ID});
+			const next: AgentState = setModState({
+				state,
+				modId: MOD_ID,
+				value: {writesThisSession: (durable?.writesThisSession ?? 0) + writesThisTurn},
+			});
+			writesThisTurn = 0;
+			return next; // committed via onCommit at the turn boundary
+		},
+
+		onRunEnd: async ({state, result}) => {
+			const durable = getModState<WriteQuotaState>({state, modId: MOD_ID});
+			options.report(
+				`run stopped (${result.stopReason}) after ${result.turnCount} turns; ` +
+					`${durable?.writesThisSession ?? 0} writes used`,
+			);
+		},
+	};
+}
+```
+
+Wire it as a loadable mod (`cmd.hooks({...})` with the same handlers) — or, when embedding the harness, `createHarness({..., mods: [createWriteQuotaMod({...})]})`.

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

@@ -0,0 +1,161 @@
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/mods/page.mdx. Regenerate: pnpm generate:knowledge -->
+
+# Mods
+
+Mods are loadable plugins written against the `ModApi` — TypeScript files that Command Code discovers on disk, loads at startup, and compiles onto its agent loop. A mod 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 written as mods against this same API.
+
+A loadable mod IS an `AgentMod` once loaded; the mod host just builds it from a factory file instead of a code import:
+
+```bash
+~/.commandcode/mods/review-guard.ts        one file = one mod
+        │
+        ▼  jiti (TypeScript, no build step)
+default-export factory(cmd: ModApi)
+        │
+        ▼  createModHost().register(...)
+hooks + addTool  ──►  ONE AgentMod (id `mod:<name>`), appended after the built-ins
+addCommand       ──►  /slash dispatch + autocomplete in the TUI
+on(event)        ──►  AgentEvent bus subscription (observe-only)
+hooks.transformInput ─►  typed-prompt interception (transform / consume)
+addProvider      ──►  ProviderModule appended to the host's provider set
+addRenderer      ──►  custom feed entries (showEntry → styled lines in the TUI)
+queueMessage     ──►  the loop's steering / follow-up drains
+```
+
+The factory receives the API bound as `cmd` (the product's name, VS Code style: `vscode.commands…` → `cmd.addCommand…`). Registration verbs are all `add*` and each returns a `Disposable` — call `.dispose()` to undo exactly that one registration.
+
+This page is the whole mods surface end to end: the quick start and loading rules first, then the full **ModApi reference**, the **hooks and events** contract, the **UI surface**, **packaging and install**, and how to **verify a mod**. Jump to any section from the sidebar.
+
+---
+
+## Quick start
+
+Create `~/.commandcode/mods/review-guard.ts`:
+
+```ts
+import type {ModApi} from '@commandcode/harness';
+
+export default function (cmd: ModApi) {
+	// Block dangerous writes (a mutating hook — see the hooks catalog).
+	cmd.hooks({
+		beforeToolCall: async ({toolName, input}) => {
+			if (toolName !== 'shell_command') return undefined;
+			const command = typeof input.command === 'string' ? input.command : '';
+			if (!command.includes('rm -rf')) return undefined;
+			const allow = await cmd.ui.confirm({title: 'Allow rm -rf?'});
+			return allow ? undefined : {block: true, additionalContext: 'Blocked by review-guard.'};
+		},
+	});
+
+	// A tool the model can call.
+	cmd.addTool({
+		schema: {
+			name: 'count_todos',
+			description: 'Count TODO markers in the repo',
+			input_schema: {type: 'object', properties: {}, required: []},
+		},
+		run: async () => {
+			const result = await cmd.exec({command: 'grep', args: ['-rc', 'TODO', '.']});
+			return {ok: true, content: [{type: 'text', text: result.stdout}]};
+		},
+	});
+
+	// A host slash command: /todos in the TUI.
+	cmd.addCommand({
+		name: 'todos',
+		description: 'Summarize open TODOs',
+		handler: () => ({prompt: 'List every TODO comment in this repo and rank by urgency.'}),
+	});
+
+	// Observe the event stream (never mutates — mutation is what hooks are for).
+	cmd.on('turn_end', () => cmd.ui.notify('turn finished'));
+}
+```
+
+It loads on the next session (or `cmd --mod ./review-guard.ts` to try it without installing). The factory may be async; jiti compiles the TypeScript at load time, so there is no build step.
+
+---
+
+## Where mods load from
+
+| Location | Scope | Notes |
+|---|---|---|
+| built-in | shipped | compiled-in first-party mods (providers, titling, …); registered first |
+| `~/.commandcode/mods/*.ts` | user | loose files, one mod each |
+| `~/.commandcode/mods/<dir>/` | user | `package.json` manifest → `mods/` dir → `index.ts` |
+| `<project>/.commandcode/mods/…` | project | same layout; loads only once the workspace is trusted |
+| settings `mods.paths` | user/project | explicit files/dirs, relative to the settings scope |
+| settings `mods.sources` | user/project | installed packages (see [Packaging and install](./packaging.md#packaging-and-install)) |
+| `--mod <path>` | session | repeatable; loads ahead of installed, wins name collisions |
+
+Dot-entries and `node_modules` are never scanned (the package registry lives under `mods/.registry/` precisely so discovery skips it). Duplicate mod names keep the first and warn. Disable without deleting via settings:
+
+```json
+{"mods": {"disabled": ["review-guard"]}}
+```
+
+---
+
+## 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.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).
+
+---
+
+## Built-in mods
+
+Command Code's own features ride this exact API. First-party providers (`provider-anthropic` / `provider-copilot` / `provider-openai`), the update notice, and the harness-side titling and taste-learning triggers are **built-in mods**: compiled-in factories registered on the same host before any discovered mod. They are not special — they use `cmd.addProvider`, `cmd.on`, and `cmd.hooks` like any mod, appear in `cmd mods list` with source `builtin`, and honor the same disable key:
+
+```json
+{"mods": {"disabled": ["provider-copilot", "update-notice", "titling", "learning"]}}
+```
+
+Built-in mods always win a name collision against a discovered mod of the same name (the loader shadows the file with a warning), and they are compiled in — never jiti-loaded from a writable path, so they are not supply-chain surface. Structural harness mods (workspace, compaction, checkpoints) are load-bearing for correctness and stay unconditional; only the observer-style built-ins above are disable-able.
+
+---
+
+## Runnable examples
+
+Runnable, single-file example mods ship with Command Code inside the bundled `mod-builder` skill (`src/skills/bundled/mod-builder/examples/`) and are validated in CI — they load through the real loader on every test run, so they never rot. Ask Command Code to "build a mod" and it reads these.
+
+| File | Shows |
+|---|---|
+| `slash-command.ts` | `addCommand` — a `/command` returning `{prompt}` or `{message}` |
+| `custom-tool.ts` | `addTool` — a model-callable tool with `run` + `exec` |
+| `block-dangerous-commands.ts` | `hooks.beforeToolCall` — block/allow with a confirm |
+| `input-shortcuts.ts` | `hooks.transformInput` — rewrite / handle typed input |
+| `observe-events.ts` | `on(event)` + the cross-mod `events` bus |
+| `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')` |
+| `status-and-widgets.ts` | `ui.setStatus` footer segment + `ui.widget` above the editor + a timed confirm |
+| `kitchen-sink.ts` | every capability in one annotated file |
+
+---
+
+## Boundaries (deliberate)
+
+- **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).
+- **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.
+- **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})`). See `packages/harness/src/mod-host/` for the pieces and its `__tests__/` for executable examples.
+
+---
+
+## The reference sections
+
+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.
+- [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/packaging.md

@@ -0,0 +1,63 @@
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/mods/page.mdx. Regenerate: pnpm generate:knowledge -->
+
+# Packaging and install
+
+A mod starts life as a loose file in `~/.commandcode/mods/`. When it should be shared — with a team, or the world — it becomes a **package**: an npm package, a git repo, or a local directory that `cmd mods add` installs and Command Code loads on every session.
+
+## Install, remove, list, update
+
+```bash
+cmd mods add npm:@team/review-mod@1.2.0     # npm registry
+cmd mods add owner/repo@v1                  # GitHub shorthand (any git host via git:<host>/…)
+cmd mods add ./tools/local-mod              # local path, referenced in place
+cmd mods add -g owner/repo                  # user scope instead of project
+cmd mods list
+cmd mods update                             # reinstall missing, reconcile pinned refs
+cmd mods remove owner/repo
+```
+
+Sources persist in the `mods.sources` settings key (project scope writes `.commandcode/settings.json`, `-g` writes `~/.commandcode/settings.json`). Identity is version/ref-agnostic — `owner/repo@v1` and `https://github.com/owner/repo` are the same package, and a project entry shadows the same identity at user scope. Installs land in `<scope>/.commandcode/mods/.registry/{npm,git}/…`; startup never runs npm/git on its own — a configured-but-missing package is a warning pointing at `cmd mods update`.
+
+## What a package ships
+
+A package declares what it ships via `package.json` — exact paths, directories, or globs (expanded against the package root; entries escaping the root are dropped):
+
+```json
+{
+	"name": "@team/review-mod",
+	"commandcode": {"mods": ["./src/review.ts", "src/checks/*.ts"]}
+}
+```
+
+No manifest → the `mods/` convention directory → a root `index.ts`, in that order.
+
+## Filtering a source's mods
+
+A `mods.sources` entry can be the object form to load only part of a package:
+
+```json
+{
+	"mods": {
+		"sources": [
+			{"source": "owner/review-pack", "mods": ["review/*.ts", "!review/slow.ts"]}
+		]
+	}
+}
+```
+
+Four pattern kinds, applied in precedence order: `-path` force-exclude (exact, beats everything) → `+path` force-include (exact, restores what globs dropped) → `!glob` exclude → plain-glob include (when any includes exist, an entry must match one). Patterns match the entry's package-relative path or its mod name. `cmd mods add` / `remove` preserve hand-written object entries — they never flatten your filters.
+
+## Disabling without deleting
+
+```json
+{"mods": {"disabled": ["review-guard"]}}
+```
+
+Works for discovered files, installed packages, and the disable-able built-ins (`provider-copilot`, `update-notice`, `titling`, `learning`).
+
+## Trust and safety
+
+- **There is no sandbox** — a mod is arbitrary code; install packages you trust.
+- **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).

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

@@ -0,0 +1,63 @@
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/mods/page.mdx. Regenerate: pnpm generate:knowledge -->
+
+# UI surface
+
+Everything a mod can put on screen rides `cmd.ui`, `cmd.addRenderer`, and `cmd.showEntry`. All of it is line-based and host-agnostic: the TUI wires real rendering, headless runs degrade to deterministic defaults, and a crashing renderer becomes a warning — never a broken screen.
+
+## 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
+});
+```
+
+## Footer status segments
+
+`cmd.ui.setStatus(text | null)` — a persistent per-mod segment in the TUI footer (under the input panel). One segment per mod: a new call replaces the text, `null` clears it, the returned `Disposable` clears it too. Segments from multiple mods concatenate in load order. Headless: renders nowhere (no-op).
+
+## Editor widgets
+
+`cmd.ui.widget({placement: 'above-editor' | 'below-editor', render: () => lines})` — a line-based widget the TUI renders around the input panel. Same verbatim-lines contract as `addRenderer` (style with ansi); `render` re-runs on every repaint, and `cmd.ui.refreshWidgets()` requests a repaint after your data changes. A throwing render is skipped (reported as a `mod_error`) so siblings keep rendering. Headless: no-op.
+
+```ts
+let failing = 0;
+cmd.ui.widget({
+	placement: 'above-editor',
+	render: () => [failing > 0 ? `✗ ${failing} tests failing` : '✓ tests green'],
+});
+cmd.on('tool_completed', () => {
+	failing = readFailingCount();
+	cmd.ui.refreshWidgets();
+});
+```
+
+## Custom feed rendering
+
+- `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.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.
+
+Rendering is deliberately **line-based, not component-based**: mods return styled text lines, never React components. 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.
+
+## Headless behavior at a glance
+
+| Surface | Interactive TUI | Headless (`-p`) |
+|---|---|---|
+| `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` | footer segment | no-op |
+| `widget` | rendered around the editor | no-op |
+| `showEntry` | rendered feed row | dropped |
+
+The `status-and-widgets.ts` bundled example exercises all of this in one file — see [Runnable examples](./overview.md#runnable-examples).