command-code 0.52.5 → 1.0.1

package/dist/bundled/mod-builder/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: mod-builder
+description: Build a Command Code mod (a loadable plugin) end to end — a TypeScript file that registers tools, slash commands, lifecycle hooks, event observers, input interception, custom renderers, flags, or a model provider through the ModApi. Use when the user wants to create, build, generate, or scaffold a mod, extend Command Code with custom behavior, add a custom tool or slash command, intercept input, block or rewrite tool calls, or turn a workflow into a reusable plugin.
+---
+
+# Mod Builder
+
+You are building a **mod**: a TypeScript file that Command Code discovers on disk and loads
+onto its agent loop. A mod is the plugin unit — it can add tools the model calls, slash
+commands, mutating lifecycle hooks, event observers, typed-input interception, custom feed
+rendering, configurable flags, and model providers. This is the same API Command Code's own
+built-in features (providers, titling, update notice) are written against.
+
+Two resources ship next to this file — use them instead of searching the codebase:
+
+- `examples/` — runnable, single-file example mods, one per capability. Read the one
+  closest to the job and adapt it.
+- `reference/` — the full mods documentation, generated from the public docs
+  (commandcode.ai/docs/mods). This is the authoritative API reference:
+
+<!-- generated:reference-index:start -->
+- `reference/overview.md` — Mods
+- `reference/api.md` — ModApi reference
+- `reference/hooks-and-events.md` — Hooks and events
+- `reference/ui.md` — UI surface
+- `reference/packaging.md` — Packaging and install
+- `reference/verify.md` — Verify a mod
+<!-- generated:reference-index:end -->
+
+## 1. The shape of a mod
+
+A mod is a file that default-exports a factory. The factory receives the API bound as `cmd`
+and registers everything up front (it may be async):
+
+```typescript
+import type {ModApi} from '@commandcode/harness';
+
+export default function (cmd: ModApi) {
+	cmd.addCommand({name: 'hello', handler: () => ({message: 'hi from a mod'})});
+}
+```
+
+Save it at `~/.commandcode/mods/hello.ts` (personal) or `<project>/.commandcode/mods/hello.ts`
+(project — loads once the workspace is trusted). It loads next session, or test it now with
+`cmd --mod ./hello.ts`. No build step — jiti compiles the TypeScript at load.
+
+## 2. Pick the capability
+
+Every registration verb is `add*` and returns a `Disposable` (`.dispose()` undoes it). Match
+the job to the seam, then open the matching example file:
+
+| The mod should… | Use | Example |
+|---|---|---|
+| add a `/command` | `cmd.addCommand({name, handler})` | `examples/slash-command.ts` |
+| add a tool the model calls | `cmd.addTool({schema, run})` | `examples/custom-tool.ts` |
+| block or rewrite a tool call | `cmd.hooks({beforeToolCall})` | `examples/block-dangerous-commands.ts` |
+| rewrite or consume typed input | `cmd.hooks({transformInput})` | `examples/input-shortcuts.ts` |
+| keep a finished run going / react to session start·end | `cmd.hooks({onStop, onSessionStart, onSessionEnd})` | `examples/lifecycle-hooks.ts` |
+| react to what happens | `cmd.on(event, handler)` | `examples/observe-events.ts` |
+| print custom styled feed rows | `cmd.addRenderer` + `cmd.showEntry` | `examples/custom-entry-renderer.ts` |
+| take configurable options | `cmd.addFlag` + `cmd.getFlag` | `examples/flags-and-options.ts` |
+| everything at once (a tour) | — | `examples/kitchen-sink.ts` |
+
+## 3. 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`). See `reference/hooks-and-events.md` for the full set. 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.
+
+## 4. Tools and commands, precisely
+
+- **Tool `run`** receives `{input, runtime, signal}` and returns
+  `{ok: true, content: [{type: 'text', text}]}` or `{ok: false, error}`. Mark
+  `readOnly: true` when the tool never mutates (stays available in plan mode). A mod tool
+  whose name collides with an existing tool is skipped with a `mod_error` — pick a distinct,
+  namespaced name.
+- **Command `handler`** returns DATA, never a live callback: `{prompt}` runs an automated
+  model turn, `{message}` renders an info row, nothing = pure side effect. It gets
+  `{args, ui, cwd, exec}`.
+
+## 5. Verify what you built
+
+Do NOT declare the mod done until it demonstrably loads and its surface works. The loop
+(full detail in `reference/verify.md`):
+
+1. **Load it without installing** — `cmd --mod ./your-mod.ts`. A file that fails to import,
+   exports no factory, or throws in its factory becomes a warning — never a crashed session —
+   so an unchecked mod can fail silently.
+2. **Confirm it registered** — `cmd mods list` must show the mod with zero load warnings.
+   If it is missing, the printed warning says why (import error, no default-export factory,
+   factory threw, duplicate name).
+3. **Exercise every registered surface** — a slash command must appear in `/` autocomplete
+   and run; a tool must be callable by the model by name; a hook must be triggered (ask for
+   the guarded action and watch the block/rewrite land); a widget/status must render around
+   the input panel.
+4. **Iterate with `/reload`** — mods load once per process; `/reload` restarts and
+   re-imports every mod.
+5. **Headless check when CI matters** — `cmd -p "…" --mod ./your-mod.ts`; dialogs resolve
+   deterministic defaults (confirm → false, select/input → undefined), so the mod must
+   behave sensibly under them.
+
+Working inside the Command Code repo itself? The examples are validated by
+`packages/harness/src/mod-host/__tests__/examples.test.ts` — run it after touching them, and
+run `pnpm generate:knowledge` after editing the docs under `packages/docs/src/app/mods/`
+(the `reference/` files here are generated from them).
+
+## 6. Ship it (optional)
+
+- Personal: leave it in `~/.commandcode/mods/`.
+- A package: a `package.json` with `{"commandcode": {"mods": ["./index.ts"]}}`, installed via
+  `cmd mods add npm:<name>` / `cmd mods add owner/repo` / `cmd mods add ./local-dir`.
+  Full packaging/filtering detail: `reference/packaging.md`.
+
+## Boundaries to state up front
+
+- **No sandbox** — a mod is arbitrary code; install packages you trust. Project mods are
+  trust-gated like project skills.
+- **Reload is `/reload`** — mods load once per process; `/reload` restarts and re-imports.
+- **Providers extend, never replace** — `cmd.addProvider` adds to the provider set.
+- **Rendering is line-based** — `cmd.addRenderer` returns styled text lines, not React
+  components, so a mod renders in any host and a broken renderer can't break the screen.

