@cruxy/cli 0.13.0 → 0.16.0

package/dist/hooks/config.js

@@ -0,0 +1,253 @@
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+import { COMMANDS_DIR_NAME, GLOBAL_DIR_NAME, HOOKS_FILE_NAME, } from "../constants.js";
+import { defaultBlocking, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, SlashFrontmatterSchema, } from "./types.js";
+/** The real sources for a project root. */
+export function defaultHookSources(cwd) {
+    return {
+        project: path.join(path.resolve(cwd), GLOBAL_DIR_NAME),
+        user: globalDir(),
+    };
+}
+/** Load and resolve the full hook + command catalog. */
+export async function loadHookCatalog(sources) {
+    const hookCandidates = [];
+    const commandCandidates = [];
+    const errors = [];
+    // Precedence order: project first, then user.
+    for (const source of HOOK_SOURCE_PRECEDENCE) {
+        await scanHooksFile(source, sources[source], hookCandidates, errors);
+        await scanCommandsDir(source, sources[source], commandCandidates, errors);
+    }
+    return {
+        hooks: resolvePrecedence(hookCandidates),
+        commands: resolvePrecedence(commandCandidates),
+        errors,
+    };
+}
+// ── hooks.json ────────────────────────────────────────────────────────────────
+async function scanHooksFile(source, dir, out, errors) {
+    const file = path.join(dir, HOOKS_FILE_NAME);
+    let text;
+    try {
+        text = await fs.readFile(file, "utf8");
+    }
+    catch (err) {
+        // Missing file is normal (source absent); other errors are reported.
+        if (err.code !== "ENOENT") {
+            errors.push({
+                source,
+                file,
+                name: HOOKS_FILE_NAME,
+                message: `could not read ${HOOKS_FILE_NAME}: ${err.message}`,
+            });
+        }
+        return;
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        errors.push({
+            source,
+            file,
+            name: HOOKS_FILE_NAME,
+            message: `invalid JSON: ${err.message}`,
+        });
+        return;
+    }
+    // Top-level shape only; each hook is validated individually below so ONE bad
+    // entry is excluded + surfaced while the valid hooks in the same file survive
+    // (same discipline as the skills loader — never all-or-nothing).
+    if (json === null ||
+        typeof json !== "object" ||
+        !Array.isArray(json.hooks)) {
+        errors.push({
+            source,
+            file,
+            name: HOOKS_FILE_NAME,
+            message: 'hooks.json must be an object with a "hooks" array',
+        });
+        return;
+    }
+    const rawHooks = json.hooks;
+    const seen = new Set();
+    for (const [i, raw] of rawHooks.entries()) {
+        const label = raw &&
+            typeof raw === "object" &&
+            typeof raw.name === "string"
+            ? raw.name
+            : `entry #${i}`;
+        const parsed = HookSpecSchema.safeParse(raw);
+        if (!parsed.success) {
+            errors.push({
+                source,
+                file,
+                name: label,
+                message: `invalid hook: ${formatZod(parsed.error)}`,
+            });
+            continue;
+        }
+        const spec = parsed.data;
+        if (seen.has(spec.name)) {
+            errors.push({
+                source,
+                file,
+                name: spec.name,
+                message: `duplicate hook name "${spec.name}" within the ${source} source`,
+            });
+            continue;
+        }
+        seen.add(spec.name);
+        out.push({
+            name: spec.name,
+            event: spec.event,
+            command: spec.command,
+            blocking: spec.blocking ?? defaultBlocking(spec.event),
+            source,
+        });
+    }
+}
+// ── commands/*.md ─────────────────────────────────────────────────────────────
+async function scanCommandsDir(source, dir, out, errors) {
+    const commandsDir = path.join(dir, COMMANDS_DIR_NAME);
+    let entries;
+    try {
+        entries = await fs.readdir(commandsDir, { withFileTypes: true });
+    }
+    catch (err) {
+        if (err.code !== "ENOENT") {
+            errors.push({
+                source,
+                file: commandsDir,
+                name: COMMANDS_DIR_NAME,
+                message: `could not read commands dir: ${err.message}`,
+            });
+        }
+        return;
+    }
+    entries.sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith(".md"))
+            continue;
+        const name = entry.name.slice(0, -".md".length);
+        const file = path.join(commandsDir, entry.name);
+        if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) {
+            errors.push({
+                source,
+                file,
+                name,
+                message: `command filename must be kebab-case: "${entry.name}"`,
+            });
+            continue;
+        }
+        let text;
+        try {
+            text = await fs.readFile(file, "utf8");
+        }
+        catch (err) {
+            errors.push({ source, file, name, message: err.message });
+            continue;
+        }
+        try {
+            out.push(parseCommand(text, name, source, file));
+        }
+        catch (err) {
+            errors.push({ source, file, name, message: err.message });
+        }
+    }
+}
+/** Parse + validate one `commands/<name>.md` into a {@link SlashCommandSpec}. */
+function parseCommand(text, name, source, file) {
+    const { raw, body } = splitFrontmatter(text);
+    const parsed = SlashFrontmatterSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`invalid frontmatter: ${formatZod(parsed.error)}`);
+    }
+    const fm = parsed.data;
+    if (fm.kind === "shell") {
+        if (!fm.command) {
+            throw new Error('a "shell" command requires a `command:` in frontmatter');
+        }
+        return {
+            name,
+            kind: "shell",
+            description: fm.description,
+            command: fm.command,
+            source,
+        };
+    }
+    // prompt (default): the markdown body IS the template.
+    const template = body.trim();
+    if (template === "") {
+        throw new Error('a "prompt" command needs a non-empty template body');
+    }
+    if (fm.command) {
+        throw new Error('a "prompt" command must not set `command:` (use kind: shell)');
+    }
+    void file;
+    return {
+        name,
+        kind: "prompt",
+        description: fm.description,
+        template,
+        source,
+    };
+}
+// ── shared helpers ────────────────────────────────────────────────────────────
+/**
+ * First occurrence of a name wins (candidates arrive in precedence order —
+ * project before user), so a project definition overrides a user one. A
+ * duplicate *within* a source was already reported by the scanner.
+ */
+function resolvePrecedence(candidates) {
+    const byName = new Map();
+    for (const c of candidates)
+        if (!byName.has(c.name))
+            byName.set(c.name, c);
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/;
+/** Split a `---`-delimited frontmatter block (flat `key: value` scalars) from
+ * the body. A strict, tiny YAML subset — anything else is a loud error. */
+function splitFrontmatter(text) {
+    if (!/^---[ \t]*\r?\n/.test(text)) {
+        throw new Error("must begin with a YAML frontmatter block delimited by '---'");
+    }
+    const match = FRONTMATTER_RE.exec(text);
+    if (!match) {
+        throw new Error("frontmatter block is not terminated by a closing '---'");
+    }
+    const raw = {};
+    for (const rawLine of match[1].split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line === "" || line.startsWith("#"))
+            continue;
+        const colon = line.indexOf(":");
+        if (colon === -1) {
+            throw new Error(`invalid frontmatter line (expected "key: value"): ${JSON.stringify(rawLine)}`);
+        }
+        const key = line.slice(0, colon).trim();
+        if (key in raw)
+            throw new Error(`duplicate frontmatter key: ${JSON.stringify(key)}`);
+        raw[key] = stripQuotes(line.slice(colon + 1).trim());
+    }
+    return { raw, body: match[2] ?? "" };
+}
+function stripQuotes(value) {
+    if (value.length >= 2) {
+        const first = value[0];
+        const last = value[value.length - 1];
+        if ((first === '"' || first === "'") && first === last) {
+            return value.slice(1, -1);
+        }
+    }
+    return value;
+}
+function formatZod(error) {
+    return error.issues
+        .map((i) => i.path.length ? `${i.path.join(".")}: ${i.message}` : i.message)
+        .join("; ");
+}

