@goodfoot/agent-hooks 1.0.0

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

@@ -0,0 +1,76 @@
+/**
+ * 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 type { HookContext, UnexpectedErrorHandler, UnexpectedErrorPolicy } from "../../core/types.js";
+import { type AllowedUnexpectedErrorPolicy } from "./events.js";
+import type { PostInvocationOutput, PostToolUseOutput, PreInvocationOutput, PreToolUseOutput, StopOutput } from "./outputs.js";
+import type { HookEventName, PostInvocationInput, PostToolUseInput, PreInvocationInput, PreToolUseInput, StopInput } from "./types.js";
+export type { HookContext, UnexpectedErrorHandler, UnexpectedErrorPolicy };
+/** The two events whose bound config accepts a `matcher`, as a literal union. */
+type EventWithMatcher = "PreToolUse" | "PostToolUse";
+/** The base field list every Antigravity hook config shares. */
+export interface HookConfig {
+    matcher?: string;
+    timeout?: number;
+    unexpectedError?: UnexpectedErrorPolicy;
+    onUnexpectedError?: UnexpectedErrorHandler;
+}
+/**
+ * Per-event config: `matcher` only appears in the type for
+ * {@link EventWithMatcher}, and `unexpectedError` is narrowed per event by
+ * the advisory allow-list ({@link AllowedUnexpectedErrorPolicy}).
+ * @template TEvent - The event the factory binds.
+ */
+export type HookConfigFor<TEvent extends HookEventName> = Omit<HookConfig, "matcher" | "unexpectedError"> & (TEvent extends EventWithMatcher ? Pick<HookConfig, "matcher"> : Record<never, never>) & {
+    unexpectedError?: AllowedUnexpectedErrorPolicy<TEvent>;
+};
+type PreToolUseResult = PreToolUseOutput | undefined;
+type PostToolUseResult = PostToolUseOutput | undefined;
+type PreInvocationResult = PreInvocationOutput | undefined;
+type PostInvocationResult = PostInvocationOutput | undefined;
+type StopResult = StopOutput | undefined;
+/**
+ * A bound Antigravity hook: the wrapped handler plus its driver metadata.
+ * Carries both `hookEventName` (this surface's historical property name)
+ * and `eventName` (the core driver's property), identical values.
+ * @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> {
+    (input: TInput, context: HookContext): Promise<TOutput | null>;
+    hookEventName: TEvent;
+    eventName: string;
+    matcher?: string;
+    timeout?: number;
+    unexpectedError?: UnexpectedErrorPolicy;
+    onUnexpectedError?: UnexpectedErrorHandler;
+    createContext?: (input: TInput) => HookContext;
+}
+/** Creates a PreToolUse hook handler. */
+export declare function preToolUseHook(config: HookConfigFor<"PreToolUse">, handler: (input: PreToolUseInput, context: HookContext) => PreToolUseResult | Promise<PreToolUseResult>): HookFunction<PreToolUseInput, PreToolUseResult, "PreToolUse">;
+/** Creates a PostToolUse hook handler. */
+export declare function postToolUseHook(config: HookConfigFor<"PostToolUse">, handler: (input: PostToolUseInput, context: HookContext) => PostToolUseResult | Promise<PostToolUseResult>): HookFunction<PostToolUseInput, PostToolUseResult, "PostToolUse">;
+/** Creates a PreInvocation hook handler. */
+export declare function preInvocationHook(config: HookConfigFor<"PreInvocation">, handler: (input: PreInvocationInput, context: HookContext) => PreInvocationResult | Promise<PreInvocationResult>): HookFunction<PreInvocationInput, PreInvocationResult, "PreInvocation">;
+/** Creates a PostInvocation hook handler. */
+export declare function postInvocationHook(config: HookConfigFor<"PostInvocation">, handler: (input: PostInvocationInput, context: HookContext) => PostInvocationResult | Promise<PostInvocationResult>): HookFunction<PostInvocationInput, PostInvocationResult, "PostInvocation">;
+/** Creates a Stop hook handler. */
+export declare function stopHook(config: HookConfigFor<"Stop">, handler: (input: StopInput, context: HookContext) => StopResult | Promise<StopResult>): HookFunction<StopInput, StopResult, "Stop">;

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

@@ -0,0 +1,27 @@
+/**
+ * `@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
+ */
+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 { createAntigravityTransport, execute } from "./transport.js";
+export type { BaseHookInput, HookErrorPhase, HookEventName, HookInput, PostInvocationInput, PostToolUseInput, PreInvocationInput, PreToolUseInput, StopInput, } from "./types.js";

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