package/dist/bundled/mod-builder/examples/block-dangerous-commands.ts

@@ -0,0 +1,41 @@
+// Example mod: a policy guard that can BLOCK a tool call.
+//
+// cmd.hooks are the mutating lifecycle. `beforeToolCall` runs before every tool executes
+// and may:
+//   return { block: true, additionalContext }  → the call never runs; the model is told why
+//   return { input: rewritten }                 → the call runs with rewritten input
+//   return undefined                            → allow unchanged
+//
+// This is where you'd enforce org policy, sandbox paths, or require confirmation. The guard
+// below refuses `rm -rf` and force-pushes unless the user confirms in the TUI.
+
+import type {ModApi} from '@commandcode/harness';
+
+const DANGEROUS = [
+	/\brm\s+-rf\b/,
+	/\bgit\s+push\b.*--force\b/,
+	/\bgit\s+push\s+-f\b/,
+];
+
+export default function (cmd: ModApi): void {
+	cmd.hooks({
+		beforeToolCall: async ({toolName, input}) => {
+			if (toolName !== 'shell_command') return undefined;
+			const command =
+				typeof input.command === 'string' ? input.command : '';
+			if (!DANGEROUS.some(pattern => pattern.test(command)))
+				return undefined;
+
+			const allow = await cmd.ui.confirm({
+				title: 'Dangerous command',
+				message: `Allow: ${command}`,
+			});
+			if (allow) return undefined;
+			return {
+				block: true,
+				additionalContext:
+					'Blocked by the safety mod. Ask the user to run this manually if it is really intended.',
+			};
+		},
+	});
+}

