@cruxy/cli 0.14.0 → 0.16.0

package/dist/cli/session-factory.d.ts

@@ -4,7 +4,7 @@ import type { CheckpointService } from "../checkpoint/index.js";
 import type { SandboxService } from "../sandbox/index.js";
 import type { StreamRenderer } from "../render/index.js";
 import { type ApproveAction } from "../tools/index.js";
-import { Session } from "../agent/index.js";
+import { Session, type LifecycleHookRunner } from "../agent/index.js";
 /**
  * Wrap the approval gate with the C.32 auto-checkpoint hook. Ordering is the
  * whole point: a tool mutates only *after* `requestApproval` resolves, so
@@ -24,4 +24,4 @@ export declare function withCheckpointGate(requestApproval: (action: ApproveActi
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService, sandbox?: SandboxService): Session;
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService, sandbox?: SandboxService, hooks?: LifecycleHookRunner): Session;

package/dist/cli/session-factory.js

@@ -5,7 +5,7 @@ import { getGitInfo } from "../utils/git.js";
 import { ApprovalService, InteractivePolicy, SessionAllowlist, classify, defaultPromptIO, } from "../approval/index.js";
 import { shouldUseColor } from "../errors/index.js";
 import { buildDefaultRegistry } from "../tools/index.js";
-import { Session } from "../agent/index.js";
+import { Session, } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
 import { SubagentOrchestrator, makeSpawnSubagentTool, } from "../subagent/index.js";
 /**
@@ -87,7 +87,7 @@ export function withCheckpointGate(requestApproval, checkpoints, cwd) {
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints, sandbox) {
+export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints, sandbox, hooks) {
     const provider = createProvider({
         provider: config.model.provider,
         apiKey,
@@ -166,6 +166,7 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
             projectInstructions,
             planMode: true,
             planRunner,
+            hooks,
         });
     }
     const approval = new ApprovalService({
@@ -181,5 +182,6 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         ctx,
         git,
         projectInstructions,
+        hooks,
     });
 }

package/dist/config/schema.d.ts

@@ -339,6 +339,32 @@ export declare const SandboxConfigSchema: z.ZodObject<{
     mounts?: string[] | undefined;
 }>;
 export type SandboxConfig = z.infer<typeof SandboxConfigSchema>;
+/**
+ * Hooks + custom slash commands (C.19). Hooks run user-authored shell commands
+ * on lifecycle events — a real execution surface — so they are OFF by default
+ * and, when on, still funnel through the SAME U.3 gate + C.16 sandbox as any
+ * agent command (never a bypass). The hook *definitions* live in layered
+ * `hooks.json` files (project > user, source-tracked for the trust model); this
+ * schema holds only the global toggles.
+ */
+export declare const HooksConfigSchema: z.ZodObject<{
+    /** Master switch. When false, NO hook ever fires (config with hooks stays
+     * inert until explicitly enabled). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Whether to interactively prompt to trust a project's hooks the first time
+     * they would run. When false, untrusted project hooks fail loud
+     * (CRUXY_E_HOOK_UNTRUSTED) instead of prompting — never auto-trust.
+     */
+    trustPrompt: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    enabled: boolean;
+    trustPrompt: boolean;
+}, {
+    enabled?: boolean | undefined;
+    trustPrompt?: boolean | undefined;
+}>;
+export type HooksConfig = z.infer<typeof HooksConfigSchema>;
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export declare const McpServerSchema: z.ZodObject<{
     command: z.ZodOptional<z.ZodString>;
@@ -654,6 +680,23 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         timeout?: number | undefined;
         mounts?: string[] | undefined;
     }>>;