package/dist/hooks/index.d.ts

@@ -0,0 +1,6 @@
+export { HOOK_EVENTS, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, HooksFileSchema, SlashFrontmatterSchema, defaultBlocking, type HookCatalog, type HookConfigError, type HookDefinition, type HookEvent, type HookSource, type HookSpec, type HookTrust, type SlashCommandSpec, type SlashKind, } from "./types.js";
+export { defaultHookSources, loadHookCatalog, type HookSources, } from "./config.js";
+export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPath, type TrustStore, } from "./trust.js";
+export { HookRunner, type HookRunnerDeps, type TrustPromptInfo, } from "./runner.js";
+export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, type SlashResolution, } from "./slash.js";
+export { buildHooksService, type BuildHooksServiceOptions, type HooksService, } from "./service.js";

package/dist/hooks/index.js

@@ -0,0 +1,6 @@
+export { HOOK_EVENTS, HOOK_SOURCE_PRECEDENCE, HookSpecSchema, HooksFileSchema, SlashFrontmatterSchema, defaultBlocking, } from "./types.js";
+export { defaultHookSources, loadHookCatalog, } from "./config.js";
+export { fileTrustStore, fingerprintHooks, isTrusted, memoryTrustStore, trustPath, } from "./trust.js";
+export { HookRunner, } from "./runner.js";
+export { BUILTIN_SLASH_COMMANDS, expandTemplate, isBuiltinSlash, resolveSlash, } from "./slash.js";
+export { buildHooksService, } from "./service.js";

