@goodfoot/agent-hooks 1.0.0

package/dist/agents/codex/hooks.js

@@ -0,0 +1,93 @@
+/**
+ * Typed factory functions for Codex hooks, built on the shared core
+ * {@link ../core/define-hook.ts|defineHook}.
+ *
+ * Public surface mirrors the source codex-hooks package 1.3.0: same factory names,
+ * config shapes (`MatcherHookConfig`/`NoMatcherHookConfig`, including
+ * `statusMessage`), result unions, and `hookEventName` metadata property.
+ * Two deliberate additions carry the consolidation contract:
+ *
+ * - every factory injects the advisory allow-list policy gate, so
+ *   `unexpectedError: "continue"` fails closed at factory-call time for any
+ *   event not on {@link ADVISORY_EVENTS};
+ * - non-advisory events' config types narrow the policy field via
+ *   {@link MatcherHookConfigFor}/{@link NoMatcherHookConfigFor}, rejecting
+ *   `"continue"` at compile time as well.
+ * @module
+ */
+import { defineHook } from "../../core/define-hook.js";
+import { ADVISORY_EVENTS } from "./events.js";
+// ============================================================================
+// Generic Factory
+// ============================================================================
+/**
+ * The runtime policy gate injected into every Codex factory: rejects
+ * `unexpectedError: "continue"` at factory-call time for any event not on
+ * the advisory allow-list ({@link ADVISORY_EVENTS}). Mirrors the Claude Code
+ * surface's gate exactly — one closure serves all ten events because the
+ * gate receives the event name.
+ */
+const advisoryPolicyGate = (eventName, policy) => policy !== "continue" || ADVISORY_EVENTS.includes(eventName);
+/**
+ * Creates a Codex hook function for a specific event on the shared core.
+ * Binds the event name, injects the advisory allow-list policy gate, and
+ * carries the Codex-specific `statusMessage` through to the returned
+ * metadata.
+ * @internal
+ */
+function createHookFunction(hookEventName, config, handler) {
+    const coreConfig = {
+        matcher: "matcher" in config ? config.matcher : undefined,
+        timeout: config.timeout,
+        unexpectedError: config.unexpectedError,
+        onUnexpectedError: config.onUnexpectedError,
+    };
+    const hookFn = defineHook(hookEventName, coreConfig, handler, advisoryPolicyGate);
+    const codexFn = hookFn;
+    codexFn.hookEventName = hookEventName;
+    codexFn.statusMessage = config.statusMessage;
+    return codexFn;
+}
+// ============================================================================
+// Factories (signatures copied from the source package; configs narrowed)
+// ============================================================================
+/** Creates a PreToolUse hook handler. Excluded from the advisory list. */
+export function preToolUseHook(config, handler) {
+    return createHookFunction("PreToolUse", config, handler);
+}
+/** Creates a PostToolUse hook handler. Blocking variant excluded from the advisory list. */
+export function postToolUseHook(config, handler) {
+    return createHookFunction("PostToolUse", config, handler);
+}
+/** Creates a PermissionRequest hook handler. Excluded from the advisory list. */
+export function permissionRequestHook(config, handler) {
+    return createHookFunction("PermissionRequest", config, handler);
+}
+/** Creates a UserPromptSubmit hook handler. Advisory enrichment hook. */
+export function userPromptSubmitHook(config, handler) {
+    return createHookFunction("UserPromptSubmit", config, handler);
+}
+/** Creates a SessionStart hook handler. Advisory enrichment hook. */
+export function sessionStartHook(config, handler) {
+    return createHookFunction("SessionStart", config, handler);
+}
+/** Creates a SubagentStart hook handler. Advisory enrichment hook. */
+export function subagentStartHook(config, handler) {
+    return createHookFunction("SubagentStart", config, handler);
+}
+/** Creates a Stop hook handler. Blocking variant excluded from the advisory list. */
+export function stopHook(config, handler) {
+    return createHookFunction("Stop", config, handler);
+}
+/** Creates a SubagentStop hook handler. Blocking variant excluded from the advisory list. */
+export function subagentStopHook(config, handler) {
+    return createHookFunction("SubagentStop", config, handler);
+}
+/** Creates a PreCompact hook handler. Excluded by default pending doc clarification. */
+export function preCompactHook(config, handler) {
+    return createHookFunction("PreCompact", config, handler);
+}
+/** Creates a PostCompact hook handler. Excluded by default pending doc clarification. */
+export function postCompactHook(config, handler) {
+    return createHookFunction("PostCompact", config, handler);
+}

