@goodfoot/agent-hooks 1.0.7 → 1.0.9

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

@@ -1,37 +1,39 @@
 /**
- * Antigravity hook event names and the (currently empty) advisory allow-list.
+ * Antigravity hook event names, the grouped/flat structural split, and the
+ * (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"`.
+ * The host's hook reference — pinned in this directory's `CONTRACT.md` —
+ * names five events and splits them structurally: `PreToolUse` and
+ * `PostToolUse` wrap their handlers in a `{ matcher, hooks }` group, while
+ * `PreInvocation`, `PostInvocation`, and `Stop` list handler objects
+ * directly and ignore any matcher. {@link EVENTS_WITH_MATCHER} is that split,
+ * and `cli-support.ts` emits `hooks.json` from it.
  *
- * 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.
+ * The advisory allow-list is empty, and stays empty: the reference names no
+ * event as safe to fail open. That default is load-bearing here in a way it
+ * is not on the other two agents, because Antigravity has no exit-code
+ * channel at all (every event is payload-only — see `transport.ts` and
+ * `outputs.ts`'s {@link AntigravityBlockError}), so a fail-open swallow has
+ * no loud path to degrade to. `AntigravityBlockError` is what would make
+ * widening the list safe 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
  */
 import type { UnexpectedErrorPolicy } from "../../core/types.js";
 import type { HookEventName } from "./types.js";
 /** All Antigravity hook event names as a readonly array. */
 export declare const HOOK_EVENT_NAMES: readonly ["PreToolUse", "PostToolUse", "PreInvocation", "PostInvocation", "Stop"];
-/** The two events whose config accepts a `matcher` (plan step 5.3: "matcher on the two ToolUse events"). */
+/**
+ * The two events whose `hooks.json` entry is grouped under a `matcher`. The
+ * other three are flat: the host ignores a matcher on them entirely.
+ */
 export declare const EVENTS_WITH_MATCHER: readonly HookEventName[];
 /**
  * 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.
+ * Every shipped event. The host's hook reference names no event as safe to
+ * fail open, so this is a transcribed conclusion, not a placeholder.
  */
 export declare const EXCLUDED_FROM_ADVISORY: readonly ["PreToolUse", "PostToolUse", "PreInvocation", "PostInvocation", "Stop"];
 /** The exclusion set as a literal union. Currently every event. */
@@ -40,7 +42,7 @@ export type ExcludedEventName = (typeof EXCLUDED_FROM_ADVISORY)[number];
 export type IsExcludedEvent<TEventName extends HookEventName> = TEventName extends ExcludedEventName ? true : false;
 /** The advisory allow-list as a literal union: every event except {@link ExcludedEventName} — currently `never`. */
 export type AdvisoryEventName = Exclude<HookEventName, ExcludedEventName>;
-/** The advisory allow-list. Empty until a future `CONTRACT.md` names an entry. */
+/** The advisory allow-list. Empty: `CONTRACT.md` names no event safe to fail open. */
 export declare const ADVISORY_EVENTS: readonly AdvisoryEventName[];
 /**
  * The policy type an event may carry, narrowed by allow-list membership.

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

@@ -2,20 +2,19 @@
  * 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.
+ * 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, and `CONTRACT.md` names no event
+ * safe to fail open); {@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.
+ * list twice. The host ignores a matcher on the other three events entirely,
+ * so accepting one there would be a silent no-op.
  * @module
  */
 import type { HookContext, UnexpectedErrorHandler, UnexpectedErrorPolicy } from "../../core/types.js";

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

@@ -1,27 +1,20 @@
 /**
  * `@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 five hook factories, their per-event output builders, the
+ * `AntigravityBlockError` block signal, the wire input/output types, and the
+ * runtime `execute` entry point. No default export.
  *
- * 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.
+ * Every shape here is transcribed from `CONTRACT.md` in this directory, which
+ * pins the host's own hook reference. Two consequences shape the whole
+ * surface: keys are camelCase, and each event has a **different** stdout
+ * shape rather than one shared envelope.
  * @module
  */
 export type { AdvisoryEventName, AllowedUnexpectedErrorPolicy, ExcludedEventName, IsExcludedEvent, } from "./events.js";
 export { ADVISORY_EVENTS, EVENTS_WITH_MATCHER, EXCLUDED_FROM_ADVISORY, HOOK_EVENT_NAMES } from "./events.js";
 export type { HookConfig, HookConfigFor, HookContext, HookFunction, UnexpectedErrorHandler, UnexpectedErrorPolicy, } from "./hooks.js";
 export { postInvocationHook, postToolUseHook, preInvocationHook, preToolUseHook, stopHook } from "./hooks.js";