package/dist/bundled/mod-builder/examples/custom-entry-renderer.ts

@@ -0,0 +1,32 @@
+// Example mod: render a custom entry into the feed with your own styling.
+//
+// Two pieces:
+//   cmd.addRenderer(type, data => lines)  → registers how a custom entry type prints
+//   cmd.showEntry(type, data)             → pushes an entry of that type into the live feed
+//
+// Rendering is line-based: the renderer returns styled terminal lines (use raw ansi escape
+// codes, picocolors, or @commandcode/tui helpers). Unrendered types pretty-print as JSON.
+// The TUI wires the feed sink; headless runs drop entries. A throwing renderer degrades to
+// a warning notice, never a broken screen.
+//
+// Pair showEntry with cmd.session.appendCustomEntry when the data should also persist to
+// the transcript.
+
+import type {ModApi} from '@commandcode/harness';
+
+const GREEN = '\x1b[32m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+export default function (cmd: ModApi): void {
+	cmd.addRenderer('score', data => {
+		const {label, value} = data as {label: string; value: number};
+		const bar = '█'.repeat(Math.max(0, Math.min(10, value)));
+		return [`${GREEN}${label}${RESET} ${bar} ${DIM}${value}/10${RESET}`];
+	});
+
+	// Show a scored entry whenever a run finishes (contrived — a real mod would compute it).
+	cmd.on('run_end', () => {
+		cmd.showEntry('score', {label: 'confidence', value: 8});
+	});
+}

package/dist/bundled/mod-builder/examples/custom-tool.ts

@@ -0,0 +1,53 @@
+// Example mod: a tool the MODEL can call.
+//
+// cmd.addTool registers a ToolModule — the same shape the built-in tools use. The model
+// sees the schema and decides when to call it; `run` receives the parsed input plus the
+// harness Runtime (filesystem + shell), and returns a result:
+//   { ok: true,  content: [{type: 'text', text}] }  → success, text goes back to the model
+//   { ok: false, error }                             → the model sees the error and can retry
+//
+// Mark `readOnly: true` if the tool never mutates — it then stays available in plan mode
+// and takes the read-only permission fast-path.
+
+import type {ModApi} from '@commandcode/harness';
+
+export default function (cmd: ModApi): void {
+	cmd.addTool({
+		schema: {
+			name: 'count_todos',
+			description:
+				'Count TODO/FIXME markers across the repository and report the total.',
+			input_schema: {
+				type: 'object',
+				properties: {
+					path: {
+						type: 'string',
+						description:
+							'Directory to search (defaults to the repo root).',
+					},
+				},
+				required: [],
+			},
+		},
+		readOnly: true,
+		run: async ({input}) => {
+			const path = typeof input.path === 'string' ? input.path : '.';
+			const result = await cmd.exec({
+				command: 'grep',
+				args: ['-rIoE', 'TODO|FIXME', path],
+			});
+			const count = result.stdout
+				.split('\n')
+				.filter(line => line.length > 0).length;
+			return {
+				ok: true,
+				content: [
+					{
+						type: 'text',
+						text: `${count} TODO/FIXME markers in ${path}`,
+					},
+				],
+			};
+		},
+	});
+}

package/dist/bundled/mod-builder/examples/flags-and-options.ts

@@ -0,0 +1,29 @@
+// Example mod: declare configurable flags.
+//
+// cmd.addFlag declares a named option with a type and default. The user sets it at launch
+// with repeatable `--mod-option name=value`:
+//   cmd --mod-option verbose=true --mod-option reviewer=alice
+//
+// Read the live value with cmd.getFlag(name). Boolean-declared flags coerce "true"/"false"
+// text to a boolean; string flags keep the text verbatim. A flag only belongs to the mod
+// that declared it.
+
+import type {ModApi} from '@commandcode/harness';
+
+export default function (cmd: ModApi): void {
+	cmd.addFlag('verbose', {
+		type: 'boolean',
+		default: false,
+		description: 'Announce every finished turn.',
+	});
+	cmd.addFlag('reviewer', {
+		type: 'string',
+		default: 'the team',
+		description: 'Who to address review summaries to.',
+	});
+
+	cmd.on('run_end', () => {
+		if (cmd.getFlag('verbose') !== true) return;
+		cmd.ui.notify(`turn done — summary is for ${cmd.getFlag('reviewer')}`);
+	});
+}