package/dist/hooks/runner.d.ts

@@ -0,0 +1,76 @@
+import type { ToolContext } from "../tools/types.js";
+import { type TrustStore } from "./trust.js";
+import type { HookDefinition, HookEvent } from "./types.js";
+/**
+ * The hook runner (C.19) — the security core. When a lifecycle event fires, it
+ * runs the matching user-authored hooks, but a hook is **never** an approval
+ * bypass:
+ *
+ * 1. **Project trust gate** (supply-chain safety). Before ANY project hook runs,
+ *    the repo must be trusted for its current hook fingerprint. Untrusted →
+ *    prompt (interactive) or `CRUXY_E_HOOK_UNTRUSTED` (non-interactive / declined
+ *    / `trustPrompt` off). A cloned repo's hooks never execute silently. User
+ *    hooks skip this prompt (you authored them) but NOT the gate below.
+ * 2. **Per-command gate + sandbox** — every hook command goes through the SAME
+ *    {@link runGatedShell} as `run_command`: the U.3 approval gate then the C.16
+ *    sandbox (or host). There is no privileged route.
+ * 3. **Blocking vs advisory** — a blocking hook that fails aborts the action
+ *    fail-closed (`CRUXY_E_HOOK_FAILED`); an advisory hook reports and continues.
+ */
+/** What the interactive trust prompt is shown. */
+export interface TrustPromptInfo {
+    root: string;
+    hooks: HookDefinition[];
+}
+export interface HookRunnerDeps {
+    /** Resolved hooks (with sources) for this project. */
+    hooks: HookDefinition[];
+    /** Persisted per-repo trust (see `trust.ts`). */
+    trust: TrustStore;
+    /** `config.hooks.enabled` — when false, nothing ever fires. */
+    enabled: boolean;
+    /** `config.hooks.trustPrompt` — when false, untrusted project hooks fail loud
+     * rather than prompting (never auto-trust). */
+    trustPrompt: boolean;
+    /** Whether cruxy can actually prompt (stdin is a TTY). */
+    interactive: boolean;
+    /** Project root — the trust key and fingerprint scope. */
+    cwd: string;
+    /** Interactive trust prompt (returns true to trust). Required only when a
+     * project defines hooks and `trustPrompt` + `interactive` are both on. */
+    promptTrust?: (info: TrustPromptInfo) => Promise<boolean>;
+    /** "running hook: <name>" surface (visible on every fire). */
+    announce?: (message: string) => void;
+    /** Advisory-failure surface (blocking failures throw instead). */
+    reportFailure?: (message: string) => void;
+    /** Injectable clock for the recorded trust timestamp (tests). */
+    now?: () => string;
+}
+export declare class HookRunner {
+    private readonly deps;
+    constructor(deps: HookRunnerDeps);
+    /** The project hooks — the trust-gated subset. */
+    private get projectHooks();
+    /**
+     * Fire every hook registered for `event`, in catalog order. Resolves normally
+     * when all hooks pass (or advisory ones fail); THROWS `CRUXY_E_HOOK_FAILED`
+     * when a blocking hook fails, or `CRUXY_E_HOOK_UNTRUSTED` when a project's
+     * hooks are not trusted. A no-op when hooks are disabled or none match.
+     */
+    fire(event: HookEvent, ctx: ToolContext): Promise<void>;
+    /**
+     * Ensure this repo's project hooks are trusted for their current fingerprint.
+     * Records trust on an interactive accept; throws `CRUXY_E_HOOK_UNTRUSTED` on
+     * decline, when `trustPrompt` is off, or when non-interactive — NEVER
+     * auto-trusts. The fingerprint covers ALL project hooks, so a change to any of
+     * them invalidates a prior decision (stale → re-prompt).
+     */
+    private ensureProjectTrust;
+    /**
+     * Run one hook command through the shared gate + sandbox path and reduce it to
+     * a pass/fail verdict. A throw from {@link runGatedShell} (non-interactive
+     * approval, sandbox start failure) is a failure whose policy the caller
+     * applies — so an advisory hook can never abort the run on an infra error.
+     */
+    private runOne;
+}

