@goodfoot/agent-hooks 1.0.0

package/README.md

@@ -0,0 +1,137 @@
+# `@goodfoot/agent-hooks`
+
+Unified agent hooks library for AI coding CLIs. One package consolidating the
+runtime previously split across `@goodfoot/claude-code-hooks` and
+`@goodfoot/codex-hooks`, with per-agent entry points.
+
+**Status: `0.1.0` — core only.** This release ships the agent-neutral core:
+the shared driver, transport abstraction, hook factory primitive, `Logger`,
+and env utilities. Per-agent entry points (`@goodfoot/agent-hooks/claude-code`,
+`/codex`, `/antigravity`) do not exist yet; they are added to the package
+`exports` map only in the version that lands their implementation — never
+pre-declared.
+
+## Exports map policy
+
+The `exports` map is an explicit, closed list of subpaths. It deliberately
+does **not** include a `./*` wildcard subpath (unlike the source packages):
+a wildcard would make every internal module independently importable,
+defeating the root-export lint. This is a permanent rule enforced by the
+package's own test suite (`tests/export-surface.test.ts`), which also carries
+a fail-case fixture proving the check rejects a wildcard entry.
+
+## Core API
+
+### `defineHook(eventName, config, handler, policyGate?)`
+
+Factory primitive every agent's per-event factory builds on:
+
+```typescript
+import { defineHook } from '@goodfoot/agent-hooks';
+
+const hook = defineHook(
+  'UserPromptSubmit',
+  { unexpectedError: 'continue' },
+  async (input, { logger }) => {
+    logger.info('Enriching prompt');
+    return { additionalContext: '…' };
+  },
+  // Optional per-event policy gate injected by each agent; core never
+  // hardcodes an event list. Returning false (or throwing) fails closed.
+  (eventName, policy) => policy === undefined || policy === 'continue',
+);
+```
+
+### `Transport` and `drive(transport, hookFn)`
+
+Core owns the try/catch skeleton — stdin read, JSON parse, handler invocation,
+outcome classification, buffered single-write emission, process exit — and has
+no knowledge of exit codes or stdout policy. Every wire decision belongs to
+the agent's transport:
+
+```typescript
+import { drive, type Transport } from '@goodfoot/agent-hooks';
+
+const transport: Transport<MyOutput> = {
+  finalize: (outcome) => {
+    switch (outcome.kind) {
+      case 'response':
+        return { stdout: JSON.stringify(outcome.output ?? {}), exitCode: 0 };
+      case 'block':
+        return { stderr: outcome.error.message, exitCode: 2 };
+      default:
+        return { stderr: 'internal error', exitCode: 1 };
+    }
+  },
+};
+
+await drive(transport, myHook);
+```
+
+`finalize(outcome)` is a pure mapping called exactly once per invocation. The
+optional `rawStdout(output)` predicate declares which returned outputs carry
+a plain-text protocol payload (e.g. worktree events whose stdout the host
+reads verbatim); matching outputs are classified as `{ kind: "rawStdout",
+stdout }` instead of `response`. Returned outputs are never modified by core.
+
+### Outcomes
+
+`HookOutcome<TOutput>` is a discriminated union:
+
+| `kind` | Payload | Produced when |
+|---|---|---|
+| `response` | `output: TOutput \| undefined` | handler returned normally (`undefined` = empty response), or a throw was swallowed under `unexpectedError: "continue"` |
+| `block` | `error: HookBlockError` | handler threw a `HookBlockError` |
+| `handlerError` | `error: unknown; phase` | any other failure, classified at its phase (`read`, `parse`, `handler`, …) |
+| `rawStdout` | `stdout: string` | the transport's `rawStdout` predicate matched a normal return |
+
+### `HookBlockError`
+
+```typescript
+import { HookBlockError } from '@goodfoot/agent-hooks';
+
+throw new HookBlockError('blocked: writes outside workspace', { tool: 'Bash' });
+```
+
+`drive()` classifies a caught `HookBlockError` **before** consulting the
+`unexpectedError` policy: it always routes to the `block` outcome, under every
+policy value. This is what lets an advisory event's intentional block survive
+a crash mid-computation instead of being silently swallowed by the
+fail-open policy. Any other throw remains subject to policy exactly as in the
+source packages: `"continue"` swallows it into the empty response;
+the default `"error"` policy yields the `handlerError` outcome. A normally
+returned value always passes through to `finalize` unmodified — core never
+inspects returned output for block-signaling fields.
+
+Agents may subclass or re-export `HookBlockError`; each agent's transport
+owns the wire translation of the `block` outcome for its events.
+
+### `unexpectedError` policy
+
+- `"error"` (default): unexpected failures surface to the transport as
+  `handlerError` outcomes.
+- `"continue"`: opt-in fail-open for advisory hooks — unexpected failures are
+  swallowed into the empty response, reported through the optional
+  `onUnexpectedError` callback and the logger. Never use it for hooks that
+  enforce permission, safety, or policy decisions; a `HookBlockError` still
+  gets through (see above), but ordinary bugs will not.
+
+Malformed or unreadable stdin is classified at its phase like any other
+unexpected failure (`handlerError` with `phase: "parse"`) and logged as
+`Failed to parse stdin JSON`; each agent's transport decides the wire shape
+for that classification.
+
+### `Logger`
+
+Structured logging ported behavior-identically from the source packages:
+silent by default, never writes stdout/stderr, optional JSON Lines file output
+via `AGENT_HOOKS_LOG_FILE`, event subscription via `logger.on(level, handler)`.
+
+## Development
+
+```bash
+yarn workspace @goodfoot/agent-hooks run typecheck
+yarn workspace @goodfoot/agent-hooks run build
+yarn workspace @goodfoot/agent-hooks run lint
+yarn workspace @goodfoot/agent-hooks run test
+```