+    hooks: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When false, NO hook ever fires (config with hooks stays
+         * inert until explicitly enabled). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Whether to interactively prompt to trust a project's hooks the first time
+         * they would run. When false, untrusted project hooks fail loud
+         * (CRUXY_E_HOOK_UNTRUSTED) instead of prompting — never auto-trust.
+         */
+        trustPrompt: z.ZodDefault<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        enabled: boolean;
+        trustPrompt: boolean;
+    }, {
+        enabled?: boolean | undefined;
+        trustPrompt?: boolean | undefined;
+    }>>;
     mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
         command: z.ZodOptional<z.ZodString>;
         args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
@@ -672,6 +715,23 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     cruxy: {
         gatewayUrl: string;
     };
+    checkpoint: {
+        enabled: boolean;
+        retention: number;
+    };
+    sandbox: {
+        image: string;
+        enabled: boolean;
+        memory: string;
+        network: "none" | "host-loopback" | "full";
+        pids: number;
+        cpus: number;
+        mounts: string[];
+        timeout?: number | undefined;
+    };
+    approval: {
+        mode: "prompt";
+    };
     model: {
         provider: "cruxy" | "anthropic" | "openai" | "custom";
         model: string;
@@ -702,9 +762,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         compactThreshold: number;
         keepRecentMessages: number;
     };
-    approval: {
-        mode: "prompt";
-    };
     index: {
         search: {
             defaultK: number;
@@ -720,10 +777,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines: number;
         };
     };