package/dist/hooks/runner.js

@@ -0,0 +1,114 @@
+import { hookFailed, hookUntrusted, messageOf } from "../errors/index.js";
+import { runGatedShell } from "../tools/shell/exec.js";
+import { fingerprintHooks, isTrusted } from "./trust.js";
+export class HookRunner {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** The project hooks — the trust-gated subset. */
+    get projectHooks() {
+        return this.deps.hooks.filter((h) => h.source === "project");
+    }
+    /**
+     * Fire every hook registered for `event`, in catalog order. Resolves normally
+     * when all hooks pass (or advisory ones fail); THROWS `CRUXY_E_HOOK_FAILED`
+     * when a blocking hook fails, or `CRUXY_E_HOOK_UNTRUSTED` when a project's
+     * hooks are not trusted. A no-op when hooks are disabled or none match.
+     */
+    async fire(event, ctx) {
+        if (!this.deps.enabled)
+            return;
+        const applicable = this.deps.hooks.filter((h) => h.event === event);
+        if (applicable.length === 0)
+            return;
+        // Trust gate FIRST — before any project hook can reach execution.
+        if (applicable.some((h) => h.source === "project")) {
+            await this.ensureProjectTrust();
+        }
+        for (const hook of applicable) {
+            this.deps.announce?.(`running hook: ${hook.name}`);
+            const verdict = await this.runOne(hook, ctx);
+            if (verdict.ok)
+                continue;
+            if (hook.blocking) {
+                // Fail-closed: stop, do not run the remaining hooks, abort the action.
+                throw hookFailed(hook.name, verdict.reason ?? "hook failed");
+            }
+            // Advisory: the action already happened (or proceeds) — report, continue.
+            this.deps.reportFailure?.(`hook "${hook.name}" failed (advisory): ${verdict.reason ?? "unknown"}`);
+        }
+    }
+    /**
+     * Ensure this repo's project hooks are trusted for their current fingerprint.
+     * Records trust on an interactive accept; throws `CRUXY_E_HOOK_UNTRUSTED` on
+     * decline, when `trustPrompt` is off, or when non-interactive — NEVER
+     * auto-trusts. The fingerprint covers ALL project hooks, so a change to any of
+     * them invalidates a prior decision (stale → re-prompt).
+     */
+    async ensureProjectTrust() {
+        const projectHooks = this.projectHooks;
+        const fingerprint = fingerprintHooks(projectHooks);
+        if (isTrusted(this.deps.trust, this.deps.cwd, fingerprint))
+            return;
+        // Never auto-trust: no prompt possible → fail loud.
+        if (!this.deps.interactive ||
+            !this.deps.trustPrompt ||
+            !this.deps.promptTrust) {
+            throw hookUntrusted(this.deps.cwd, projectHooks.length);
+        }
+        const trusted = await this.deps.promptTrust({
+            root: this.deps.cwd,
+            hooks: projectHooks,
+        });
+        if (!trusted) {
+            // Decline is not recorded — the next run asks again. Nothing runs now.
+            throw hookUntrusted(this.deps.cwd, projectHooks.length);
+        }
+        this.deps.trust.record({
+            root: this.deps.cwd,
+            fingerprint,
+            at: this.deps.now?.() ?? nowIso(),
+        });
+    }
+    /**
+     * Run one hook command through the shared gate + sandbox path and reduce it to
+     * a pass/fail verdict. A throw from {@link runGatedShell} (non-interactive
+     * approval, sandbox start failure) is a failure whose policy the caller
+     * applies — so an advisory hook can never abort the run on an infra error.
+     */
+    async runOne(hook, ctx) {
+        let outcome;
+        try {
+            outcome = await runGatedShell(hook.command, ctx);
+        }
+        catch (err) {
+            return { ok: false, reason: messageOf(err) ?? "hook could not run" };
+        }
+        return evaluate(outcome);
+    }
+}
+/** Reduce a gated-shell outcome to pass/fail. Success is EXACTLY exit code 0. */
+function evaluate(outcome) {
+    if (!outcome.approved) {
+        return {
+            ok: false,
+            reason: outcome.rejection ?? "declined at the approval prompt",
+        };
+    }
+    const e = outcome.exec;
+    if (e.timedOut)
+        return { ok: false, reason: "timed out" };
+    if (e.spawnError !== undefined)
+        return { ok: false, reason: e.spawnError };
+    if (e.exitCode !== 0) {
+        return {
+            ok: false,
+            reason: `exited with code ${e.exitCode ?? e.signal ?? "unknown"}`,
+        };
+    }
+    return { ok: true };
+}
+function nowIso() {
+    return new Date().toISOString();
+}

