command-code 1.0.0 → 1.1.0

package/dist/bundled/command-code-knowledge/reference/skills.md

@@ -2,7 +2,7 @@
 
 # Agent Skills
 
-Command Code supports Agent Skills — a lightweight, open standard for extending AI agents with specialized knowledge and workflows.
+Command Code supports Agent Skills - a lightweight, open standard for extending AI agents with specialized knowledge and workflows.
 
 ---
 
@@ -154,9 +154,9 @@ Command Code also discovers skills from `.agents/skills/` (project) and `~/.agen
 
 ### Extra locations
 
-Beyond the standard directories, you can point Command Code at any skills folder — a directory of skills, or a single skill directory containing `SKILL.md`.
+Beyond the standard directories, you can point Command Code at any skills folder - a directory of skills, or a single skill directory containing `SKILL.md`.
 
-**In settings** — add a `skills` array to `settings.json` (user-global `~/.commandcode/settings.json`, project `.commandcode/settings.json`, or `.commandcode/settings.local.json`):
+**In settings** - add a `skills` array to `settings.json` (user-global `~/.commandcode/settings.json`, project `.commandcode/settings.json`, or `.commandcode/settings.local.json`):
 
 ```json  theme={null}
 {
@@ -168,9 +168,9 @@ Beyond the standard directories, you can point Command Code at any skills folder
 }
 ```
 
-`~/` expands to your home directory; relative paths resolve against the project root (the git root, or the working directory outside a repo). Settings layers overwrite the array whole — the highest layer that defines `skills` wins. This is also the way to load a skills folder kept outside the standard locations like `~/.commandcode/skills` — a shared team drive, or a folder maintained for another Agent-Skills tool.
+`~/` expands to your home directory; relative paths resolve against the project root (the git root, or the working directory outside a repo). Settings layers overwrite the array whole - the highest layer that defines `skills` wins. This is also the way to load a skills folder kept outside the standard locations like `~/.commandcode/skills` - a shared team drive, or a folder maintained for another Agent-Skills tool.
 
-**At launch** — the `--skill` flag adds a location for one session and is repeatable; `--no-skills` skips discovery entirely (paths given via `--skill` still load):
+**At launch** - the `--skill` flag adds a location for one session and is repeatable; `--no-skills` skips discovery entirely (paths given via `--skill` still load):
 
 ```bash  theme={null}
 cmd --skill ./my-skill --skill ~/team/shared-skills
@@ -208,12 +208,12 @@ Skills, custom commands, and built-ins all share the same `/` menu. Skill locati
 
 Put simply: project-level always trumps user-level, and within the same level `.commandcode/` is favored over `.agents/`.
 
-When two locations provide the same skill name, the higher-precedence copy wins and every shadowed copy is reported as a **Duplicate names** warning in the `/skills` issues view and `cmd skills list --debug` — a shadowed skill is never dropped silently.
+When two locations provide the same skill name, the higher-precedence copy wins and every shadowed copy is reported as a **Duplicate names** warning in the `/skills` issues view and `cmd skills list --debug` - a shadowed skill is never dropped silently.
 
 **What happens on a collision.** When a skill name matches a built-in or a custom command:
 
-- Typing `/<name>` always resolves to the higher-precedence owner — the skill is not invoked.
-- The skill still appears in the `/` menu with a `[skill]` badge and a ` — shadowed by /<owner>` note, so you can see it exists and understand why `/<name>` runs the built-in command instead. Command Code prefers visibility with a marker over silently dropping the row.
+- Typing `/<name>` always resolves to the higher-precedence owner - the skill is not invoked.
+- The skill still appears in the `/` menu with a `[skill]` badge and a ` - shadowed by /<owner>` note, so you can see it exists and understand why `/<name>` runs the built-in command instead. Command Code prefers visibility with a marker over silently dropping the row.
 
 ---
 
@@ -233,12 +233,12 @@ This opens an interactive menu showing:
 - All project-level skills with `(project)` label
 - Skills from `.agents/skills/` (user or project) show a dim `[.agents]` badge
 - Use **arrow keys** to navigate
