@goodfoot/agent-hooks 1.0.0

package/dist/agents/claude-code/transport.js

@@ -0,0 +1,254 @@
+/**
+ * Wire transport for Claude Code hooks.
+ *
+ * Rewritten against the core `drive()`/`Transport` interface (plan step 2.1);
+ * the wire semantics carried over from the source runtime are:
+ *
+ * - success → output JSON serialized to stdout, exit 0 (empty object `{}`
+ *   when the handler returned nothing);
+ * - a returned `stderr` payload → that message written to stderr, exit code
+ *   `EXIT_CODES.BLOCK` (2) and **no stdout write at all** — Claude Code's
+ *   hook-result parser treats any stdout that parses as JSON as success
+ *   regardless of exit code, so blocking via stderr only takes effect when
+ *   stdout carries no JSON;
+ * - an unexpected handler error under the default `"error"` policy → its
+ *   stacktrace on stderr, exit 2, no stdout;
+ * - malformed/unreadable stdin → fail-open unconditionally, `{}` + exit 0;
+ * - worktree events (`WorktreeCreate`, always; `WorktreeRemove`, when a path
+ *   is supplied) carry their plain-text payload in `rawStdout`, which is
+ *   written verbatim — the host reads stdout as the worktree path.
+ *
+ * Plus the class-finding fix new to this package: a caught
+ * {@link HookBlockError} — classified by `drive()` **before** policy is ever
+ * consulted — is translated per event via {@link BLOCK_SHAPE_BY_EVENT}
+ * (`PreToolUse`/`PermissionRequest` get their narrower native deny shapes,
+ * every other event gets `{ continue: false, stopReason }`), so an advisory
+ * event's intentional block survives even when the decision computation
+ * itself throws mid-way.
+ * @module
+ * @example
+ * ```typescript
+ * // In a compiled hook file
+ * import { execute } from './transport.js';
+ * import myHook from './my-hook.js';
+ *
+ * execute(myHook);
+ * ```
+ * @see https://code.claude.com/docs/en/hooks
+ */
+import { logger } from "../../core/logger.js";
+import { drive } from "../../core/transport.js";
+import { HOOK_EVENT_NAMES } from "./events.js";
+import { EXIT_CODES } from "./outputs.js";
+// ============================================================================
+// Block Translation
+// ============================================================================
+/**
+ * Per-event translation table for a caught {@link HookBlockError}.
+ *
+ * Absent events fall back to the whole-session shape
+ * (`{ continue: false, stopReason }`). The two entries present here are the
+ * events whose native protocol refuses *that one tool call* rather than
+ * halting the session — reusing exactly the shapes `outputs.ts`'s builders
+ * produce natively:
+ *
+ * - `PreToolUse` → `hookSpecificOutput.permissionDecision: "deny"`
+ * - `PermissionRequest` → `hookSpecificOutput.decision.behavior: "deny"`
+ */
+export const BLOCK_SHAPE_BY_EVENT = {
+    PermissionRequest: (reason) => ({
+        hookSpecificOutput: { hookEventName: "PermissionRequest", decision: { behavior: "deny", message: reason } },
+    }),
+    PreToolUse: (reason) => ({
+        hookSpecificOutput: {
+            hookEventName: "PreToolUse",
+            permissionDecision: "deny",
+            permissionDecisionReason: reason,
+        },
+    }),
+};
+/**
+ * Translates a caught {@link HookBlockError} into this event's block wire
+ * payload. The lookup is per event ({@link BLOCK_SHAPE_BY_EVENT}), never a
+ * single template applied everywhere; `error.fields` — when supplied by the
+ * thrower — is merged on top for callers needing extra wire fields (e.g.
+ * `interrupt` on a permission deny).
+ */
+function translateBlockToPayload(eventName, error) {
+    const reason = error.message;
+    const known = HOOK_EVENT_NAMES.includes(eventName) ? eventName : undefined;
+    const payload = known !== undefined
+        ? (BLOCK_SHAPE_BY_EVENT[known]?.(reason) ?? { continue: false, stopReason: reason })
+        : { continue: false, stopReason: reason };
+    if (error.fields !== undefined) {
+        Object.assign(payload, error.fields);
+    }
+    return payload;
+}
+// ============================================================================
+// Output Conversion
+// ============================================================================
+/**
+ * Converts a SpecificHookOutput to HookOutput for wire format.
+ *
+ * SpecificHookOutput types have: { _type, stdout, stderr?, rawStdout? }
+ * HookOutput has: { stdout, stderr?, rawStdout? }
+ *
+ * Since output builders now produce wire-format directly, this function
+ * simply strips the `_type` discriminator field.
+ * @param specificOutput - The specific output from a hook handler
+ * @returns HookOutput ready for serialization
+ * @see https://code.claude.com/docs/en/hooks#hook-output-structure
+ */
+export function convertToHookOutput(specificOutput) {
+    const { stdout, stderr, rawStdout } = specificOutput;
+    const result = { stdout };
+    if (stderr !== undefined) {
+        result.stderr = stderr;
+    }
+    if (rawStdout !== undefined) {
+        result.rawStdout = rawStdout;
+    }
+    return result;
+}
+/** Renders any thrown value the way the source runtime wrote it to stderr. */
+function formatErrorText(error) {
+    return error instanceof Error ? `${error.stack ?? error.message}\n` : `${String(error)}\n`;
+}
+/**
+ * Plain-text-protocol detector: which factories' outputs carry a bare-string
+ * stdout payload the host reads verbatim. `WorktreeCreate` always does (its
+ * builder requires `worktreePath`); `WorktreeRemove` only when a path was
+ * supplied. Every other event returns undefined and stays on the JSON path.
+ */
+function detectRawStdout(output) {
+    if (output._type === "WorktreeCreate" || output._type === "WorktreeRemove") {
+        return output.rawStdout;
+    }
+    return undefined;
+}
+// ============================================================================
+// Transport
+// ============================================================================
+/**
+ * Builds the Claude Code wire transport for one event.
+ *
+ * `policy`/`onUnexpectedError` close over the executing hook's configuration
+ * purely to reproduce the source runtime's serialize-failure wiring: under
+ * `"continue"` a serialization failure still emits `{}` at exit 0, while the
+ * default `"error"` policy surfaces the stacktrace and exits
+ * `EXIT_CODES.ERROR`. Every other policy decision (block precedence,
+ * swallow-vs-surface of unexpected throws) lives in `drive()`.
+ * @param eventName - The bound hook event name (drives the block translation)
+ * @param policy - The executing hook's resolved fail-open policy
+ * @param onUnexpectedError - Optional diagnostic sink, forwarded for parity
+ * with the source runtime's serialize-failure reporting.
+ */
+export function createClaudeCodeTransport(eventName, policy, onUnexpectedError) {
+    return {
+        finalize(outcome) {
+            switch (outcome.kind) {
+                case "response": {
+                    const converted = outcome.output === null || outcome.output === undefined ? undefined : convertToHookOutput(outcome.output);
+                    // Exit-code BLOCK: the handler's own intentional signal (e.g.
+                    // `teammateIdleOutput({ stderr })`), unaffected by `policy`. No
+                    // stdout write on this path — see module docs.
+                    if (converted?.stderr !== undefined) {
+                        return { stderr: converted.stderr, exitCode: EXIT_CODES.BLOCK };
+                    }
+                    let serializedText;
+                    try {
+                        serializedText =
+                            converted?.rawStdout !== undefined ? converted.rawStdout : JSON.stringify(converted?.stdout ?? {});
+                    }
+                    catch (error) {
+                        logger.logError(error, "Failed to serialize hook output");
+                        if (policy !== "continue") {
+                            return { stderr: formatErrorText(error), exitCode: EXIT_CODES.ERROR };
+                        }
+                        onUnexpectedError?.(error, "serialize");
+                        serializedText = "{}";
+                    }
+                    return { stdout: serializedText, exitCode: EXIT_CODES.SUCCESS };
+                }
+                case "rawStdout":
+                    return { stdout: outcome.stdout, exitCode: EXIT_CODES.SUCCESS };
+                case "block": {
+                    // Intentional block signal via HookBlockError: translated per event
+                    // onto the success channel (JSON stdout, exit 0) — never the
+                    // exit-code BLOCK path above, which carries no machine-readable
+                    // decision.
+                    return {
+                        stdout: JSON.stringify(translateBlockToPayload(eventName, outcome.error)),
+                        exitCode: EXIT_CODES.SUCCESS,
+                    };
+                }
+                case "handlerError": {
+                    // Malformed/unreadable stdin fails open unconditionally, matching
+                    // the source runtime's long-standing default for every hook.
+                    if (outcome.phase === "read" || outcome.phase === "parse") {
+                        logger.error(`Invalid JSON input: ${outcome.error instanceof Error ? outcome.error.message : String(outcome.error)}`);
+                        return { stdout: "{}", exitCode: EXIT_CODES.SUCCESS };
+                    }
+                    // Unexpected handler throw surfaced under the default policy:
+                    // stacktrace to stderr, exit 2 (BLOCK), no JSON on stdout.
+                    logger.error(`Hook handler error: ${outcome.error instanceof Error ? outcome.error.message : String(outcome.error)}`);
+                    return { stderr: formatErrorText(outcome.error), exitCode: EXIT_CODES.BLOCK };
+                }
+            }
+        },
+        rawStdout: detectRawStdout,
+    };
+}
+// ============================================================================
+// Execute
+// ============================================================================
+/**
+ * Executes a hook handler with full runtime orchestration (delegates to the
+ * shared core driver with this agent's transport).
+ *
+ * This is the main entry point that compiled hooks use. When a compiled hook
+ * runs as a CLI:
+ *
+ * 1. Reads all stdin
+ * 2. Parses JSON (wire format with snake_case properties)
+ * 3. Sets up logger context (hookType, input)
+ * 4. Calls handler with input and context (logger)
+ * 5. Handles any errors, logs them
+ * 6. Writes JSON to stdout
+ * 7. Closes logger
+ * 8. Exits with appropriate code
+ * @param hookFn - The hook function to execute (from hook factory)
+ * @example
+ * ```typescript
+ * // In compiled hook file
+ * import { execute } from '@goodfoot/agent-hooks/claude-code/runtime';
+ * import { preToolUseHook, preToolUseOutput } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * const myHook = preToolUseHook({ matcher: 'Bash' }, async (input, { logger }) => {
+ *   logger.info('Processing Bash command');
+ *   return preToolUseOutput({ allow: true });
+ * });
+ *
+ * execute(myHook);
+ * ```
+ * @see https://code.claude.com/docs/en/hooks
+ */
+export async function execute(hookFn) {
+    const policy = hookFn.unexpectedError ?? "error";
+    const transport = createClaudeCodeTransport(hookFn.eventName, policy, hookFn.onUnexpectedError);
+    // Soundness note: a factory-built hook whose context extends the base (only
+    // SessionStart today) attaches its own `createContext`, so `drive()` hands
+    // the handler the extended context it declares; the variance narrowing here
+    // never substitutes the base context for a required extended one.
+    //
+    // NOTE on the stream-write phase: the shared driver performs the buffered
+    // stream writes after `finalize` without an unexpectedError-policy gate.
+    // The source runtime gated that phase like every other unexpected failure
+    // (reported + exit 0 under "continue", stacktrace + ERROR(1) under the
+    // default policy); reproducing that here is impossible without re-catching
+    // `drive()`'s own completion exits, which would intercept every legitimate
+    // `process.exit` path. The gate belongs where the writes happen: see the
+    // task-2 report for the exact core need.
+    await drive(transport, hookFn);
+}