package/dist/agents/antigravity/events.js

@@ -0,0 +1,42 @@
+/**
+ * Antigravity hook event names and the (currently empty) advisory allow-list.
+ *
+ * Unlike Claude Code's and Codex's allow-lists, which transcribe a named set
+ * of enrichment hooks out of a shipped README, Antigravity has no in-repo
+ * doc to transcribe from this release (Step 0 descope — see the plan's Step
+ * 5 blockquote). The allow-list therefore defaults to **every event
+ * excluded**, not a curated subset, until a future card's `CONTRACT.md`
+ * names a specific enrichment hook safe to opt into `unexpectedError:
+ * "continue"`.
+ *
+ * That default is itself gated on a second precondition: because Antigravity
+ * has no exit-code channel at all (every event is payload-only — see
+ * `transport.ts` and `outputs.ts`'s {@link AntigravityBlockError}), a
+ * fail-open swallow on this agent has no narrower fallback than Claude
+ * Code's or Codex's — there is no stderr+exit-2 loud path to fall back to.
+ * `AntigravityBlockError` landing first (this same step) is what makes it
+ * safe to ever widen this list at all: an intentional block computed
+ * mid-throw still survives `unexpectedError: "continue"` via `drive()`'s
+ * pre-policy classification, exactly as it does for the other two agents.
+ * @module
+ */
+/** All Antigravity hook event names as a readonly array. */
+export const HOOK_EVENT_NAMES = [
+    "PreToolUse",
+    "PostToolUse",
+    "PreInvocation",
+    "PostInvocation",
+    "Stop",
+];
+/** The two events whose config accepts a `matcher` (plan step 5.3: "matcher on the two ToolUse events"). */
+export const EVENTS_WITH_MATCHER = ["PreToolUse", "PostToolUse"];
+/**
+ * Events never allowed the fail-open `unexpectedError: "continue"` policy.
+ *
+ * Every shipped event, by default — see module docs. This is a stated
+ * default (plan Decisions: "advisory list default empty until CONTRACT.md
+ * justifies an entry"), not a silent gap.
+ */
+export const EXCLUDED_FROM_ADVISORY = [...HOOK_EVENT_NAMES];
+/** The advisory allow-list. Empty until a future `CONTRACT.md` names an entry. */
+export const ADVISORY_EVENTS = HOOK_EVENT_NAMES.filter((eventName) => !EXCLUDED_FROM_ADVISORY.includes(eventName));

