command-code 1.0.0 → 1.1.0

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

@@ -2,7 +2,9 @@
 
 # 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.
+> **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.
 
 A loadable mod IS an `AgentMod` once loaded; the mod host just builds it from a factory file instead of a code import:
 
@@ -22,7 +24,7 @@ addRenderer      ──►  custom feed entries (showEntry → styled lines in t
 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.
+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.
 
 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.
 
@@ -36,7 +38,7 @@ Create `~/.commandcode/mods/review-guard.ts`:
 import type {ModApi} from '@commandcode/harness';
 
 export default function (cmd: ModApi) {
-	// Block dangerous writes (a mutating hook — see the hooks catalog).
+	// Block dangerous writes (a mutating hook - see the hooks catalog).
 	cmd.hooks({
 		beforeToolCall: async ({toolName, input}) => {
 			if (toolName !== 'shell_command') return undefined;
@@ -67,7 +69,7 @@ export default function (cmd: ModApi) {
 		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).
+	// Observe the event stream (never mutates - mutation is what hooks are for).
 	cmd.on('turn_end', () => cmd.ui.notify('turn finished'));
 }
 ```
@@ -98,8 +100,8 @@ Dot-entries and `node_modules` are never scanned (the package registry lives und
 
 ## 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).
+- **`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).
 
@@ -107,28 +109,28 @@ If you find yourself wanting an `on` handler to stop a tool, you want a hook ins
 
 ## 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:
+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.
+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.
+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 |
+| `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 |
+| `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 |
@@ -139,9 +141,9 @@ Runnable, single-file example mods ship with Command Code inside the bundled `mo
 ## 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.
+- **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.

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

@@ -2,7 +2,7 @@
 
 # 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.
+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
 
@@ -16,11 +16,11 @@ cmd mods update                             # reinstall missing, reconcile pinne
 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`.
+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):
+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
 {
@@ -45,7 +45,7 @@ A `mods.sources` entry can be the object form to load only part of a package:
 }
 ```
 
-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.
+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
 
@@ -57,7 +57,7 @@ Works for discovered files, installed packages, and the disable-able built-ins (
 
 ## 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; 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.
+- **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

@@ -2,16 +2,16 @@
 
 # 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.
+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.
+- `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.
+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({
@@ -23,11 +23,11 @@ const proceed = await cmd.ui.confirm({
 
 ## 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).
+`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.
+`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;
@@ -43,8 +43,8 @@ cmd.on('tool_completed', () => {
 
 ## 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.
+- `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.
 
@@ -60,4 +60,4 @@ Rendering is deliberately **line-based, not component-based**: mods return style
 | `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).
+The `status-and-widgets.ts` bundled example exercises all of this in one file - see [Runnable examples](./overview.md#runnable-examples).

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

@@ -2,7 +2,7 @@
 
 # Verify a mod
 
-A mod that fails to import, exports no factory, or throws in its factory becomes a **warning — never a crashed session**. That safety also means a broken mod can fail silently if you never check. This section is the verification loop: load it, list it, exercise it, reload it.
+A mod that fails to import, exports no factory, or throws in its factory becomes a **warning - never a crashed session**. That safety also means a broken mod can fail silently if you never check. This section is the verification loop: load it, list it, exercise it, reload it.
 
 ## 1. Load it without installing
 
@@ -10,7 +10,7 @@ A mod that fails to import, exports no factory, or throws in its factory becomes
 cmd --mod ./your-mod.ts
 ```
 
-`--mod` is repeatable, loads ahead of installed mods, and wins name collisions — the fastest try-it loop. No build step: jiti compiles the TypeScript at load.
+`--mod` is repeatable, loads ahead of installed mods, and wins name collisions - the fastest try-it loop. No build step: jiti compiles the TypeScript at load.
 
 ## 2. Confirm it registered
 
@@ -22,12 +22,12 @@ Your mod must appear, with no load warnings. If it does not appear, the warning
 
 ## 3. Exercise every surface it registers
 
-- **Slash command** — type `/` in the chat input: the command must appear in autocomplete with its description. Run it; `{message}` renders an info row, `{prompt}` starts an automated turn.
-- **Tool** — ask the model to use it by name ("call count_todos"). The tool call renders in the feed like any built-in.
-- **Hook** — trigger the behavior it guards (for a `beforeToolCall` blocker, ask for the blocked action and watch the block reason land as the tool result).
-- **Input interception** — type the pattern `transformInput` matches and confirm the rewrite/consume happened.
-- **Status / widget** — the footer segment appears under the input panel; the widget renders around the editor.
-- **Renderer** — `cmd.showEntry` rows render styled; an unregistered type pretty-prints as JSON.
+- **Slash command** - type `/` in the chat input: the command must appear in autocomplete with its description. Run it; `{message}` renders an info row, `{prompt}` starts an automated turn.
+- **Tool** - ask the model to use it by name ("call count_todos"). The tool call renders in the feed like any built-in.
+- **Hook** - trigger the behavior it guards (for a `beforeToolCall` blocker, ask for the blocked action and watch the block reason land as the tool result).
+- **Input interception** - type the pattern `transformInput` matches and confirm the rewrite/consume happened.
+- **Status / widget** - the footer segment appears under the input panel; the widget renders around the editor.
+- **Renderer** - `cmd.showEntry` rows render styled; an unregistered type pretty-prints as JSON.
 
 ### Test: block-dangerous-commands guards rm -rf
 
@@ -38,12 +38,12 @@ Run rm -rf /tmp/scratch-dir
 Expected result:
 
 - ✅ The mod's confirm dialog appears before the shell command runs
-- ✅ Declining blocks the tool — the model sees the block reason and adapts
+- ✅ Declining blocks the tool - the model sees the block reason and adapts
 - ❌ No `tool_running` fires for the blocked call
 
 ## 4. Iterate with /reload
 
-Mods load once per process. After editing the file, run `/reload` — it restarts Command Code, resumes the session, and re-discovers and re-imports every mod (jiti caches nothing between loads).
+Mods load once per process. After editing the file, run `/reload` - it restarts Command Code, resumes the session, and re-discovers and re-imports every mod (jiti caches nothing between loads).
 
 ## 5. Headless check (CI)
 
@@ -55,4 +55,4 @@ Print mode loads user-scope and `--mod` mods with the UI bridge degraded to dete
 
 ## Working from the bundled examples
 
-Command Code ships runnable single-file examples inside the bundled `mod-builder` skill — each one loads through the real mod loader in CI on every test run, so copying one is copying something proven to load. In the Command Code repo itself, the same validation is a vitest suite (`packages/harness/src/mod-host/__tests__/examples.test.ts`); if you are contributing an example, that test must stay green.
+Command Code ships runnable single-file examples inside the bundled `mod-builder` skill - each one loads through the real mod loader in CI on every test run, so copying one is copying something proven to load. In the Command Code repo itself, the same validation is a vitest suite (`packages/harness/src/mod-host/__tests__/examples.test.ts`); if you are contributing an example, that test must stay green.