@@ -0,0 +1,107 @@
+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 declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+};
+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:
+ *
+ * - `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.
+ */
+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;
+/**
+ * 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.
+ */
+export interface AntigravityHookOutput {
+    decision?: AntigravityDecision;
+    reason?: string;
+    additionalContext?: string;
+    updatedInput?: unknown;
+    stop?: boolean;
+    systemMessage?: string;
+}
+export interface HookOutput {
+    stdout: AntigravityHookOutput;
+}
+export interface PreToolUseOptions {
+    decision?: AntigravityDecision;
+    reason?: string;
+    additionalContext?: string;
+    updatedInput?: unknown;
+    systemMessage?: string;
+}
+export interface PostToolUseOptions {
+    decision?: AntigravityPostDecision;
+    reason?: string;
+    additionalContext?: string;
+    systemMessage?: string;
+}
+export interface PreInvocationOptions {
+    decision?: Extract<AntigravityDecision, "allow" | "deny" | "ask">;
+    reason?: string;
+    additionalContext?: string;
+    systemMessage?: string;
+}
+export interface PostInvocationOptions {
+    additionalContext?: string;
+    systemMessage?: string;
+}
+export interface StopOptions {
+    stop?: boolean;
+    reason?: string;
+    systemMessage?: string;
+}
+/**
+ * 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 declare class AntigravityBlockError extends HookBlockError {
+    readonly reason: string;
+    constructor(reason: string);
+}
+export declare function preToolUseOutput(options?: PreToolUseOptions): PreToolUseOutput;
+export declare function postToolUseOutput(options?: PostToolUseOptions): PostToolUseOutput;
+export declare function preInvocationOutput(options?: PreInvocationOptions): PreInvocationOutput;
+export declare function postInvocationOutput(options?: PostInvocationOptions): PostInvocationOutput;
+export declare function stopOutput(options?: StopOptions): StopOutput;
+export {};

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

@@ -0,0 +1,47 @@
+/**
+ * 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 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";
+/**
+ * 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 declare function createAntigravityTransport(): Transport<SpecificHookOutput | undefined>;
+/**
+ * Executes a hook handler with full runtime orchestration (delegates to the
+ * shared core driver with this agent's transport).
+ */
+export declare function execute<TInput extends HookInput, TOutput>(hookFn: HookFunction<TInput, TOutput, HookEventName>): Promise<void>;

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

@@ -0,0 +1,58 @@
+/**
+ * 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 type HookEventName = "PreToolUse" | "PostToolUse" | "PreInvocation" | "PostInvocation" | "Stop";
+export interface BaseHookInput {
+    cwd: string;
+    hook_event_name: HookEventName;
+    session_id: string;
+}
+export interface PreToolUseInput extends BaseHookInput {
+    hook_event_name: "PreToolUse";
+    tool_name: string;
+    tool_input: unknown;
+}
+export interface PostToolUseInput extends BaseHookInput {
+    hook_event_name: "PostToolUse";
+    tool_name: string;
+    tool_input: unknown;
+    tool_response: unknown;
+}
+export interface PreInvocationInput extends BaseHookInput {
+    hook_event_name: "PreInvocation";
+    prompt: string;
+}
+export interface PostInvocationInput extends BaseHookInput {
+    hook_event_name: "PostInvocation";
+    response: string | null;
+}
+export interface StopInput extends BaseHookInput {
+    hook_event_name: "Stop";
+    last_assistant_message: string | null;
+}
+export type HookInput = PreToolUseInput | PostToolUseInput | PreInvocationInput | PostInvocationInput | StopInput;
+/**
+ * "error" (default) surfaces an unexpected runtime failure through the
+ * transport's stderr diagnostic channel (see `transport.ts` — Antigravity has
+ * 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.
+ */
+export type UnexpectedErrorPolicy = "error" | "continue";
+/** The runtime phase in which an unexpected error occurred. */
+export type HookErrorPhase = "read" | "parse" | "handler" | "serialize" | "write" | "cleanup";
+/**
+ * Best-effort diagnostic sink for unexpected errors under the "continue"
+ * policy. Errors thrown by this handler are swallowed.
+ */
+export type UnexpectedErrorHandler = (error: unknown, phase: HookErrorPhase) => void;

package/types/agents/claude-code/env.d.ts

@@ -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/types/agents/claude-code/events.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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
+ */
+import type { UnexpectedErrorPolicy } from "../../core/types.js";
+import type { HookEventName } from "./types.js";
+/**
+ * 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 declare const HOOK_EVENT_NAMES: readonly ["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 declare const EXCLUDED_FROM_ADVISORY: readonly ["PreToolUse", "PermissionRequest", "Stop", "SubagentStop", "WorktreeCreate", "WorktreeRemove"];
+/**
+ * Type-level membership check for the advisory allow-list.
+ *
+ * Resolves to `true` only for event names excluded from the allow-list.
+ */
+export type IsExcludedEvent<TEventName extends HookEventName> = TEventName extends ExcludedEventName ? true : false;
+/** The exclusion set as a literal union. */
+export type ExcludedEventName = (typeof EXCLUDED_FROM_ADVISORY)[number];
+/** The advisory allow-list as a literal union: every event except {@link ExcludedEventName}. */
+export type AdvisoryEventName = Exclude<HookEventName, ExcludedEventName>;
+/**
+ * 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 declare const ADVISORY_EVENTS: readonly AdvisoryEventName[];
+/**
+ * The policy type an event may carry, narrowed by allow-list membership.
+ *
+ * Advisory events keep the full `"error" | "continue"` union; every excluded
+ * event collapses to `"error"`, so passing `"continue"` there is rejected at
+ * compile time (and again at factory-call time by the runtime gate).
+ */
+export type AllowedUnexpectedErrorPolicy<TEventName extends HookEventName> = IsExcludedEvent<TEventName> extends true ? Exclude<UnexpectedErrorPolicy, "continue"> : UnexpectedErrorPolicy;