package/dist/agents/codex/index.js

@@ -0,0 +1,21 @@
+/**
+ * `@goodfoot/agent-hooks/codex` — the Codex agent surface.
+ *
+ * Re-exports all 10 hook factories, their output builders (reserved fields
+ * emitted only when passed), the `BlockError` block signal, input/output
+ * types, constants, the advisory allow-list events module, Logger, and the
+ * runtime `execute` entry point. No default export.
+ * @module
+ */
+// Logger exports
+export { LOG_LEVELS, Logger, logger } from "../../core/logger.js";
+// Constants
+export { DEFAULT_ESBUILD_LOADERS, DEFAULT_TIMEOUT_MS, EVENTS_WITH_MATCHER, EVENTS_WITH_TEXT_OUTPUT, HOOK_FACTORY_TO_EVENT, PACKAGE_NAME, } from "./constants.js";
+// Advisory allow-list events
+export { ADVISORY_EVENTS, EXCLUDED_FROM_ADVISORY, HOOK_EVENT_NAMES } from "./events.js";
+// Hook factory functions - all 10 event types
+export { permissionRequestHook, postCompactHook, postToolUseHook, preCompactHook, preToolUseHook, sessionStartHook, stopHook, subagentStartHook, subagentStopHook, userPromptSubmitHook, } from "./hooks.js";
+// Output types and builders (BlockError subclasses core HookBlockError)
+export { BlockError, EXIT_CODES, permissionRequestOutput, postCompactOutput, postToolUseOutput, preCompactOutput, preToolUseLegacyBlockOutput, preToolUseOutput, rawOutput, sessionStartOutput, stopOutput, subagentStartOutput, subagentStopOutput, userPromptSubmitOutput, } from "./outputs.js";
+// Runtime exports - execute function and wire conversion
+export { convertToHookOutput, createCodexTransport, execute } from "./transport.js";

package/dist/agents/codex/outputs.js