package/dist/agents/claude-code/types.js

@@ -0,0 +1,11 @@
+/**
+ * Type definitions for Claude Code hooks.
+ *
+ * This module provides:
+ * - Hook input types (wire format with snake_case)
+ * - Tool input types for type guards
+ * - SDK type re-exports for extension and reference
+ * @see https://code.claude.com/docs/en/hooks
+ * @module
+ */
+export {};

package/dist/agents/codex/cli-support.js

@@ -0,0 +1,318 @@
+/**
+ * Codex-specific CLI internals: AST analysis (with `statusMessage`), bundle
+ * compilation linking the Codex runtime module, command-context detection
+ * (`.codex-plugin` marker / `.codex` local mode / absolute), hooks.json
+ * generation with Codex's matcher/timeout-seconds/statusMessage rules, and
+ * plugin-mode stable-names default.
+ *
+ * Driver-level primitives (loader parsing, glob discovery, content hashing,
+ * symlink re-rooting, stale-bundle pruning) are imported from the shared CLI
+ * module — never re-derived here.
+ * @module
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as esbuild from "esbuild";
+import ts from "typescript";
+import { buildEsbuildLoaderMap, discoverHookSourceFiles, parseEsbuildLoaderFlag, pruneStaleHashedBundles, sha256Prefix8, symlinkVisiblePath, } from "../../cli.js";
+import { EVENTS_WITH_MATCHER, HOOK_FACTORY_TO_EVENT } from "./constants.js";
+/**
+ * Extracts Codex hook metadata (event name, matcher, timeout in
+ * milliseconds, status message) from a TypeScript source file's default
+ * export of a hook factory call.
+ */
+export function analyzeCodexHookFile(sourcePath) {
+    const sourceCode = fs.readFileSync(sourcePath, "utf-8");
+    const sourceFile = ts.createSourceFile(sourcePath, sourceCode, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    let metadata;
+    function extractFromExpression(expression) {
+        if (ts.isParenthesizedExpression(expression)) {
+            return extractFromExpression(expression.expression);
+        }
+        if (!ts.isCallExpression(expression)) {
+            return undefined;
+        }
+        let factoryName;
+        if (ts.isIdentifier(expression.expression)) {
+            factoryName = expression.expression.text;
+        }
+        else if (ts.isPropertyAccessExpression(expression.expression)) {
+            factoryName = expression.expression.name.text;
+        }
+        if (factoryName === undefined) {
+            return undefined;
+        }
+        const hookEventName = HOOK_FACTORY_TO_EVENT[factoryName];
+        if (hookEventName === undefined) {
+            return undefined;
+        }
+        let matcher;
+        let timeout;
+        let statusMessage;
+        const configArg = expression.arguments[0];
+        if (configArg !== undefined && ts.isObjectLiteralExpression(configArg)) {
+            for (const property of configArg.properties) {
+                if (!ts.isPropertyAssignment(property)) {
+                    continue;
+                }
+                const name = ts.isIdentifier(property.name) ? property.name.text : undefined;
+                if (name === undefined) {
+                    continue;
+                }
+                if (name === "matcher" &&
+                    (ts.isStringLiteral(property.initializer) || ts.isNoSubstitutionTemplateLiteral(property.initializer))) {
+                    matcher = property.initializer.text;
+                }
+                if (name === "statusMessage" &&
+                    (ts.isStringLiteral(property.initializer) || ts.isNoSubstitutionTemplateLiteral(property.initializer))) {
+                    statusMessage = property.initializer.text;
+                }
+                if (name === "timeout" && ts.isNumericLiteral(property.initializer)) {
+                    timeout = Number(property.initializer.text);
+                }
+            }
+        }
+        return { hookEventName, matcher, timeout, statusMessage };
+    }
+    function visit(node) {
+        if (ts.isExportAssignment(node) && !node.isExportEquals) {
+            metadata = extractFromExpression(node.expression);
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(sourceFile);
+    return metadata;
+}
+/**
+ * Compiles one Codex hook to a self-contained ESM executable whose entry
+ * wrapper imports this package's Codex runtime module (`execute`).
+ */
+export async function compileCodexHook(sourcePath, loaders, sourcemap = true) {
+    const resolveDir = path.dirname(sourcePath);
+    const runtimePathAbsolute = symlinkVisiblePath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "./transport.js"), resolveDir);
+    let relativeRuntimePath = path.relative(resolveDir, runtimePathAbsolute).replace(/\\/g, "/");
+    if (!relativeRuntimePath.startsWith(".")) {
+        relativeRuntimePath = `./${relativeRuntimePath}`;
+    }
+    const relativeSourcePath = `./${path.basename(sourcePath)}`.replace(/\\/g, "/");
+    const wrapperContent = `import hook from ${JSON.stringify(relativeSourcePath)};
+import { execute } from ${JSON.stringify(relativeRuntimePath)};
+execute(hook);
+`;
+    const baseName = path.basename(sourcePath, path.extname(sourcePath));
+    const result = await esbuild.build({
+        stdin: {
+            contents: wrapperContent,
+            resolveDir,
+            sourcefile: `${baseName}-entry.ts`,
+            loader: "ts",
+        },
+        loader: loaders,
+        format: "esm",
+        platform: "node",
+        target: "node20",
+        bundle: true,
+        sourcemap: sourcemap ? "inline" : false,
+        write: false,
+        external: ["node:*", "fs", "path", "os", "crypto", "module", "url"],
+        mainFields: ["module", "main"],
+        conditions: ["import", "node"],
+        preserveSymlinks: true,
+    });
+    const content = result.outputFiles?.[0]?.text;
+    if (content === undefined) {
+        throw new Error(`esbuild produced no output for ${sourcePath}`);
+    }
+    return { content, contentHash: sha256Prefix8(content) };
+}
+async function compileAllCodexHooks(hookFiles, outputDir, loaders, options) {
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+    const compiledHooks = [];
+    const writtenFilenames = new Set();
+    for (const sourcePath of hookFiles) {
+        const metadata = analyzeCodexHookFile(sourcePath);
+        if (metadata === undefined) {
+            continue;
+        }
+        const { content, contentHash } = await compileCodexHook(sourcePath, loaders, options.sourcemap);
+        const baseName = path.basename(sourcePath, path.extname(sourcePath));
+        const outputFilename = options.stableNames ? `${baseName}.mjs` : `${baseName}.${contentHash}.mjs`;
+        const outputPath = path.join(outputDir, outputFilename);
+        fs.writeFileSync(outputPath, `#!/usr/bin/env -S node --enable-source-maps\n${content}`, {
+            encoding: "utf-8",
+            mode: 0o755,
+        });
+        writtenFilenames.add(outputFilename);
+        compiledHooks.push({ sourcePath, outputPath, outputFilename, metadata });
+    }
+    if (options.stableNames) {
+        pruneStaleHashedBundles(outputDir, writtenFilenames);
+    }
+    return compiledHooks;
+}
+/**
+ * Detects the command context: `.codex-plugin/` marker found by walking up
+ * from the output → plugin mode; explicit `--plugin-root` flag → plugin mode
+ * anchored at the output's parent; output under a `/.codex` segment →
+ * codex-local mode; otherwise absolute.
+ */
+export function detectCodexCommandContext(outputPath, pluginRootFlag) {
+    const normalizedOutputPath = outputPath.replace(/\\/g, "/");
+    let currentDir = path.dirname(outputPath);
+    const filesystemRoot = path.parse(currentDir).root;
+    const maxLevels = 4;
+    let level = 0;
+    while (currentDir !== filesystemRoot && level < maxLevels) {
+        const marker = path.join(currentDir, ".codex-plugin");
+        if (fs.existsSync(marker) && fs.statSync(marker).isDirectory()) {
+            return { mode: "plugin", pluginRoot: currentDir };
+        }
+        currentDir = path.dirname(currentDir);
+        level++;
+    }
+    if (pluginRootFlag) {
+        const hooksDir = path.dirname(outputPath);
+        return { mode: "plugin", pluginRoot: path.dirname(hooksDir) };
+    }
+    if (normalizedOutputPath.indexOf("/.codex") >= 0) {
+        return { mode: "codex-local" };
+    }
+    return { mode: "absolute" };
+}
+function timeoutMsToSeconds(timeout) {
+    if (timeout === undefined) {
+        return undefined;
+    }
+    return Math.max(1, Math.ceil(timeout / 1000));
+}
+function groupCodexHooksByEventAndMatcher(compiledHooks) {
+    const grouped = new Map();
+    for (const hook of compiledHooks) {
+        const eventGroup = grouped.get(hook.metadata.hookEventName) ?? new Map();
+        grouped.set(hook.metadata.hookEventName, eventGroup);
+        const matcherKey = EVENTS_WITH_MATCHER.has(hook.metadata.hookEventName) ? hook.metadata.matcher : undefined;
+        const matcherGroup = eventGroup.get(matcherKey) ?? [];
+        matcherGroup.push(hook);
+        eventGroup.set(matcherKey, matcherGroup);
+    }
+    return grouped;
+}
+function shellQuote(value) {
+    return JSON.stringify(value);
+}
+function generateCodexCommandPath(outputPath, hookOutputPath, executable, context) {
+    const normalizedHookPath = hookOutputPath.replace(/\\/g, "/");
+    if (context.mode === "plugin" && context.pluginRoot !== undefined) {
+        const relativeHookPath = path.relative(context.pluginRoot, hookOutputPath).replace(/\\/g, "/");
+        return `${executable} ${shellQuote(`\${PLUGIN_ROOT}/${relativeHookPath}`)}`;
+    }
+    if (context.mode === "codex-local") {
+        const normalizedOutputPath = outputPath.replace(/\\/g, "/");
+        const repoMarkerIndex = normalizedOutputPath.indexOf("/.codex");
+        if (repoMarkerIndex >= 0) {
+            const repoRoot = normalizedOutputPath.slice(0, repoMarkerIndex);
+            const relativeHookPath = path.relative(repoRoot, hookOutputPath).replace(/\\/g, "/");
+            return `${executable} "$(git rev-parse --show-toplevel)/${relativeHookPath}"`;
+        }
+    }
+    return `${executable} ${shellQuote(normalizedHookPath)}`;
+}
+/** Generates Codex hooks.json: matchers only where the event supports them, timeouts in seconds, statusMessage when set. */
+export function generateCodexHooksJson(compiledHooks, outputPath, executable = "node", context = detectCodexCommandContext(outputPath, false)) {
+    const grouped = groupCodexHooksByEventAndMatcher(compiledHooks);
+    const hooks = {};
+    for (const eventName of [
+        "PreToolUse",
+        "PostToolUse",
+        "PermissionRequest",
+        "UserPromptSubmit",
+        "SessionStart",
+        "SubagentStart",
+        "Stop",
+        "SubagentStop",
+        "PreCompact",
+        "PostCompact",
+    ]) {
+        const matcherMap = grouped.get(eventName);
+        if (matcherMap === undefined) {
+            continue;
+        }
+        hooks[eventName] = Array.from(matcherMap.entries()).map(([matcher, entries]) => ({
+            ...(EVENTS_WITH_MATCHER.has(eventName) && matcher !== undefined ? { matcher } : {}),
+            hooks: entries.map((entry) => ({
+                type: "command",
+                command: generateCodexCommandPath(outputPath, entry.outputPath, executable, context),
+                ...(timeoutMsToSeconds(entry.metadata.timeout) !== undefined
+                    ? { timeout: timeoutMsToSeconds(entry.metadata.timeout) }
+                    : {}),
+                ...(entry.metadata.statusMessage !== undefined ? { statusMessage: entry.metadata.statusMessage } : {}),
+            })),
+        }));
+    }
+    return { hooks };
+}
+/**
+ * Validates Codex build/scaffold arguments beyond the shared `--agent` gate:
+ * `-i` and `-o` required for build mode; scaffold requires `--hooks` and
+ * `-o`.
+ */
+export function validateCodexArgs(args) {
+    if (args.scaffold !== undefined && args.scaffold !== "") {
+        if (args.output === "") {
+            return "Scaffold mode requires -o/--output";
+        }
+        if (args.hooks === undefined || args.hooks === "") {
+            return "Scaffold mode requires --hooks";
+        }
+        return undefined;
+    }
+    if (args.input === "") {
+        return "Missing required argument: -i/--input";
+    }
+    if (args.output === "") {
+        return "Missing required argument: -o/--output";
+    }
+    for (const loaderFlag of args.loaderFlags) {
+        if (parseEsbuildLoaderFlag(loaderFlag) === undefined) {
+            return `Invalid --loader value: ${loaderFlag}. Expected .ext=type`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Runs the Codex build/scaffold branch of the unified CLI. Plugin mode
+ * defaults to hash-free stable filenames; every other mode defaults to
+ * hashed names unless `--stable-names` is passed explicitly (source
+ * parity).
+ */
+export async function runCodexCli(args) {
+    if (args.scaffold !== undefined && args.scaffold !== "") {
+        const { scaffoldProject } = await import("./scaffold.js");
+        scaffoldProject({
+            directory: path.resolve(process.cwd(), args.scaffold),
+            hooks: (args.hooks ?? "")
+                .split(",")
+                .map((value) => value.trim())
+                .filter(Boolean),
+            outputPath: args.output,
+        });
+        return;
+    }
+    const cwd = process.cwd();
+    const hookFiles = await discoverHookSourceFiles(args.input, cwd);
+    const absoluteOutputPath = path.resolve(cwd, args.output);
+    const outputDir = path.dirname(absoluteOutputPath);
+    const context = detectCodexCommandContext(absoluteOutputPath, args.pluginRoot);
+    const stableNames = args.stableNames ?? context.mode === "plugin";
+    const sourcemap = args.sourcemap ?? true;
+    const loaders = buildEsbuildLoaderMap(args.loaderFlags);
+    const compiledHooks = await compileAllCodexHooks(hookFiles, outputDir, loaders, {
+        stableNames,
+        sourcemap,
+    });
+    const hooksJson = generateCodexHooksJson(compiledHooks, absoluteOutputPath, args.executable ?? "node", context);
+    fs.writeFileSync(absoluteOutputPath, `${JSON.stringify(hooksJson, null, 2)}\n`);
+}

package/dist/agents/codex/constants.js

@@ -0,0 +1,29 @@
+export const PACKAGE_NAME = "@goodfoot/agent-hooks";
+export const DEFAULT_TIMEOUT_MS = 600_000;
+export const DEFAULT_STATUS_MESSAGE = undefined;
+export const DEFAULT_ESBUILD_LOADERS = {
+    ".md": "text",
+};
+export const HOOK_FACTORY_TO_EVENT = {
+    preToolUseHook: "PreToolUse",
+    postToolUseHook: "PostToolUse",
+    permissionRequestHook: "PermissionRequest",
+    userPromptSubmitHook: "UserPromptSubmit",
+    sessionStartHook: "SessionStart",
+    subagentStartHook: "SubagentStart",
+    stopHook: "Stop",
+    subagentStopHook: "SubagentStop",
+    preCompactHook: "PreCompact",
+    postCompactHook: "PostCompact",
+};
+export const EVENTS_WITH_MATCHER = new Set([
+    "PreToolUse",
+    "PostToolUse",
+    "PermissionRequest",
+    "SessionStart",
+    "SubagentStart",
+    "SubagentStop",
+    "PreCompact",
+    "PostCompact",
+]);
+export const EVENTS_WITH_TEXT_OUTPUT = new Set(["SessionStart", "UserPromptSubmit", "SubagentStart"]);

package/dist/agents/codex/events.js

@@ -0,0 +1,68 @@
+/**
+ * Codex hook event names and the advisory fail-open allow-list.
+ *
+ * `HOOK_EVENT_NAMES` mirrors the `HookEventName` union in `types.ts` (10
+ * events). The advisory allow-list is **not** authored here: per the plan's
+ * derivation rule it is transcribed from `codex-hooks/README.md` — quoted
+ * below above the provenance notes — and `ADVISORY_EVENTS` is derived
+ * mechanically as "every event except the exclusion set". The unit test in
+ * `tests/agents/codex/` transcribes the same sentence a second time,
+ * independently, so the runtime list and the test oracle are two copies of
+ * the citation rather than one list read twice.
+ * @module
+ */
+/**
+ * All Codex hook event names as a readonly array (same order as the
+ * `HookEventName` union).
+ */
+export const HOOK_EVENT_NAMES = [
+    "PreToolUse",
+    "PostToolUse",
+    "PermissionRequest",
+    "UserPromptSubmit",
+    "SessionStart",
+    "SubagentStart",
+    "Stop",
+    "SubagentStop",
+    "PreCompact",
+    "PostCompact",
+];
+/**
+ * Events never allowed the fail-open `unexpectedError: "continue"` policy.
+ *
+ * Transcribed verbatim from codex-hooks/README.md (Fail-Open Execution
+ * section):
+ *
+ * > Only opt in for **advisory enrichment hooks** — ones that add optional
+ * > context and whose failure should be invisible to the user (e.g.
+ * > `UserPromptSubmit`, `SessionStart`, `SubagentStart` context nudges). Do
+ * > not use `"continue"` for hooks that make permission, safety, or policy
+ * > decisions (`PreToolUse`, `PermissionRequest`, blocking
+ * > `PostToolUse`/`Stop`/`SubagentStop` checks) — silently swallowing a
+ * > failure there means the hook's decision was silently skipped.
+ *
+ * Provenance of each element:
+ *
+ * - `PreToolUse`, `PermissionRequest`, blocking `PostToolUse`/`Stop`/
+ *   `SubagentStop` — named verbatim in the README sentence above.
+ * - `PreCompact`, `PostCompact` — **not mentioned anywhere in the README**;
+ *   excluded by default (fail-closed) until a future card's docs justify an
+ *   entry. This is a stated default, not a silent gap (plan Decisions).
+ */
+export const EXCLUDED_FROM_ADVISORY = [
+    "PreToolUse",
+    "PostToolUse",
+    "PermissionRequest",
+    "Stop",
+    "SubagentStop",
+    "PreCompact",
+    "PostCompact",
+];
+/**
+ * The advisory allow-list: every Codex event except
+ * {@link EXCLUDED_FROM_ADVISORY} — exactly the README's three named
+ * enrichment hooks. Only these accept `unexpectedError: "continue"`,
+ * enforced at factory-call time by the injected policy gate and at compile
+ * time by the excluded events' narrowed config types.
+ */
+export const ADVISORY_EVENTS = HOOK_EVENT_NAMES.filter((eventName) => !EXCLUDED_FROM_ADVISORY.includes(eventName));