-    checkpoint: {
-        enabled: boolean;
-        retention: number;
-    };
     subagent: {
         maxDepth: number;
         defaultBudget: {
@@ -737,15 +790,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         captureBytes: number;
         command?: string | undefined;
     };
-    sandbox: {
-        image: string;
+    hooks: {
         enabled: boolean;
-        memory: string;
-        network: "none" | "host-loopback" | "full";
-        pids: number;
-        cpus: number;
-        mounts: string[];
-        timeout?: number | undefined;
+        trustPrompt: boolean;
     };
     mcpServers: Record<string, {
         command?: string | undefined;
@@ -757,6 +804,23 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     cruxy?: {
         gatewayUrl?: string | undefined;
     } | undefined;
+    checkpoint?: {
+        enabled?: boolean | undefined;
+        retention?: number | undefined;
+    } | undefined;
+    sandbox?: {
+        image?: string | undefined;
+        enabled?: boolean | undefined;
+        memory?: string | undefined;
+        network?: "none" | "host-loopback" | "full" | undefined;
+        pids?: number | undefined;
+        cpus?: number | undefined;
+        timeout?: number | undefined;
+        mounts?: string[] | undefined;
+    } | undefined;
+    approval?: {
+        mode?: "prompt" | undefined;
+    } | undefined;
     model?: {
         provider?: "cruxy" | "anthropic" | "openai" | "custom" | undefined;
         model?: string | undefined;
@@ -787,9 +851,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         compactThreshold?: number | undefined;
         keepRecentMessages?: number | undefined;
     } | undefined;
-    approval?: {
-        mode?: "prompt" | undefined;
-    } | undefined;
     index?: {
         search?: {
             defaultK?: number | undefined;
@@ -805,10 +866,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     } | undefined;
-    checkpoint?: {
-        enabled?: boolean | undefined;
-        retention?: number | undefined;
-    } | undefined;
     subagent?: {
         maxDepth?: number | undefined;
         defaultBudget?: {
@@ -822,15 +879,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         command?: string | undefined;
         captureBytes?: number | undefined;
     } | undefined;
-    sandbox?: {
-        image?: string | undefined;
+    hooks?: {
         enabled?: boolean | undefined;
-        memory?: string | undefined;
-        network?: "none" | "host-loopback" | "full" | undefined;
-        pids?: number | undefined;
-        cpus?: number | undefined;
-        timeout?: number | undefined;
-        mounts?: string[] | undefined;
+        trustPrompt?: boolean | undefined;
     } | undefined;
     mcpServers?: Record<string, {
         command?: string | undefined;

package/dist/config/schema.js

@@ -233,6 +233,27 @@ export const SandboxConfigSchema = z
     mounts: z.array(z.string().min(1)).default([]),
 })
     .strict();
+/**
+ * Hooks + custom slash commands (C.19). Hooks run user-authored shell commands
+ * on lifecycle events — a real execution surface — so they are OFF by default
+ * and, when on, still funnel through the SAME U.3 gate + C.16 sandbox as any
+ * agent command (never a bypass). The hook *definitions* live in layered
+ * `hooks.json` files (project > user, source-tracked for the trust model); this
+ * schema holds only the global toggles.
+ */
+export const HooksConfigSchema = z
+    .object({
+    /** Master switch. When false, NO hook ever fires (config with hooks stays
+     * inert until explicitly enabled). */
+    enabled: z.boolean().default(false),
+    /**
+     * Whether to interactively prompt to trust a project's hooks the first time
+     * they would run. When false, untrusted project hooks fail loud
+     * (CRUXY_E_HOOK_UNTRUSTED) instead of prompting — never auto-trust.
+     */
+    trustPrompt: z.boolean().default(true),
+})
+    .strict();
 /** MCP server entry — stdio or URL transport (wired up in a later phase). */
 export const McpServerSchema = z
     .object({
@@ -256,6 +277,7 @@ export const CruxyConfigSchema = z
     subagent: SubagentConfigSchema.default({}),
     test: TestConfigSchema.default({}),
     sandbox: SandboxConfigSchema.default({}),
+    hooks: HooksConfigSchema.default({}),
     mcpServers: z.record(z.string(), McpServerSchema).default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })

package/dist/constants.d.ts

@@ -21,6 +21,15 @@ export declare const PROJECT_INSTRUCTION_FILENAMES: string[];
  * root for shipped builtins.
  */
 export declare const SKILLS_DIR_NAME = "skills";
+/** Hook definitions file, under the project dir (`<cwd>/.cruxy/hooks.json`) and
+ * the global dir (`~/.cruxy/hooks.json`). Pure data, validated, never eval'd (C.19). */
+export declare const HOOKS_FILE_NAME = "hooks.json";
+/** Custom slash-command directory (`<cwd>/.cruxy/commands`, `~/.cruxy/commands`);
+ * one `<name>.md` per command (frontmatter + template body), mirroring skills. */
+export declare const COMMANDS_DIR_NAME = "commands";
+/** Per-repo hook-trust record, in the GLOBAL dir only (`~/.cruxy/trust.json`) —
+ * never in a repo, so cloning carries no trust (C.19 supply-chain safety). */
+export declare const TRUST_FILE_NAME = "trust.json";
 /**
  * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
  * Anchored the same way as the package.json lookup above: both `dist/` and

package/dist/constants.js

@@ -41,6 +41,15 @@ export const PROJECT_INSTRUCTION_FILENAMES = ["CRUXY.md", "AGENTS.md"];
  * root for shipped builtins.
  */
 export const SKILLS_DIR_NAME = "skills";
+/** Hook definitions file, under the project dir (`<cwd>/.cruxy/hooks.json`) and
+ * the global dir (`~/.cruxy/hooks.json`). Pure data, validated, never eval'd (C.19). */
+export const HOOKS_FILE_NAME = "hooks.json";
+/** Custom slash-command directory (`<cwd>/.cruxy/commands`, `~/.cruxy/commands`);
+ * one `<name>.md` per command (frontmatter + template body), mirroring skills. */
+export const COMMANDS_DIR_NAME = "commands";
+/** Per-repo hook-trust record, in the GLOBAL dir only (`~/.cruxy/trust.json`) —
+ * never in a repo, so cloning carries no trust (C.19 supply-chain safety). */
+export const TRUST_FILE_NAME = "trust.json";
 /**
  * Absolute path of the shipped builtin skills directory (`<pkg>/skills`).
  * Anchored the same way as the package.json lookup above: both `dist/` and

package/dist/errors/constructors.d.ts

@@ -46,6 +46,22 @@ export declare function sandboxImage(image: string, underlying?: unknown): Cruxy
  * can't launch is never papered over with a host run.
  */
 export declare function sandboxExec(underlying?: unknown): CruxyError;
+/**
+ * A blocking hook failed (non-zero exit, gate-declined, or errored). The action
+ * that fired it is aborted fail-closed — a failing pre-check must stop, never
+ * proceed. Advisory hooks report but never raise this.
+ */
+export declare function hookFailed(name: string, reason: string, underlying?: unknown): CruxyError;
+/**
+ * A project (a cloned/opened repo) defines hooks that have not been trusted for
+ * this machine. Cruxy NEVER runs another author's hooks silently — trust is an
+ * explicit, per-repo decision recorded in your home, not in the repo.
+ */
+export declare function hookUntrusted(root: string, count: number): CruxyError;
+/** A malformed hook definition — excluded from the catalog, never eval'd. */
+export declare function hookInvalid(reason: string, source?: string): CruxyError;
+/** A malformed custom slash-command definition — excluded and surfaced. */
+export declare function slashInvalid(reason: string, source?: string): CruxyError;
 /**
  * A side-effecting action needs approval but cruxy can't ask (non-interactive,
  * no policy). Default-deny — never auto-approve. A distinct exit code (10) so CI

package/dist/errors/constructors.js

@@ -282,6 +282,63 @@ export function sandboxExec(underlying) {
         underlying,
     });
 }
+// ── hooks + custom slash commands (exit 13) — C.19 ────────────────────────────
+/**
+ * A blocking hook failed (non-zero exit, gate-declined, or errored). The action
+ * that fired it is aborted fail-closed — a failing pre-check must stop, never
+ * proceed. Advisory hooks report but never raise this.
+ */
+export function hookFailed(name, reason, underlying) {
+    return new CruxyError({
+        code: ErrorCode.HookFailed,
+        title: `blocking hook "${name}" failed — action aborted`,
+        cause: reason,
+        nextSteps: [
+            `fix the hook command, or mark it advisory (blocking: false) if it should not block`,
+            "run `cruxy hooks list` to inspect the configured hooks",
+        ],
+        meta: { name },
+        underlying,
+    });
+}
+/**
+ * A project (a cloned/opened repo) defines hooks that have not been trusted for
+ * this machine. Cruxy NEVER runs another author's hooks silently — trust is an
+ * explicit, per-repo decision recorded in your home, not in the repo.
+ */
+export function hookUntrusted(root, count) {
+    return new CruxyError({
+        code: ErrorCode.HookUntrusted,
+        title: `this project defines ${count} hook${count === 1 ? "" : "s"} that are not trusted`,
+        cause: "project hooks are authored by whoever wrote the repo; cruxy will not run them until you review and trust them",
+        nextSteps: [
+            "review them with `cruxy hooks list`",
+            `trust them with \`cruxy hooks trust ${root}\` (after reviewing)`,
+            "or set hooks.enabled=false to disable hooks entirely",
+        ],
+        meta: { root, count },
+    });
+}
+/** A malformed hook definition — excluded from the catalog, never eval'd. */
+export function hookInvalid(reason, source) {
+    return new CruxyError({
+        code: ErrorCode.HookInvalid,
+        title: "a hook definition is malformed",
+        cause: reason,
+        nextSteps: ["fix the hook definition; see `cruxy hooks list` for details"],
+        meta: { source },
+    });
+}
+/** A malformed custom slash-command definition — excluded and surfaced. */
+export function slashInvalid(reason, source) {
+    return new CruxyError({
+        code: ErrorCode.SlashInvalid,
+        title: "a custom slash-command definition is malformed",
+        cause: reason,
+        nextSteps: ["fix the command definition (frontmatter + body)"],
+        meta: { source },
+    });
+}
 // ── approval (exit 10) ────────────────────────────────────────────────────────
 /**
  * A side-effecting action needs approval but cruxy can't ask (non-interactive,

package/dist/errors/types.d.ts

@@ -57,6 +57,17 @@ export declare const ErrorCode: {
     readonly SandboxUnavailable: "CRUXY_E_SANDBOX_UNAVAILABLE";
     readonly SandboxImage: "CRUXY_E_SANDBOX_IMAGE";
     readonly SandboxExec: "CRUXY_E_SANDBOX_EXEC";
+    /** A blocking hook failed (non-zero exit / declined / errored) → the action
+     * is aborted fail-closed. Advisory hooks never raise this. */
+    readonly HookFailed: "CRUXY_E_HOOK_FAILED";
+    /** A project defines hooks that have not been trusted for this repo — they are
+     * never run silently (supply-chain safety). */
+    readonly HookUntrusted: "CRUXY_E_HOOK_UNTRUSTED";
+    /** A malformed hook definition — excluded from the catalog and surfaced,
+     * never eval'd. */
+    readonly HookInvalid: "CRUXY_E_HOOK_INVALID";
+    /** A malformed custom slash-command definition — excluded and surfaced. */
+    readonly SlashInvalid: "CRUXY_E_SLASH_INVALID";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -70,6 +70,18 @@ export const ErrorCode = {
     SandboxUnavailable: "CRUXY_E_SANDBOX_UNAVAILABLE",
     SandboxImage: "CRUXY_E_SANDBOX_IMAGE",
     SandboxExec: "CRUXY_E_SANDBOX_EXEC",
+    // hooks + custom slash commands (exit 13) — C.19
+    /** A blocking hook failed (non-zero exit / declined / errored) → the action
+     * is aborted fail-closed. Advisory hooks never raise this. */
+    HookFailed: "CRUXY_E_HOOK_FAILED",
+    /** A project defines hooks that have not been trusted for this repo — they are
+     * never run silently (supply-chain safety). */
+    HookUntrusted: "CRUXY_E_HOOK_UNTRUSTED",
+    /** A malformed hook definition — excluded from the catalog and surfaced,
+     * never eval'd. */
+    HookInvalid: "CRUXY_E_HOOK_INVALID",
+    /** A malformed custom slash-command definition — excluded and surfaced. */
+    SlashInvalid: "CRUXY_E_SLASH_INVALID",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -123,6 +135,13 @@ const EXIT_CODES = {
     [ErrorCode.SandboxUnavailable]: 12,
     [ErrorCode.SandboxImage]: 12,
     [ErrorCode.SandboxExec]: 12,
+    // Hooks + custom slash commands (C.19). A blocking-hook failure and an
+    // untrusted project are execution-safety stops; malformed definitions are
+    // usage/config problems but share the category for a greppable exit code.
+    [ErrorCode.HookFailed]: 13,
+    [ErrorCode.HookUntrusted]: 13,
+    [ErrorCode.HookInvalid]: 13,
+    [ErrorCode.SlashInvalid]: 13,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/hooks/config.d.ts

@@ -0,0 +1,21 @@
+import { type HookCatalog } from "./types.js";
+/**
+ * Discovery for hooks + custom slash commands (C.19), mirroring the C.18 skills
+ * loader: scan layered sources (project > user), validate every definition
+ * fail-loud, exclude the malformed (collected as {@link HookConfigError}, never
+ * thrown past the loader, never eval'd), and resolve precedence. Hook
+ * definitions carry their {@link HookSource} — the trust model depends on
+ * telling a repo's hooks (project) apart from your own (user).
+ */
+/** The two source directories (each a `.cruxy` dir holding `hooks.json` and
+ * `commands/`). */
+export interface HookSources {
+    /** `<cwd>/.cruxy` */
+    project: string;
+    /** `~/.cruxy` */
+    user: string;
+}
+/** The real sources for a project root. */
+export declare function defaultHookSources(cwd: string): HookSources;
+/** Load and resolve the full hook + command catalog. */
+export declare function loadHookCatalog(sources: HookSources): Promise<HookCatalog>;