package/dist/hooks/service.d.ts

@@ -0,0 +1,38 @@
+import type { CruxyConfig } from "../config/index.js";
+import type { logger as Logger } from "../utils/logger.js";
+import { type HookSources } from "./config.js";
+import { HookRunner, type TrustPromptInfo } from "./runner.js";
+import { type TrustStore } from "./trust.js";
+import type { HookCatalog, SlashCommandSpec } from "./types.js";
+/**
+ * Construction/wiring for the hooks subsystem (C.19). Loads the layered catalog,
+ * builds the {@link HookRunner} with the real trust store + an interactive trust
+ * prompt, and exposes the resolved custom slash commands. Everything the runner
+ * needs is injectable so the security behavior is unit-testable without touching
+ * disk or a TTY.
+ */
+export interface HooksService {
+    /** The lifecycle firing seam (threaded into the loop / session). */
+    runner: HookRunner;
+    /** Resolved custom slash commands (project > user). */
+    commands: SlashCommandSpec[];
+    /** The full catalog (for `cruxy hooks list` + surfacing load errors). */
+    catalog: HookCatalog;
+}
+export interface BuildHooksServiceOptions {
+    cwd: string;
+    config: CruxyConfig;
+    /** Whether cruxy can prompt (stdin is a TTY). */
+    interactive: boolean;
+    logger: typeof Logger;
+    sources?: HookSources;
+    trust?: TrustStore;
+    promptTrust?: (info: TrustPromptInfo) => Promise<boolean>;
+    now?: () => string;
+}
+/**
+ * Load the catalog and assemble the {@link HooksService}. Malformed definitions
+ * are surfaced (never eval'd, never silently dropped) through the logger; the
+ * valid ones proceed.
+ */
+export declare function buildHooksService(opts: BuildHooksServiceOptions): Promise<HooksService>;

