@goodfoot/agent-hooks 1.0.0

package/types/agents/codex/cli-support.d.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 esbuild from "esbuild";
+import type { HookEventName } from "./types.js";
+/** Codex CLI arguments accepted on top of the shared `--agent codex` gate. */
+export interface CodexCliArgs {
+    input: string;
+    output: string;
+    executable?: string;
+    loaderFlags: string[];
+    pluginRoot: boolean;
+    stableNames?: boolean;
+    sourcemap?: boolean;
+}
+export type CommandMode = "plugin" | "codex-local" | "absolute";
+export interface CommandContext {
+    mode: CommandMode;
+    pluginRoot?: string;
+}
+export interface CodexHookMetadata {
+    hookEventName: HookEventName;
+    matcher?: string;
+    timeout?: number;
+    statusMessage?: string;
+}
+interface CompiledHook {
+    sourcePath: string;
+    outputPath: string;
+    outputFilename: string;
+    metadata: CodexHookMetadata;
+}
+interface HookConfigEntry {
+    type: "command";
+    command: string;
+    timeout?: number;
+    statusMessage?: string;
+}
+export interface CodexMatcherEntry {
+    matcher?: string;
+    hooks: HookConfigEntry[];
+}
+export interface CodexHooksJson {
+    hooks: Partial<Record<HookEventName, CodexMatcherEntry[]>>;
+}
+type HookLoaderMap = Record<string, esbuild.Loader>;
+/**
+ * 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 declare function analyzeCodexHookFile(sourcePath: string): CodexHookMetadata | undefined;
+/**
+ * Compiles one Codex hook to a self-contained ESM executable whose entry
+ * wrapper imports this package's Codex runtime module (`execute`).
+ */
+export declare function compileCodexHook(sourcePath: string, loaders: HookLoaderMap, sourcemap?: boolean): Promise<{
+    content: string;
+    contentHash: string;
+}>;
+/**
+ * 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 declare function detectCodexCommandContext(outputPath: string, pluginRootFlag: boolean): CommandContext;
+/** Generates Codex hooks.json: matchers only where the event supports them, timeouts in seconds, statusMessage when set. */
+export declare function generateCodexHooksJson(compiledHooks: CompiledHook[], outputPath: string, executable?: string, context?: CommandContext): CodexHooksJson;
+/**
+ * Validates Codex build/scaffold arguments beyond the shared `--agent` gate:
+ * `-i` and `-o` required for build mode; scaffold requires `--hooks` and
+ * `-o`.
+ */
+export declare function validateCodexArgs(args: CodexCliArgs & {
+    scaffold?: string;
+    hooks?: string;
+}): string | 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 declare function runCodexCli(args: {
+    input: string;
+    output: string;
+    executable?: string;
+    loaderFlags: string[];
+    pluginRoot: boolean;
+    stableNames?: boolean;
+    sourcemap?: boolean;
+    scaffold?: string;
+    hooks?: string;
+}): Promise<void>;
+export {};

package/types/agents/codex/constants.d.ts

@@ -0,0 +1,10 @@
+import type { HookEventName } from "./types.js";
+export declare const PACKAGE_NAME = "@goodfoot/agent-hooks";
+export declare const DEFAULT_TIMEOUT_MS = 600000;
+export declare const DEFAULT_STATUS_MESSAGE: undefined;
+export declare const DEFAULT_ESBUILD_LOADERS: {
+    readonly ".md": "text";
+};
+export declare const HOOK_FACTORY_TO_EVENT: Record<string, HookEventName>;
+export declare const EVENTS_WITH_MATCHER: Set<HookEventName>;
+export declare const EVENTS_WITH_TEXT_OUTPUT: Set<HookEventName>;

package/types/agents/codex/events.d.ts

