@goodfoot/agent-hooks 1.0.0 → 1.0.2

package/README.md

@@ -1,27 +1,190 @@
 # `@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.
+**Build AI coding agent hooks in TypeScript — one package, any supported agent.**
 
-**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.
+`@goodfoot/agent-hooks` is the unified successor to `@goodfoot/claude-code-hooks` and
+`@goodfoot/codex-hooks`: a shared agent-neutral core (hook factory primitive, transport
+driver, `Logger`, env/stdin utilities) with a per-agent entry point on top. Write
+TypeScript hooks, compile them with the bundled CLI, and run the resulting
+self-contained executables under Claude Code or Codex.
 
-## Exports map policy
+**Status: `1.0.0`.** Three entry points ship and are published: `@goodfoot/agent-hooks/claude-code`
+(full parity with `@goodfoot/claude-code-hooks`), `@goodfoot/agent-hooks/codex` (full
+parity with `@goodfoot/codex-hooks`), and `@goodfoot/agent-hooks/opencode` (native support
+for OpenCode's in-process plugin model — see [OpenCode](#opencode) below). Antigravity CLI
+support exists internally as typed factories, output builders, and a conformance matrix,
+but is **not** part of this release's public surface — there is no
+`@goodfoot/agent-hooks/antigravity` export yet, and `--agent antigravity` is rejected by
+the CLI. It ships once a non-interactive, authenticated Antigravity CLI exists to
+validate against.
 
-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.
+## Install
+
+```bash
+yarn add @goodfoot/agent-hooks
+# or npm install, pnpm, etc.
+```
+
+## Quick Start
+
+### 1. Write a hook
+
+Import factories from your target agent's entry point. **Note:** you must use
+`export default` and the factory function — the CLI's build step relies on it.
+
+Claude Code (`@goodfoot/agent-hooks/claude-code`):
+
+```typescript
+import { preToolUseHook, preToolUseOutput } from '@goodfoot/agent-hooks/claude-code';
+
+export default preToolUseHook({ matcher: 'Bash' }, async (input, { logger }) => {
+  const { command } = input.tool_input as { command: string };
+
+  // Use logger, NEVER console.log
+  logger.info('Checking command', { command });
+
+  if (command.trim() === 'ls') {
+    return preToolUseOutput({
+      systemMessage: 'Auto-approved: ls command is safe.',
+      hookSpecificOutput: { permissionDecision: 'allow' },
+    });
+  }
+
+  return preToolUseOutput({ systemMessage: 'Command passed through for review.' });
+});
+```
+
+Codex (`@goodfoot/agent-hooks/codex`):
+
+```typescript
+import { preToolUseHook, preToolUseOutput } from '@goodfoot/agent-hooks/codex';
+
+export default preToolUseHook(async (input, { logger }) => {
+  logger.info('Checking tool call', { tool: input.tool_name });
+  return preToolUseOutput({});
+});
+```
+
+### 2. Compile
+
+The `--agent` flag is required and never inferred — always pass it explicitly:
+
+```bash
+npx -y @goodfoot/agent-hooks --agent claude-code -i "hooks/**/*.ts" -o "./dist/hooks.json"
+npx -y @goodfoot/agent-hooks --agent codex -i "src/**/*.ts" -o ".codex/hooks.json"
+```
+
+Or scaffold a starter project:
+
+```bash
+npx -y @goodfoot/agent-hooks --agent claude-code --scaffold ./my-hooks --hooks Stop,SubagentStop -o dist/hooks.json
+```
+
+Run `npx -y @goodfoot/agent-hooks --help` for the full flag reference, including
+Codex-specific options (e.g. `--plugin-root`), `--log`/`--log-env-var`, `--executable`,
+and `--loader`.
+
+### 3. Run
+
+The compiled output is a self-contained executable per hook; point your agent's hook
+configuration (Claude Code's `hooks.json`, Codex's plugin `hooks.json`) at the compiled
+files, same as with the deprecated per-agent packages.
+
+## Hook events
+
+Each entry point exports one factory function and one matching output builder per
+supported event. Import both from the same entry point (`@goodfoot/agent-hooks/claude-code`
+or `@goodfoot/agent-hooks/codex`) — do not mix events or output builders across agents.
+
+- **Claude Code** (`src/agents/claude-code`): the full 30-factory surface ported from
+  `@goodfoot/claude-code-hooks`, including `preToolUseHook`, `postToolUseHook`,
+  `sessionStartHook`, `notificationHook`, `permissionRequestHook`, `elicitationHook`,
+  task/teammate hooks, `worktreeCreateHook`, and the `tool-helpers` type guards
+  (`isBashTool`, `isEditTool`, …).
+- **Codex** (`src/agents/codex`): the 10-factory surface ported from
+  `@goodfoot/codex-hooks`, including `preToolUseHook`, `postToolUseHook`,
+  `sessionStartHook`, `stopHook`, `subagentStartHook`/`subagentStopHook`,
+  `userPromptSubmitHook`, `preCompactHook`/`postCompactHook`, and `permissionRequestHook`.
+
+## OpenCode
+
+OpenCode's plugin model is a long-lived, in-process JS module with a stable callback map
+(`Hooks`) — not the one-shot stdin/stdout command-hook model Claude Code and Codex use, so
+`@goodfoot/agent-hooks/opencode` does **not** route through `defineHook`/`Transport`/`drive`.
+It ships its own primitives instead:
+
+```typescript
+import { defineOpenCodePlugin, guardAdvisory, createRootSessionRegistry } from '@goodfoot/agent-hooks/opencode';
+
+const sessions = createRootSessionRegistry();
+
+export default defineOpenCodePlugin({
+  id: 'my-plugin',
+  server: async ({ client }) => ({
+    event: guardAdvisory('event', async ({ event }) => {
+      if (event.type === 'session.created') {
+        sessions.observe(event.properties.info.id, event.properties.info.parentID);
+      } else {
+        sessions.observeResumed(event.properties.info?.id ?? '');
+      }
+    }, 'continue'),
+
+    'tool.execute.before': async (input, output) => {
+      if (input.tool === 'bash' && sessions.isRoot(input.sessionID)) {
+        output.args = { ...output.args, timeout: 30_000 };
+      }
+    },
+  }),
+});
+```
+
+- **`defineOpenCodePlugin({ id, server })`** validates and returns the `{ id, server }`
+  module shape OpenCode's real loader (`getServerPlugin`) accepts as a default export —
+  a bare `server` function also satisfies the loader and needs no wrapper.
+- **`guardAdvisory(name, handler, policy, onError?)`** applies the same opt-in
+  `"continue"` fail-open policy described below, restricted at the type level to
+  *advisory* callback names — `permission.ask` is the one policy-enforcing callback
+  (a real allow/deny security decision) and is rejected at compile time, since silently
+  swallowing its failure would skip that decision instead of making it.
+- **`createRootSessionRegistry()`** tracks session parentage and resumption across the
+  plugin's lifetime: a resumed session does not necessarily re-emit `session.created`, so
+  `observe`/`observeResumed` record first-seen-event distinctly and `isRoot`/`isResumed`
+  answer from that record.
+
+Compile with the same unified CLI, but `--agent opencode` treats `-o`/`--output` as a
+plugin-artifact **directory**, not a manifest path — OpenCode config references built
+files directly, so there is no `hooks.json`-equivalent manifest or shebang wrapper:
+
+```bash
+npx -y @goodfoot/agent-hooks --agent opencode -i "src/**/*.ts" -o "./.opencode/plugin"
+```
+
+Point `opencode.json`'s plugin list (or the equivalent config in your OpenCode host) at
+the compiled `.mjs` file(s) under that output directory.
+
+`@opencode-ai/plugin` is an **optional peer dependency** — only required if you import
+`@goodfoot/agent-hooks/opencode`; Claude Code and Codex hook authors never need it
+installed.
+
+## Fail-open advisory hooks
+
+Both entry points support the same opt-in `unexpectedError: "continue"` hook config used
+by the deprecated packages: unexpected runtime failures (stdin read, parse, handler
+execution, output serialization, stdout write, logger cleanup) are swallowed into the
+empty response instead of surfacing a failed-hook error. It is rejected — at the type
+level and at runtime — for events where fail-open would be unsafe (`PreToolUse`,
+`PermissionRequest`, blocking `Stop`/`SubagentStop`, `WorktreeCreate`/`WorktreeRemove` on
+Claude Code; permission/blocking events on Codex). A thrown `HookBlockError` always wins
+over this policy and still blocks.
 
 ## Core API
 
+The root export (`@goodfoot/agent-hooks`, no subpath) exposes only the agent-neutral
+core that each entry point is built on. It has no knowledge of exit codes or stdout
+policy — that's owned entirely by each agent's transport. Use this if you're extending
+an existing entry point or adding support for a new agent; hook authors targeting
+Claude Code or Codex should import from the per-agent entry point instead.
+
 ### `defineHook(eventName, config, handler, policyGate?)`
 
 Factory primitive every agent's per-event factory builds on:
@@ -127,6 +290,27 @@ 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)`.
 
+## Exports map policy
+
+The `exports` map is an explicit, closed list of subpaths. It deliberately
+does **not** include a `./*` wildcard subpath (unlike the deprecated 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.
+
+## Migrating from `@goodfoot/claude-code-hooks` / `@goodfoot/codex-hooks`
+
+Both source packages are deprecated in favor of this one. Migration is a dependency
+swap, not a behavior change:
+
+1. Replace the dependency: `@goodfoot/claude-code-hooks` → `@goodfoot/agent-hooks`, or
+   `@goodfoot/codex-hooks` → `@goodfoot/agent-hooks`.
+2. Update imports to the matching entry point: `@goodfoot/agent-hooks/claude-code` or
+   `@goodfoot/agent-hooks/codex`. Factory and output-builder names are unchanged.
+3. Update `build` scripts and any committed `hooks.json` to invoke the `agent-hooks` CLI
+   binary with the required `--agent <claude-code|codex>` flag.
+
 ## Development
 
 ```bash

package/dist/agents/codex/scaffold.js

@@ -54,7 +54,7 @@ function generatePackageJson(projectName, outputPath) {
             typecheck: "tsc --noEmit",
         },
         dependencies: {
-            [PACKAGE_NAME]: "^1.0.0",
+            [PACKAGE_NAME]: "^1.0.2",
         },
         devDependencies: {
             "@biomejs/biome": "2.4.9",

package/dist/agents/opencode/cli-support.js

@@ -0,0 +1,119 @@
+/**
+ * OpenCode-specific CLI internals: bundling each selected plugin entry to a
+ * standalone ESM artifact and validating its `{ id, server }` (or bare
+ * function) default-export contract against a real dynamic import of the
+ * built output — not a hand-rolled AST check, which could pass a shape the
+ * actual OpenCode loader would still reject.
+ *
+ * Unlike Codex's `compileCodexHook`, there is no wrapper content and no
+ * `execute()` runtime module to link: OpenCode imports the plugin author's
+ * own default export directly, so the bundle *is* the artifact — no
+ * stdin/stdout driver, no `hooks.json` manifest, no shebang.
+ *
+ * Driver-level primitives (loader parsing, glob discovery) are imported from
+ * the shared CLI module — never re-derived here.
+ * @module
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import * as esbuild from "esbuild";
+import { buildEsbuildLoaderMap, discoverHookSourceFiles, parseEsbuildLoaderFlag } from "../../cli.js";
+/**
+ * Bundles one OpenCode plugin entry to a self-contained ESM artifact. The
+ * source file's own default export is preserved unchanged — no wrapper.
+ */
+export async function compileOpenCodePlugin(sourcePath, loaders, sourcemap = true) {
+    const result = await esbuild.build({
+        entryPoints: [sourcePath],
+        loader: loaders,
+        format: "esm",
+        platform: "node",
+        target: "node20",
+        bundle: true,
+        sourcemap: sourcemap ? "inline" : false,
+        write: false,
+        external: ["node:*", "fs", "path", "os", "crypto", "module", "url"],
+        mainFields: ["module", "main"],
+        conditions: ["import", "node"],
+        preserveSymlinks: true,
+    });
+    const content = result.outputFiles?.[0]?.text;
+    if (content === undefined) {
+        throw new Error(`esbuild produced no output for ${sourcePath}`);
+    }
+    return content;
+}
+/**
+ * Validates that `outputPath`'s default export matches OpenCode's real
+ * loader contract (`getServerPlugin`): either a bare function, or an object
+ * with a `server` function property. Imports the built artifact itself
+ * rather than statically analyzing source, so the check exercises exactly
+ * what OpenCode's loader will see.
+ * @throws Error when the default export matches neither shape.
+ */
+export async function validateOpenCodePluginModule(outputPath) {
+    const imported = await import(pathToFileURL(outputPath).href);
+    const defaultExport = imported.default;
+    const isBareFunction = typeof defaultExport === "function";
+    const isServerModule = typeof defaultExport === "object" &&
+        defaultExport !== null &&
+        typeof defaultExport.server === "function";
+    if (!isBareFunction && !isServerModule) {
+        throw new Error(`${outputPath}: default export must be a function or a { server } object (OpenCode's loader contract), got ${typeof defaultExport}`);
+    }
+}
+async function compileAllOpenCodePlugins(pluginFiles, outputDir, loaders, sourcemap) {
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+    const compiled = [];
+    for (const sourcePath of pluginFiles) {
+        const content = await compileOpenCodePlugin(sourcePath, loaders, sourcemap);
+        const baseName = path.basename(sourcePath, path.extname(sourcePath));
+        const outputPath = path.join(outputDir, `${baseName}.mjs`);
+        fs.writeFileSync(outputPath, content, { encoding: "utf-8" });
+        try {
+            await validateOpenCodePluginModule(outputPath);
+        }
+        catch (error) {
+            fs.rmSync(outputPath);
+            throw error;
+        }
+        compiled.push({ sourcePath, outputPath });
+    }
+    return compiled;
+}
+/**
+ * Validates OpenCode build arguments beyond the shared `--agent` gate: `-i`
+ * and `-o` required, loader flags well-formed.
+ */
+export function validateOpenCodeArgs(args) {
+    if (args.input === "") {
+        return "Missing required argument: -i/--input";
+    }
+    if (args.output === "") {
+        return "Missing required argument: -o/--output";
+    }
+    for (const loaderFlag of args.loaderFlags) {
+        if (parseEsbuildLoaderFlag(loaderFlag) === undefined) {
+            return `Invalid --loader value: ${loaderFlag}. Expected .ext=type`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Runs the OpenCode build branch of the unified CLI: discovers plugin entry
+ * files matching `--input`, bundles each to a standalone ESM artifact under
+ * `--output` (treated as a directory — OpenCode plugin config references
+ * these files directly, there is no manifest), and validates each artifact's
+ * default export against OpenCode's real loader contract.
+ */
+export async function runOpenCodeCli(args) {
+    const cwd = process.cwd();
+    const pluginFiles = await discoverHookSourceFiles(args.input, cwd);
+    const outputDir = path.resolve(cwd, args.output);
+    const loaders = buildEsbuildLoaderMap(args.loaderFlags);
+    const sourcemap = args.sourcemap ?? true;
+    return compileAllOpenCodePlugins(pluginFiles, outputDir, loaders, sourcemap);
+}

package/dist/agents/opencode/events.js

@@ -0,0 +1,33 @@
+/**
+ * OpenCode callback policy split: which lifecycle callbacks may opt into
+ * guarded fail-open (`"continue"`) behavior, and which must always surface
+ * failures.
+ *
+ * Unlike Codex's advisory allow-list (transcribed from `codex-hooks/README.md`,
+ * an external source-of-truth document), OpenCode has no prior source package
+ * to transcribe from — this package *is* the source of truth for its own
+ * OpenCode surface. The split below is derived directly from CARD.md's
+ * Desired Functionality section (committed to the card repository, itself
+ * the authorization for this contract): "Advisory callbacks can opt into
+ * guarded fail-open behavior with observable diagnostics; policy-enforcing
+ * callbacks default to surfacing failures."
+ *
+ * `permission.ask` is the only callback whose `output.status` is an
+ * allow/deny/ask *security decision* — swallowing a failure there means the
+ * decision was silently skipped, exactly the Codex precedent
+ * (`PreToolUse`/`PermissionRequest`) this mirrors. Every other lifecycle
+ * callback only observes or additively enriches (message/tool mutation,
+ * shell env, event notification) and is therefore advisory.
+ * @module
+ */
+import { OPENCODE_HOOK_NAMES } from "./types.js";
+/** Callbacks that must always surface failures — never eligible for `"continue"`. */
+export const POLICY_ENFORCING_EVENTS = ["permission.ask"];
+/**
+ * The advisory allow-list: every OpenCode lifecycle callback except
+ * {@link POLICY_ENFORCING_EVENTS}. Only these accept
+ * `unexpectedError: "continue"`, enforced at compile time by
+ * {@link AllowedUnexpectedErrorPolicy} and at call time by
+ * {@link ../../core/define-hook.ts|the policy-gate pattern}.
+ */
+export const ADVISORY_EVENTS = OPENCODE_HOOK_NAMES.filter((name) => !POLICY_ENFORCING_EVENTS.includes(name));

package/dist/agents/opencode/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@goodfoot/agent-hooks/opencode` — the OpenCode agent surface.
+ *
+ * Re-exports OpenCode-native types (narrowed from `@opencode-ai/plugin`),
+ * the advisory/policy-enforcing callback split, the shared error-policy
+ * vocabulary, and the plugin authoring primitives. No default export at this
+ * subpath — `defineOpenCodePlugin`'s *return value* is the `{ id, server }`
+ * default export a plugin author's own module produces, not something this
+ * barrel exports itself.
+ * @module
+ */
+export { ADVISORY_EVENTS, POLICY_ENFORCING_EVENTS } from "./events.js";
+export { createRootSessionRegistry, defineOpenCodePlugin, guardAdvisory } from "./plugin.js";
+export { applyOpenCodeErrorPolicy } from "./policy.js";
+export { OPENCODE_HOOK_NAMES } from "./types.js";

package/dist/agents/opencode/plugin.js

@@ -0,0 +1,72 @@
+/**
+ * Plugin authoring primitives for `@goodfoot/agent-hooks/opencode`.
+ *
+ * `defineOpenCodePlugin` validates the `{ id, server }` module contract that
+ * OpenCode's real loader (`getServerPlugin`, verified live against
+ * `sst/opencode`'s `packages/opencode/src/plugin/index.ts`) accepts as a
+ * default export. `createRootSessionRegistry` and `guardAdvisory` are
+ * optional composition helpers a `server` factory may call — not a required
+ * framework, since a plugin author can also return a raw {@link Hooks}
+ * object built directly from `./types.js`.
+ * @module
+ */
+import { applyOpenCodeErrorPolicy } from "./policy.js";
+/**
+ * Validates and returns an OpenCode plugin module definition.
+ *
+ * @param definition - `id` must be a non-empty string; `server` must be a
+ * function matching upstream's {@link Plugin} signature.
+ * @returns `definition`, unchanged, once validated.
+ * @throws Error when `id` is missing/empty or `server` is not a function.
+ */
+export function defineOpenCodePlugin(definition) {
+    if (typeof definition.id !== "string" || definition.id.length === 0) {
+        throw new Error(`defineOpenCodePlugin: "id" must be a non-empty string, got ${JSON.stringify(definition.id)}`);
+    }
+    if (typeof definition.server !== "function") {
+        throw new Error(`defineOpenCodePlugin: "server" must be a function, got ${typeof definition.server}`);
+    }
+    return { id: definition.id, server: definition.server };
+}
+/** Creates a fresh, empty {@link RootSessionRegistry}. */
+export function createRootSessionRegistry() {
+    const parentBySessionId = new Map();
+    const resumedSessionIds = new Set();
+    const recordIfUnseen = (sessionId, parentId, resumed) => {
+        if (parentBySessionId.has(sessionId)) {
+            return;
+        }
+        parentBySessionId.set(sessionId, parentId);
+        if (resumed) {
+            resumedSessionIds.add(sessionId);
+        }
+    };
+    return {
+        observe(sessionId, parentId) {
+            recordIfUnseen(sessionId, parentId, false);
+        },
+        observeResumed(sessionId, parentId) {
+            recordIfUnseen(sessionId, parentId, true);
+        },
+        isRoot(sessionId) {
+            return parentBySessionId.get(sessionId) === undefined;
+        },
+        isResumed(sessionId) {
+            return resumedSessionIds.has(sessionId);
+        },
+    };
+}
+/**
+ * Wraps an advisory OpenCode callback with {@link applyOpenCodeErrorPolicy},
+ * restricted at the type level to {@link AdvisoryEventName}s — a
+ * policy-enforcing callback name is a compile-time error here, since
+ * swallowing its failure would silently skip a security decision.
+ *
+ * @param name - An advisory callback name from `./types.js`'s `Hooks` map.
+ * @param handler - The callback implementation to guard.
+ * @param policy - The configured policy; `undefined` behaves as `"error"`.
+ * @param onError - Best-effort diagnostic sink for a swallowed `"continue"` error.
+ */
+export function guardAdvisory(name, handler, policy, onError) {
+    return applyOpenCodeErrorPolicy(name, handler, policy, onError);
+}

package/dist/agents/opencode/policy.js

@@ -0,0 +1,40 @@
+/**
+ * OpenCode error-policy application.
+ *
+ * Reuses only the host-neutral policy vocabulary from
+ * {@link ../../core/types.ts} — not {@link ../../core/define-hook.ts|defineHook}
+ * itself, which is built around a single one-shot handler call and doesn't
+ * fit OpenCode's long-lived, heterogeneous callback map.
+ * @module
+ */
+/**
+ * Wraps an advisory OpenCode callback so an unexpected throw is handled
+ * per `policy` instead of propagating to the OpenCode server process.
+ *
+ * - `"error"` (default): rethrows unchanged.
+ * - `"continue"`: swallows the error, invokes `onError` (if provided) as a
+ *   best-effort diagnostic sink, and resolves instead of rejecting.
+ *
+ * Never call this for a policy-enforcing callback (see
+ * {@link ./events.ts|POLICY_ENFORCING_EVENTS}) — {@link ./plugin.ts|guardAdvisory}
+ * is the only intended caller and restricts callback names accordingly.
+ *
+ * @param name - The callback name, used only for the diagnostic sink.
+ * @param handler - The callback implementation to guard.
+ * @param policy - The configured policy; `undefined` behaves as `"error"`.
+ * @param onError - Best-effort diagnostic sink for a swallowed `"continue"` error.
+ * @throws Error the handler threw is thrown when `policy` is `"error"`.
+ */
+export function applyOpenCodeErrorPolicy(_name, handler, policy, onError) {
+    if (policy !== "continue") {
+        return handler;
+    }
+    return async (...args) => {
+        try {
+            await handler(...args);
+        }
+        catch (error) {
+            onError?.(error, "handler");
+        }
+    };
+}

package/dist/agents/opencode/types.js

@@ -0,0 +1,40 @@
+/**
+ * OpenCode-native types for `@goodfoot/agent-hooks/opencode`.
+ *
+ * OpenCode loads a long-lived, in-process plugin module rather than spawning
+ * a one-shot command-hook process: {@link PluginModule} (`{ id?, server }`)
+ * or a bare {@link Plugin} function is what OpenCode's real loader accepts —
+ * verified directly against the installed `@opencode-ai/plugin@1.18.23`
+ * `.d.ts`, not the (looser) public docs page. This module re-exports and
+ * narrows those upstream types; it never redeclares OpenCode's callback
+ * input/output shapes by hand, so this surface can't drift from the SDK it
+ * wraps.
+ * @module
+ */
+/**
+ * The stable, lifecycle-callback keys of {@link Hooks} — excludes `tool`
+ * (custom tool definitions, not a lifecycle callback), `auth` and `provider`
+ * (static registration objects), and `dispose` (a no-argument cleanup
+ * callback with no policy semantics of its own).
+ *
+ * Order matches declaration order in the upstream `Hooks` interface.
+ */
+export const OPENCODE_HOOK_NAMES = [
+    "event",
+    "config",
+    "chat.message",
+    "chat.params",
+    "chat.headers",
+    "permission.ask",
+    "command.execute.before",
+    "tool.execute.before",
+    "shell.env",
+    "tool.execute.after",
+    "experimental.chat.messages.transform",
+    "experimental.chat.system.transform",
+    "experimental.provider.small_model",
+    "experimental.session.compacting",
+    "experimental.compaction.autocontinue",
+    "experimental.text.complete",
+    "tool.definition",
+];

package/dist/cli.js

@@ -26,7 +26,7 @@ import { scaffoldProject } from "./scaffold.js";
 // ============================================================================
 // Constants
 // ============================================================================
-const VERSION = "1.0.0";
+const VERSION = "1.0.2";
 const DEFAULT_ESBUILD_LOADERS = {
     ".md": "text",
 };
@@ -65,10 +65,12 @@ Usage:
                             under a .codex/ directory use git-toplevel-relative commands.
 
 Required Arguments:
-  --agent <claude-code|codex|antigravity>
+  --agent <claude-code|codex|antigravity|opencode>
       The agent runtime the hooks are built for. Determines the hook surface
       validated at build time and the runtime module linked into each compiled
       bundle. There is no default: omitting this flag is an error.
+      With --agent opencode, -o/--output is treated as a plugin artifact
+      directory (no hooks.json manifest is generated).
       Example: --agent claude-code
 
 Build Mode (compile existing hooks):
@@ -325,11 +327,11 @@ function validateArgs(args) {
     // --agent is required and never inferred (plan step 2.3). Validate the
     // value against the agents this release knows, so a typo fails closed
     // instead of silently building for the wrong runtime.
-    const VALID_AGENTS = ["claude-code", "codex", "antigravity"];
+    const VALID_AGENTS = ["claude-code", "codex", "antigravity", "opencode"];
     const isKnownAgent = (value) => VALID_AGENTS.includes(value);
     if (!isKnownAgent(args.agent)) {
         return args.agent === ""
-            ? "Missing required argument: --agent <claude-code|codex|antigravity>"
+            ? "Missing required argument: --agent <claude-code|codex|antigravity|opencode>"
             : `Invalid --agent value: ${args.agent}. Valid agents: ${VALID_AGENTS.join(", ")}`;
     }
     // Scaffold mode validation
@@ -1217,9 +1219,42 @@ async function main() {
             closeLog();
         }
     }
+    if (args.agent === "opencode") {
+        const { runOpenCodeCli, validateOpenCodeArgs } = await import("./agents/opencode/cli-support.js");
+        const openCodeValidationError = validateOpenCodeArgs({
+            input: args.input,
+            output: args.output,
+            loaderFlags: args.loaderFlags ?? [],
+            sourcemap: args.sourcemap,
+        });
+        if (openCodeValidationError !== undefined) {
+            process.stderr.write(`Error: ${openCodeValidationError}\n\n`);
+            process.stdout.write(HELP_TEXT);
+            process.exit(1);
+        }
+        try {
+            const compiled = await runOpenCodeCli({
+                input: args.input,
+                output: args.output,
+                loaderFlags: args.loaderFlags ?? [],
+                sourcemap: args.sourcemap,
+            });
+            process.stdout.write(`Generated ${compiled.length} plugin artifact(s) in ${path.resolve(process.cwd(), args.output)}\n`);
+            process.exit(0);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log("error", "OpenCode build failed", { error: message });
+            process.stderr.write(`Error: ${message}\n`);
+            process.exit(1);
+        }
+        finally {
+            closeLog();
+        }
+    }
     // Antigravity ships in step 5; fail closed until then.
     if (args.agent !== "claude-code") {
-        process.stderr.write(`Error: --agent ${args.agent} is not implemented in this release; only "claude-code" and "codex" build today (antigravity ships in step 5).\n`);
+        process.stderr.write(`Error: --agent ${args.agent} is not implemented in this release; only "claude-code", "codex", and "opencode" build today (antigravity ships in step 5).\n`);
         process.exit(1);
     }
     // Handle scaffold mode

package/dist/scaffold.js

@@ -131,7 +131,7 @@ function generatePackageJson(projectName, outputPath) {
             typecheck: "tsc --noEmit",
         },
         dependencies: {
-            "@goodfoot/agent-hooks": "^1.0.0",
+            "@goodfoot/agent-hooks": "^1.0.2",
         },
         devDependencies: {
             "@biomejs/biome": "2.4.16",
@@ -427,7 +427,9 @@ describe("${eventName} Hook", () => {
     const result = await hook(mockInput, context);
 
     // Verify output has expected structure
-    expect(result).toBeDefined();
+    if (result == null) {
+      throw new Error("hook returned null");
+    }
     expect(result).toHaveProperty("_type", "${eventName}");
     expect(result).toHaveProperty("stdout");
     expect(typeof result.stdout).toBe("object");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfoot/agent-hooks",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Unified agent hooks library: shared core runtime with per-agent entry points for Claude Code, Codex, and Antigravity",
   "homepage": "https://github.com/goodfoot-io/marketplace/tree/main/packages/agent-hooks",
   "repository": {
@@ -38,6 +38,10 @@
     "./codex": {
       "import": "./dist/agents/codex/index.js",
       "types": "./types/agents/codex/index.d.ts"
+    },
+    "./opencode": {
+      "import": "./dist/agents/opencode/index.js",
+      "types": "./types/agents/opencode/index.d.ts"
     }
   },
   "bin": "./dist/cli.js",
@@ -51,9 +55,18 @@
     "glob": "^11.0.0",
     "typescript": "^5.9.3"
   },
+  "peerDependencies": {
+    "@opencode-ai/plugin": "^1.18.23"
+  },
+  "peerDependenciesMeta": {
+    "@opencode-ai/plugin": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.162",
     "@biomejs/biome": "2.4.16",
+    "@opencode-ai/plugin": "1.18.23",
     "@types/node": "^24",
     "tsx": "^4.20.6",
     "vitest": "4.0.13"

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

@@ -0,0 +1,57 @@
+/**
+ * OpenCode-specific CLI internals: bundling each selected plugin entry to a
+ * standalone ESM artifact and validating its `{ id, server }` (or bare
+ * function) default-export contract against a real dynamic import of the
+ * built output — not a hand-rolled AST check, which could pass a shape the
+ * actual OpenCode loader would still reject.
+ *
+ * Unlike Codex's `compileCodexHook`, there is no wrapper content and no
+ * `execute()` runtime module to link: OpenCode imports the plugin author's
+ * own default export directly, so the bundle *is* the artifact — no
+ * stdin/stdout driver, no `hooks.json` manifest, no shebang.
+ *
+ * Driver-level primitives (loader parsing, glob discovery) are imported from
+ * the shared CLI module — never re-derived here.
+ * @module
+ */
+import * as esbuild from "esbuild";
+/** OpenCode CLI arguments accepted on top of the shared `--agent opencode` gate. */
+export interface OpenCodeCliArgs {
+    input: string;
+    output: string;
+    loaderFlags: string[];
+    sourcemap?: boolean;
+}
+type HookLoaderMap = Record<string, esbuild.Loader>;
+interface CompiledOpenCodePlugin {
+    sourcePath: string;
+    outputPath: string;
+}
+/**
+ * Bundles one OpenCode plugin entry to a self-contained ESM artifact. The
+ * source file's own default export is preserved unchanged — no wrapper.
+ */
+export declare function compileOpenCodePlugin(sourcePath: string, loaders: HookLoaderMap, sourcemap?: boolean): Promise<string>;
+/**
+ * Validates that `outputPath`'s default export matches OpenCode's real
+ * loader contract (`getServerPlugin`): either a bare function, or an object
+ * with a `server` function property. Imports the built artifact itself
+ * rather than statically analyzing source, so the check exercises exactly
+ * what OpenCode's loader will see.
+ * @throws Error when the default export matches neither shape.
+ */
+export declare function validateOpenCodePluginModule(outputPath: string): Promise<void>;
+/**
+ * Validates OpenCode build arguments beyond the shared `--agent` gate: `-i`
+ * and `-o` required, loader flags well-formed.
+ */
+export declare function validateOpenCodeArgs(args: OpenCodeCliArgs): string | undefined;
+/**
+ * Runs the OpenCode build branch of the unified CLI: discovers plugin entry
+ * files matching `--input`, bundles each to a standalone ESM artifact under
+ * `--output` (treated as a directory — OpenCode plugin config references
+ * these files directly, there is no manifest), and validates each artifact's
+ * default export against OpenCode's real loader contract.
+ */
+export declare function runOpenCodeCli(args: OpenCodeCliArgs): Promise<CompiledOpenCodePlugin[]>;
+export {};

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

@@ -0,0 +1,46 @@
+/**
+ * OpenCode callback policy split: which lifecycle callbacks may opt into
+ * guarded fail-open (`"continue"`) behavior, and which must always surface
+ * failures.
+ *
+ * Unlike Codex's advisory allow-list (transcribed from `codex-hooks/README.md`,
+ * an external source-of-truth document), OpenCode has no prior source package
+ * to transcribe from — this package *is* the source of truth for its own
+ * OpenCode surface. The split below is derived directly from CARD.md's
+ * Desired Functionality section (committed to the card repository, itself
+ * the authorization for this contract): "Advisory callbacks can opt into
+ * guarded fail-open behavior with observable diagnostics; policy-enforcing
+ * callbacks default to surfacing failures."
+ *
+ * `permission.ask` is the only callback whose `output.status` is an
+ * allow/deny/ask *security decision* — swallowing a failure there means the
+ * decision was silently skipped, exactly the Codex precedent
+ * (`PreToolUse`/`PermissionRequest`) this mirrors. Every other lifecycle
+ * callback only observes or additively enriches (message/tool mutation,
+ * shell env, event notification) and is therefore advisory.
+ * @module
+ */
+import type { UnexpectedErrorPolicy } from "../../core/types.js";
+import { type OpenCodeHookName } from "./types.js";
+/** Callbacks that must always surface failures — never eligible for `"continue"`. */
+export declare const POLICY_ENFORCING_EVENTS: readonly ["permission.ask"];
+/** The policy-enforcing set as a literal union. */
+export type PolicyEnforcingEventName = (typeof POLICY_ENFORCING_EVENTS)[number];
+/** Type-level membership check: `true` only for policy-enforcing callback names. */
+export type IsPolicyEnforcingEvent<TName extends OpenCodeHookName> = TName extends PolicyEnforcingEventName ? true : false;
+/** The advisory allow-list as a literal union: every callback except {@link PolicyEnforcingEventName}. */
+export type AdvisoryEventName = Exclude<OpenCodeHookName, PolicyEnforcingEventName>;
+/**
+ * The advisory allow-list: every OpenCode lifecycle callback except
+ * {@link POLICY_ENFORCING_EVENTS}. Only these accept
+ * `unexpectedError: "continue"`, enforced at compile time by
+ * {@link AllowedUnexpectedErrorPolicy} and at call time by
+ * {@link ../../core/define-hook.ts|the policy-gate pattern}.
+ */
+export declare const ADVISORY_EVENTS: readonly AdvisoryEventName[];
+/**
+ * The policy type a callback may carry, narrowed by allow-list membership:
+ * advisory callbacks keep `"error" | "continue"`; every policy-enforcing
+ * callback collapses to `"error"`.
+ */
+export type AllowedUnexpectedErrorPolicy<TName extends OpenCodeHookName> = IsPolicyEnforcingEvent<TName> extends true ? Exclude<UnexpectedErrorPolicy, "continue"> : UnexpectedErrorPolicy;

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

@@ -0,0 +1,19 @@
+/**
+ * `@goodfoot/agent-hooks/opencode` — the OpenCode agent surface.
+ *
+ * Re-exports OpenCode-native types (narrowed from `@opencode-ai/plugin`),
+ * the advisory/policy-enforcing callback split, the shared error-policy
+ * vocabulary, and the plugin authoring primitives. No default export at this
+ * subpath — `defineOpenCodePlugin`'s *return value* is the `{ id, server }`
+ * default export a plugin author's own module produces, not something this
+ * barrel exports itself.
+ * @module
+ */
+export type { AdvisoryEventName, AllowedUnexpectedErrorPolicy, IsPolicyEnforcingEvent, PolicyEnforcingEventName, } from "./events.js";
+export { ADVISORY_EVENTS, POLICY_ENFORCING_EVENTS } from "./events.js";
+export type { RootSessionRegistry } from "./plugin.js";
+export { createRootSessionRegistry, defineOpenCodePlugin, guardAdvisory } from "./plugin.js";
+export type { UnexpectedErrorHandler, UnexpectedErrorPolicy } from "./policy.js";
+export { applyOpenCodeErrorPolicy } from "./policy.js";
+export type { Hooks, OpenCodeHookHandler, OpenCodeHookName, Plugin, PluginInput, PluginModule, PluginOptions, } from "./types.js";
+export { OPENCODE_HOOK_NAMES } from "./types.js";

package/types/agents/opencode/plugin.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Plugin authoring primitives for `@goodfoot/agent-hooks/opencode`.
+ *
+ * `defineOpenCodePlugin` validates the `{ id, server }` module contract that
+ * OpenCode's real loader (`getServerPlugin`, verified live against
+ * `sst/opencode`'s `packages/opencode/src/plugin/index.ts`) accepts as a
+ * default export. `createRootSessionRegistry` and `guardAdvisory` are
+ * optional composition helpers a `server` factory may call — not a required
+ * framework, since a plugin author can also return a raw {@link Hooks}
+ * object built directly from `./types.js`.
+ * @module
+ */
+import type { AdvisoryEventName } from "./events.js";
+import { type UnexpectedErrorHandler, type UnexpectedErrorPolicy } from "./policy.js";
+import type { OpenCodeHookHandler, Plugin, PluginInput, PluginModule } from "./types.js";
+/**
+ * Validates and returns an OpenCode plugin module definition.
+ *
+ * @param definition - `id` must be a non-empty string; `server` must be a
+ * function matching upstream's {@link Plugin} signature.
+ * @returns `definition`, unchanged, once validated.
+ * @throws Error when `id` is missing/empty or `server` is not a function.
+ */
+export declare function defineOpenCodePlugin(definition: {
+    id: string;
+    server: Plugin;
+}): PluginModule;
+/**
+ * Tracks OpenCode session parentage and resumption across a plugin's
+ * lifetime.
+ *
+ * Live testing of a prior implementation of this pattern found that a
+ * *resumed* session does not necessarily re-emit `session.created` — it may
+ * first appear only through later activity (e.g. `session.updated`,
+ * `message.updated`) for a session id the registry has never observed. This
+ * registry treats that as the resumed-session signal `isResumed` reports.
+ */
+export interface RootSessionRegistry {
+    /**
+     * Records that `sessionId` was observed via a `session.created` event,
+     * optionally as a child of `parentId`. Idempotent: observing the same
+     * `sessionId` twice does not change its recorded parentage or resumed
+     * status.
+     */
+    observe(sessionId: string, parentId?: string): void;
+    /**
+     * Records that `sessionId` was observed via any event *other than*
+     * `session.created` — the resumed-session signal. Idempotent the same way
+     * as {@link observe}; calling either method after the other for the same
+     * `sessionId` does not change its already-recorded resumed status.
+     */
+    observeResumed(sessionId: string, parentId?: string): void;
+    /** `true` when `sessionId` has no recorded parent. */
+    isRoot(sessionId: string): boolean;
+    /**
+     * `true` when `sessionId` was first observed through a non-`session.created`
+     * event name rather than through `session.created` itself.
+     */
+    isResumed(sessionId: string): boolean;
+}
+/** Creates a fresh, empty {@link RootSessionRegistry}. */
+export declare function createRootSessionRegistry(): RootSessionRegistry;
+/**
+ * Wraps an advisory OpenCode callback with {@link applyOpenCodeErrorPolicy},
+ * restricted at the type level to {@link AdvisoryEventName}s — a
+ * policy-enforcing callback name is a compile-time error here, since
+ * swallowing its failure would silently skip a security decision.
+ *
+ * @param name - An advisory callback name from `./types.js`'s `Hooks` map.
+ * @param handler - The callback implementation to guard.
+ * @param policy - The configured policy; `undefined` behaves as `"error"`.
+ * @param onError - Best-effort diagnostic sink for a swallowed `"continue"` error.
+ */
+export declare function guardAdvisory<TName extends AdvisoryEventName>(name: TName, handler: OpenCodeHookHandler<TName>, policy: UnexpectedErrorPolicy | undefined, onError?: UnexpectedErrorHandler): OpenCodeHookHandler<TName>;
+export type { PluginInput };

package/types/agents/opencode/policy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * OpenCode error-policy application.
+ *
+ * Reuses only the host-neutral policy vocabulary from
+ * {@link ../../core/types.ts} — not {@link ../../core/define-hook.ts|defineHook}
+ * itself, which is built around a single one-shot handler call and doesn't
+ * fit OpenCode's long-lived, heterogeneous callback map.
+ * @module
+ */
+import type { UnexpectedErrorHandler, UnexpectedErrorPolicy } from "../../core/types.js";
+export type { UnexpectedErrorHandler, UnexpectedErrorPolicy };
+/**
+ * Wraps an advisory OpenCode callback so an unexpected throw is handled
+ * per `policy` instead of propagating to the OpenCode server process.
+ *
+ * - `"error"` (default): rethrows unchanged.
+ * - `"continue"`: swallows the error, invokes `onError` (if provided) as a
+ *   best-effort diagnostic sink, and resolves instead of rejecting.
+ *
+ * Never call this for a policy-enforcing callback (see
+ * {@link ./events.ts|POLICY_ENFORCING_EVENTS}) — {@link ./plugin.ts|guardAdvisory}
+ * is the only intended caller and restricts callback names accordingly.
+ *
+ * @param name - The callback name, used only for the diagnostic sink.
+ * @param handler - The callback implementation to guard.
+ * @param policy - The configured policy; `undefined` behaves as `"error"`.
+ * @param onError - Best-effort diagnostic sink for a swallowed `"continue"` error.
+ * @throws Error the handler threw is thrown when `policy` is `"error"`.
+ */
+export declare function applyOpenCodeErrorPolicy<TArgs extends unknown[]>(_name: string, handler: (...args: TArgs) => Promise<void>, policy: UnexpectedErrorPolicy | undefined, onError?: UnexpectedErrorHandler): (...args: TArgs) => Promise<void>;

package/types/agents/opencode/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * OpenCode-native types for `@goodfoot/agent-hooks/opencode`.
+ *
+ * OpenCode loads a long-lived, in-process plugin module rather than spawning
+ * a one-shot command-hook process: {@link PluginModule} (`{ id?, server }`)
+ * or a bare {@link Plugin} function is what OpenCode's real loader accepts —
+ * verified directly against the installed `@opencode-ai/plugin@1.18.23`
+ * `.d.ts`, not the (looser) public docs page. This module re-exports and
+ * narrows those upstream types; it never redeclares OpenCode's callback
+ * input/output shapes by hand, so this surface can't drift from the SDK it
+ * wraps.
+ * @module
+ */
+import type { Hooks, Plugin, PluginInput, PluginModule, PluginOptions } from "@opencode-ai/plugin";
+export type { Hooks, Plugin, PluginInput, PluginModule, PluginOptions };
+/**
+ * The stable, lifecycle-callback keys of {@link Hooks} — excludes `tool`
+ * (custom tool definitions, not a lifecycle callback), `auth` and `provider`
+ * (static registration objects), and `dispose` (a no-argument cleanup
+ * callback with no policy semantics of its own).
+ *
+ * Order matches declaration order in the upstream `Hooks` interface.
+ */
+export declare const OPENCODE_HOOK_NAMES: readonly ["event", "config", "chat.message", "chat.params", "chat.headers", "permission.ask", "command.execute.before", "tool.execute.before", "shell.env", "tool.execute.after", "experimental.chat.messages.transform", "experimental.chat.system.transform", "experimental.provider.small_model", "experimental.session.compacting", "experimental.compaction.autocontinue", "experimental.text.complete", "tool.definition"];
+/** Literal union of {@link OPENCODE_HOOK_NAMES}. */
+export type OpenCodeHookName = (typeof OPENCODE_HOOK_NAMES)[number];
+/** The handler type for a given lifecycle callback name, narrowed from {@link Hooks}. */
+export type OpenCodeHookHandler<TName extends OpenCodeHookName> = NonNullable<Hooks[TName]>;