package/dist/hooks/service.js

@@ -0,0 +1,49 @@
+import { readSingleKey } from "../components/input.js";
+import { shouldUseColor } from "../errors/index.js";
+import { themeForColor } from "../theme/index.js";
+import { defaultHookSources, loadHookCatalog, } from "./config.js";
+import { HookRunner } from "./runner.js";
+import { fileTrustStore } from "./trust.js";
+/**
+ * Load the catalog and assemble the {@link HooksService}. Malformed definitions
+ * are surfaced (never eval'd, never silently dropped) through the logger; the
+ * valid ones proceed.
+ */
+export async function buildHooksService(opts) {
+    const sources = opts.sources ?? defaultHookSources(opts.cwd);
+    const catalog = await loadHookCatalog(sources);
+    for (const err of catalog.errors) {
+        opts.logger.warn(`ignoring malformed ${err.source} hook/command "${err.name}": ${err.message}`);
+    }
+    const trust = opts.trust ?? fileTrustStore();
+    const runner = new HookRunner({
+        hooks: catalog.hooks,
+        trust,
+        enabled: opts.config.hooks.enabled,
+        trustPrompt: opts.config.hooks.trustPrompt,
+        interactive: opts.interactive,
+        cwd: opts.cwd,
+        promptTrust: opts.promptTrust ?? defaultTrustPrompt,
+        announce: (message) => opts.logger.info(message),
+        reportFailure: (message) => opts.logger.warn(message),
+        now: opts.now,
+    });
+    return { runner, commands: catalog.commands, catalog };
+}
+/**
+ * The real interactive trust prompt: list the project's hooks (name → event →
+ * command) and read a single y/N key. Default-deny — anything but `y` (including
+ * EOF / Ctrl-C) declines, so an untrusted repo never runs on a stray keypress.
+ */
+async function defaultTrustPrompt(info) {
+    const t = themeForColor(shouldUseColor());
+    const out = process.stderr;
+    out.write(`\n${t.warning(t.strong("!"))} this project defines ${t.strong(String(info.hooks.length))} hook${info.hooks.length === 1 ? "" : "s"} (authored by the repo):\n`);
+    for (const h of info.hooks) {
+        out.write(`  ${t.muted(`${h.event}`)} ${t.strong(h.name)} ${t.muted("→")} ${h.command}\n`);
+    }
+    out.write(`${t.muted("review these carefully.")} trust and run this project's hooks? ${t.muted("[y/N]")} `);
+    const key = (await readSingleKey()).toLowerCase();
+    out.write("\n");
+    return key === "y";
+}

package/dist/hooks/slash.d.ts