-export { AntigravityBlockError, type AntigravityDecision, type AntigravityHookOutput, type AntigravityPostDecision, EXIT_CODES, type ExitCode, type HookOutput, type PostInvocationOptions, type PostInvocationOutput, type PostToolUseOptions, type PostToolUseOutput, type PreInvocationOptions, type PreInvocationOutput, type PreToolUseOptions, type PreToolUseOutput, postInvocationOutput, postToolUseOutput, preInvocationOutput, preToolUseOutput, type SpecificHookOutput, type StopOptions, type StopOutput, stopOutput, } from "./outputs.js";
+export { AntigravityBlockError, type AntigravityDecision, type AntigravityHookOutput, EXIT_CODES, type ExitCode, type HookOutput, type InjectStep, type PostInvocationOptions, type PostInvocationOutput, type PostInvocationStdout, type PostToolUseOutput, type PostToolUseStdout, type PreInvocationOptions, type PreInvocationOutput, type PreInvocationStdout, type PreToolUseOptions, type PreToolUseOutput, type PreToolUseStdout, postInvocationOutput, postToolUseOutput, preInvocationOutput, preToolUseOutput, type SpecificHookOutput, type StopDecision, type StopOptions, type StopOutput, type StopStdout, stopOutput, type TerminationBehavior, } from "./outputs.js";
 export { createAntigravityTransport, execute } from "./transport.js";
-export type { BaseHookInput, HookErrorPhase, HookEventName, HookInput, PostInvocationInput, PostToolUseInput, PreInvocationInput, PreToolUseInput, StopInput, } from "./types.js";
+export type { AntigravityToolCall, BaseHookInput, HookErrorPhase, HookEventName, HookInput, PostInvocationInput, PostToolUseInput, PreInvocationInput, PreToolUseInput, StopInput, } from "./types.js";

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

@@ -1,3 +1,14 @@
+/**
+ * Antigravity output builders, one per event.
+ *
+ * Unlike Claude Code and Codex, Antigravity gives each event a **different**
+ * stdout shape — there is no single envelope every event shares. `PreToolUse`
+ * returns a permission decision, `PostToolUse` returns `{}` and nothing else,
+ * the two invocation events return injected steps, and `Stop` returns a
+ * continue-or-not decision. Each builder below emits only the fields its own
+ * event's contract names; see `CONTRACT.md` in this directory.
+ * @module
+ */
 import { HookBlockError } from "../../core/transport.js";
 /**
  * Antigravity has no exit-code signaling channel: every event replies at
@@ -11,97 +22,115 @@ export declare const EXIT_CODES: {
 };
 export type ExitCode = (typeof EXIT_CODES)[keyof typeof EXIT_CODES];
 /**
- * The full permission-decision vocabulary a `PreToolUse` handler may return,
- * derived structurally from Codex's narrower `PreToolUsePermissionDecision`
- * (`"allow" | "deny" | "ask"`) plus the two additional values the plan names
- * verbatim (`force_ask`, `deny_unless_prior_grant`) with no further doc to
- * cite this release:
+ * The `PreToolUse` permission vocabulary, verbatim from the host reference:
  *
- * - `force_ask` — like `ask`, but the handler is asserting the host may not
- *   auto-resolve this prompt from a prior grant even if one would otherwise
- *   apply;
- * - `deny_unless_prior_grant` — deny unless the host already holds a prior
- *   grant covering this exact call.
+ * - `allow` — run the tool without prompting;
+ * - `deny` — hard block the execution immediately;
+ * - `ask` — prompt the user, respecting the "Always Allow" cache;
+ * - `force_ask` — always prompt, ignoring cached permissions.
+ *
+ * There is no fifth value. An earlier draft of this surface carried
+ * `deny_unless_prior_grant`; the host reference does not define it, and the
+ * host would treat it as an unrecognized decision.
  */