package/dist/agents/antigravity/hooks.js

@@ -0,0 +1,59 @@
+/**
+ * Typed factory functions for Antigravity hooks, built on the shared core
+ * {@link ../../core/define-hook.ts|defineHook}.
+ *
+ * This release ships the typed factory surface and output builders only
+ * (plan Step 5, item-6 descope) — no `CONTRACT.md`-derived e2e file, no
+ * `./antigravity` export. Every factory injects the advisory allow-list
+ * policy gate, so `unexpectedError: "continue"` fails closed at
+ * factory-call time for every event ({@link ADVISORY_EVENTS} is empty this
+ * release); {@link HookConfigFor} additionally narrows the policy field at
+ * compile time.
+ *
+ * Antigravity's config surface is a single conditional type rather than the
+ * separate matcher/no-matcher interface pair Claude Code and Codex use: only
+ * two of the five events (`PreToolUse`, `PostToolUse`) carry a `matcher`
+ * ({@link EVENTS_WITH_MATCHER} in `events.ts`), and a conditional type on the
+ * bound event expresses that distinction without duplicating the base field
+ * list twice.
+ * @module
+ */
+import { defineHook } from "../../core/define-hook.js";
+import { ADVISORY_EVENTS } from "./events.js";
+/**
+ * Rejects `unexpectedError: "continue"` unless the bound event is on
+ * {@link ADVISORY_EVENTS} — every event, this release, since that list is
+ * currently empty.
+ */
+const advisoryPolicyGate = (eventName, policy) => policy !== "continue" || ADVISORY_EVENTS.includes(eventName);
+function bindHook(event, config, handler) {
+    const coreConfig = {
+        matcher: config.matcher,
+        timeout: config.timeout,
+        unexpectedError: config.unexpectedError,
+        onUnexpectedError: config.onUnexpectedError,
+    };
+    const bound = defineHook(event, coreConfig, handler, advisoryPolicyGate);
+    bound.hookEventName = event;
+    return bound;
+}
+/** Creates a PreToolUse hook handler. */
+export function preToolUseHook(config, handler) {
+    return bindHook("PreToolUse", config, handler);
+}
+/** Creates a PostToolUse hook handler. */
+export function postToolUseHook(config, handler) {
+    return bindHook("PostToolUse", config, handler);
+}
+/** Creates a PreInvocation hook handler. */
+export function preInvocationHook(config, handler) {
+    return bindHook("PreInvocation", config, handler);
+}
+/** Creates a PostInvocation hook handler. */
+export function postInvocationHook(config, handler) {
+    return bindHook("PostInvocation", config, handler);
+}
+/** Creates a Stop hook handler. */
+export function stopHook(config, handler) {
+    return bindHook("Stop", config, handler);
+}

package/dist/agents/antigravity/index.js

@@ -0,0 +1,28 @@
+/**
+ * `@goodfoot/agent-hooks/antigravity` — the Antigravity agent surface.
+ *
+ * **Not yet published as a package subpath.** Step 5 ships under its item-6
+ * descope (Step 0 concluded "not runnable / unknown" for the real
+ * `antigravity` CLI in this release's environment): typed factories, output
+ * builders, and a conformance matrix only. `packages/agent-hooks/package.json`
+ * deliberately does not add a `./antigravity` `exports` entry this release —
+ * see `tests/export-surface.test.ts`, which asserts the exports map stays
+ * closed at `.`/`./claude-code`/`./codex`. This module exists for in-repo
+ * testing (the conformance matrix imports it directly by relative path) and
+ * for the follow-up card that resolves the CLI-availability question to
+ * build on without re-deriving the surface from scratch.
+ *
+ * Re-exports the 5 hook factories, their output builders (reserved fields
+ * emitted only when passed), the `AntigravityBlockError` block signal,
+ * input/output types, and the runtime `execute` entry point. No default
+ * export.
+ * @module
+ */
+// Advisory allow-list events
+export { ADVISORY_EVENTS, EVENTS_WITH_MATCHER, EXCLUDED_FROM_ADVISORY, HOOK_EVENT_NAMES } from "./events.js";
+// Hook factory functions - all 5 event types
+export { postInvocationHook, postToolUseHook, preInvocationHook, preToolUseHook, stopHook } from "./hooks.js";
+// Output types and builders (AntigravityBlockError subclasses core HookBlockError)
+export { AntigravityBlockError, EXIT_CODES, postInvocationOutput, postToolUseOutput, preInvocationOutput, preToolUseOutput, stopOutput, } from "./outputs.js";
+// Runtime exports - execute function and transport factory
+export { createAntigravityTransport, execute } from "./transport.js";