@@ -0,0 +1,189 @@
+import { HookBlockError } from "../../core/transport.js";
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    ERROR: 1,
+    BLOCK: 2,
+};
+/**
+ * The Codex block signal, carried into the new package as a subclass of the
+ * shared core {@link ../core/transport.ts|HookBlockError} so `drive()`
+ * classifies it **before** consulting `unexpectedError` policy — carrying an
+ * ordering the source runtime already implemented (`runtime.ts` tested
+ * `instanceof BlockError` ahead of the policy branch). Public surface is
+ * preserved: `name`, `reason`, and `instanceof BlockError` semantics are
+ * unchanged, and `instanceof HookBlockError` now also holds.
+ */
+export class BlockError extends HookBlockError {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.name = "BlockError";
+        this.reason = reason;
+    }
+}
+function omitUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function buildOutput(type, stdout, stderr) {
+    return {
+        _type: type,
+        stdout: omitUndefined(stdout),
+        ...(stderr !== undefined ? { stderr } : {}),
+    };
+}
+export function rawOutput(stdout, stderr) {
+    return buildOutput("Raw", stdout, stderr);
+}
+export function preToolUseOutput(options = {}) {
+    const hasSpecific = options.additionalContext !== undefined ||
+        options.permissionDecision !== undefined ||
+        options.permissionDecisionReason !== undefined ||
+        options.updatedInput !== undefined;
+    const hookSpecificOutput = hasSpecific
+        ? omitUndefined({
+            hookEventName: "PreToolUse",
+            additionalContext: options.additionalContext,
+            permissionDecision: options.permissionDecision,
+            permissionDecisionReason: options.permissionDecisionReason,
+            updatedInput: options.updatedInput,
+        })
+        : undefined;
+    return buildOutput("PreToolUse", {
+        continue: options.continue,
+        stopReason: options.stopReason,
+        suppressOutput: options.suppressOutput,
+        systemMessage: options.systemMessage,
+        decision: options.decision,
+        reason: options.reason,
+        hookSpecificOutput,
+    });
+}
+export function preToolUseLegacyBlockOutput(options) {
+    return buildOutput("PreToolUse", {
+        systemMessage: options.systemMessage,
+        decision: options.decision,
+        reason: options.reason,
+    });
+}
+export function postToolUseOutput(options = {}) {
+    const hasSpecific = options.additionalContext !== undefined || options.updatedMCPToolOutput !== undefined;
+    const hookSpecificOutput = hasSpecific
+        ? omitUndefined({
+            hookEventName: "PostToolUse",
+            additionalContext: options.additionalContext,
+            updatedMCPToolOutput: options.updatedMCPToolOutput,
+        })
+        : undefined;
+    return buildOutput("PostToolUse", {
+        continue: options.continue,
+        stopReason: options.stopReason,
+        suppressOutput: options.suppressOutput,
+        systemMessage: options.systemMessage,
+        decision: options.decision,
+        reason: options.reason,
+        hookSpecificOutput,
+    });
+}
+export function permissionRequestOutput(options) {
+    const decision = omitUndefined({
+        behavior: options.behavior,
+        message: options.message,
+        interrupt: options.interrupt,
+        updatedInput: options.updatedInput,
+        updatedPermissions: options.updatedPermissions,
+    });
+    const hookSpecificOutput = {
+        hookEventName: "PermissionRequest",
+        decision,
+    };
+    return buildOutput("PermissionRequest", {
+        continue: options.continue,
+        stopReason: options.stopReason,
+        suppressOutput: options.suppressOutput,
+        systemMessage: options.systemMessage,
+        hookSpecificOutput,
+    });
+}
+export function userPromptSubmitOutput(options = {}) {
+    const hookSpecificOutput = options.additionalContext !== undefined
+        ? {
+            hookEventName: "UserPromptSubmit",
+            additionalContext: options.additionalContext,
+        }
+        : undefined;
+    return buildOutput("UserPromptSubmit", {
+        continue: options.continue,
+        stopReason: options.stopReason,
+        suppressOutput: options.suppressOutput,
+        systemMessage: options.systemMessage,
+        decision: options.decision,
+        reason: options.reason,
+        hookSpecificOutput,
+    });
+}
+export function sessionStartOutput(options = {}) {
+    const hookSpecificOutput = options.additionalContext !== undefined
+        ? {
+            hookEventName: "SessionStart",
+            additionalContext: options.additionalContext,
+        }
+        : undefined;
+    return buildOutput("SessionStart", {
+        continue: options.continue,
+        stopReason: options.stopReason,
+        suppressOutput: options.suppressOutput,
+        systemMessage: options.systemMessage,
+        hookSpecificOutput,
+    });
+}
+export function subagentStartOutput(options = {}) {
+    const hookSpecificOutput = options.additionalContext !== undefined
+        ? {
+            hookEventName: "SubagentStart",
+            additionalContext: options.additionalContext,
+        }
+        : undefined;
+    return buildOutput("SubagentStart", {
+        continue: options.continue,
+        stopReason: options.stopReason,
+        suppressOutput: options.suppressOutput,
+        systemMessage: options.systemMessage,
+        hookSpecificOutput,
+    });
+}
+export function stopOutput(options = {}) {
+    return buildOutput("Stop", {
+        continue: options.continue,
+        stopReason: options.stopReason,
+        suppressOutput: options.suppressOutput,
+        systemMessage: options.systemMessage,
+        decision: options.decision,
+        reason: options.reason,
+    });
+}
+export function subagentStopOutput(options = {}) {
+    return buildOutput("SubagentStop", {
+        continue: options.continue,
+        stopReason: options.stopReason,
+        suppressOutput: options.suppressOutput,
+        systemMessage: options.systemMessage,
+        decision: options.decision,
+        reason: options.reason,
+    });
+}
+export function preCompactOutput(options = {}) {
+    return buildOutput("PreCompact", {
+        continue: options.continue,
+        stopReason: options.stopReason,
+        suppressOutput: options.suppressOutput,
+        systemMessage: options.systemMessage,
+    });
+}
+export function postCompactOutput(options = {}) {
+    return buildOutput("PostCompact", {
+        continue: options.continue,
+        stopReason: options.stopReason,
+        suppressOutput: options.suppressOutput,
+        systemMessage: options.systemMessage,
+    });
+}

package/dist/agents/codex/scaffold.js