-- Press **Enter** to open any skill in your editor (or toggle it — see [Enable or disable skills](#enable-or-disable-skills))
+- Press **Enter** to open any skill in your editor (or toggle it - see [Enable or disable skills](#enable-or-disable-skills))
 - Press **Esc** to close and return to your session
 
 Every installed skill is also surfaced as a first-class slash command in the `/` menu. If you install a skill named `pr-desc`, you will see `/pr-desc`, sorted after built-ins and any custom commands in the slash menu.
 
-If a skill name collides with a built-in or a custom command, the skill still appears in the `/` menu with a `[skill]` badge and a ` — shadowed by /<owner>` note. Typing `/<name>` always resolves to the higher-precedence owner, not the skill. See [Selection priority](#selection-priority) above for the full order.
+If a skill name collides with a built-in or a custom command, the skill still appears in the `/` menu with a `[skill]` badge and a ` - shadowed by /<owner>` note. Typing `/<name>` always resolves to the higher-precedence owner, not the skill. See [Selection priority](#selection-priority) above for the full order.
 
 ---
 
@@ -266,13 +266,13 @@ Please follow /code-conv when writing the new module and /pr when opening the re
 
 ### 3. Inferred suggestion
 
-Command Code scans your prompt and suggests a matching skill when one clearly fits. Ordinary prompts keep working exactly like before — inferred suggestions just help you discover what is available.
+Command Code scans your prompt and suggests a matching skill when one clearly fits. Ordinary prompts keep working exactly like before - inferred suggestions just help you discover what is available.
 
 ---
 
 ## Create skills
 
-  The fastest way to create a skill is to ask Command Code to build it for you. The bundled `skill-builder` skill walks the agent through scoping the job, picking a valid name and location, writing spec-compliant frontmatter, and verifying the result loads — just describe the workflow you want captured, or invoke `/skill-builder` directly.
+  The fastest way to create a skill is to ask Command Code to build it for you. The bundled `skill-builder` skill walks the agent through scoping the job, picking a valid name and location, writing spec-compliant frontmatter, and verifying the result loads - just describe the workflow you want captured, or invoke `/skill-builder` directly.
 
 ### User-level skills
 
@@ -417,7 +417,7 @@ All endpoints require Bearer token in Authorization header except:
 EOF
 ```
 
-You can also install community skills directly from GitHub without manually creating files — see [`cmd skills add`](#cmd-skills-add) in the command reference.
+You can also install community skills directly from GitHub without manually creating files - see [`cmd skills add`](#cmd-skills-add) in the command reference.
 
 ---
 
@@ -500,7 +500,7 @@ Each skill must be in its own directory:
     └── SKILL.md
 ```
 
-Skills can also be grouped under intermediate folders — see [Nested skill folders](#nested-skill-folders).
+Skills can also be grouped under intermediate folders - see [Nested skill folders](#nested-skill-folders).
 
 ### Adding supporting files
 
@@ -614,7 +614,7 @@ Command Code additionally honors these extension fields. Several mirror the Agen
 | -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- |
 | `argument-hint`            | No       | Shown next to the skill in the `/` menu so you know what arguments it expects (e.g. `argument-hint: "<branch> [--draft]"`).             |
 | `when_to_use`              | No       | Extra trigger context (trigger phrases, example requests) appended to the description in the model-facing catalog, so auto-invocation matches on it too. |
-| `disable-model-invocation` | No       | When `true`, the skill is hidden from the model entirely — it never appears in the skill catalog and can't be auto-loaded. Only an explicit `/skill-name` invocation runs it. Use for destructive or highly contextual workflows. |
+| `disable-model-invocation` | No       | When `true`, the skill is hidden from the model entirely - it never appears in the skill catalog and can't be auto-loaded. Only an explicit `/skill-name` invocation runs it. Use for destructive or highly contextual workflows. |
 | `user-invocable`           | No       | When `false`, the skill stays model-invocable but is hidden from the `/` menu. Use for background knowledge that isn't a command you'd run by hand. |
 | `disallowed-tools`         | No       | Space-delimited list (or YAML array) of tools the skill should not use. Parsed and surfaced alongside `allowed-tools`.                  |
 | `arguments`                | No       | Ordered names for positional arguments (`arguments: issue branch`), enabling `$issue` / `$branch` placeholders in the body.             |
@@ -643,12 +643,12 @@ When you invoke a skill with `/skill-name <args>`, Command Code substitutes thes
 | `$ARGUMENTS` | All arguments as a single string. If the body has no placeholder, non-empty arguments are appended as an `ARGUMENTS: …` footer. |
 | `$ARGUMENTS[N]` / `${N}` | The Nth argument, 0-indexed (`$ARGUMENTS[0]` / `${0}` is the first). |
 | `$name` | A [declared named argument](#skills-specification). With `arguments: issue branch`, `$issue` is the first argument and `$branch` the second. Only declared names are replaced. |
-| `${COMMANDCODE_SKILL_DIR}` | Absolute path to the skill's own directory — use it to reference bundled `scripts/` or `references/` regardless of the working directory. |
+| `${COMMANDCODE_SKILL_DIR}` | Absolute path to the skill's own directory - use it to reference bundled `scripts/` or `references/` regardless of the working directory. |
 | `${COMMANDCODE_PROJECT_DIR}` | The project root (git root, otherwise the current directory). |
 | `${COMMANDCODE_SESSION_ID}` | The current session id, when available. |
 | `${COMMANDCODE_EFFORT}` | The active reasoning-effort level, when available. |
 
-The `${CLAUDE_SKILL_DIR}`, `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_SESSION_ID}`, and `${CLAUDE_EFFORT}` aliases resolve to the same values, so a skill written for Claude Code works unchanged. Only these known tokens are substituted — any other `${...}` (for example a literal `${HOME}`) is left untouched.
+The `${CLAUDE_SKILL_DIR}`, `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_SESSION_ID}`, and `${CLAUDE_EFFORT}` aliases resolve to the same values, so a skill written for Claude Code works unchanged. Only these known tokens are substituted - any other `${...}` (for example a literal `${HOME}`) is left untouched.
 
 All placeholders substitute in a single pass and arguments are inserted literally: argument text that itself looks like a placeholder (`$ARGUMENTS`, `$$`, a declared `$name`) lands as-is and is never expanded again.
 
@@ -656,8 +656,8 @@ All placeholders substitute in a single pass and arguments are inserted literall
 
 A skill body can run shell commands and inline their output before the body reaches the model, so the model reads live data instead of a command. Two forms are recognized:
 
-* **Inline** — `` !`git status --short` `` runs a single command. The `!` is only honored at the start of a line or directly after whitespace, so `KEY=!`cmd`` stays literal.
-* **Fenced** — a ` ```! ` code block runs a multi-line script:
+* **Inline** - `` !`git status --short` `` runs a single command. The `!` is only honored at the start of a line or directly after whitespace, so `KEY=!`cmd`` stays literal.
+* **Fenced** - a ` ```! ` code block runs a multi-line script:
 
 ````md
 ```!
@@ -666,9 +666,9 @@ git rev-parse --short HEAD
 ```
 ````
 
-Each placeholder is replaced with the command's output, once, left to right — output is never re-scanned for more placeholders. Commands run from the project directory, with the `COMMANDCODE_SKILL_DIR` / `COMMANDCODE_PROJECT_DIR` (and `CLAUDE_*` alias) values exported to their environment.
+Each placeholder is replaced with the command's output, once, left to right - output is never re-scanned for more placeholders. Commands run from the project directory, with the `COMMANDCODE_SKILL_DIR` / `COMMANDCODE_PROJECT_DIR` (and `CLAUDE_*` alias) values exported to their environment.
 
-To turn this off — so opening a skill never shells out — set `disableSkillShellExecution: true` in `settings.json`. Every placeholder is then replaced with `[shell command execution disabled by policy]` instead of running.
+To turn this off - so opening a skill never shells out - set `disableSkillShellExecution: true` in `settings.json`. Every placeholder is then replaced with `[shell command execution disabled by policy]` instead of running.
 
 ### Optional directories
 
@@ -788,9 +788,9 @@ cmd skills add https://github.com/remotion-dev/skills --skill remotion-best-prac
 
 **Multi-skill repos.** When a repo contains multiple skills and `--skill` is not specified, Command Code shows an interactive prompt to select which skills to install.
 
-**Name collisions.** Skill names share the `/` menu with built-in commands (`/clear`, `/help`, `/share`, `/rewind`, …) and with the custom commands in `.commandcode/commands/`. Built-ins and custom commands take precedence — typing `/<name>` resolves to the owner, not to the skill.
+**Name collisions.** Skill names share the `/` menu with built-in commands (`/clear`, `/help`, `/share`, `/rewind`, …) and with the custom commands in `.commandcode/commands/`. Built-ins and custom commands take precedence - typing `/<name>` resolves to the owner, not to the skill.
 
-If you install a skill whose name collides with one of those, `cmd skills add` still completes normally — nothing blocks the install. The skill then appears in the `/` menu with a `[skill]` badge and a `shadowed by /<owner>` note so you can see it exists, while `/<name>` continues to route to the higher-precedence owner. See [Selection priority](#selection-priority) for the full order.
+If you install a skill whose name collides with one of those, `cmd skills add` still completes normally - nothing blocks the install. The skill then appears in the `/` menu with a `[skill]` badge and a `shadowed by /<owner>` note so you can see it exists, while `/<name>` continues to route to the higher-precedence owner. See [Selection priority](#selection-priority) for the full order.
 
 ### cmd skills list
 
@@ -885,7 +885,7 @@ cmd skills remove frontend-design --global
 cmd skills remove my-skill --yes
 ```
 
-**Skill name rules.** Skill names must use lowercase letters, numbers, and hyphens only — no path separators, dots, or uppercase.
+**Skill name rules.** Skill names must use lowercase letters, numbers, and hyphens only - no path separators, dots, or uppercase.
 
 ---
 
@@ -925,13 +925,13 @@ Each skill should do one thing well:
 
 ### Pick a name that does not collide
 
-Skill names share the `/` menu with built-in commands like `/clear`, `/help`, `/share`, and `/rewind`, and with any custom commands you define in `.commandcode/commands/`. Those take precedence — typing `/<name>` routes to the owner and the skill renders with a `shadowed by` note next to its `[skill]` badge.
+Skill names share the `/` menu with built-in commands like `/clear`, `/help`, `/share`, and `/rewind`, and with any custom commands you define in `.commandcode/commands/`. Those take precedence - typing `/<name>` routes to the owner and the skill renders with a `shadowed by` note next to its `[skill]` badge.
 
 Prefer task-oriented names that are unlikely to overlap:
 
 **Safe:** `pr-desc`, `api-guidelines`, `release-notes`, `code-review`
 
-**Risky:** `clear`, `help`, `share`, `rewind` — these are built-in.
+**Risky:** `clear`, `help`, `share`, `rewind` - these are built-in.
 
 ### Use progressive disclosure
 
@@ -977,7 +977,7 @@ Command Code fully implements the [Agent Skills open standard](https://agentskil
 * **Shareable**: Publish for your team or community
 * **Auditable**: Plain text files anyone can read
 
-Validation follows the standard strictly — including the rule that a skill's `name` must match its directory name. Skills that break a rule are skipped with a categorized warning (visible in `/skills` and `cmd skills list --debug`) rather than failing the session, and a missing or empty `description` always prevents loading. Command Code's extension fields (`argument-hint`, `disable-model-invocation`, `model`) live alongside the standard fields and are ignored by other implementations; unknown frontmatter fields from other tools are ignored in turn.
+Validation follows the standard strictly - including the rule that a skill's `name` must match its directory name. Skills that break a rule are skipped with a categorized warning (visible in `/skills` and `cmd skills list --debug`) rather than failing the session, and a missing or empty `description` always prevents loading. Command Code's extension fields (`argument-hint`, `disable-model-invocation`, `model`) live alongside the standard fields and are ignored by other implementations; unknown frontmatter fields from other tools are ignored in turn.
 
 ---
 

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

@@ -2,7 +2,7 @@
 
 # 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.
+`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
 
@@ -29,13 +29,13 @@
 
 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.
+- `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)
 
@@ -51,16 +51,16 @@ What each does:
 
 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`).
+- `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)
+## `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`.
 
@@ -72,10 +72,10 @@ Details:
 
 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.
+- `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).
+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).

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

@@ -2,18 +2,18 @@
 
 # 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.
+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
+## 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,
+  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)
@@ -21,11 +21,11 @@ run({state, userInput?, config})
     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
+    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 —
+    ◆ 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
@@ -62,13 +62,13 @@ run({state, userInput?, config})
 
 ```bash
 for each tool_use:  → tool_queued {toolCallId, toolName, input}   ← ALWAYS the original input
-phase 1 — permissions (always sequential):
+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'):
+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
@@ -85,59 +85,59 @@ phase 2 — execution (sequential, or parallel when config.toolExecution='parall
 ### 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.
+- `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.
+- `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.
+- 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".
+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.
+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).
+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.
+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.
+- `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).
+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.
+- `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.
+- `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.
+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`
 
@@ -145,12 +145,12 @@ Fires once, awaited, after the loop exits and before the `run_end` event. `state
 
 ### `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.
+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.
+- 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
@@ -158,18 +158,18 @@ 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.'};
+		return {continue: true, reason: 'Tests are not green yet - keep going.'};
 	},
 };
 ```
 
-## `ModContext.session` — the mods' persistence surface
+## `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`.
+- **`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';
@@ -188,11 +188,11 @@ const mod = {
 };
 ```
 
-`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.
+`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`:
+`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
@@ -200,26 +200,26 @@ const next  = setModState({state, modId: 'my-mod', value: {...}}); // fresh Agen
 ```
 
 - **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.
+- 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.
+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 | — |
+| `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_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 |
@@ -234,10 +234,10 @@ One sync sink, fan out with `createEventBus`. Payloads are snapshots — never l
 | `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 | — |
+| `interrupted` | abort observed | - |
 | `run_error` | non-retryable failure | the raw `Error` |
 
-## Worked example — a write-quota mod
+## 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`.
 
@@ -248,7 +248,7 @@ import {getModState, setModState} from '@commandcode/harness';
 const MOD_ID = 'write-quota';
 
 interface WriteQuotaState {
-	readonly writesThisSession: number; // durable — survives resume
+	readonly writesThisSession: number; // durable - survives resume
 }
 
 export function createWriteQuotaMod(options: {
@@ -257,7 +257,7 @@ export function createWriteQuotaMod(options: {
 	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).
+	// (beforeToolCall cannot return state - see modState conventions).
 	let writesThisTurn = 0;
 
 	return {
@@ -268,7 +268,7 @@ export function createWriteQuotaMod(options: {
 			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.
+				// core emits tool_hook_blocked. The run continues - the model adapts.
 				return {
 					block: true,
 					additionalContext: `Writes outside ${options.allowedRoot} are not allowed.`,
@@ -305,4 +305,4 @@ export function createWriteQuotaMod(options: {
 }
 ```
 
-Wire it as a loadable mod (`cmd.hooks({...})` with the same handlers) — or, when embedding the harness, `createHarness({..., mods: [createWriteQuotaMod({...})]})`.
+Wire it as a loadable mod (`cmd.hooks({...})` with the same handlers) - or, when embedding the harness, `createHarness({..., mods: [createWriteQuotaMod({...})]})`.