package/dist/agents/antigravity/outputs.js

@@ -0,0 +1,81 @@
+import { HookBlockError } from "../../core/transport.js";
+/**
+ * Antigravity has no exit-code signaling channel: every event replies at
+ * exit 0 and every decision — allow, deny, or ask — is expressed inside the
+ * JSON payload. `EXIT_CODES.SUCCESS` is the only member for that reason; see
+ * `transport.ts`'s module docs for the consequence this has for
+ * {@link AntigravityBlockError}.
+ */
+export const EXIT_CODES = {
+    SUCCESS: 0,
+};
+/**
+ * The Antigravity block signal, carried as a subclass of the shared core
+ * {@link ../../core/transport.ts|HookBlockError} so `drive()` classifies it
+ * **before** consulting `unexpectedError` policy — exactly mirroring Claude
+ * Code's `HookBlockError` usage and Codex's `BlockError` re-export.
+ *
+ * This mechanism is a stated *prerequisite*, not a follow-up, for
+ * Antigravity specifically: because every Antigravity event replies at exit
+ * 0 with the decision expressed only in the JSON payload (Research, plan
+ * Step 5), a handler that throws mid-decision has no narrower exit-code
+ * fallback to land on the way Codex's stderr+exit-2 channel does — the block
+ * decision would otherwise be indistinguishable from a swallowed crash. This
+ * class landing is what makes it safe to ever widen `events.ts`'s advisory
+ * allow-list past empty.
+ */
+export class AntigravityBlockError extends HookBlockError {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.name = "AntigravityBlockError";
+        this.reason = reason;
+    }
+}
+function omitUndefined(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined));
+}
+function buildOutput(type, stdout) {
+    return {
+        _type: type,
+        stdout: omitUndefined(stdout),
+    };
+}
+export function preToolUseOutput(options = {}) {
+    return buildOutput("PreToolUse", {
+        decision: options.decision,
+        reason: options.reason,
+        additionalContext: options.additionalContext,
+        updatedInput: options.updatedInput,
+        systemMessage: options.systemMessage,
+    });
+}
+export function postToolUseOutput(options = {}) {
+    return buildOutput("PostToolUse", {
+        decision: options.decision,
+        reason: options.reason,
+        additionalContext: options.additionalContext,
+        systemMessage: options.systemMessage,
+    });
+}
+export function preInvocationOutput(options = {}) {
+    return buildOutput("PreInvocation", {
+        decision: options.decision,
+        reason: options.reason,
+        additionalContext: options.additionalContext,
+        systemMessage: options.systemMessage,
+    });
+}
+export function postInvocationOutput(options = {}) {
+    return buildOutput("PostInvocation", {
+        additionalContext: options.additionalContext,
+        systemMessage: options.systemMessage,
+    });
+}
+export function stopOutput(options = {}) {
+    return buildOutput("Stop", {
+        stop: options.stop,
+        reason: options.reason,
+        systemMessage: options.systemMessage,
+    });
+}

package/dist/agents/antigravity/transport.js