@@ -0,0 +1,273 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { HOOK_FACTORY_TO_EVENT, PACKAGE_NAME } from "./constants.js";
+const VALID_HOOK_EVENT_NAMES = new Set(Object.values(HOOK_FACTORY_TO_EVENT));
+const EVENT_LOOKUP = new Map(Array.from(VALID_HOOK_EVENT_NAMES).map((value) => [value.toLowerCase(), value]));
+const EVENT_TO_FACTORY = Object.fromEntries(Object.entries(HOOK_FACTORY_TO_EVENT).map(([factory, eventName]) => [eventName, factory]));
+const EVENT_TO_OUTPUT = {
+    PreToolUse: "preToolUseOutput",
+    PostToolUse: "postToolUseOutput",
+    PermissionRequest: "permissionRequestOutput",
+    UserPromptSubmit: "userPromptSubmitOutput",
+    SessionStart: "sessionStartOutput",
+    SubagentStart: "subagentStartOutput",
+    Stop: "stopOutput",
+    SubagentStop: "subagentStopOutput",
+    PreCompact: "preCompactOutput",
+    PostCompact: "postCompactOutput",
+};
+export function validateHookNames(hookNames) {
+    const normalized = [];
+    const invalid = [];
+    for (const hookName of hookNames) {
+        const eventName = EVENT_LOOKUP.get(hookName.toLowerCase());
+        if (eventName === undefined) {
+            invalid.push(hookName);
+        }
+        else {
+            normalized.push(eventName);
+        }
+    }
+    if (invalid.length > 0) {
+        return {
+            valid: false,
+            error: `Invalid hook names: ${invalid.join(", ")}. Valid names: ${Array.from(VALID_HOOK_EVENT_NAMES).join(", ")}`,
+        };
+    }
+    return { valid: true, normalized };
+}
+function toKebabCase(value) {
+    return value
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+        .toLowerCase();
+}
+function generatePackageJson(projectName, outputPath) {
+    return `${JSON.stringify({
+        name: projectName,
+        version: "1.0.0",
+        type: "module",
+        scripts: {
+            build: `agent-hooks --agent codex -i "src/**/*.ts" -o "${outputPath}"`,
+            test: "vitest run",
+            lint: "biome check .",
+            typecheck: "tsc --noEmit",
+        },
+        dependencies: {
+            [PACKAGE_NAME]: "^1.0.0",
+        },
+        devDependencies: {
+            "@biomejs/biome": "2.4.9",
+            "@types/node": "^24.0.0",
+            typescript: "^5.9.3",
+            vitest: "^4.0.13",
+        },
+        engines: {
+            node: ">=20.11.0",
+        },
+    }, null, 2)}\n`;
+}
+function generateTsConfig() {
+    return `${JSON.stringify({
+        compilerOptions: {
+            target: "ES2022",
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+        include: ["src/**/*.ts", "test/**/*.ts"],
+        exclude: ["dist", "node_modules"],
+    }, null, 2)}\n`;
+}
+function generateBiomeConfig() {
+    return `{
+  "$schema": "https://biomejs.dev/schemas/2.4.9/schema.json",
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 120
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    }
+  }
+}
+`;
+}
+function generateVitestConfig() {
+    return `import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    include: ["test/**/*.test.ts"],
+  },
+});
+`;
+}
+function generateReadme(projectName, hooks) {
+    const hookList = hooks.map((hookName) => `\`${hookName}\``).join(", ");
+    return `# ${projectName}
+
+This project contains Codex hooks built with \`${PACKAGE_NAME}\`. The scaffold is intentionally narrow: it targets only the five synchronous command hook events Codex currently supports. This project includes: ${hookList}.
+
+Run \`npm install\`, then \`npm run build\` to compile the hooks and generate \`hooks.json\`. Use \`npm test\` to run the starter tests.
+`;
+}
+function generateGitignore() {
+    return `dist/
+node_modules/
+*.log
+`;
+}
+function generateHookSource(eventName) {
+    const factory = EVENT_TO_FACTORY[eventName];
+    const output = EVENT_TO_OUTPUT[eventName];
+    const importItems = [factory, output].join(", ");
+    switch (eventName) {
+        case "PreToolUse":
+            return `import { ${importItems} } from "${PACKAGE_NAME}";
+
+export default ${factory}({ matcher: "Bash" }, (input) => {
+  if (input.tool_input.command.includes("rm -rf")) {
+    return ${output}({
+      systemMessage: "Blocked dangerous shell command.",
+      permissionDecision: "deny",
+      permissionDecisionReason: "Refusing destructive Bash command.",
+    });
+  }
+});
+`;
+        case "PostToolUse":
+            return `import { ${importItems} } from "${PACKAGE_NAME}";
+
+export default ${factory}({ matcher: "Bash" }, (input) => {
+  return ${output}({
+    additionalContext: \`Observed Bash command: \${input.tool_input.command}\`,
+  });
+});
+`;
+        case "SessionStart":
+            return `import { ${importItems} } from "${PACKAGE_NAME}";
+
+export default ${factory}({ matcher: "startup" }, () => {
+  return ${output}({
+    additionalContext: "Project-specific Codex hook context loaded.",
+  });
+});
+`;
+        case "UserPromptSubmit":
+            return `import { ${importItems} } from "${PACKAGE_NAME}";
+
+export default ${factory}({}, (input) => {
+  if (input.prompt.trim().length === 0) {
+    return ${output}({
+      decision: "block",
+      reason: "Prompt must not be empty.",
+    });
+  }
+});
+`;
+        case "Stop":
+            return `import { ${importItems} } from "${PACKAGE_NAME}";
+
+export default ${factory}({}, (input) => {
+  if (input.stop_hook_active && input.last_assistant_message === null) {
+    return ${output}({
+      continue: true,
+      systemMessage: "Stop hook observed an empty assistant message.",
+    });
+  }
+});
+`;
+        case "PermissionRequest":
+            return `import { ${importItems} } from "${PACKAGE_NAME}";
+
+export default ${factory}({ matcher: "Bash" }, (input) => {
+  return ${output}({
+    behavior: "allow",
+    message: \`Allowed \${input.tool_name} via PermissionRequest hook.\`,
+  });
+});
+`;
+        case "SubagentStart":
+            return `import { ${importItems} } from "${PACKAGE_NAME}";
+
+export default ${factory}({ matcher: ".*" }, (input) => {
+  return ${output}({
+    additionalContext: \`Subagent \${input.agent_type} (\${input.agent_id}) starting.\`,
+  });
+});
+`;
+        case "SubagentStop":
+            return `import { ${importItems} } from "${PACKAGE_NAME}";
+
+export default ${factory}({ matcher: ".*" }, (input) => {
+  if (input.last_assistant_message === null) {
+    return ${output}({
+      decision: "block",
+      reason: \`Subagent \${input.agent_type} produced no message.\`,
+    });
+  }
+});
+`;
+        case "PreCompact":
+            return `import { ${importItems} } from "${PACKAGE_NAME}";
+
+export default ${factory}({ matcher: "manual" }, () => {
+  return ${output}({
+    systemMessage: "Compaction starting.",
+  });
+});
+`;
+        case "PostCompact":
+            return `import { ${importItems} } from "${PACKAGE_NAME}";
+
+export default ${factory}({ matcher: "manual" }, () => {
+  return ${output}({
+    systemMessage: "Compaction complete.",
+  });
+});
+`;
+    }
+}
+function generateHookTest(eventName) {
+    const filename = toKebabCase(eventName);
+    return `import hook from "../src/${filename}.js";
+import { describe, expect, it } from "vitest";
+
+describe("${eventName} hook", () => {
+  it("exports a ${eventName} hook", () => {
+    expect(hook.hookEventName).toBe("${eventName}");
+  });
+});
+`;
+}
+export function scaffoldProject(options) {
+    const validation = validateHookNames(options.hooks);
+    if (!validation.valid) {
+        throw new Error(validation.error);
+    }
+    const { directory, outputPath } = options;
+    if (fs.existsSync(directory)) {
+        throw new Error(`Directory already exists: ${directory}`);
+    }
+    fs.mkdirSync(path.join(directory, "src"), { recursive: true });
+    fs.mkdirSync(path.join(directory, "test"), { recursive: true });
+    const projectName = path.basename(directory);
+    fs.writeFileSync(path.join(directory, "package.json"), generatePackageJson(projectName, outputPath));
+    fs.writeFileSync(path.join(directory, "tsconfig.json"), generateTsConfig());
+    fs.writeFileSync(path.join(directory, "biome.json"), generateBiomeConfig());
+    fs.writeFileSync(path.join(directory, "vitest.config.ts"), generateVitestConfig());
+    fs.writeFileSync(path.join(directory, ".gitignore"), generateGitignore());
+    fs.writeFileSync(path.join(directory, "README.md"), generateReadme(projectName, validation.normalized));
+    for (const hookName of validation.normalized) {
+        const baseName = toKebabCase(hookName);
+        fs.writeFileSync(path.join(directory, "src", `${baseName}.ts`), generateHookSource(hookName));
+        fs.writeFileSync(path.join(directory, "test", `${baseName}.test.ts`), generateHookTest(hookName));
+    }
+}