package/dist/bundled/mod-builder/examples/input-shortcuts.ts

@@ -0,0 +1,41 @@
+// Example mod: intercept what the user types before the model sees it.
+//
+// hooks.transformInput runs on every typed user prompt. Return:
+//   { action: 'transform', text }        → rewrite the prompt (handlers chain; the next
+//                                           mod sees your rewrite)
+//   { action: 'handled', message? }       → consume the prompt entirely; no model turn runs
+//                                           (an optional info row renders in its place)
+//   { action: 'continue' } / undefined    → pass through unchanged
+//
+// Automated turns, meta messages, slash commands, and image-carrying prompts never reach
+// transformInput — it only sees text the USER typed. A throwing handler is skipped, never
+// blocking the prompt.
+
+import type {ModApi} from '@commandcode/harness';
+
+const SHORTCUTS: Record<string, string> = {
+	'#ship':
+		'Run the test suite, then the linter, then summarize what is left before this can ship.',
+	'#review': 'Review the current git diff for bugs and risky changes.',
+};
+
+export default function (cmd: ModApi): void {
+	cmd.hooks({
+		transformInput: ({text}) => {
+			const trimmed = text.trim();
+
+			// A local slash-like command handled entirely by the mod.
+			if (trimmed === '#help') {
+				return {
+					action: 'handled',
+					message: `Shortcuts: ${Object.keys(SHORTCUTS).join(', ')}`,
+				};
+			}
+
+			const expansion = SHORTCUTS[trimmed];
+			if (expansion) return {action: 'transform', text: expansion};
+
+			return {action: 'continue'};
+		},
+	});
+}

package/dist/bundled/mod-builder/examples/kitchen-sink.ts

