@cruxy/cli 0.13.0 → 0.16.0

package/dist/agent/loop.d.ts

@@ -1,8 +1,15 @@
 import type { Message, Provider, Usage } from "@cruxy/sdk";
 import type { CruxyConfig } from "../config/index.js";
+import type { HookEvent } from "../hooks/index.js";
 import type { StreamRenderer } from "../render/index.js";
 import type { ToolContext } from "../tools/index.js";
 import { ToolRegistry } from "../tools/index.js";
+/** The lifecycle-hook firing seam (C.19). Structural so the loop stays
+ * decoupled from the concrete `HookRunner`. `fire` resolves when hooks pass (or
+ * advisory ones fail) and throws `CRUXY_E_HOOK_FAILED` on a blocking failure. */
+export interface LifecycleHookRunner {
+    fire(event: HookEvent, ctx: ToolContext): Promise<void>;
+}
 export interface RunAgentArgs {
     /**
      * The full running conversation. The caller owns history and must append the
@@ -43,6 +50,13 @@ export interface RunAgentArgs {
      * histories stay coherent — overshoot is bounded by one turn.
      */
     budget?: LoopBudget;
+    /**
+     * Lifecycle hooks (C.19). When set, `before-tool` fires before each tool call
+     * (a blocking failure fails the call closed — the tool does NOT run), and
+     * `after-tool` / `on-file-change` fire after. Omitted for subagents and the
+     * no-hooks path, so their tools never fire hooks.
+     */
+    hooks?: LifecycleHookRunner;
 }
 /**
  * The budget seam for {@link runAgent}: implementations track their own caps

package/dist/agent/loop.js

@@ -1,5 +1,8 @@
-import { providerUnsupported } from "../errors/index.js";
+import { CruxyError, providerUnsupported } from "../errors/index.js";
 import { buildSystemPrompt } from "./prompts.js";
+/** Tools whose successful call is a file change (drives the `on-file-change`
+ * hook). Kept in sync with the file-mutating tool set. */
+const FILE_MUTATING_TOOLS = new Set(["write_file", "edit_file", "apply_patch"]);
 /**
  * Drive the model/tool loop over an existing conversation. Streams each turn,
  * renders assistant text, reassembles tool calls, executes them, feeds the
@@ -146,9 +149,26 @@ async function driveLoop(args, renderer) {
             // long calls), end commits the ✓/✗ trail note. Same information as the
             // old status/note pair, now typed and duration-aware.
             renderer?.toolLifecycle({ event: "start", label });
+            // before-tool (C.19): a blocking pre-check that fails aborts THIS tool
+            // fail-closed — the tool never runs; the model is told via an error
+            // result. The hook command itself went through the U.3 gate + C.16 sandbox
+            // (same path as run_command), so a hook is never an approval bypass.
+            const blocked = await fireBeforeTool(args.hooks, ctx, call.id);
+            if (blocked) {
+                renderer?.toolLifecycle({ event: "end", label, ok: false });
+                toolResults.push(blocked);
+                continue;
+            }
             const result = await runToolCall(call, registry, ctx);
             renderer?.toolLifecycle({ event: "end", label, ok: !result.is_error });
             toolResults.push(result);
+            // after-tool + on-file-change (C.19): fire once the action is done.
+            // Advisory by default (report, don't rewrite history); a hook explicitly
+            // marked blocking here throws and aborts the run.
+            await args.hooks?.fire("after-tool", ctx);
+            if (!result.is_error && FILE_MUTATING_TOOLS.has(call.name)) {
+                await args.hooks?.fire("on-file-change", ctx);
+            }
         }
         messages.push({ role: "user", content: toolResults });
     }
@@ -192,6 +212,32 @@ function describeToolCall(call) {
  * results rather than thrown exceptions, so the model can read the error and
  * self-correct on the next turn.
  */