@@ -0,0 +1,84 @@
+/**
+ * Wire transport for Antigravity hooks, built against the core
+ * `drive()`/`Transport` interface — the same seam Claude Code's and Codex's
+ * transports are rewritten/re-exported against.
+ *
+ * Antigravity's wire semantics are the simplest of the three shipped agents,
+ * and also the least forgiving: **every reply exits 0, unconditionally.**
+ * There is no exit-code channel at all — not the 2-of-30-events native-deny
+ * split Claude Code has, not Codex's uniform stderr+exit-2 `BlockError`
+ * channel. Every decision (allow/deny/ask and its finer variants) and every
+ * unexpected-failure diagnostic lives inside the JSON stdout payload:
+ *
+ * - success → `JSON.stringify(output.stdout)` at exit 0; `null`/`undefined`
+ *   serializes as `{}`.
+ * - a caught {@link AntigravityBlockError} → `{ decision: "deny", reason,
+ *   ...fields }` on stdout at exit 0 — this is why the class is a stated
+ *   prerequisite (`outputs.ts` module docs, `events.ts` module docs): with no
+ *   exit-code fallback, a block computed mid-throw has nowhere else to land.
+ * - an unexpected handler/runtime failure → its stacktrace on stderr
+ *   (diagnostic only, not a wire signal) plus the empty response `{}` on
+ *   stdout, still at exit 0.
+ * @module
+ * @example
+ * ```typescript
+ * // In a compiled hook file
+ * import { execute } from './transport.js';
+ * import myHook from './my-hook.js';
+ *
+ * execute(myHook);
+ * ```
+ */
+import { drive } from "../../core/transport.js";
+import { AntigravityBlockError, EXIT_CODES } from "./outputs.js";
+function formatErrorText(error) {
+    return error instanceof Error ? `${error.stack ?? error.message}\n` : `${String(error)}\n`;
+}
+// ============================================================================
+// Transport
+// ============================================================================
+/**
+ * Builds the Antigravity wire transport. Every branch returns
+ * `exitCode: EXIT_CODES.SUCCESS` — see module docs — so the only thing that
+ * varies per outcome is what lands on stdout (the machine-readable payload)
+ * versus stderr (a diagnostic no host is asserted to read).
+ */
+export function createAntigravityTransport() {
+    return {
+        finalize(outcome) {
+            switch (outcome.kind) {
+                case "response":
+                case "rawStdout": {
+                    // rawStdout cannot occur here — no rawStdout predicate is
+                    // registered below — but the union demands handling.
+                    const stdoutJson = outcome.kind === "response" && outcome.output !== null && outcome.output !== undefined
+                        ? JSON.stringify(outcome.output.stdout)
+                        : "{}";
+                    return { stdout: stdoutJson, exitCode: EXIT_CODES.SUCCESS };
+                }
+                case "block": {
+                    const reason = outcome.error instanceof AntigravityBlockError ? outcome.error.reason : outcome.error.message;
+                    const fields = outcome.error.fields ?? {};
+                    return { stdout: JSON.stringify({ decision: "deny", reason, ...fields }), exitCode: EXIT_CODES.SUCCESS };
+                }
+                case "handlerError": {
+                    return {
+                        stderr: formatErrorText(outcome.error),
+                        stdout: "{}",
+                        exitCode: EXIT_CODES.SUCCESS,
+                    };
+                }
+            }
+        },
+    };
+}
+// ============================================================================
+// Execute
+// ============================================================================
+/**
+ * Executes a hook handler with full runtime orchestration (delegates to the
+ * shared core driver with this agent's transport).
+ */
+export async function execute(hookFn) {
+    await drive(createAntigravityTransport(), hookFn);
+}

package/dist/agents/antigravity/types.js

@@ -0,0 +1,11 @@
+/**
+ * Antigravity wire types (plan step 5, item-6 descope: typed factories +
+ * output builders + conformance matrix only — no `CONTRACT.md` pin, no
+ * published protocol doc exists for this release). Shapes below are the
+ * minimal surface the plan names for the five shipped events
+ * (`PreToolUse`/`PostToolUse`/`PreInvocation`/`PostInvocation`/`Stop`),
+ * derived structurally from Claude Code's and Codex's `types.ts` rather than
+ * from any Antigravity-specific reference — there is none to cite yet.
+ * @module
+ */
+export {};

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