@@ -0,0 +1,110 @@
+// Example mod: the KITCHEN SINK — every ModApi capability in one file, so you can see how
+// the pieces fit together. In practice a mod does one job; this one is a tour.
+//
+// A mod is a TypeScript file that default-exports a factory. The factory receives the API
+// bound as `cmd` and registers everything up front. It may be async (await setup work
+// before returning). Every registration returns a Disposable — call .dispose() to undo
+// exactly that one registration.
+
+import type {ModApi} from '@commandcode/harness';
+
+export default function (cmd: ModApi): void {
+	// ── identity ──────────────────────────────────────────────────────────────────────
+	// cmd.name is this mod's name; cmd.cwd is the workspace root.
+
+	// ── flags: configurable options (cmd --mod-option strict=true) ──────────────────────
+	cmd.addFlag('strict', {type: 'boolean', default: false});
+
+	// ── hooks: the MUTATING lifecycle (compose in registration order) ───────────────────
+	cmd.hooks({
+		// Add to the system prompt every request.
+		appendSystemPrompt: () => 'Prefer small, reviewable diffs.',
+
+		// Rewrite or block a tool call before it runs.
+		beforeToolCall: async ({toolName, input}) => {
+			if (toolName !== 'shell_command') return undefined;
+			const command =
+				typeof input.command === 'string' ? input.command : '';
+			if (
+				cmd.getFlag('strict') === true &&
+				command.includes('--no-verify')
+			)
+				return {
+					block: true,
+					additionalContext: 'strict mode forbids --no-verify',
+				};
+			return undefined;
+		},
+
+		// Inspect or rewrite a tool result after it runs.
+		afterToolCall: async ({result}) => {
+			if (typeof result !== 'string' || !result.includes('DEPRECATED'))
+				return undefined;
+			return {
+				additionalContext:
+					'A tool result mentioned DEPRECATED — flag it.',
+			};
+		},
+
+		// Intercept typed input before the model sees it.
+		transformInput: ({text}) =>
+			text.trim() === '#note'
+				? {action: 'handled', message: 'noted.'}
+				: {action: 'continue'},
+
+		// Fires once the run completes (post-turn work).
+		onRunEnd: async () => {
+			cmd.showEntry('summary', {tools: 'see feed'});
+		},
+	});
+
+	// ── a tool the model can call ───────────────────────────────────────────────────────
+	cmd.addTool({
+		schema: {
+			name: 'repo_size',
+			description: 'Report the number of tracked files.',
+			input_schema: {type: 'object', properties: {}, required: []},
+		},
+		readOnly: true,
+		run: async () => {
+			const {stdout} = await cmd.exec({
+				command: 'git',
+				args: ['ls-files'],
+			});
+			const count = stdout.split('\n').filter(Boolean).length;
+			return {
+				ok: true,
+				content: [{type: 'text', text: `${count} tracked files`}],
+			};
+		},
+	});
+
+	// ── a slash command ─────────────────────────────────────────────────────────────────
+	cmd.addCommand({
+		name: 'sink-status',
+		description: 'Show mod status',
+		handler: () => ({message: `strict = ${cmd.getFlag('strict')}`}),
+	});
+
+	// ── a custom feed renderer + the entry it renders ──────────────────────────────────
+	cmd.addRenderer('summary', data => [`◆ summary: ${JSON.stringify(data)}`]);
+
+	// ── observe events (never mutate here) ──────────────────────────────────────────────
+	cmd.on('tool_errored', () => cmd.ui.notify('a tool errored', 'warning'));
+
+	// ── live surfaces (usable any time after the harness binds) ─────────────────────────
+	// cmd.ui.notify / confirm / select / input — talk to the user.
+	// cmd.queueMessage({content, deliverAs}) — steer the running loop or queue a follow-up.
+	// cmd.session — durable custom-entry persistence (undefined until bound).
+	// cmd.sessions — compact(), tree(), leafId(), navigateTree(...), setLabel(...).
+	// cmd.setModel / setEffort / setSessionName.
+	// cmd.getAllTools / getActiveTools / setActiveTools — a mod-managed tool filter.
+	//
+	// Example: on the first run, greet once via a queued steering message.
+	let greeted = false;
+	cmd.on('run_start', () => {
+		if (greeted) return;
+		greeted = true;
+		cmd.queueMessage({content: 'Remember to keep the change focused.'});
+	});
+}

package/dist/bundled/mod-builder/examples/lifecycle-hooks.ts

@@ -0,0 +1,64 @@
+// Example mod: the cross-agent lifecycle hooks — Stop, SessionStart/End, PostToolUseFailure,
+// and SubagentStart/Stop. Together with beforeToolCall (PreToolUse), afterToolCall (PostToolUse),
+// and transformInput (UserPromptSubmit), a mod can register a handler for every lifecycle hook
+// point the major coding agents expose. See harness/docs/mods-api.md#cross-agent-hook-parity.
+
+import type {ModApi} from '@commandcode/harness';
+
+export default function (cmd: ModApi): void {
+	// SessionStart / SessionEnd — once per session, with typed source/reason the bare
+	// `session_start` / `session_shutdown` events don't carry.
+	cmd.hooks({
+		onSessionStart: ({source}) => {
+			cmd.ui.notify(`session started (${source})`);
+		},
+		onSessionEnd: ({reason}) => {
+			cmd.ui.notify(`session ending (${reason})`);
+		},
+	});
+
+	// PostToolUse vs PostToolUseFailure — the afterToolCall hook's `isError` param tells you
+	// whether the tool's own execution failed, so you can react only to failures.
+	let toolFailures = 0;
+	cmd.hooks({
+		afterToolCall: async ({toolName, isError}) => {
+			if (isError) {
+				toolFailures += 1;
+				return {
+					additionalContext: `(${toolName} failed — ${toolFailures} failure(s) so far this run)`,
+				};
+			}
+			return undefined;
+		},
+	});
+
+	// The Stop hook — force-continue a run that would otherwise finish. Here: keep going until
+	// the model says it is done, but never more than a couple of nudges (the loop also caps this).
+	let nudges = 0;
+	cmd.hooks({
+		onStop: async ({lastAssistantText}) => {
+			if (/\bdone\b/i.test(lastAssistantText) || nudges >= 2) {
+				return {continue: false};
+			}
+			nudges += 1;
+			return {
+				continue: true,
+				reason: 'If the task is complete, say "done". Otherwise keep working.',
+			};
+		},
+	});
+
+	// SubagentStart / SubagentStop — observe the `task` tool bracketing a nested sub-agent run.
+	cmd.on('subagent_start', event => {
+		if (event.type === 'subagent_start') {
+			cmd.ui.notify(`sub-agent started: ${event.subagentType}`);
+		}
+	});
+	cmd.on('subagent_stop', event => {
+		if (event.type === 'subagent_stop') {
+			cmd.ui.notify(
+				`sub-agent ${event.subagentType} done (~${event.tokensUsed} tokens)`,
+			);
+		}
+	});
+}