+/**
+ * Fire `before-tool` hooks. Returns `null` to proceed, or a ready-made error
+ * {@link ToolResultBlock} when a blocking hook failed — the tool is then skipped
+ * (fail-closed) and the model is told, carrying the CRUXY_E_HOOK_FAILED code so
+ * the failure is greppable. A non-blocking (advisory) hook failure never reaches
+ * here — the runner reports it and resolves normally.
+ */
+async function fireBeforeTool(hooks, ctx, toolUseId) {
+    if (!hooks)
+        return null;
+    try {
+        await hooks.fire("before-tool", ctx);
+        return null;
+    }
+    catch (err) {
+        const content = CruxyError.is(err)
+            ? `${err.code}: ${err.title}${err.cause ? ` — ${err.cause}` : ""}`
+            : `before-tool hook failed: ${err.message}`;
+        return {
+            type: "tool_result",
+            tool_use_id: toolUseId,
+            content,
+            is_error: true,
+        };
+    }
+}
 async function runToolCall(call, registry, ctx) {
     const tool = registry.get(call.name);
     if (!tool) {

package/dist/agent/session.d.ts

@@ -3,7 +3,7 @@ import type { CruxyConfig } from "../config/index.js";
 import type { StreamRenderer } from "../render/index.js";
 import type { ToolContext } from "../tools/index.js";
 import type { ToolRegistry } from "../tools/index.js";
-import { type AgentResult } from "./loop.js";
+import { type AgentResult, type LifecycleHookRunner } from "./loop.js";
 /**
  * Plan-mode turn runner (C.31), injected so the agent package doesn't depend on
  * the plan package. When plan mode is on, `send` delegates the whole turn to
@@ -35,6 +35,13 @@ export interface SessionArgs {
     planMode?: boolean;
     /** The plan-mode turn runner; required for plan mode to actually engage. */
     planRunner?: PlanRunner;
+    /**
+     * Lifecycle hooks (C.19). When set, `before-run` fires before each turn (a
+     * blocking failure — including an untrusted project — aborts the turn) and
+     * `after-run` fires after; the same runner is threaded into the agent loop for
+     * `before-tool`/`after-tool`/`on-file-change`.
+     */
+    hooks?: LifecycleHookRunner;
 }
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic
@@ -65,6 +72,9 @@ export declare class Session {
     /** Mutable so `/plan` can toggle plan mode mid-session. */
     private planMode;
     constructor(args: SessionArgs);
+    /** The ambient tool capabilities (gate + sandbox + cwd/config). Exposed so a
+     * shell-bound custom slash command (C.19) runs through the SAME gated path. */
+    get toolContext(): ToolContext;
     /** Whether plan mode is currently on. */
     getPlanMode(): boolean;
     /**

package/dist/agent/session.js

@@ -1,5 +1,5 @@
 import { loadProjectInstructions } from "../config/index.js";
-import { runAgent } from "./loop.js";
+import { runAgent, } from "./loop.js";
 import { SUMMARY_SYSTEM, COMPACTION_MARKER } from "./prompts.js";
 /**
  * Estimate the token footprint of a message list with a cheap chars/4 heuristic
@@ -58,6 +58,11 @@ export class Session {
         // state where the plan directive is injected but nothing orchestrates it).
         this.planMode = (args.planMode ?? false) && args.planRunner !== undefined;
     }
+    /** The ambient tool capabilities (gate + sandbox + cwd/config). Exposed so a
+     * shell-bound custom slash command (C.19) runs through the SAME gated path. */
+    get toolContext() {
+        return this.args.ctx;
+    }
     /** Whether plan mode is currently on. */
     getPlanMode() {
         return this.planMode;
@@ -82,6 +87,10 @@ export class Session {
         this.messages.push({ role: "user", content: userPrompt });
         // Compact *before* the agent call so the turn runs against a bounded history.
         await this.maybeCompact();
+        // before-run (C.19): a blocking pre-run hook — or an untrusted project's
+        // hooks — throws here and aborts the turn before the model is engaged
+        // (fail-closed). No-op when hooks are disabled or none are registered.
+        await this.args.hooks?.fire("before-run", this.args.ctx);
         // Plan mode (C.31) delegates the whole turn to the injected runner: propose a
         // plan, approve/revise, then execute step-by-step. Falls back to the normal
         // single-shot loop when off or unwired, so existing behavior is untouched.
@@ -102,6 +111,10 @@ export class Session {
         this.messages = result.messages;
         this.usage.input_tokens += result.usage.input_tokens;
         this.usage.output_tokens += result.usage.output_tokens;
+        // after-run (C.19): advisory by default (a blocking after-run hook throws
+        // and surfaces at the boundary). The turn already completed and its history
+        // is adopted above — an advisory failure never rewrites it.
+        await this.args.hooks?.fire("after-run", this.args.ctx);
         return result;
     }
     /**

package/dist/approval/prompt.js

@@ -37,16 +37,30 @@ export async function promptForApproval(request, io) {
 export function render(request, color) {
     const t = themeForColor(color);
     const destructive = request.tier === "destructive";
-    // The risk mark carries meaning by shape (`!` vs `?`), not by color alone —
-    // so it survives NO_COLOR (U.1 accessibility groundwork).
+    // Risk survives all three degradations (U.11): the mark carries it by *shape*
+    // (`!` vs `?`) for NO_COLOR, and the label carries it by *word*
+    // (`(destructive)` / `(mutate)` / `(read)`) — never by hue alone, and legible
+    // to a screen reader that would otherwise read `!` as "exclamation mark".
     const mark = destructive ? t.danger(t.strong("!")) : t.warning("?");
-    const label = destructive ? t.danger(t.strong(" (destructive)")) : "";
+    const label = tierLabel(request.tier, t);
     const lines = [];
     lines.push(`${mark} cruxy wants to ${t.strong(request.summary)}${label}`);
     lines.push(detail(request, t));
     lines.push(choices(request.scope, t));
     return lines.filter((l) => l !== "").join("\n") + " ";
 }
+/** The worded risk tag, colored by tier — always present, so meaning never
+ * rides on the `!`/`?` shape or its color alone. */
+function tierLabel(tier, t) {
+    switch (tier) {
+        case "destructive":
+            return t.danger(t.strong(" (destructive)"));
+        case "mutate":
+            return t.warning(" (mutate)");
+        case "read":
+            return t.muted(" (read)");
+    }
+}
 /** The action detail: a diff for file actions, the command + cwd for shell/test. */
 function detail(request, t) {
     if (request.action.kind === "shell" || request.action.kind === "test") {

package/dist/brand/index.d.ts

@@ -0,0 +1 @@
+export { CANONICAL_TERMS, FORBIDDEN_MODEL_NAMES, FORBIDDEN_TERMS, MODEL_TIERS, PRODUCT_MASTHEAD, PRODUCT_NAME, PRODUCT_TAGLINE, scanForbidden, type ForbiddenTerm, type LexiconViolation, } from "./voice.js";

package/dist/brand/index.js

@@ -0,0 +1 @@
+export { CANONICAL_TERMS, FORBIDDEN_MODEL_NAMES, FORBIDDEN_TERMS, MODEL_TIERS, PRODUCT_MASTHEAD, PRODUCT_NAME, PRODUCT_TAGLINE, scanForbidden, } from "./voice.js";

package/dist/brand/voice.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The cruxy brand voice (U.8) — a tiny living document, enforced by a test, not
+ * vibes. It centralizes the product name/tagline, the canonical lexicon, and the
+ * forbidden set (deprecated synonyms + the base-model gag) so every user-facing
+ * surface reads as one product. Presentation/copy only — nothing here changes
+ * behavior; the {@link scanForbidden} helper backs the lexicon test.
+ *
+ * Voice, in one breath: concise, direct, second-person for guidance,
+ * lowercase-leaning for status, no marketing fluff, no exclamation-spam. The
+ * product name is ALWAYS lowercase `cruxy`.
+ */
+/** The product name — always lowercase, in running text, banners, and help. */
+export declare const PRODUCT_NAME = "cruxy";
+/** The one-line tagline (mirrors package.json's description). */
+export declare const PRODUCT_TAGLINE = "an agentic coding CLI";
+/** The `cruxy --help` / banner masthead: `cruxy — an agentic coding CLI`. */
+export declare const PRODUCT_MASTHEAD = "cruxy \u2014 an agentic coding CLI";
+/**
+ * The ONLY model names cruxy ever shows a user. The upstream model powering a
+ * tier is never named — a hard rule asserted by the lexicon test.
+ */
+export declare const MODEL_TIERS: readonly ["kavi", "vaani", "mira"];
+/**
+ * The canonical term for each concept — the words every surface must use.
+ * Documented here so the lexicon is reviewable in one place; the forbidden
+ * synonyms below are what the test actually enforces.
+ */
+export declare const CANONICAL_TERMS: {
+    readonly product: "cruxy";
+    readonly backend: "gateway";
+    readonly extension: "skill";
+    readonly lifecycleHook: "hook";
+    readonly undoUnit: "checkpoint";
+    readonly isolation: "sandbox";
+    readonly secret: "API key";
+    readonly pullRequest: "pull request";
+    readonly permission: "approval";
+};
+/** One deprecated/off-voice term the copy must not use, and what to use instead. */
+export interface ForbiddenTerm {
+    /** Matches the forbidden term (word-bounded, case-insensitive). */
+    pattern: RegExp;
+    /** The forbidden term, for the failure message. */
+    term: string;
+    /** The canonical term to use instead. */
+    use: string;
+}
+/**
+ * Deprecated synonyms banned from user-facing copy. Scoped to the curated
+ * surfaces the lexicon test scans (command descriptions, error output, brand +
+ * onboarding constants) — NOT a raw source grep — so legitimate internal uses
+ * (`mcpServers` config key, docker `.Server.Version`, code comments) never
+ * false-trip, while every string a user reads is covered.
+ */
+export declare const FORBIDDEN_TERMS: readonly ForbiddenTerm[];
+/**
+ * Upstream model names — the base-model gag. None may appear in user-facing
+ * copy; only {@link MODEL_TIERS} ever do. `anthropic`/`openai` are deliberately
+ * absent: they are real bring-your-own-provider config values, not model names.
+ */
+export declare const FORBIDDEN_MODEL_NAMES: RegExp;
+/** One lexicon violation found in a scanned string. */
+export interface LexiconViolation {
+    /** The forbidden term (or "model-name" for a gag violation). */
+    term: string;
+    /** The canonical replacement, when the term is a deprecated synonym. */
+    use?: string;
+}
+/**
+ * Scan one user-facing string for lexicon violations — deprecated synonyms and
+ * upstream model names. Returns every violation (empty ⇒ on-voice). Pure; the
+ * lexicon test runs it over the curated surfaces.
+ */
+export declare function scanForbidden(text: string): LexiconViolation[];

package/dist/brand/voice.js

@@ -0,0 +1,73 @@
+/**
+ * The cruxy brand voice (U.8) — a tiny living document, enforced by a test, not
+ * vibes. It centralizes the product name/tagline, the canonical lexicon, and the
+ * forbidden set (deprecated synonyms + the base-model gag) so every user-facing
+ * surface reads as one product. Presentation/copy only — nothing here changes
+ * behavior; the {@link scanForbidden} helper backs the lexicon test.
+ *
+ * Voice, in one breath: concise, direct, second-person for guidance,
+ * lowercase-leaning for status, no marketing fluff, no exclamation-spam. The
+ * product name is ALWAYS lowercase `cruxy`.
+ */
+/** The product name — always lowercase, in running text, banners, and help. */
+export const PRODUCT_NAME = "cruxy";
+/** The one-line tagline (mirrors package.json's description). */
+export const PRODUCT_TAGLINE = "an agentic coding CLI";
+/** The `cruxy --help` / banner masthead: `cruxy — an agentic coding CLI`. */
+export const PRODUCT_MASTHEAD = `${PRODUCT_NAME} — ${PRODUCT_TAGLINE}`;
+/**
+ * The ONLY model names cruxy ever shows a user. The upstream model powering a
+ * tier is never named — a hard rule asserted by the lexicon test.
+ */
+export const MODEL_TIERS = ["kavi", "vaani", "mira"];
+/**
+ * The canonical term for each concept — the words every surface must use.
+ * Documented here so the lexicon is reviewable in one place; the forbidden
+ * synonyms below are what the test actually enforces.
+ */
+export const CANONICAL_TERMS = {
+    product: "cruxy",
+    backend: "gateway",
+    extension: "skill",
+    lifecycleHook: "hook",
+    undoUnit: "checkpoint",
+    isolation: "sandbox",
+    secret: "API key",
+    pullRequest: "pull request",
+    permission: "approval",
+};
+/**
+ * Deprecated synonyms banned from user-facing copy. Scoped to the curated
+ * surfaces the lexicon test scans (command descriptions, error output, brand +
+ * onboarding constants) — NOT a raw source grep — so legitimate internal uses
+ * (`mcpServers` config key, docker `.Server.Version`, code comments) never
+ * false-trip, while every string a user reads is covered.
+ */
+export const FORBIDDEN_TERMS = [
+    { pattern: /\bplug-?ins?\b/i, term: "plugin", use: "skill" },
+    { pattern: /\btriggers?\b/i, term: "trigger", use: "hook" },
+    { pattern: /\bservers?\b/i, term: "server", use: "gateway" },
+    { pattern: /\bcruxy[- ]code\b/i, term: "cruxy-code", use: "cruxy" },
+];
+/**
+ * Upstream model names — the base-model gag. None may appear in user-facing
+ * copy; only {@link MODEL_TIERS} ever do. `anthropic`/`openai` are deliberately
+ * absent: they are real bring-your-own-provider config values, not model names.
+ */
+export const FORBIDDEN_MODEL_NAMES = /\b(claude|sonnet|opus|haiku|gpt-?\d|gemini|llama|mistral)\b/i;
+/**
+ * Scan one user-facing string for lexicon violations — deprecated synonyms and
+ * upstream model names. Returns every violation (empty ⇒ on-voice). Pure; the
+ * lexicon test runs it over the curated surfaces.
+ */
+export function scanForbidden(text) {
+    const violations = [];
+    for (const { pattern, term, use } of FORBIDDEN_TERMS) {
+        if (pattern.test(text))
+            violations.push({ term, use });
+    }
+    const model = text.match(FORBIDDEN_MODEL_NAMES);
+    if (model)
+        violations.push({ term: `model-name "${model[0]}"` });
+    return violations;
+}

package/dist/cli/commands/checkpoint.js

@@ -10,7 +10,7 @@ import { logger } from "../../utils/logger.js";
  * this command only lists.
  */
 export function checkpointCommand() {
-    const cmd = new Command("checkpoint").description("working-tree checkpoints — the undo units behind `cruxy rollback`");
+    const cmd = new Command("checkpoint").description("inspect working-tree checkpoints (the undo units behind rollback)");
     cmd
         .command("list")
         .description("list saved checkpoints, newest first")

package/dist/cli/commands/hooks.d.ts

@@ -0,0 +1,8 @@
+import { Command } from "commander";
+/**
+ * `cruxy hooks` — inspect and trust hooks + custom slash commands (C.19).
+ * `list` shows the resolved catalog (including which project hooks are trusted
+ * and any malformed definitions); `trust <path>` records the explicit,
+ * reviewed decision to run a project's hooks, bound to their current fingerprint.
+ */
+export declare function hooksCommand(): Command;

package/dist/cli/commands/hooks.js

@@ -0,0 +1,83 @@
+import path from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../../config/index.js";
+import { shouldUseColor } from "../../errors/index.js";
+import { themeForColor } from "../../theme/index.js";
+import { defaultHookSources, fileTrustStore, fingerprintHooks, isTrusted, loadHookCatalog, } from "../../hooks/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy hooks` — inspect and trust hooks + custom slash commands (C.19).
+ * `list` shows the resolved catalog (including which project hooks are trusted
+ * and any malformed definitions); `trust <path>` records the explicit,
+ * reviewed decision to run a project's hooks, bound to their current fingerprint.
+ */
+export function hooksCommand() {
+    const cmd = new Command("hooks").description("inspect and trust hooks and custom slash commands");
+    cmd
+        .command("list", { isDefault: true })
+        .description("list configured hooks, custom commands, and load errors")
+        .action(async () => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        const cwd = process.cwd();
+        const catalog = await loadHookCatalog(defaultHookSources(cwd));
+        logger.print(`${t.strong("hooks:")} ${config.hooks.enabled ? t.success("enabled") : t.warning("disabled (hooks.enabled = false)")}`);
+        const projectHooks = catalog.hooks.filter((h) => h.source === "project");
+        if (projectHooks.length > 0) {
+            const trusted = isTrusted(fileTrustStore(), cwd, fingerprintHooks(projectHooks));
+            logger.print(`${t.strong("project trust:")} ${trusted ? t.success("trusted") : t.danger("NOT trusted — run `cruxy hooks trust .`")}`);
+        }
+        printHooks(catalog.hooks, t);
+        printCommands(catalog.commands, t);
+        printErrors(catalog.errors, t);
+    });
+    cmd
+        .command("trust <path>")
+        .description("trust a project's hooks after reviewing them (records the decision)")
+        .action(async (target) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const root = path.resolve(target);
+        const catalog = await loadHookCatalog(defaultHookSources(root));
+        const projectHooks = catalog.hooks.filter((h) => h.source === "project");
+        if (projectHooks.length === 0) {
+            logger.print(t.muted(`no project hooks found under ${root}`));
+            return;
+        }
+        logger.print(t.strong(`trusting ${projectHooks.length} project hook(s):`));
+        printHooks(projectHooks, t);
+        fileTrustStore().record({
+            root,
+            fingerprint: fingerprintHooks(projectHooks),
+            at: new Date().toISOString(),
+        });
+        logger.print(`${t.success("trusted")} — these hooks may now run for ${root}. ` +
+            t.muted("changing any of them will require re-trusting."));
+    });
+    return cmd;
+}
+function printHooks(hooks, t) {
+    if (hooks.length === 0) {
+        logger.print(t.muted("  no hooks configured"));
+        return;
+    }
+    for (const h of hooks) {
+        const policy = h.blocking ? t.danger("blocking") : t.muted("advisory");
+        logger.print(`  ${t.muted(`[${h.source}]`)} ${t.strong(h.name)} ${t.muted(h.event)} ${policy}\n      ${t.muted("$")} ${h.command}`);
+    }
+}
+function printCommands(commands, t) {
+    if (commands.length === 0)
+        return;
+    logger.print(`\n${t.heading("custom slash commands:")}`);
+    for (const c of commands) {
+        logger.print(`  ${t.muted(`[${c.source}]`)} ${t.strong(`/${c.name}`)} ${t.muted(`(${c.kind})`)} — ${c.description}`);
+    }
+}
+function printErrors(errors, t) {
+    if (errors.length === 0)
+        return;
+    logger.print(`\n${t.danger(t.heading("malformed (excluded, never run):"))}`);
+    for (const e of errors) {
+        logger.print(`  ${t.muted(`[${e.source}]`)} ${t.strong(e.name)} — ${e.message}`);
+    }
+}

package/dist/cli/commands/init.js

@@ -12,7 +12,7 @@ import { runFirstWinTask } from "../onboard.js";
  */
 export function initCommand() {
     return new Command("init")
-        .description("set up cruxy in this project (key + CRUXY.md + a first run)")
+        .description("set up cruxy in this project (API key, CRUXY.md, and a first run)")
         .action(async () => {
         const t = themeForColor(shouldUseColor(process.stdout));
         if (!process.stdin.isTTY) {

package/dist/cli/commands/pr.js

@@ -14,7 +14,7 @@ import { createForgeProvider, createPrService, generateWithLlm, loadCommitGuidan
  */
 export function prCommand() {
     return new Command("pr")
-        .description("open a pull request from the current changes (generated + gated)")
+        .description("open a pull request from the current changes (generated and gated)")
         .option("-b, --base <branch>", "base branch to merge into")
         .option("-t, --title <title>", "PR title (conventional-commit subject)")
         .option("--body <body>", "PR body")

package/dist/cli/commands/rollback.js

@@ -50,7 +50,7 @@ async function pickCheckpoint(service) {
  */
 export function rollbackCommand() {
     return new Command("rollback")
-        .description("restore the working tree to a checkpoint, undoing an agent run's file changes")
+        .description("restore the working tree to a checkpoint, undoing a run's file changes")
         .argument("[id]", "checkpoint id (defaults to the most recent)")
         .action(async (id) => {
         const interactive = Boolean(process.stdin.isTTY);

package/dist/cli/commands/run.js

@@ -6,12 +6,13 @@ import { createRenderer } from "../../render/index.js";
 import { themeForColor } from "../../theme/index.js";
 import { CheckpointService } from "../../checkpoint/index.js";
 import { SandboxService } from "../../sandbox/index.js";
+import { buildHooksService } from "../../hooks/index.js";
 import { runInteractive } from "../repl.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 export function runCommand() {
     return new Command("run")
-        .description("run cruxy on a prompt (one-shot), or with no prompt for an interactive session")
+        .description("run a task once, or start an interactive session")
         .argument("[prompt...]", "the task for cruxy to perform (omit for interactive)")
         .option("--plan", "plan mode: propose a step-by-step plan for approval before executing")
         .option("--sandbox", "run shell + test commands inside an isolated container (fails loud if no runtime)")
@@ -79,9 +80,18 @@ export function runCommand() {
         if (sandbox) {
             logger.info(t.muted(`sandbox: ${sandbox.runtimeName} (network ${config.sandbox.network})`));
         }
-        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox);
+        // Hooks + custom slash commands (C.19). Built once per run: loads the
+        // layered catalog and yields the lifecycle runner (threaded into the
+        // session) + the resolved custom slash commands (given to the REPL).
+        const hooksService = await buildHooksService({
+            cwd: process.cwd(),
+            config,
+            interactive: Boolean(process.stdin.isTTY),
+            logger,
+        });
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksService.runner);
         if (interactive) {
-            await runInteractive(session, undefined, renderer, checkpoints);
+            await runInteractive(session, undefined, renderer, checkpoints, hooksService.commands);
             return;
         }
         checkpoints?.beginRun(prompt);

package/dist/cli/commands/skills.js

@@ -33,9 +33,9 @@ export function skillsCommand() {
             resetSkillServices();
             return;
         }
-        logger.print(`\n${t.strong("sources")} ${t.muted("(precedence high → low):")}`);
+        logger.print(`\n${t.heading("sources")} ${t.muted("(precedence, high to low)")}`);
         for (const { source, dir } of status.sources) {
-            logger.print(`  ${source.padEnd(8)} ${t.muted(dir)}`);
+            logger.print(`  ${t.kv(source, t.muted(dir), 8)}`);
         }
         logger.print("");
         if (status.errors.length === 0) {

package/dist/cli/program.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
-import { APP_NAME, APP_VERSION, APP_DESCRIPTION } from "../constants.js";
+import { APP_NAME, APP_VERSION } from "../constants.js";
+import { PRODUCT_MASTHEAD } from "../brand/index.js";
 import { logger } from "../utils/logger.js";
 import { shouldUseColor, usageError } from "../errors/index.js";
 import { themeForColor } from "../theme/index.js";
@@ -13,13 +14,14 @@ import { initCommand } from "./commands/init.js";
 import { checkpointCommand } from "./commands/checkpoint.js";
 import { rollbackCommand } from "./commands/rollback.js";
 import { testCommand } from "./commands/test.js";
+import { hooksCommand } from "./commands/hooks.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
     const program = new Command();
     program
         .name(APP_NAME)
-        .description(`cruxy-code — ${APP_DESCRIPTION}`)
+        .description(PRODUCT_MASTHEAD)
         .version(APP_VERSION, "-v, --version", "print the cruxy version")
         .option("-c, --config <path>", "use a specific config file")
         .option("--log-level <level>", "debug | info | warn | error | silent")
@@ -42,6 +44,7 @@ export function buildProgram() {
     program.addCommand(checkpointCommand());
     program.addCommand(rollbackCommand());
     program.addCommand(testCommand());
+    program.addCommand(hooksCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.

package/dist/cli/repl.d.ts

@@ -1,6 +1,7 @@
 import type { Readable, Writable } from "node:stream";
 import type { Session } from "../agent/index.js";
 import type { CheckpointService } from "../checkpoint/index.js";
+import { type SlashCommandSpec } from "../hooks/index.js";
 import { type StreamRenderer } from "../render/index.js";
 /**
  * The REPL's slash commands — the autocomplete candidate set (U.7). Keep in
@@ -23,4 +24,4 @@ export interface ReplIO {
  * live region, anything else the plain append-only renderer); `cruxy run`
  * passes its own so the approval prompt's status-suspend hook shares it.
  */
-export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer, checkpoints?: CheckpointService): Promise<void>;
+export declare function runInteractive(session: Session, io?: ReplIO, renderer?: StreamRenderer, checkpoints?: CheckpointService, slashCommands?: readonly SlashCommandSpec[]): Promise<void>;