-export type AntigravityDecision = "allow" | "deny" | "ask" | "force_ask" | "deny_unless_prior_grant";
-/** The narrower decision vocabulary available after a tool has already run. */
-export type AntigravityPostDecision = Extract<AntigravityDecision, "allow" | "deny">;
-interface BaseSpecificOutput<T extends string> {
-    readonly _type: T;
-    readonly stdout: AntigravityHookOutput;
-}
-export type PreToolUseOutput = BaseSpecificOutput<"PreToolUse">;
-export type PostToolUseOutput = BaseSpecificOutput<"PostToolUse">;
-export type PreInvocationOutput = BaseSpecificOutput<"PreInvocation">;
-export type PostInvocationOutput = BaseSpecificOutput<"PostInvocation">;
-export type StopOutput = BaseSpecificOutput<"Stop">;
-export type SpecificHookOutput = PreToolUseOutput | PostToolUseOutput | PreInvocationOutput | PostInvocationOutput | StopOutput;
+export type AntigravityDecision = "allow" | "deny" | "ask" | "force_ask";
 /**
- * The wire shape every event's stdout carries. Termination is expressed the
- * same payload-only way a decision is: `stop: true` asks the host to end the
- * session, there being no separate exit-code channel to carry that signal.
+ * The `Stop` decision. `"continue"` blocks the stop and re-enters the loop;
+ * any other value lets the agent stop, so `"stop"` is spelled explicitly here
+ * rather than left to an omitted field.
  */