package/dist/bundled/mod-builder/examples/observe-events.ts

@@ -0,0 +1,30 @@
+// Example mod: observe the event stream (never mutate).
+//
+// cmd.on subscribes to any AgentEvent type plus the host lifecycle events
+// `session_start` / `session_shutdown`. Observers CANNOT block tools or rewrite context —
+// that is what cmd.hooks is for. The boundary is deliberate: hooks mutate, `on` observes.
+//
+// Handlers are isolated: a throw becomes a `mod_error` event, never a crashed session.
+// Every cmd.on returns a Disposable — call .dispose() to stop observing.
+//
+// Common event types: run_start, run_end, turn_start, turn_end, model_request_start,
+// model_request_end, tool_running, tool_completed, tool_errored, notice.
+
+import type {ModApi} from '@commandcode/harness';
+
+export default function (cmd: ModApi): void {
+	let toolCalls = 0;
+
+	cmd.on('tool_completed', () => {
+		toolCalls += 1;
+	});
+
+	cmd.on('run_end', () => {
+		cmd.ui.notify(`turn finished — ${toolCalls} tool call(s) this session`);
+	});
+
+	// The cross-mod bus lets mods talk to each other without knowing about one another.
+	cmd.on('tool_errored', () => {
+		cmd.events.emit('tool-failed', {at: toolCalls});
+	});
+}

package/dist/bundled/mod-builder/examples/slash-command.ts

@@ -0,0 +1,33 @@
+// Example mod: a slash command.
+//
+// Drop this file at ~/.commandcode/mods/standup.ts and `/standup` appears in the TUI
+// slash menu. A command handler returns DATA, never a live callback:
+//   { prompt }  → submitted as an automated turn (the model runs it)
+//   { message } → rendered as an info row (no model turn)
+//   nothing     → pure side effect (e.g. it only called cmd.ui / cmd.exec)
+//
+// The handler receives { args, ui, cwd, exec } — `args` is the raw text after the
+// command name (`/standup since=yesterday` → args === "since=yesterday").
+
+import type {ModApi} from '@commandcode/harness';
+
+export default function (cmd: ModApi): void {
+	cmd.addCommand({
+		name: 'standup',
+		description: 'Summarize what changed today for standup',
+		argumentHint: '[since]',
+		handler: ({args}) => {
+			const since = args.trim() || 'this morning';
+			return {
+				prompt: `Summarize the git commits and working changes since ${since} as three standup bullets: done, in-progress, blockers.`,
+			};
+		},
+	});
+
+	// A second command that renders an info row instead of running the model.
+	cmd.addCommand({
+		name: 'where',
+		description: 'Print the current working directory',
+		handler: ({cwd}) => ({message: `You are in ${cwd}`}),
+	});
+}

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

