@x-code-cli/core 0.2.9 → 0.3.0

package/dist/hooks/config-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-schema.d.ts","sourceRoot":"","sources":["../../src/hooks/config-schema.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAgB5C,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gCAcb,CAAA;AAEhB,qBAAa,oBAAqB,SAAQ,KAAK;aAG3B,WAAW,EAAE,MAAM;gBADnC,OAAO,EAAE,MAAM,EACC,WAAW,EAAE,MAAM;CAKtC;AAED;+DAC+D;AAC/D,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,UAAU,CA0B7E"}

package/dist/hooks/config-schema.js

@@ -0,0 +1,79 @@
+// @x-code-cli/core — hooks.json zod schema
+//
+// Validates a `HookConfig` whether it came from a hooks.json file on
+// disk or an inline manifest object. Same schema both paths — keeps the
+// failure mode identical so plugin authors don't get different errors
+// depending on which form they used.
+//
+// Bad regex in `matcher` is NOT a schema error — it'd be inconvenient
+// to require authors to author / test their regex against zod's strict
+// mode. The bus catches RegExp construction errors at emit time and
+// degrades to "matches every tool" (logged for support).
+import { z } from 'zod';
+const hookEntrySchema = z.object({
+    matcher: z.string().optional(),
+    command: z.string().min(1),
+    // Platform-specific overrides. Optional; missing on a platform falls
+    // back to `command`. We deliberately don't enforce that at least one
+    // of them is set — the base command is always required.
+    commandWindows: z.string().min(1).optional(),
+    commandDarwin: z.string().min(1).optional(),
+    commandLinux: z.string().min(1).optional(),
+    timeout: z.number().int().positive().max(30_000).optional(),
+    description: z.string().optional(),
+    failurePolicy: z.enum(['allow', 'block']).optional(),
+});
+export const hookConfigSchema = z
+    .object({
+    SessionStart: z.array(hookEntrySchema).optional(),
+    UserPromptSubmit: z.array(hookEntrySchema).optional(),
+    PreToolUse: z.array(hookEntrySchema).optional(),
+    PostToolUse: z.array(hookEntrySchema).optional(),
+    PreCompact: z.array(hookEntrySchema).optional(),
+    PostCompact: z.array(hookEntrySchema).optional(),
+    SubagentStart: z.array(hookEntrySchema).optional(),
+    SubagentStop: z.array(hookEntrySchema).optional(),
+    TurnComplete: z.array(hookEntrySchema).optional(),
+    SessionEnd: z.array(hookEntrySchema).optional(),
+})
+    // Unknown keys are tolerated for forward compat (future event names).
+    .passthrough();
+export class HookConfigParseError extends Error {
+    sourceLabel;
+    constructor(message, sourceLabel) {
+        super(message);
+        this.sourceLabel = sourceLabel;
+        this.name = 'HookConfigParseError';
+    }
+}
+/** Validate an already-parsed-object form. Used for inline manifest
+ *  configs and for the body of hooks.json after JSON.parse. */
+export function parseHookConfig(raw, sourceLabel) {
+    const result = hookConfigSchema.safeParse(raw);
+    if (!result.success) {
+        const issues = result.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`).join('; ');
+        throw new HookConfigParseError(`invalid hooks config — ${issues}`, sourceLabel);
+    }
+    // Strip unknown future keys at the type boundary — passthrough kept
+    // them on the runtime object, but our HookConfig type only knows the
+    // ten events.
+    const known = {};
+    for (const k of [
+        'SessionStart',
+        'UserPromptSubmit',
+        'PreToolUse',
+        'PostToolUse',
+        'PreCompact',
+        'PostCompact',
+        'SubagentStart',
+        'SubagentStop',
+        'TurnComplete',
+        'SessionEnd',
+    ]) {
+        const arr = result.data[k];
+        if (Array.isArray(arr))
+            known[k] = arr;
+    }
+    return known;
+}
+//# sourceMappingURL=config-schema.js.map

package/dist/hooks/config-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-schema.js","sourceRoot":"","sources":["../../src/hooks/config-schema.ts"],"names":[],"mappings":"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"}

package/dist/hooks/executor.d.ts

@@ -0,0 +1,16 @@
+import type { HookDecision, HookEvent, RegisteredHook } from './types.js';
+export interface ExecuteHookOptions {
+    /** Cancels the hook child process when fired. Agent loop's abort
+     *  signal flows through here so Esc during a slow hook kills it
+     *  promptly. */
+    signal?: AbortSignal;
+    /** Override the default 5s timeout. Per-hook `entry.timeout` still
+     *  wins when both are set. Both are capped at 30s. */
+    defaultTimeoutMs?: number;
+}
+/** Run one hook against one event. Returns the parsed decision (default
+ *  allow on anything unexpected). Never throws unless the caller's
+ *  AbortSignal fires — abort is the one error worth bubbling because
+ *  the caller's loop is already shutting down. */
+export declare function executeHook(hook: RegisteredHook, event: HookEvent, opts?: ExecuteHookOptions): Promise<HookDecision>;
+//# sourceMappingURL=executor.d.ts.map

package/dist/hooks/executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/hooks/executor.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAmB,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAwB1F,MAAM,WAAW,kBAAkB;IACjC;;oBAEgB;IAChB,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB;0DACsD;IACtD,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;kDAGkD;AAClD,wBAAsB,WAAW,CAC/B,IAAI,EAAE,cAAc,EACpB,KAAK,EAAE,SAAS,EAChB,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAiEvB"}

package/dist/hooks/executor.js

@@ -0,0 +1,183 @@
+// @x-code-cli/core — Hook command executor
+//
+// Spawns a hook's shell command, writes the event JSON on stdin, reads
+// the decision JSON from stdout. The whole protocol is line-oriented:
+// one JSON object in, one JSON object out (or empty stdout = default
+// allow). Anything else on stdout is ignored — common pattern for hooks
+// that just want to log to stderr without influencing the agent.
+//
+// Failure handling is deliberately permissive (default `failurePolicy:
+// 'allow'`): a broken hook must never wedge the agent loop. Non-zero
+// exit, timeout, or crash all degrade to `allow` and log a debug
+// breadcrumb. The `block` policy is opt-in and reserved for hooks the
+// plugin author has explicitly designed as gating hooks.
+//
+// AbortSignal propagation: passed to execa's `cancelSignal` so the
+// child process is SIGKILL'd when the user hits Esc mid-hook. Same
+// machinery the shell tool uses.
+import { execa } from 'execa';
+import { getPluginUserConfigEnv } from '../plugins/user-config.js';
+import { debugLog } from '../utils.js';
+import { buildVariableContext, expandVariables } from './variables.js';
+/** Return the command appropriate for the current OS. Plugin authors
+ *  set `command` as a portable default and may add `commandWindows` /
+ *  `commandDarwin` / `commandLinux` to handle per-OS differences (e.g.
+ *  shebang line, executable name, quoting). Unknown platforms (freebsd,
+ *  sunos, aix) fall through to the base. */
+function pickPlatformCommand(entry) {
+    switch (process.platform) {
+        case 'win32':
+            return entry.commandWindows ?? entry.command;
+        case 'darwin':
+            return entry.commandDarwin ?? entry.command;
+        case 'linux':
+            return entry.commandLinux ?? entry.command;
+        default:
+            return entry.command;
+    }
+}
+const DEFAULT_TIMEOUT_MS = 5_000;
+const MAX_TIMEOUT_MS = 30_000;
+/** Run one hook against one event. Returns the parsed decision (default
+ *  allow on anything unexpected). Never throws unless the caller's
+ *  AbortSignal fires — abort is the one error worth bubbling because
+ *  the caller's loop is already shutting down. */
+export async function executeHook(hook, event, opts = {}) {
+    const timeoutMs = Math.min(hook.entry.timeout ?? opts.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    const vars = buildVariableContext({
+        pluginDir: hook.pluginDir,
+        cwd: event.session.cwd,
+        pluginId: hook.pluginId,
+    });
+    const expandedCommand = expandVariables(pickPlatformCommand(hook.entry), vars);
+    const stdinPayload = JSON.stringify(buildStdinPayload(hook, event));
+    // Merge the owning plugin's userConfig values into the hook's env.
+    // Hook scripts that need an API key declared in the manifest read it as
+    // `process.env[KEY]` without writing any glue — `${env:KEY}` substitution
+    // in the command string also resolves against this merged env. We fail
+    // silent if the read errors (no userConfig set yet ⇒ empty map).
+    let pluginEnv = {};
+    try {
+        pluginEnv = await getPluginUserConfigEnv(hook.pluginId);
+    }
+    catch (err) {
+        debugLog('hooks.user-config-read-failed', `${hook.pluginId}: ${String(err)}`);
+    }
+    try {
+        const result = await execa(expandedCommand, [], {
+            shell: true,
+            input: stdinPayload,
+            timeout: timeoutMs,
+            cancelSignal: opts.signal,
+            stdio: 'pipe',
+            reject: false, // Non-zero exits handled below explicitly, not as throws.
+            cwd: event.session.cwd,
+            env: { ...process.env, ...pluginEnv },
+        });
+        if (opts.signal?.aborted) {
+            // Aborted mid-execution. Caller's loop is winding down — surface
+            // by throwing so the bus stops cascading further hooks.
+            throw new Error('aborted');
+        }
+        if (result.timedOut) {
+            debugLog('hooks.exec-timeout', `${hook.pluginId} ${event.name}: timed out after ${timeoutMs}ms`);
+            return failurePolicyDecision(hook, `hook timed out after ${timeoutMs}ms`);
+        }
+        if (typeof result.exitCode === 'number' && result.exitCode !== 0) {
+            const stderrTail = (result.stderr ?? '').toString().slice(0, 200);
+            debugLog('hooks.exec-nonzero', `${hook.pluginId} ${event.name}: exit ${result.exitCode} stderr=${stderrTail}`);
+            return failurePolicyDecision(hook, `hook exited ${result.exitCode}`);
+        }
+        const decision = parseDecision(result.stdout ?? '', hook, event);
+        // Trace successful hook runs so plugin authors can confirm their
+        // hook actually fired without needing to add their own logging.
+        // Stdio is `pipe`d (we read the JSON decision out of stdout), so
+        // anything the hook writes to its own stderr is otherwise invisible
+        // — this breadcrumb is what `--plugin-debug` / `DEBUG_STDOUT=1`
+        // users grep for to verify the wiring.
+        debugLog('hooks.exec-ran', `${hook.pluginId} ${event.name}: decision=${decision.decision}`);
+        return decision;
+    }
+    catch (err) {
+        if (opts.signal?.aborted)
+            throw err;
+        debugLog('hooks.exec-error', `${hook.pluginId} ${event.name}: ${String(err)}`);
+        return failurePolicyDecision(hook, `hook crashed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+function failurePolicyDecision(hook, reason) {
+    if (hook.entry.failurePolicy === 'block')
+        return { decision: 'deny', reason };
+    return { decision: 'allow' };
+}
+/** Build the JSON object sent to the hook over stdin. Event-specific
+ *  fields are flattened in at the top level (matches Claude Code's
+ *  hook protocol shape). */
+function buildStdinPayload(hook, event) {
+    const base = {
+        event: event.name,
+        session: event.session,
+        plugin: { id: hook.pluginId, dir: hook.pluginDir },
+    };
+    switch (event.name) {
+        case 'UserPromptSubmit':
+            base.prompt = event.prompt;
+            break;
+        case 'PreToolUse':
+            base.tool = event.tool;
+            break;
+        case 'PostToolUse':
+            base.tool = event.tool;
+            break;
+        case 'PreCompact':
+            base.trigger = event.trigger;
+            base.messageCount = event.messageCount;
+            base.tokenEstimate = event.tokenEstimate;
+            break;
+        case 'PostCompact':
+            base.trigger = event.trigger;
+            base.messageCount = event.messageCount;
+            base.summary = event.summary;
+            break;
+        case 'SubagentStart':
+            base.agent = event.agent;
+            break;
+        case 'SubagentStop':
+            base.agent = event.agent;
+            base.durationMs = event.durationMs;
+            base.outcome = event.outcome;
+            if (event.tokenUsage)
+                base.tokenUsage = event.tokenUsage;
+            break;
+        case 'TurnComplete':
+            base.turn = event.turn;
+            if (event.tokenUsage)
+                base.tokenUsage = event.tokenUsage;
+            break;
+        // SessionStart / SessionEnd have no extra fields beyond session/plugin.
+    }
+    return base;
+}
+function parseDecision(stdout, hook, event) {
+    const trimmed = (stdout ?? '').toString().trim();
+    if (!trimmed)
+        return { decision: 'allow' };
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+            const obj = parsed;
+            const d = obj.decision;
+            if (d === 'allow' || d === 'deny' || d === 'modify') {
+                return obj;
+            }
+        }
+    }
+    catch {
+        // Not JSON — many hooks intend stdout for human eyes (logs). Treat
+        // as default allow but breadcrumb in case the user expected it to
+        // influence the agent.
+        debugLog('hooks.decision-not-json', `${hook.pluginId} ${event.name}: ignoring non-JSON stdout: ${trimmed.slice(0, 200)}`);
+    }
+    return { decision: 'allow' };
+}
+//# sourceMappingURL=executor.js.map

package/dist/hooks/executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"executor.js","sourceRoot":"","sources":["../../src/hooks/executor.ts"],"names":[],"mappings":"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"}

package/dist/hooks/index.d.ts

@@ -0,0 +1,10 @@
+export type { DecisionEvent, HookConfig, HookConfigEntry, HookDecision, HookEvent, HookEventName, RegisteredHook, SessionContext, } from './types.js';
+export { hookConfigSchema, parseHookConfig, HookConfigParseError } from './config-schema.js';
+export { buildVariableContext, expandVariables } from './variables.js';
+export type { VariableContext } from './variables.js';
+export { executeHook } from './executor.js';
+export type { ExecuteHookOptions } from './executor.js';
+export { HookRegistry, buildHookRegistry, emptyHookRegistry } from './registry.js';
+export { HookBus, emptyHookBus, aggregatePreToolUse, aggregatePostToolUse, aggregateUserPromptSubmit } from './bus.js';
+export type { EmitOptions, PreToolEffect, PostToolEffect, UserPromptEffect } from './bus.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,aAAa,EACb,UAAU,EACV,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,EACb,cAAc,EACd,cAAc,GACf,MAAM,YAAY,CAAA;AACnB,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC5F,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACtE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAC3C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACvD,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAClF,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAA;AACtH,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAA"}

package/dist/hooks/index.js

@@ -0,0 +1,6 @@
+export { hookConfigSchema, parseHookConfig, HookConfigParseError } from './config-schema.js';
+export { buildVariableContext, expandVariables } from './variables.js';
+export { executeHook } from './executor.js';
+export { HookRegistry, buildHookRegistry, emptyHookRegistry } from './registry.js';
+export { HookBus, emptyHookBus, aggregatePreToolUse, aggregatePostToolUse, aggregateUserPromptSubmit } from './bus.js';
+//# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/hooks/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAC5F,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAEtE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAE3C,OAAO,EAAE,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AAClF,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAA"}

package/dist/hooks/registry.d.ts

@@ -0,0 +1,23 @@
+import type { HookConfig, HookEventName, RegisteredHook } from './types.js';
+export declare class HookRegistry {
+    private byEvent;
+    constructor(hooks?: ReadonlyArray<RegisteredHook>);
+    /** Hooks bound to a given event, in registration order. */
+    get(event: HookEventName): readonly RegisteredHook[];
+    /** Cheap check the bus uses to skip event-payload construction when
+     *  no hook is listening — every emit-site is in a hot path. */
+    has(event: HookEventName): boolean;
+    /** Every registered hook. Used by `/plugin doctor` to list what's
+     *  active alongside which plugin contributed it. */
+    list(): readonly RegisteredHook[];
+}
+/** Build a registry from per-plugin hook configs. Iteration order of
+ *  the input array determines emit order — the caller (integration.ts)
+ *  is responsible for handing us plugins in a stable order. */
+export declare function buildHookRegistry(pluginHooks: ReadonlyArray<{
+    pluginId: string;
+    pluginDir: string;
+    config: HookConfig;
+}>): HookRegistry;
+export declare function emptyHookRegistry(): HookRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/hooks/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/hooks/registry.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAE3E,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAsC;gBAEzC,KAAK,GAAE,aAAa,CAAC,cAAc,CAAM;IASrD,2DAA2D;IAC3D,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,cAAc,EAAE;IAIpD;mEAC+D;IAC/D,GAAG,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO;IAIlC;wDACoD;IACpD,IAAI,IAAI,SAAS,cAAc,EAAE;CAKlC;AAED;;+DAE+D;AAC/D,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,aAAa,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,GACtF,YAAY,CAYd;AAED,wBAAgB,iBAAiB,IAAI,YAAY,CAEhD"}

package/dist/hooks/registry.js

@@ -0,0 +1,49 @@
+export class HookRegistry {
+    byEvent;
+    constructor(hooks = []) {
+        this.byEvent = new Map();
+        for (const h of hooks) {
+            const list = this.byEvent.get(h.event) ?? [];
+            list.push(h);
+            this.byEvent.set(h.event, list);
+        }
+    }
+    /** Hooks bound to a given event, in registration order. */
+    get(event) {
+        return this.byEvent.get(event) ?? [];
+    }
+    /** Cheap check the bus uses to skip event-payload construction when
+     *  no hook is listening — every emit-site is in a hot path. */
+    has(event) {
+        return (this.byEvent.get(event)?.length ?? 0) > 0;
+    }
+    /** Every registered hook. Used by `/plugin doctor` to list what's
+     *  active alongside which plugin contributed it. */
+    list() {
+        const all = [];
+        for (const arr of this.byEvent.values())
+            all.push(...arr);
+        return all;
+    }
+}
+/** Build a registry from per-plugin hook configs. Iteration order of
+ *  the input array determines emit order — the caller (integration.ts)
+ *  is responsible for handing us plugins in a stable order. */
+export function buildHookRegistry(pluginHooks) {
+    const all = [];
+    for (const { pluginId, pluginDir, config } of pluginHooks) {
+        for (const eventName of Object.keys(config)) {
+            const entries = config[eventName];
+            if (!entries)
+                continue;
+            for (const entry of entries) {
+                all.push({ pluginId, pluginDir, event: eventName, entry });
+            }
+        }
+    }
+    return new HookRegistry(all);
+}
+export function emptyHookRegistry() {
+    return new HookRegistry([]);
+}
+//# sourceMappingURL=registry.js.map

package/dist/hooks/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/hooks/registry.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,YAAY;IACf,OAAO,CAAsC;IAErD,YAAY,QAAuC,EAAE;QACnD,IAAI,CAAC,OAAO,GAAG,IAAI,GAAG,EAAE,CAAA;QACxB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;YAC5C,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;YACZ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;QACjC,CAAC;IACH,CAAC;IAED,2DAA2D;IAC3D,GAAG,CAAC,KAAoB;QACtB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAA;IACtC,CAAC;IAED;mEAC+D;IAC/D,GAAG,CAAC,KAAoB;QACtB,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;IACnD,CAAC;IAED;wDACoD;IACpD,IAAI;QACF,MAAM,GAAG,GAAqB,EAAE,CAAA;QAChC,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,CAAA;QACzD,OAAO,GAAG,CAAA;IACZ,CAAC;CACF;AAED;;+DAE+D;AAC/D,MAAM,UAAU,iBAAiB,CAC/B,WAAuF;IAEvF,MAAM,GAAG,GAAqB,EAAE,CAAA;IAChC,KAAK,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,WAAW,EAAE,CAAC;QAC1D,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAoB,EAAE,CAAC;YAC/D,MAAM,OAAO,GAAG,MAAM,CAAC,SAAS,CAAC,CAAA;YACjC,IAAI,CAAC,OAAO;gBAAE,SAAQ;YACtB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,GAAG,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC,CAAA;YAC5D,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,YAAY,CAAC,GAAG,CAAC,CAAA;AAC9B,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,IAAI,YAAY,CAAC,EAAE,CAAC,CAAA;AAC7B,CAAC"}

package/dist/hooks/types.d.ts

@@ -0,0 +1,165 @@
+export type HookEventName = 'SessionStart' | 'UserPromptSubmit' | 'PreToolUse' | 'PostToolUse' | 'PreCompact' | 'PostCompact' | 'SubagentStart' | 'SubagentStop' | 'TurnComplete' | 'SessionEnd';
+/** Subset of events that emit a decision the agent acts on. Other events
+ *  are fire-and-forget — hooks may run side effects (logging,
+ *  notifications) but the agent ignores their stdout. */
+export type DecisionEvent = 'UserPromptSubmit' | 'PreToolUse' | 'PostToolUse';
+/** One hook entry as it appears in hooks.json. */
+export interface HookConfigEntry {
+    /** Optional regex matching tool name. Only meaningful for PreToolUse /
+     *  PostToolUse — ignored for other events. A missing matcher means
+     *  "every tool". */
+    matcher?: string;
+    /** Shell command to run on the current platform when no platform-specific
+     *  override below is set. Supports `${pluginDir}` / `${pluginDataDir}` /
+     *  `${cwd}` / `${homedir}` / `${env:NAME}` / `${sep}` variable expansion
+     *  (see [[variables]]).
+     *
+     *  We require this even when the platform overrides are set so plugin
+     *  authors can't accidentally ship a plugin that runs on *only* one OS
+     *  — the base command is the safety net for any platform the author
+     *  didn't explicitly think about. */
+    command: string;
+    /** Platform-specific override commands. When set, the matching one
+     *  replaces `command` on that OS. Keys match `process.platform`
+     *  values; unknown platforms (freebsd / sunos / aix) fall through to
+     *  the base `command`. */
+    commandWindows?: string;
+    commandDarwin?: string;
+    commandLinux?: string;
+    /** Per-hook timeout in ms (default 5000, capped at 30000). */
+    timeout?: number;
+    description?: string;
+    /** What to do when the hook exits non-zero or crashes:
+     *
+     *    'allow'  (default) — log warning, treat as if the hook said allow
+     *    'block'            — treat as deny (only meaningful for DecisionEvents)
+     *
+     *  The default is permissive on purpose: a broken hook must not be
+     *  able to wedge the agent loop indefinitely. */
+    failurePolicy?: 'allow' | 'block';
+}
+/** A whole hooks.json file. Each event name maps to an ordered array of
+ *  entries — earlier entries run first, and for decision events a deny
+ *  short-circuits the rest. */
+export type HookConfig = Partial<Record<HookEventName, HookConfigEntry[]>>;
+/** Session-level context attached to every event payload. */
+export interface SessionContext {
+    cwd: string;
+    modelId: string;
+    /** Optional — when the CLI assigns a session id we pass it through so
+     *  hooks can correlate events. */
+    sessionId?: string;
+}
+/** Discriminated union of every event payload shape. The `name` field
+ *  doubles as the tag. The CLI builds these and hands them to
+ *  [[HookBus.emit]] — the executor serialises them as JSON for stdin. */
+export type HookEvent = {
+    name: 'SessionStart';
+    session: SessionContext;
+} | {
+    name: 'UserPromptSubmit';
+    session: SessionContext;
+    prompt: string;
+} | {
+    name: 'PreToolUse';
+    session: SessionContext;
+    tool: {
+        name: string;
+        args: unknown;
+        callId: string;
+    };
+} | {
+    name: 'PostToolUse';
+    session: SessionContext;
+    tool: {
+        name: string;
+        args: unknown;
+        callId: string;
+        output: string;
+        isError: boolean;
+    };
+} | {
+    name: 'PreCompact';
+    session: SessionContext;
+    /** Why compaction is about to run — useful for hooks that want to
+     *  decide whether to checkpoint state or skip. */
+    trigger: 'proactive' | 'reactive';
+    /** Approximate message count and token count before compaction. */
+    messageCount: number;
+    tokenEstimate: number;
+} | {
+    name: 'PostCompact';
+    session: SessionContext;
+    trigger: 'proactive' | 'reactive';
+    /** Message count after compaction — the delta from PreCompact's
+     *  messageCount tells the hook how much was reclaimed. */
+    messageCount: number;
+    /** Empty string when the path was a light-compact (no LLM summary
+     *  was written). */
+    summary: string;
+} | {
+    name: 'SubagentStart';
+    session: SessionContext;
+    agent: {
+        /** The sub-agent's registered name (e.g. `code-reviewer`). */
+        name: string;
+        /** The parent agent's one-line task description. */
+        description: string;
+        /** The full prompt the parent agent sent to the sub-agent. */
+        prompt: string;
+    };
+} | {
+    name: 'SubagentStop';
+    session: SessionContext;
+    agent: {
+        name: string;
+        description: string;
+    };
+    /** Wall-clock duration of the sub-agent run. */
+    durationMs: number;
+    /** How the sub-agent finished. `aborted` includes Esc cancellation
+     *  and reaching the per-agent maxTurns cap without finalising. */
+    outcome: 'completed' | 'aborted' | 'failed';
+    tokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+} | {
+    name: 'TurnComplete';
+    session: SessionContext;
+    turn: number;
+    tokenUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+} | {
+    name: 'SessionEnd';
+    session: SessionContext;
+};
+/** What a hook can ask the agent to do via its stdout JSON. */
+export type HookDecision = {
+    decision: 'allow';
+    context?: string;
+} | {
+    decision: 'deny';
+    reason?: string;
+} | {
+    decision: 'modify';
+    args?: unknown;
+    output?: string;
+    context?: string;
+};
+/** A hook ready to execute — paired with its owning plugin's identity
+ *  and rootDir so variable expansion can resolve `${pluginDir}`. Built
+ *  by [[buildHookRegistry]] at startup, immutable for the session. */
+export interface RegisteredHook {
+    pluginId: string;
+    /** Absolute path to the plugin's root dir — substituted into the
+     *  hook command via `${pluginDir}`. */
+    pluginDir: string;
+    event: HookEventName;
+    entry: HookConfigEntry;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/hooks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/hooks/types.ts"],"names":[],"mappings":"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"}

package/dist/hooks/types.js

@@ -0,0 +1,25 @@
+// @x-code-cli/core — Hooks subsystem types
+//
+// A hook is a shell command a plugin registers against one of six agent
+// lifecycle events. The CLI emits an event payload to the hook on stdin
+// as one JSON line; the hook may reply on stdout with a one-line JSON
+// `HookDecision` to influence what the agent does next (allow / deny /
+// modify args / inject context).
+//
+// Why shell commands and not a programmatic SDK: lowest barrier to entry
+// for plugin authors, matches the format users already see in Claude
+// Code, and keeps the surface area small (no plugin code runs inside
+// our process). See [[plugin-marketplace-design]] §8 for the full
+// rationale.
+//
+// Why ten events: enough to cover the high-value lifecycle integrations
+// (context injection, tool gating, sub-agent audit, compaction
+// instrumentation, completion notifications) without exposing every
+// internal seam we may want to refactor. Adding events later is cheap;
+// removing them is a breaking change. PreCompact / PostCompact and
+// SubagentStart / SubagentStop were added in round 2 to match the
+// Claude/Codex shape — plugins that want to log every sub-agent
+// invocation or persist state before compaction wipes it had no other
+// hook to attach to.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/hooks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/hooks/types.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,EAAE;AACF,wEAAwE;AACxE,wEAAwE;AACxE,sEAAsE;AACtE,uEAAuE;AACvE,iCAAiC;AACjC,EAAE;AACF,yEAAyE;AACzE,qEAAqE;AACrE,qEAAqE;AACrE,kEAAkE;AAClE,aAAa;AACb,EAAE;AACF,wEAAwE;AACxE,+DAA+D;AAC/D,oEAAoE;AACpE,uEAAuE;AACvE,mEAAmE;AACnE,kEAAkE;AAClE,gEAAgE;AAChE,sEAAsE;AACtE,qBAAqB"}

package/dist/hooks/variables.d.ts

@@ -0,0 +1,22 @@
+export interface VariableContext {
+    pluginDir: string;
+    /** Persistent per-plugin data directory. Pre-created by
+     *  [[buildVariableContext]] when a `pluginId` is supplied. */
+    pluginDataDir?: string;
+    cwd: string;
+    homedir?: string;
+    sep?: string;
+}
+/** Default variables derived from the current process + caller context.
+ *  Pass `pluginId` to enable `${pluginDataDir}` — we'll resolve the
+ *  per-plugin data dir path and `mkdir -p` it so the plugin can write
+ *  there immediately. mkdirSync on an existing dir is a cheap no-op. */
+export declare function buildVariableContext(input: {
+    pluginDir: string;
+    cwd: string;
+    pluginId?: string;
+}): VariableContext;
+/** Expand `${pluginDir}` / `${pluginDataDir}` / `${cwd}` / `${homedir}` /
+ *  `${sep}` / `${env:NAME}` references. Unknown patterns are left verbatim. */
+export declare function expandVariables(source: string, ctx: VariableContext): string;
+//# sourceMappingURL=variables.d.ts.map