@@ -0,0 +1,48 @@
+import type { SlashCommandSpec } from "./types.js";
+/**
+ * Custom slash-command resolution (C.19). Builtins are reserved and always win —
+ * a custom command can never shadow `/help`, `/exit`, etc. A resolved custom
+ * command is either a `prompt` (expanded to safe text fed to the agent) or a
+ * `shell` binding (executed through the SAME gate + sandbox as everything else,
+ * by the caller). Nothing here executes anything; it only resolves + expands.
+ */
+/** The builtin slash commands (C.13) — reserved, not overridable. */
+export declare const BUILTIN_SLASH_COMMANDS: readonly ["help", "clear", "compact", "reload", "plan", "exit", "quit"];
+/** Is `name` (no leading slash) a reserved builtin? */
+export declare function isBuiltinSlash(name: string): boolean;
+/** The outcome of resolving a `/…` line against the custom catalog. */
+export type SlashResolution = 
+/** A builtin — the REPL's own dispatch handles it (custom never shadows it). */
+{
+    kind: "builtin";
+    name: string;
+}
+/** A prompt-template command, already expanded to the text to send the agent. */
+ | {
+    kind: "prompt";
+    spec: SlashCommandSpec;
+    prompt: string;
+}
+/** A shell-bound command — the caller runs `spec.command` through the gate. */
+ | {
+    kind: "shell";
+    spec: SlashCommandSpec;
+    args: string;
+}
+/** Not a slash line, or an unknown command. */
+ | {
+    kind: "none";
+};
+/**
+ * Resolve one input line. Non-slash input and unknown names → `none`. Builtins
+ * short-circuit to `builtin` BEFORE the custom catalog is consulted, so a custom
+ * command named after a builtin is inert (surfaced separately at load time).
+ */
+export declare function resolveSlash(line: string, commands: readonly SlashCommandSpec[]): SlashResolution;
+/**
+ * Expand a prompt template — substitute every `{{args}}` with the caller's args.
+ * Pure text in, pure text out: the result is fed to the agent as a user prompt,
+ * so a prompt command can never execute anything (that is the whole safety of
+ * the default `prompt` kind).
+ */
+export declare function expandTemplate(template: string, args: string): string;

package/dist/hooks/slash.js

@@ -0,0 +1,58 @@
+/**
+ * Custom slash-command resolution (C.19). Builtins are reserved and always win —
+ * a custom command can never shadow `/help`, `/exit`, etc. A resolved custom
+ * command is either a `prompt` (expanded to safe text fed to the agent) or a
+ * `shell` binding (executed through the SAME gate + sandbox as everything else,
+ * by the caller). Nothing here executes anything; it only resolves + expands.
+ */
+/** The builtin slash commands (C.13) — reserved, not overridable. */
+export const BUILTIN_SLASH_COMMANDS = [
+    "help",
+    "clear",
+    "compact",
+    "reload",
+    "plan",
+    "exit",
+    "quit",
+];
+const BUILTINS = new Set(BUILTIN_SLASH_COMMANDS);
+/** Is `name` (no leading slash) a reserved builtin? */
+export function isBuiltinSlash(name) {
+    return BUILTINS.has(name);
+}
+/**
+ * Resolve one input line. Non-slash input and unknown names → `none`. Builtins
+ * short-circuit to `builtin` BEFORE the custom catalog is consulted, so a custom
+ * command named after a builtin is inert (surfaced separately at load time).
+ */
+export function resolveSlash(line, commands) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("/"))
+        return { kind: "none" };
+    const space = trimmed.indexOf(" ");
+    const name = (space === -1 ? trimmed.slice(1) : trimmed.slice(1, space)).trim();
+    const args = space === -1 ? "" : trimmed.slice(space + 1).trim();
+    if (name === "")
+        return { kind: "none" };
+    if (isBuiltinSlash(name))
+        return { kind: "builtin", name };
+    const spec = commands.find((c) => c.name === name);
+    if (!spec)
+        return { kind: "none" };
+    if (spec.kind === "shell")
+        return { kind: "shell", spec, args };
+    return {
+        kind: "prompt",
+        spec,
+        prompt: expandTemplate(spec.template ?? "", args),
+    };
+}
+/**
+ * Expand a prompt template — substitute every `{{args}}` with the caller's args.
+ * Pure text in, pure text out: the result is fed to the agent as a user prompt,
+ * so a prompt command can never execute anything (that is the whole safety of
+ * the default `prompt` kind).
+ */
+export function expandTemplate(template, args) {
+    return template.replaceAll("{{args}}", args);
+}