@@ -0,0 +1,81 @@
+<!-- GENERATED FILE — do not edit. Source: packages/docs/src/app/mods/page.mdx. Regenerate: pnpm generate:knowledge -->
+
+# ModApi reference
+
+`export default function (cmd: ModApi)` — the factory. `ModFactory = (cmd: ModApi) => void | Promise<void>`. Every `add*` / `on` / `hooks` call returns `Disposable { dispose(): void }` — `.dispose()` undoes exactly that one registration (idempotent; a second call is a no-op). Disposables make a registration retractable and are the seam future hot-reload will recycle.
+
+## Fields
+
+| Member | Type | Notes |
+|---|---|---|
+| `cmd.name` | `string` | the mod's name (from filename / manifest) |
+| `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.sessions` | `ModSessionControls` | `compact` / `tree` / `leafId` / `navigateTree` / `setLabel` |
+
+## Registration (factory-time; each returns `Disposable`)
+
+| Method | Signature |
+|---|---|
+| `cmd.hooks` | `(hooks: ModHooks) => Disposable` |
+| `cmd.addTool` | `(tool: ToolModule) => Disposable` |
+| `cmd.addCommand` | `(command: {name; description?; argumentHint?; handler}) => Disposable` |
+| `cmd.addFlag` | `(name, {type: 'boolean'\|'string'; default?; description?}) => Disposable` |
+| `cmd.addProvider` | `(module: ProviderModule) => Disposable` |
+| `cmd.addRenderer` | `(customType: string, (data) => readonly string[]) => Disposable` |
+| `cmd.on` | `(event: AgentEventType \| 'session_start' \| 'session_shutdown', handler) => Disposable` |
+
+What each does:
+
+- `cmd.hooks(hooks)` — the mutating lifecycle hooks: the `AgentMod` surface (transformContext, beforeToolCall, afterToolCall, onTurnStart/End, appendSystemPrompt, shouldStopAfterTurn, prepareNextTurn, onRunEnd, **onStop**) **plus `transformInput`, `onSessionStart`, and `onSessionEnd`**. Multiple calls compose in order with mod-runner semantics (threading, chaining, any-true, later-wins). See [the hook contracts](./hooks-and-events.md#the-hook-contracts) for the full contract of each hook.
+- `cmd.addTool(toolModule)` — a `ToolModule` the model can call; same collision policy as `AgentMod.tools` (existing names win, collision emits `mod_error`). The tool's `run` receives `{input, runtime, signal}` and returns `{ok: true, content: [{type: 'text', text}]}` or `{ok: false, error}`. Mark `readOnly: true` when the tool never mutates (stays available in plan mode).
+- `cmd.addCommand({name, description, handler})` — a `/name` slash command. The handler returns data, not callbacks: `{prompt}` submits an automated turn, `{message}` renders an info row, nothing = pure side effect. It gets `{args, ui, cwd, exec}`. First registration of a name wins across mods.
+- `cmd.addFlag(name, {type, default})` / `cmd.getFlag(name)` — named options; values come from repeatable `--mod-option name=value` CLI flags (defaults apply otherwise).
+- `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.
+
+## Live methods (any time after the harness binds)
+
+| Method | Signature |
+|---|---|
+| `cmd.getFlag` | `(name) => boolean \| string \| undefined` |
+| `cmd.showEntry` | `(customType, data?) => void` |
+| `cmd.queueMessage` | `({content, deliverAs?: 'steer' \| 'follow-up'}) => void` |
+| `cmd.exec` | `({command, args?, cwd?, signal?}) => Promise<{stdout, stderr, code}>` |
+| `cmd.setSessionName` / `setModel` / `setEffort` | `(value) => void` (buffered pre-bind) |
+| `cmd.getAllTools` / `getActiveTools` | `() => readonly string[]` |
+| `cmd.setActiveTools` | `(names: readonly string[]) => void` |
+
+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`. The full dialog/status/widget 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).
+- `cmd.session` — the `ModSessionApi` persistence seam (appendCustomEntry / appendCustomMessageEntry / getCustomEntries), undefined until bound. See [ModContext.session — the mods' persistence surface](./hooks-and-events.md#mod-context-session-the-mods-persistence-surface).
+- `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.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`).
+
+## `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`.
+
+- `beforeToolCall` returns `{block?, input?, additionalContext?, terminate?}`.
+- `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?}`.
+- `onSessionStart`/`onSessionEnd` receive `{source}` / `{reason}`.
+
+The per-hook contracts, ordering guarantees, and error policy are in [the hook contracts](./hooks-and-events.md#the-hook-contracts).
+
+- `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.
+
+## `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).