@@ -0,0 +1,63 @@
+/**
+ * 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
+ */
+import type { UnexpectedErrorPolicy } from "../../core/types.js";
+import type { HookEventName } from "./types.js";
+/**
+ * All Codex hook event names as a readonly array (same order as the
+ * `HookEventName` union).
+ */
+export declare const HOOK_EVENT_NAMES: readonly ["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 declare const EXCLUDED_FROM_ADVISORY: readonly ["PreToolUse", "PostToolUse", "PermissionRequest", "Stop", "SubagentStop", "PreCompact", "PostCompact"];
+/** The exclusion set as a literal union. */
+export type ExcludedEventName = (typeof EXCLUDED_FROM_ADVISORY)[number];
+/** Type-level membership check: `true` only for excluded event names. */
+export type IsExcludedEvent<TEventName extends HookEventName> = TEventName extends ExcludedEventName ? true : false;
+/** The advisory allow-list as a literal union: every event except {@link ExcludedEventName}. */
+export type AdvisoryEventName = Exclude<HookEventName, ExcludedEventName>;
+/**
+ * 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 declare const ADVISORY_EVENTS: readonly AdvisoryEventName[];
+/**
+ * The policy type an event may carry, narrowed by allow-list membership:
+ * advisory events keep `"error" | "continue"`; every excluded event collapses
+ * to `"error"`.
+ */
+export type AllowedUnexpectedErrorPolicy<TEventName extends HookEventName> = IsExcludedEvent<TEventName> extends true ? Exclude<UnexpectedErrorPolicy, "continue"> : UnexpectedErrorPolicy;

package/types/agents/codex/hooks.d.ts

@@ -0,0 +1,135 @@
+/**
+ * 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 type { HookContext, UnexpectedErrorHandler, UnexpectedErrorPolicy } from "../../core/types.js";
+import { type AllowedUnexpectedErrorPolicy } from "./events.js";
+import type { PermissionRequestOutput, PostCompactOutput, PostToolUseOutput, PreCompactOutput, PreToolUseOutput, SessionStartOutput, StopOutput, SubagentStartOutput, SubagentStopOutput, UserPromptSubmitOutput } from "./outputs.js";
+import type { HookEventName, PermissionRequestInput, PostCompactInput, PostToolUseInput, PreCompactInput, PreToolUseInput, SessionStartInput, StopInput, SubagentStartInput, SubagentStopInput, UserPromptSubmitInput } from "./types.js";
+/**
+ * Policy/phase/diagnostic vocabulary is shared across agents and owned by the
+ * core; re-exported here so the Codex surface keeps its historical import
+ * site (`hooks.js`). See the Claude Code surface's documentation of the same
+ * vocabulary for the full fail-open contract.
+ */
+export type { HookContext, UnexpectedErrorHandler, UnexpectedErrorPolicy };
+/**
+ * The base config shapes from the source package. `statusMessage` is a Codex
+ *-specific field: it flows into generated `hooks.json` entries by the CLI.
+ */
+export interface MatcherHookConfig {
+    matcher?: string;
+    timeout?: number;
+    statusMessage?: string;
+    unexpectedError?: UnexpectedErrorPolicy;
+    onUnexpectedError?: UnexpectedErrorHandler;
+}
+export interface NoMatcherHookConfig {
+    timeout?: number;
+    statusMessage?: string;
+    unexpectedError?: UnexpectedErrorPolicy;
+    onUnexpectedError?: UnexpectedErrorHandler;
+}
+/**
+ * Per-event matcher config with the fail-open policy narrowed by the advisory
+ * allow-list: excluded events collapse `unexpectedError` to `"error"` only.
+ * @template TEvent - The event the factory binds.
+ */
+export type MatcherHookConfigFor<TEvent extends HookEventName> = Omit<MatcherHookConfig, "unexpectedError"> & {
+    unexpectedError?: AllowedUnexpectedErrorPolicy<TEvent>;
+};
+/** Per-event no-matcher variant of {@link MatcherHookConfigFor}. @template TEvent - The event the factory binds. */
+export type NoMatcherHookConfigFor<TEvent extends HookEventName> = Omit<NoMatcherHookConfig, "unexpectedError"> & {
+    unexpectedError?: AllowedUnexpectedErrorPolicy<TEvent>;
+};
+type PreToolUseResult = PreToolUseOutput | undefined;
+type PostToolUseResult = PostToolUseOutput | undefined;
+type PermissionRequestResult = PermissionRequestOutput | undefined;
+type UserPromptSubmitResult = UserPromptSubmitOutput | string | undefined;
+type SessionStartResult = SessionStartOutput | string | undefined;
+type SubagentStartResult = SubagentStartOutput | string | undefined;
+type StopResult = StopOutput | undefined;
+type SubagentStopResult = SubagentStopOutput | undefined;
+type PreCompactResult = PreCompactOutput | undefined;
+type PostCompactResult = PostCompactOutput | undefined;
+/**
+ * The result of a hook factory — a function wrapping the handler, carrying
+ * its metadata for the driver and the CLI's AST analysis. Preserves the
+ * source package's `hookEventName` property name alongside the core's
+ * `eventName`.
+ * @template TInput - The input type for this hook
+ * @template TOutput - The output type for this hook
+ * @template TEvent - The literal event name this hook is bound to
+ */
+export interface HookFunction<TInput, TOutput, TEvent extends string> {
+    /**
+     * Execute the hook handler with the given input and context.
+     */
+    (input: TInput, context: HookContext): Promise<TOutput | null>;
+    /**
+     * The Codex event name this hook is for (source-package property name).
+     */
+    hookEventName: TEvent;
+    /**
+     * The core driver's event-name property; identical value.
+     */
+    eventName: string;
+    /**
+     * The matcher pattern, if configured.
+     */
+    matcher?: string;
+    /**
+     * The timeout in milliseconds, if configured.
+     */
+    timeout?: number;
+    /**
+     * Codex-specific status message shown while the hook runs.
+     */
+    statusMessage?: string;
+    /**
+     * The fail-open policy, if configured.
+     */
+    unexpectedError?: UnexpectedErrorPolicy;
+    /**
+     * The diagnostic callback for the "continue" policy, if configured.
+     */
+    onUnexpectedError?: UnexpectedErrorHandler;
+    /**
+     * Optional context factory (unused by the Codex surface today; part of the
+     * shared core function shape).
+     */
+    createContext?: (input: TInput) => HookContext;
+}
+/** Creates a PreToolUse hook handler. Excluded from the advisory list. */
+export declare function preToolUseHook(config: MatcherHookConfigFor<"PreToolUse">, handler: (input: PreToolUseInput, context: HookContext) => PreToolUseResult | Promise<PreToolUseResult>): HookFunction<PreToolUseInput, PreToolUseResult, "PreToolUse">;
+/** Creates a PostToolUse hook handler. Blocking variant excluded from the advisory list. */
+export declare function postToolUseHook(config: MatcherHookConfigFor<"PostToolUse">, handler: (input: PostToolUseInput, context: HookContext) => PostToolUseResult | Promise<PostToolUseResult>): HookFunction<PostToolUseInput, PostToolUseResult, "PostToolUse">;
+/** Creates a PermissionRequest hook handler. Excluded from the advisory list. */
+export declare function permissionRequestHook(config: MatcherHookConfigFor<"PermissionRequest">, handler: (input: PermissionRequestInput, context: HookContext) => PermissionRequestResult | Promise<PermissionRequestResult>): HookFunction<PermissionRequestInput, PermissionRequestResult, "PermissionRequest">;
+/** Creates a UserPromptSubmit hook handler. Advisory enrichment hook. */
+export declare function userPromptSubmitHook(config: NoMatcherHookConfigFor<"UserPromptSubmit">, handler: (input: UserPromptSubmitInput, context: HookContext) => UserPromptSubmitResult | Promise<UserPromptSubmitResult>): HookFunction<UserPromptSubmitInput, UserPromptSubmitResult, "UserPromptSubmit">;
+/** Creates a SessionStart hook handler. Advisory enrichment hook. */
+export declare function sessionStartHook(config: MatcherHookConfigFor<"SessionStart">, handler: (input: SessionStartInput, context: HookContext) => SessionStartResult | Promise<SessionStartResult>): HookFunction<SessionStartInput, SessionStartResult, "SessionStart">;
+/** Creates a SubagentStart hook handler. Advisory enrichment hook. */
+export declare function subagentStartHook(config: MatcherHookConfigFor<"SubagentStart">, handler: (input: SubagentStartInput, context: HookContext) => SubagentStartResult | Promise<SubagentStartResult>): HookFunction<SubagentStartInput, SubagentStartResult, "SubagentStart">;
+/** Creates a Stop hook handler. Blocking variant excluded from the advisory list. */
+export declare function stopHook(config: NoMatcherHookConfigFor<"Stop">, handler: (input: StopInput, context: HookContext) => StopResult | Promise<StopResult>): HookFunction<StopInput, StopResult, "Stop">;
+/** Creates a SubagentStop hook handler. Blocking variant excluded from the advisory list. */
+export declare function subagentStopHook(config: MatcherHookConfigFor<"SubagentStop">, handler: (input: SubagentStopInput, context: HookContext) => SubagentStopResult | Promise<SubagentStopResult>): HookFunction<SubagentStopInput, SubagentStopResult, "SubagentStop">;
+/** Creates a PreCompact hook handler. Excluded by default pending doc clarification. */
+export declare function preCompactHook(config: MatcherHookConfigFor<"PreCompact">, handler: (input: PreCompactInput, context: HookContext) => PreCompactResult | Promise<PreCompactResult>): HookFunction<PreCompactInput, PreCompactResult, "PreCompact">;
+/** Creates a PostCompact hook handler. Excluded by default pending doc clarification. */
+export declare function postCompactHook(config: MatcherHookConfigFor<"PostCompact">, handler: (input: PostCompactInput, context: HookContext) => PostCompactResult | Promise<PostCompactResult>): HookFunction<PostCompactInput, PostCompactResult, "PostCompact">;

package/types/agents/codex/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@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
+ */
+export type { LogEvent, LogEventHandler, LoggerConfig, LogLevel, Unsubscribe } from "../../core/logger.js";
+export { LOG_LEVELS, Logger, logger } from "../../core/logger.js";
+export { DEFAULT_ESBUILD_LOADERS, DEFAULT_TIMEOUT_MS, EVENTS_WITH_MATCHER, EVENTS_WITH_TEXT_OUTPUT, HOOK_FACTORY_TO_EVENT, PACKAGE_NAME, } from "./constants.js";
+export type { AdvisoryEventName, AllowedUnexpectedErrorPolicy, ExcludedEventName, IsExcludedEvent, } from "./events.js";
+export { ADVISORY_EVENTS, EXCLUDED_FROM_ADVISORY, HOOK_EVENT_NAMES } from "./events.js";
+export type { HookContext, HookFunction, MatcherHookConfig, MatcherHookConfigFor, NoMatcherHookConfig, NoMatcherHookConfigFor, UnexpectedErrorHandler, UnexpectedErrorPolicy, } from "./hooks.js";
+export { permissionRequestHook, postCompactHook, postToolUseHook, preCompactHook, preToolUseHook, sessionStartHook, stopHook, subagentStartHook, subagentStopHook, userPromptSubmitHook, } from "./hooks.js";
+export { BlockError, EXIT_CODES, type ExitCode, type HookOutput, type HookSpecificOutput, type PermissionRequestBehavior, type PermissionRequestDecision, type PermissionRequestHookSpecificOutput, type PermissionRequestOptions, type PermissionRequestOutput, type PostCompactOptions, type PostCompactOutput, type PostToolUseHookSpecificOutput, type PostToolUseOptions, type PostToolUseOutput, type PreCompactOptions, type PreCompactOutput, type PreToolUseHookSpecificOutput, type PreToolUseLegacyBlockOptions, type PreToolUseOptions, type PreToolUseOutput, type PreToolUsePermissionDecision, permissionRequestOutput, postCompactOutput, postToolUseOutput, preCompactOutput, preToolUseLegacyBlockOutput, preToolUseOutput, type RawOutput, rawOutput, type SessionStartHookSpecificOutput, type SessionStartOptions, type SessionStartOutput, type SpecificHookOutput, type StopOptions, type StopOutput, type SubagentStartHookSpecificOutput, type SubagentStartOptions, type SubagentStartOutput, type SubagentStopOptions, type SubagentStopOutput, type SyncHookJSONOutput, sessionStartOutput, stopOutput, subagentStartOutput, subagentStopOutput, type UserPromptSubmitHookSpecificOutput, type UserPromptSubmitOptions, type UserPromptSubmitOutput, userPromptSubmitOutput, } from "./outputs.js";
+export { convertToHookOutput, createCodexTransport, execute } from "./transport.js";
+export type { BaseHookInput, HookErrorPhase, HookEventName, HookInput, PermissionMode, PermissionRequestInput, PostCompactInput, PostToolUseInput, PreCompactInput, PreCompactTrigger, PreToolUseInput, SessionStartInput, SessionStartSource, StopInput, SubagentStartInput, SubagentStopInput, UserPromptSubmitInput, } from "./types.js";

package/types/agents/codex/outputs.d.ts

@@ -0,0 +1,190 @@
+import { HookBlockError } from "../../core/transport.js";
+export declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly ERROR: 1;
+    readonly BLOCK: 2;
+};
+export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
+interface BaseSpecificOutput<T extends string> {
+    readonly _type: T;
+    readonly stdout: SyncHookJSONOutput;
+    readonly stderr?: string;
+}
+export type RawOutput = BaseSpecificOutput<"Raw">;
+export type PreToolUseOutput = BaseSpecificOutput<"PreToolUse">;
+export type PostToolUseOutput = BaseSpecificOutput<"PostToolUse">;
+export type PermissionRequestOutput = BaseSpecificOutput<"PermissionRequest">;
+export type UserPromptSubmitOutput = BaseSpecificOutput<"UserPromptSubmit">;
+export type SessionStartOutput = BaseSpecificOutput<"SessionStart">;
+export type SubagentStartOutput = BaseSpecificOutput<"SubagentStart">;
+export type StopOutput = BaseSpecificOutput<"Stop">;
+export type SubagentStopOutput = BaseSpecificOutput<"SubagentStop">;
+export type PreCompactOutput = BaseSpecificOutput<"PreCompact">;
+export type PostCompactOutput = BaseSpecificOutput<"PostCompact">;
+export type SpecificHookOutput = RawOutput | PreToolUseOutput | PostToolUseOutput | PermissionRequestOutput | UserPromptSubmitOutput | SessionStartOutput | SubagentStartOutput | StopOutput | SubagentStopOutput | PreCompactOutput | PostCompactOutput;
+export interface HookOutput {
+    stdout: SyncHookJSONOutput;
+    stderr?: string;
+}
+export interface SyncHookJSONOutput {
+    continue?: boolean;
+    decision?: "approve" | "block";
+    hookSpecificOutput?: HookSpecificOutput;
+    reason?: string;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+}
+export type HookSpecificOutput = PreToolUseHookSpecificOutput | PostToolUseHookSpecificOutput | PermissionRequestHookSpecificOutput | UserPromptSubmitHookSpecificOutput | SessionStartHookSpecificOutput | SubagentStartHookSpecificOutput;
+export type PreToolUsePermissionDecision = "allow" | "deny" | "ask";
+export interface PreToolUseHookSpecificOutput {
+    hookEventName: "PreToolUse";
+    additionalContext?: string;
+    permissionDecision?: PreToolUsePermissionDecision;
+    permissionDecisionReason?: string;
+    updatedInput?: unknown;
+}
+export interface PostToolUseHookSpecificOutput {
+    hookEventName: "PostToolUse";
+    additionalContext?: string;
+    updatedMCPToolOutput?: unknown;
+}
+export type PermissionRequestBehavior = "allow" | "deny";
+export interface PermissionRequestDecision {
+    behavior: PermissionRequestBehavior;
+    message?: string;
+    interrupt?: boolean;
+    updatedInput?: unknown;
+    updatedPermissions?: unknown;
+}
+export interface PermissionRequestHookSpecificOutput {
+    hookEventName: "PermissionRequest";
+    decision?: PermissionRequestDecision;
+}
+export interface UserPromptSubmitHookSpecificOutput {
+    hookEventName: "UserPromptSubmit";
+    additionalContext?: string;
+}
+export interface SessionStartHookSpecificOutput {
+    hookEventName: "SessionStart";
+    additionalContext?: string;
+}
+export interface SubagentStartHookSpecificOutput {
+    hookEventName: "SubagentStart";
+    additionalContext?: string;
+}
+export interface PreToolUseOptions {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+    decision?: "approve" | "block";
+    reason?: string;
+    additionalContext?: string;
+    permissionDecision?: PreToolUsePermissionDecision;
+    permissionDecisionReason?: string;
+    updatedInput?: unknown;
+}
+export interface PreToolUseLegacyBlockOptions {
+    systemMessage?: string;
+    decision: "block";
+    reason: string;
+}
+export interface PostToolUseOptions {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+    decision?: "block";
+    reason?: string;
+    additionalContext?: string;
+    updatedMCPToolOutput?: unknown;
+}
+export interface PermissionRequestOptions {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+    behavior: PermissionRequestBehavior;
+    message?: string;
+    interrupt?: boolean;
+    updatedInput?: unknown;
+    updatedPermissions?: unknown;
+}
+export interface UserPromptSubmitOptions {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+    decision?: "block";
+    reason?: string;
+    additionalContext?: string;
+}
+export interface SessionStartOptions {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+    additionalContext?: string;
+}
+export interface SubagentStartOptions {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+    additionalContext?: string;
+}
+export interface StopOptions {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+    decision?: "block";
+    reason?: string;
+}
+export interface SubagentStopOptions {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+    decision?: "block";
+    reason?: string;
+}
+export interface PreCompactOptions {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+}
+export interface PostCompactOptions {
+    continue?: boolean;
+    stopReason?: string;
+    suppressOutput?: boolean;
+    systemMessage?: string;
+}
+/**
+ * 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 declare class BlockError extends HookBlockError {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare function rawOutput(stdout: SyncHookJSONOutput, stderr?: string): SpecificHookOutput;
+export declare function preToolUseOutput(options?: PreToolUseOptions): PreToolUseOutput;
+export declare function preToolUseLegacyBlockOutput(options: PreToolUseLegacyBlockOptions): PreToolUseOutput;
+export declare function postToolUseOutput(options?: PostToolUseOptions): PostToolUseOutput;
+export declare function permissionRequestOutput(options: PermissionRequestOptions): PermissionRequestOutput;
+export declare function userPromptSubmitOutput(options?: UserPromptSubmitOptions): UserPromptSubmitOutput;
+export declare function sessionStartOutput(options?: SessionStartOptions): SessionStartOutput;
+export declare function subagentStartOutput(options?: SubagentStartOptions): SubagentStartOutput;
+export declare function stopOutput(options?: StopOptions): StopOutput;
+export declare function subagentStopOutput(options?: SubagentStopOptions): SubagentStopOutput;
+export declare function preCompactOutput(options?: PreCompactOptions): PreCompactOutput;
+export declare function postCompactOutput(options?: PostCompactOptions): PostCompactOutput;
+export {};

package/types/agents/codex/scaffold.d.ts

@@ -0,0 +1,14 @@
+import type { HookEventName } from "./types.js";
+export interface ScaffoldOptions {
+    directory: string;
+    hooks: string[];
+    outputPath: string;
+}
+export declare function validateHookNames(hookNames: string[]): {
+    valid: true;
+    normalized: HookEventName[];
+} | {
+    valid: false;
+    error: string;
+};
+export declare function scaffoldProject(options: ScaffoldOptions): void;

package/types/agents/codex/transport.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Wire transport for Codex hooks, rewritten against the core
+ * `drive()`/`Transport` interface; the wire semantics carry over
+ * `codex-hooks/src/runtime.ts` verbatim:
+ *
+ * - **BlockError → its reason written to stderr + exit 2, regardless of
+ *   policy** — a single translation for every event including
+ *   `SubagentStart`; there is deliberately no per-event table here (Codex
+ *   has no narrower native deny shape than the stderr channel). The source
+ *   runtime already classified `BlockError` ahead of the policy branch; that
+ *   precedence now lives in `drive()` via {@link BlockError} extending the
+ *   core `HookBlockError`.
+ * - every other unexpected failure (stdin read, parse, handler, serialize,
+ *   write, cleanup) under the default `"error"` policy → stacktrace on
+ *   stderr + exit 1 (`ERROR`) — note Codex exits **1**, unlike Claude Code's
+ *   handler-error exit 2; under `"continue"` → reported and swallowed to the
+ *   event's valid empty output `{}` at exit 0. Malformed stdin is therefore
+ *   NOT unconditionally fail-open on Codex — the policy decides, exactly as
+ *   in the source runtime.
+ * - success → `JSON.stringify(output.stdout)` at exit 0; a `null`/`undefined`
+ *   result serializes as `{}`, valid for every event's output schema.
+ * - a returned `stderr` **field** on an output object is carried by
+ *   `convertToHookOutput` but discarded by the success path — the source
+ *   runtime only ever serialized `output.stdout`; blocking is expressed
+ *   exclusively through the thrown-`BlockError` channel.
+ *
+ * String returns (`"Loaded from text"`) are normalized into the event's
+ * additionalContext output for the three text-output events; any other event
+ * rejecting plain text throws exactly like the source, flowing through the
+ * standard policy-gated error path.
+ * @module
+ * @example
+ * ```typescript
+ * // In a compiled hook file
+ * import { execute } from './transport.js';
+ * import myHook from './my-hook.js';
+ *
+ * execute(myHook);
+ * ```
+ */
+import type { Transport } from "../../core/transport.js";
+import type { HookFunction } from "./hooks.js";
+import { type SpecificHookOutput } from "./outputs.js";
+import type { HookEventName, HookInput } from "./types.js";
+/**
+ * Converts a SpecificHookOutput to the wire shape by stripping the `_type`
+ * discriminator (source parity: builders produce wire-format directly).
+ */
+export declare function convertToHookOutput(output: SpecificHookOutput): {
+    stdout: SpecificHookOutput["stdout"];
+    stderr?: string;
+};
+/**
+ * Normalizes a plain-string handler return into the event's additionalContext
+ * output; non-text events reject strings with the source package's exact
+ * error, which then flows through the standard policy-gated error path.
+ */
+export declare function normalizeStringOutput(hookEventName: HookEventName, result: string): SpecificHookOutput;
+/**
+ * Builds the Codex wire transport. Unlike the Claude Code adapter there is no
+ * per-event block-shape table: every caught {@link BlockError} translates to
+ * `stderr: reason + "\n"` at exit 2 under every policy value, and no
+ * `rawStdout` predicate exists because Codex has no plain-text-stdout
+ * protocol events (the `rawOutput()` builder is ordinary JSON passthrough).
+ */
+export declare function createCodexTransport(): Transport<SpecificHookOutput | undefined>;
+/**
+ * Executes a hook handler with full runtime orchestration (delegates to the
+ * shared core driver with this agent's transport). String returns are
+ * normalized before the driver sees them so that a plain-text violation
+ * classifies through the same policy gate as any other handler failure,
+ * matching the source runtime's observable wire behaviour.
+ */
+export declare function execute<TInput extends HookInput, TOutput>(hookFn: HookFunction<TInput, TOutput, HookEventName>): Promise<void>;