@@ -0,0 +1,27 @@
+/**
+ * Environment variable utilities for Claude Code hooks.
+ *
+ * The implementation lives in the committed core (`../../core/env.ts`), which
+ * is a byte-for-byte port of `claude-code-hooks/src/env.ts`; this module is
+ * the per-agent import site so the Claude Code surface keeps its historical
+ * `env.js` path on the barrel.
+ * @module
+ * @example
+ * ```typescript
+ * import { getProjectDir, persistEnvVar, isRemoteEnvironment } from '@goodfoot/agent-hooks/claude-code';
+ *
+ * // Get project directory
+ * const projectDir = getProjectDir();
+ *
+ * // Check if running remotely
+ * if (isRemoteEnvironment()) {
+ *   // Handle remote-specific logic
+ * }
+ *
+ * // In SessionStart hook: persist environment variables
+ * persistEnvVar('NODE_ENV', 'production');
+ * persistEnvVar('API_KEY', 'secret-key');
+ * ```
+ * @see https://code.claude.com/docs/en/hooks#hook-execution-details
+ */
+export { CLAUDE_ENV_VARS, getEnvFilePath, getProjectDir, isRemoteEnvironment, persistEnvVar, persistEnvVars, } from "../../core/env.js";

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

@@ -0,0 +1,87 @@
+/**
+ * Claude Code hook event names and the advisory fail-open allow-list.
+ *
+ * `HOOK_EVENT_NAMES` is copied verbatim from `claude-code-hooks/src/types.ts`
+ * (all 30 events, same order). The advisory allow-list is **not** authored
+ * here: per the plan's derivation rule it is transcribed from CARD.md:75 —
+ * quoted below above `EXCLUDED_FROM_ADVISORY` — and `ADVISORY_EVENTS` is
+ * derived mechanically as "every event except the exclusion set". The unit
+ * test in `tests/agents/claude-code/` 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 Claude Code hook event names as a readonly array.
+ *
+ * Useful for iteration and validation.
+ * @example
+ * ```typescript
+ * for (const eventName of HOOK_EVENT_NAMES) {
+ *   console.log(`Supported hook: ${eventName}`);
+ * }
+ * ```
+ */
+export const HOOK_EVENT_NAMES = [
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PostToolBatch",
+    "Notification",
+    "UserPromptExpansion",
+    "UserPromptSubmit",
+    "SessionStart",
+    "SessionEnd",
+    "Stop",
+    "StopFailure",
+    "SubagentStart",
+    "SubagentStop",
+    "PreCompact",
+    "PostCompact",
+    "PermissionRequest",
+    "PermissionDenied",
+    "Setup",
+    "TeammateIdle",
+    "TaskCreated",
+    "TaskCompleted",
+    "Elicitation",
+    "ElicitationResult",
+    "ConfigChange",
+    "InstructionsLoaded",
+    "WorktreeCreate",
+    "WorktreeRemove",
+    "CwdChanged",
+    "FileChanged",
+    "MessageDisplay",
+];
+/**
+ * Events never allowed the fail-open `unexpectedError: "continue"` policy.
+ *
+ * Transcribed verbatim from CARD.md:75:
+ *
+ * > `unexpectedError: "continue"` is rejected at the type level and at
+ * > runtime for any event not on that agent's advisory list (never
+ * > `PreToolUse`, `PermissionRequest`, blocking `Stop`/`SubagentStop`,
+ * > `WorktreeCreate`/`WorktreeRemove` on Claude Code; ...).
+ *
+ * The first five refuse because a swallowed failure silently grants the very
+ * decision the hook was supposed to make; the worktree pair additionally
+ * speaks a plain-text stdout protocol with no safe generic fallback, so a
+ * swallowed failure would write literal `{}` where the host expects a path.
+ */
+export const EXCLUDED_FROM_ADVISORY = [
+    "PreToolUse",
+    "PermissionRequest",
+    "Stop",
+    "SubagentStop",
+    "WorktreeCreate",
+    "WorktreeRemove",
+];
+/**
+ * The advisory allow-list: every Claude Code event except
+ * {@link EXCLUDED_FROM_ADVISORY}. Only these events accept
+ * `unexpectedError: "continue"` — enforced at factory-call time by the
+ * policy gate injected into {@link ../core/define-hook.ts|defineHook} 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));