-export interface AntigravityHookOutput {
+export type StopDecision = "continue" | "stop";
+/** How the host should treat loop termination after `PostInvocation`. */
+export type TerminationBehavior = "force_continue" | "terminate" | "";
+/**
+ * A step injected by `PreInvocation` or `PostInvocation`. Exactly one of the
+ * three forms per entry.
+ */
+export type InjectStep = {
+    toolCall: {
+        name: string;
+        args: Record<string, unknown>;
+    };
+} | {
+    userMessage: string;
+} | {
+    ephemeralMessage: string;
+};
+/** `PreToolUse` stdout. */
+export interface PreToolUseStdout {
     decision?: AntigravityDecision;
     reason?: string;
-    additionalContext?: string;
-    updatedInput?: unknown;
-    stop?: boolean;
-    systemMessage?: string;
-}
-export interface HookOutput {
-    stdout: AntigravityHookOutput;
+    permissionOverrides?: string[];
+    overwrite?: Record<string, unknown>;
 }
-export interface PreToolUseOptions {
-    decision?: AntigravityDecision;
-    reason?: string;
-    additionalContext?: string;
-    updatedInput?: unknown;
-    systemMessage?: string;
+/** `PostToolUse` stdout: the contract specifies an empty object and nothing else. */
+export type PostToolUseStdout = Record<string, never>;
+/** `PreInvocation` stdout. */
+export interface PreInvocationStdout {
+    injectSteps?: InjectStep[];
 }
-export interface PostToolUseOptions {
-    decision?: AntigravityPostDecision;
-    reason?: string;
-    additionalContext?: string;
-    systemMessage?: string;
+/** `PostInvocation` stdout. */
+export interface PostInvocationStdout {
+    injectSteps?: InjectStep[];
+    terminationBehavior?: TerminationBehavior;
 }
-export interface PreInvocationOptions {
-    decision?: Extract<AntigravityDecision, "allow" | "deny" | "ask">;
+/** `Stop` stdout. */
+export interface StopStdout {
+    decision?: StopDecision;
     reason?: string;
-    additionalContext?: string;
-    systemMessage?: string;
 }
-export interface PostInvocationOptions {
-    additionalContext?: string;
-    systemMessage?: string;
+interface BaseSpecificOutput<TType extends string, TStdout> {
+    readonly _type: TType;
+    readonly stdout: TStdout;
 }
-export interface StopOptions {
-    stop?: boolean;
-    reason?: string;
-    systemMessage?: string;
+export type PreToolUseOutput = BaseSpecificOutput<"PreToolUse", PreToolUseStdout>;
+export type PostToolUseOutput = BaseSpecificOutput<"PostToolUse", PostToolUseStdout>;
+export type PreInvocationOutput = BaseSpecificOutput<"PreInvocation", PreInvocationStdout>;
+export type PostInvocationOutput = BaseSpecificOutput<"PostInvocation", PostInvocationStdout>;
+export type StopOutput = BaseSpecificOutput<"Stop", StopStdout>;
+export type SpecificHookOutput = PreToolUseOutput | PostToolUseOutput | PreInvocationOutput | PostInvocationOutput | StopOutput;
+/** The union of every event's stdout shape. */
+export type AntigravityHookOutput = PreToolUseStdout | PostToolUseStdout | PreInvocationStdout | PostInvocationStdout | StopStdout;
+export interface HookOutput {
+    stdout: AntigravityHookOutput;
 }
+export type PreToolUseOptions = PreToolUseStdout;
+export type PreInvocationOptions = PreInvocationStdout;
+export type PostInvocationOptions = PostInvocationStdout;
+export type StopOptions = StopStdout;
 /**
  * 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.
+ * The class matters more here than on the other two agents: because every
+ * Antigravity event replies at exit 0 with the decision expressed only in the
+ * JSON payload, a handler that throws mid-decision has no narrower exit-code
+ * fallback to land on the way Codex's stderr+exit-2 channel does. Without
+ * this class the block would be indistinguishable from a swallowed crash.
+ *
+ * The transport serializes it as `{ "decision": "deny", ... }`, which the
+ * host acts on for `PreToolUse` only. On the other four events the reply is
+ * well-formed but carries no decision the host recognizes, so it reads as an
+ * empty response.
  */
 export declare class AntigravityBlockError extends HookBlockError {
     readonly reason: string;
     constructor(reason: string);
 }
+/** Builds a `PreToolUse` reply: a permission decision, optionally with argument overwrites. */
 export declare function preToolUseOutput(options?: PreToolUseOptions): PreToolUseOutput;
-export declare function postToolUseOutput(options?: PostToolUseOptions): PostToolUseOutput;
+/**
+ * Builds the `PostToolUse` reply. The contract defines the reply as an empty
+ * object, so this builder takes no options: there is nothing a `PostToolUse`
+ * handler can tell the host.
+ */
+export declare function postToolUseOutput(): PostToolUseOutput;
+/** Builds a `PreInvocation` reply carrying steps to inject before the model runs. */
 export declare function preInvocationOutput(options?: PreInvocationOptions): PreInvocationOutput;
+/** Builds a `PostInvocation` reply: injected steps, a termination override, or both. */
 export declare function postInvocationOutput(options?: PostInvocationOptions): PostInvocationOutput;
+/** Builds a `Stop` reply. `decision: "continue"` blocks the stop; `reason` is injected as a system message. */
 export declare function stopOutput(options?: StopOptions): StopOutput;
 export {};

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

@@ -0,0 +1,16 @@
+import type { HookEventName } from "./types.js";
+export interface ScaffoldOptions {
+    directory: string;
+    hooks: string[];
+    outputPath: string;
+}
+/** Resolves user-supplied hook names case-insensitively, rejecting the whole list on any miss. */
+export declare function validateHookNames(requested: string[]): {
+    valid: true;
+    normalized: HookEventName[];
+} | {
+    valid: false;
+    error: string;
+};
+/** Creates a new Antigravity hook project. Refuses to write into an existing directory. */
+export declare function scaffoldProject(options: ScaffoldOptions): void;

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

@@ -3,7 +3,7 @@
  * `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,
+ * Antigravity's wire semantics are the simplest of the four 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`
@@ -16,6 +16,8 @@
  *   ...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.
+ *   The host acts on that decision for `PreToolUse`; on the other four events
+ *   it is a well-formed reply carrying no decision the host recognizes.
  * - 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.

package/types/agents/antigravity/types.d.ts

@@ -1,41 +1,68 @@
 /**
- * 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.
+ * Antigravity wire types, transcribed from the host's own hook reference.
+ *
+ * Source of record: `assets/external/skills/agy-customizations/docs/hooks.md`,
+ * embedded in the `agy` binary and pinned verbatim in this directory's
+ * `CONTRACT.md`. Nothing here is derived by analogy from Claude Code or
+ * Codex — the three agents' payloads share no field.
+ *
+ * Two properties of this contract drive every shape below:
+ *
+ * 1. **All keys are camelCase** (protojson encoding), including `stepIdx` and
+ *    `conversationId`.
+ * 2. **No payload carries its own event name.** Claude Code's
+ *    `hook_event_name` and Codex's equivalent have no counterpart here; a
+ *    handler knows its event only from the factory it was built with.
  * @module
  */
 export type HookEventName = "PreToolUse" | "PostToolUse" | "PreInvocation" | "PostInvocation" | "Stop";
+/**
+ * System metadata present on every payload.
+ *
+ * `transcriptPath` and `artifactDirectoryPath` name a product-specific
+ * directory (`antigravity/`, `antigravity-cli/`, or `antigravity-ide/`
+ * depending on the interface), so neither may be pattern-matched.
+ */
 export interface BaseHookInput {
-    cwd: string;
-    hook_event_name: HookEventName;
-    session_id: string;
+    conversationId: string;
+    workspacePaths: string[];
+    transcriptPath: string;
+    artifactDirectoryPath: string;
+    modelName: string;
+}
+/**
+ * A tool call as the host presents it. `name` is the step type lowercased with
+ * the `CORTEX_STEP_TYPE_` prefix removed — the same string a `matcher` regex
+ * is tested against.
+ */
+export interface AntigravityToolCall {
+    name: string;
+    args: Record<string, unknown>;
 }
 export interface PreToolUseInput extends BaseHookInput {
-    hook_event_name: "PreToolUse";
-    tool_name: string;
-    tool_input: unknown;
+    toolCall: AntigravityToolCall;
+    stepIdx: number;
 }
+/** `error` is present only when the tool failed (e.g. `"exit status 1"`). */
 export interface PostToolUseInput extends BaseHookInput {
-    hook_event_name: "PostToolUse";
-    tool_name: string;
-    tool_input: unknown;
-    tool_response: unknown;
+    stepIdx: number;
+    error?: string;
 }
 export interface PreInvocationInput extends BaseHookInput {
-    hook_event_name: "PreInvocation";
-    prompt: string;
+    invocationNum: number;
+    initialNumSteps: number;
 }
+/** Identical to {@link PreInvocationInput}; the host sends the same payload. */
 export interface PostInvocationInput extends BaseHookInput {
-    hook_event_name: "PostInvocation";
-    response: string | null;
+    invocationNum: number;
+    initialNumSteps: number;
 }
+/** `terminationReason` is an open string — `"model_stop"`, `"max_steps_exceeded"`, `"error"`, and others. */
 export interface StopInput extends BaseHookInput {
-    hook_event_name: "Stop";
-    last_assistant_message: string | null;
+    executionNum: number;
+    terminationReason: string;
+    error?: string;
+    fullyIdle: boolean;
 }
 export type HookInput = PreToolUseInput | PostToolUseInput | PreInvocationInput | PostInvocationInput | StopInput;
 /**
@@ -44,9 +71,9 @@ export type HookInput = PreToolUseInput | PostToolUseInput | PreInvocationInput
  * no exit-code channel at all, so this never changes the process exit code).
  *
  * "continue" would swallow an unexpected failure into the event's empty
- * response. No event currently accepts it: {@link EXCLUDED_FROM_ADVISORY | the
- * advisory allow-list} in `events.ts` defaults to every event until a future
- * `CONTRACT.md` names an enrichment hook safe to opt in.
+ * response. No event accepts it: {@link EXCLUDED_FROM_ADVISORY | the advisory
+ * allow-list} in `events.ts` excludes every event, because the host's
+ * reference names no event as safe to fail open.
  */
 export type UnexpectedErrorPolicy = "error" | "continue";
 /** The runtime phase in which an unexpected error occurred. */

package/types/cli.d.ts

@@ -28,7 +28,7 @@ type HookContext = "plugin" | "agent";
  * Command-line arguments parsed from process.argv.
  */
 interface CliArgs {
-    /** Target agent runtime (required): "claude-code" | "codex" | "antigravity". */
+    /** Target agent runtime (required): "claude-code" | "codex" | "antigravity" | "opencode". */
     agent: string;
     /** Glob pattern for hook source files. */
     input: string;

package/types/index.d.ts

@@ -6,8 +6,8 @@
  * {@link HookBlockError}, the Logger, env utilities, and stdin helpers.
  *
  * Per-agent entry points (`@goodfoot/agent-hooks/claude-code`, `/codex`,
- * `/antigravity`) are added to the package `exports` map only in the step
- * that lands their implementation — never pre-declared.
+ * `/opencode`, `/antigravity`) expose each host's native protocol without
+ * leaking host-specific types through this root module.
  * @module
  */
 export { defineHook } from "./core/define-hook.js";