@goodfoot/agent-hooks 1.0.11 → 1.0.14

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @goodfoot/agent-hooks npm package changelog
 
+## 1.0.14
+
+Compiles each OpenCode source into an installable plugin directory containing `package.json` and `index.js`. OpenCode 2.1.2 rejects the previous bare `.mjs` configuration paths. Generated packages support discovery under `.opencode/plugins/` and explicit directory entries in `plugins`.
+
+## 1.0.13
+
+Targets OpenCode 2.1.2 with the `@opencode/plugin` SDK. Plugin definitions now use `id` and `setup`, hook types follow V2 domain registrations with one mutable event, and compilation rejects V1 entrypoints.
+
+## 1.0.12
+
+Waits for stdout and stderr writes to complete before exiting, preventing truncated hook responses and error diagnostics when output is piped. Asynchronous stdout write failures now follow the existing unexpected-error policy without retrying the payload.
+
 ## 1.0.11
 
 Moves generated-file tracking out of `hooks.json` into a sibling `hooks.meta.json`, because Claude Code rejects a hooks manifest carrying any key besides `hooks`. The manifest is now a pure function of its inputs, so a rebuild that changes nothing writes identical bytes and leaves the host's hook-trust hash intact. A missing or unreadable sidecar is treated as "nothing tracked as generated", which preserves the entries already in the manifest rather than pruning them.

package/README.md

@@ -104,34 +104,16 @@ the root `plugin.json` required by that install command.
 
 #### OpenCode
 
-These plugin packages are not published to npm, so `opencode plugin` takes a path into a
-checkout rather than a module name:
+Clone this repository and register the built plugin directory in OpenCode V2's
+`opencode.json`, using an absolute path to your checkout:
 
-```bash
-git clone https://github.com/goodfoot-io/marketplace.git
-opencode plugin "$PWD/marketplace/plugins-opencode/agent-hooks"
+```json
+{
+  "plugins": ["/absolute/path/to/marketplace/plugins-opencode/agent-hooks"]
+}
 ```
 
-Pass a path, not a bare name. `opencode plugin` resolves a specifier containing a
-separator as a path — absolute, `./`-prefixed, and plain relative forms all load on
-OpenCode 1.18.23. A single segment with no separator (`agent-hooks`) is instead resolved as an
-npm package name and silently fails to load, with nothing logged. The absolute form
-above avoids the ambiguity.
-
-That is the whole install — no `opencode.json` editing. `opencode plugin` writes only the
-top-level `plugin` key, and OpenCode keeps `plugin` and `skills` as disjoint config keys,
-so registering the module would not by itself surface its skills. The plugin closes that
-gap from the inside: its `config` hook runs against the resolved config before use and
-appends its own bundled `skills/` directory to `skills.paths`, resolved relative to
-wherever the package was installed. Installing is enough.
-
-Without flags this installs into the current project's `.opencode/opencode.json`. Add
-`-g` to install into the global config instead.
-
-Verify with `opencode debug skill`. Its output is large and embeds whole skill bodies:
-redirect it to a file and search there. Piping it to `head` truncates the JSON mid-string
-and reports a present skill as missing.
-
+The plugin contributes its bundled authoring skills through `ctx.skill.transform`.
 Installing this skill is separate from compiling hooks *for* OpenCode, covered in
 [OpenCode](#opencode) below.
 
@@ -235,69 +217,55 @@ or `@goodfoot/agent-hooks/codex`) — do not mix events or output builders acros
 
 ## 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:
+OpenCode 2.1.2 loads a long-lived plugin definition with a stable `id` and
+`setup(ctx)`. Register hooks on their owning domains during setup:
 
 ```typescript
-import { defineOpenCodePlugin, guardAdvisory, createRootSessionRegistry } from '@goodfoot/agent-hooks/opencode';
-
-const sessions = createRootSessionRegistry();
+import { defineOpenCodePlugin, guardAdvisory } from '@goodfoot/agent-hooks/opencode';
 
 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 if (event.type === 'session.updated') {
-        sessions.observeResumed(event.properties.info.id, event.properties.info.parentID);
-      }
-    }, 'continue'),
-
-    'tool.execute.before': async (input, output) => {
-      if (input.tool === 'bash' && sessions.isRoot(input.sessionID)) {
-        output.args = { ...output.args, timeout: 30_000 };
+  async setup(ctx) {
+    await ctx.tool.hook('execute.before', guardAdvisory('tool.execute.before', async (event) => {
+      if (event.tool === 'bash') {
+        event.input = { ...(event.input as Record<string, unknown>), timeout: 30_000 };
       }
-    },
-  }),
+    }, 'continue'));
+  },
 });
 ```
 
-- **`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.
-
-`Hooks` also includes `config?: (input: Config) => Promise<void>`, which runs against the
-resolved config before use and can mutate it. That is how a plugin contributes
-configuration it would otherwise need the user to hand-write — the plugins in this
-repository use it to append their own `skills/` directory to `skills.paths`, so installing
-one delivers its skills without any `opencode.json` edit.
-
-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:
+`guardAdvisory` accepts domain-prefixed V2 hook names and preserves the native
+single mutable event argument. Permission evaluation (`permission.evaluate`)
+always surfaces failures and cannot opt into `continue`.
+`createRootSessionRegistry()` remains available for tracking observed session
+parentage and resumption; consume events with `ctx.event.subscribe()` and abort
+subscriptions in the cleanup function returned by `setup`.
+
+Configuration contributions use domain transforms such as `ctx.skill.transform`.
+There is no returned V1 `config` callback or global mutable config object.
+
+Compile plugins with the unified CLI:
 
 ```bash
-npx -y @goodfoot/agent-hooks --agent opencode -i "src/**/*.ts" -o "./.opencode/plugin"
+npx -y @goodfoot/agent-hooks --agent opencode -i "src/**/*.ts" -o "./.opencode/plugins"
 ```
 
-Point `opencode.json`'s plugin list (or the equivalent config in your OpenCode host) at
-the compiled `.mjs` file(s) under that output directory.
+Each source emits a plugin package directory: `src/my-plugin.ts` produces
+`.opencode/plugins/my-plugin/package.json` and `index.js`. The compiler validates
+the entrypoint as a V2 `{ id, setup }` definition. OpenCode discovers these
+package directories under `.opencode/plugins/` automatically.
+
+For output elsewhere, add each generated package directory to `plugins`:
+
+```json
+{ "plugins": ["./build/plugins/my-plugin"] }
+```
 
-`@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.
+OpenCode 2.1.2 rejects individual `.js` or `.mjs` paths in that list.
+`@opencode/plugin@^2.1.2` is an optional peer dependency, required only for the
+OpenCode entry point. See the [official V2 plugin migration guide](https://opencode.ai/v2/docs/build/plugins/migrate-v1/)
+for domain hooks, transforms, and cleanup.
 
 ## Fail-open advisory hooks
 

package/dist/agents/antigravity/scaffold.js

@@ -50,7 +50,7 @@ function packageJson(projectName, outputPath) {
             lint: "biome check .",
             typecheck: "tsc --noEmit",
         },
-        dependencies: { [PACKAGE_NAME]: "^1.0.11" },
+        dependencies: { [PACKAGE_NAME]: "^1.0.14" },
         devDependencies: {
             "@biomejs/biome": "2.4.9",
             "@types/node": "^24.0.0",

package/dist/agents/codex/scaffold.js

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

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

@@ -1,13 +1,12 @@
 /**
- * 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
+ * OpenCode-specific CLI internals: bundling each selected plugin entry to an
+ * ESM plugin directory and validating its V2 `{ id, setup }` 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
+ * own default export directly from the package entry point — no
  * stdin/stdout driver, no `hooks.json` manifest, no shebang.
  *
  * Driver-level primitives (loader parsing, glob discovery) are imported from
@@ -46,41 +45,55 @@ export async function compileOpenCodePlugin(sourcePath, loaders, sourcemap = fal
 }
 /**
  * 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
+ * V2 loader contract: an object with a stable non-empty `id` and a
+ * `setup` function. 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.
+ * @throws Error when the default export is not a V2 plugin definition.
  */
 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}`);
+    const definition = defaultExport;
+    if (typeof definition !== "object" ||
+        definition === null ||
+        typeof definition.id !== "string" ||
+        definition.id.trim().length === 0 ||
+        typeof definition.setup !== "function") {
+        throw new Error(`${outputPath}: default export must be a V2 { id, setup } plugin definition`);
     }
 }
 async function compileAllOpenCodePlugins(pluginFiles, outputDir, loaders, sourcemap) {
-    if (!fs.existsSync(outputDir)) {
-        fs.mkdirSync(outputDir, { recursive: true });
+    const outputPaths = pluginFiles.map((sourcePath) => path.join(outputDir, path.basename(sourcePath, path.extname(sourcePath))));
+    if (new Set(outputPaths).size !== outputPaths.length) {
+        throw new Error("OpenCode plugin source basenames must be unique within the output directory");
     }
+    fs.mkdirSync(outputDir, { recursive: true });
+    const stagingDir = fs.mkdtempSync(path.join(outputDir, ".opencode-build-"));
     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);
+    try {
+        // Validate fresh modules before replacing any previously built entry points.
+        // Unique staging paths also prevent dynamic import's cache hiding rebuild errors.
+        for (const [index, sourcePath] of pluginFiles.entries()) {
+            const content = await compileOpenCodePlugin(sourcePath, loaders, sourcemap);
+            const stagedPath = path.join(stagingDir, String(index));
+            fs.mkdirSync(stagedPath);
+            fs.writeFileSync(path.join(stagedPath, "package.json"), `${JSON.stringify({ private: true, type: "module", main: "index.js", exports: "./index.js" }, null, 2)}\n`, "utf-8");
+            const entryPath = path.join(stagedPath, "index.js");
+            fs.writeFileSync(entryPath, content, "utf-8");
+            await validateOpenCodePluginModule(entryPath);
+            compiled.push({ sourcePath, outputPath: outputPaths[index] });
         }
-        catch (error) {
-            fs.rmSync(outputPath);
-            throw error;
+        for (const [index, { outputPath }] of compiled.entries()) {
+            fs.mkdirSync(outputPath, { recursive: true });
+            for (const filename of ["package.json", "index.js"]) {
+                fs.renameSync(path.join(stagingDir, String(index), filename), path.join(outputPath, filename));
+            }
         }
-        compiled.push({ sourcePath, outputPath });
+    }
+    finally {
+        // Only remove compiler-owned staging data; preserve other files in plugin directories.
+        fs.rmSync(stagingDir, { recursive: true, force: true });
     }
     return compiled;
 }
@@ -104,9 +117,9 @@ export function validateOpenCodeArgs(args) {
 }
 /**
  * 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
+ * files matching `--input`, bundles each to a package directory under
+ * `--output`. OpenCode plugin config references these directories; each contains
+ * package.json and index.js. Validates each entry point's
  * default export against OpenCode's real loader contract.
  */
 export async function runOpenCodeCli(args) {

package/dist/agents/opencode/events.js

@@ -1,28 +1,6 @@
-/**
- * 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"];
+export const POLICY_ENFORCING_EVENTS = ["permission.evaluate"];
 /**
  * The advisory allow-list: every OpenCode lifecycle callback except
  * {@link POLICY_ENFORCING_EVENTS}. Only these accept

package/dist/agents/opencode/index.js

@@ -1,10 +1,10 @@
 /**
  * `@goodfoot/agent-hooks/opencode` — the OpenCode agent surface.
  *
- * Re-exports OpenCode-native types (narrowed from `@opencode-ai/plugin`),
+ * Re-exports OpenCode-native types (narrowed from `@opencode/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 }`
+ * subpath — `defineOpenCodePlugin`'s *return value* is the `{ id, setup }`
  * default export a plugin author's own module produces, not something this
  * barrel exports itself.
  * @module

package/dist/agents/opencode/plugin.js

@@ -1,32 +1,13 @@
-/**
- * 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.
- */
+/** Validates a V2 plugin definition before OpenCode loads it. */
 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.id !== "string" || definition.id.trim().length === 0) {
+        throw new Error('defineOpenCodePlugin: "id" must be a non-empty string');
     }
-    if (typeof definition.server !== "function") {
-        throw new Error(`defineOpenCodePlugin: "server" must be a function, got ${typeof definition.server}`);
+    if (typeof definition.setup !== "function") {
+        throw new Error('defineOpenCodePlugin: "setup" must be a function');
     }
-    return { id: definition.id, server: definition.server };
+    return definition;
 }
 /** Creates a fresh, empty {@link RootSessionRegistry}. */
 export function createRootSessionRegistry() {

package/dist/agents/opencode/types.js

@@ -1,40 +1,20 @@
-/**
- * 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",
+    "aisdk.sdk",
+    "aisdk.language",
+    "session.prompt",
+    "session.context",
+    "session.compaction",
+    "session.generate",
+    "session.title",
+    "session.model.request",
+    "session.http.request",
+    "session.http.response",
+    "session.experimental.ws.handshake",
+    "session.experimental.ws.send",
+    "session.experimental.ws.receive",
+    "session.retry",
+    "permission.evaluate",
+    "shell.create.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.11";
+const VERSION = "1.0.14";
 /** Filename of the tracking sidecar written beside hooks.json. */
 const HOOKS_META_FILENAME = "hooks.meta.json";
 const DEFAULT_ESBUILD_LOADERS = {
@@ -71,8 +71,8 @@ Required Arguments:
       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).
+      With --agent opencode, -o/--output contains one plugin package directory
+      per source (package.json and index.js; no hooks.json is generated).
       With --agent antigravity, -o/--output is the hooks.json path at the
       plugin root; bundles are written to a bin/ directory beside it and the
       generated commands are relative to the manifest, which is the working
@@ -1335,7 +1335,7 @@ async function main() {
                 loaderFlags: args.loaderFlags ?? [],
                 sourcemap: args.sourcemap,
             });
-            process.stdout.write(`Generated ${compiled.length} plugin artifact(s) in ${path.resolve(process.cwd(), args.output)}\n`);
+            process.stdout.write(`Generated ${compiled.length} plugin package(s) in ${path.resolve(process.cwd(), args.output)}\n`);
             process.exit(0);
         }
         catch (error) {

package/dist/core/transport.js

@@ -111,18 +111,29 @@ function classify(error, phase, policy, onUnexpectedError) {
     }
     return { kind: "handlerError", error, phase };
 }
+// A successful write return value only describes buffering; its callback confirms delivery.
+function writeStream(stream, content) {
+    return new Promise((resolve, reject) => {
+        stream.write(content, (error) => {
+            if (error)
+                reject(error);
+            else
+                resolve();
+        });
+    });
+}
 /**
  * Writes an unexpected (non-handler, runtime-owned) error's stacktrace to
  * stderr. Used for cleanup/finalize failures under the default `"error"`
  * policy, which exit with code 1 — these are not the handler's own
  * intentional signal.
  */
-function writeUnexpectedErrorStderr(error) {
+async function writeUnexpectedErrorStderr(error) {
     if (error instanceof Error) {
-        process.stderr.write(`${error.stack ?? error.message}\n`);
+        await writeStream(process.stderr, `${error.stack ?? error.message}\n`);
     }
     else {
-        process.stderr.write(`${String(error)}\n`);
+        await writeStream(process.stderr, `${String(error)}\n`);
     }
 }
 /**
@@ -198,7 +209,7 @@ export async function drive(transport, hookFn) {
             cleanupQuietly();
             process.exit(FALLBACK_EXIT_SUCCESS);
         }
-        writeUnexpectedErrorStderr(error);
+        await writeUnexpectedErrorStderr(error);
         cleanupQuietly();
         process.exit(FALLBACK_EXIT_ERROR);
     }
@@ -206,15 +217,15 @@ export async function drive(transport, hookFn) {
         cleanup(policy, onUnexpectedError);
     }
     catch (error) {
-        writeUnexpectedErrorStderr(error);
+        await writeUnexpectedErrorStderr(error);
         process.exit(FALLBACK_EXIT_ERROR);
     }
     if (finalized.stderr !== undefined) {
-        process.stderr.write(finalized.stderr);
+        await writeStream(process.stderr, finalized.stderr);
     }
     if (finalized.stdout !== undefined) {
         try {
-            process.stdout.write(finalized.stdout);
+            await writeStream(process.stdout, finalized.stdout);
         }
         catch (error) {
             if (policy === "continue") {
@@ -222,7 +233,7 @@ export async function drive(transport, hookFn) {
                 cleanupQuietly();
                 process.exit(FALLBACK_EXIT_SUCCESS);
             }
-            writeUnexpectedErrorStderr(error);
+            await writeUnexpectedErrorStderr(error);
             cleanupQuietly();
             process.exit(FALLBACK_EXIT_ERROR);
         }

package/dist/scaffold.js

@@ -131,7 +131,7 @@ function generatePackageJson(projectName, outputPath) {
             typecheck: "tsc --noEmit",
         },
         dependencies: {
-            "@goodfoot/agent-hooks": "^1.0.11",
+            "@goodfoot/agent-hooks": "^1.0.14",
         },
         devDependencies: {
             "@biomejs/biome": "2.4.16",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfoot/agent-hooks",
-  "version": "1.0.11",
+  "version": "1.0.14",
   "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": {
@@ -22,7 +22,7 @@
   "scripts": {
     "typecheck": "tsc --noEmit",
     "build": "tsc --build tsconfig.build.json",
-    "lint": "biome check --write --unsafe --max-diagnostics 500 ./src ./tests ./e2e ./scripts && node ./scripts/check-stale-imports.mjs",
+    "lint": "biome check --write --unsafe --max-diagnostics 500 ./src ./tests ./e2e ./scripts ./vitest.config.ts && node ./scripts/check-stale-imports.mjs",
     "test": "node ./scripts/check-stale-imports.mjs && node ./scripts/check-agent-duplication.mjs && vitest run",
     "release": "bash ../../scripts/release-package.sh agent-hooks",
     "release:dry-run": "bash ../../scripts/release-package.sh agent-hooks --dry-run"
@@ -56,24 +56,29 @@
     }
   },
   "dependencies": {
-    "esbuild": "^0.24.0",
+    "esbuild": "^0.28.2",
     "glob": "^11.0.0",
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@opencode-ai/plugin": "^1.18.23"
+    "@opencode/plugin": "^2.1.2"
   },
   "peerDependenciesMeta": {
-    "@opencode-ai/plugin": {
+    "@opencode/plugin": {
       "optional": true
     }
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.162",
+    "@anthropic-ai/sdk": "^0.133.0",
     "@biomejs/biome": "2.4.16",
-    "@opencode-ai/plugin": "1.18.23",
-    "@types/node": "^24",
+    "@goodfoot/vitest-cache": "workspace:*",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opencode/plugin": "2.1.2",
+    "@types/node": "^26.6.5",
     "tsx": "^4.20.6",
-    "vitest": "4.0.13"
+    "vite": "8.3.4",
+    "vitest": "patch:vitest@npm%3A5.0.4#~/.yarn/patches/vitest-npm-5.0.4-2ab4bceca5.patch",
+    "zod": "^4.6.7"
   }
 }

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

@@ -1,13 +1,12 @@
 /**
- * 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
+ * OpenCode-specific CLI internals: bundling each selected plugin entry to an
+ * ESM plugin directory and validating its V2 `{ id, setup }` 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
+ * own default export directly from the package entry point — no
  * stdin/stdout driver, no `hooks.json` manifest, no shebang.
  *
  * Driver-level primitives (loader parsing, glob discovery) are imported from
@@ -34,11 +33,11 @@ interface CompiledOpenCodePlugin {
 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
+ * V2 loader contract: an object with a stable non-empty `id` and a
+ * `setup` function. 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.
+ * @throws Error when the default export is not a V2 plugin definition.
  */
 export declare function validateOpenCodePluginModule(outputPath: string): Promise<void>;
 /**
@@ -48,9 +47,9 @@ export declare function validateOpenCodePluginModule(outputPath: string): Promis
 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
+ * files matching `--input`, bundles each to a package directory under
+ * `--output`. OpenCode plugin config references these directories; each contains
+ * package.json and index.js. Validates each entry point's
  * default export against OpenCode's real loader contract.
  */
 export declare function runOpenCodeCli(args: OpenCodeCliArgs): Promise<CompiledOpenCodePlugin[]>;

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

@@ -1,29 +1,8 @@
-/**
- * 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
- */
+/** V2 permission evaluation always surfaces errors; enrichment hooks may opt into continue. @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"];
+export declare const POLICY_ENFORCING_EVENTS: readonly ["permission.evaluate"];
 /** 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. */

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

@@ -1,10 +1,10 @@
 /**
  * `@goodfoot/agent-hooks/opencode` — the OpenCode agent surface.
  *
- * Re-exports OpenCode-native types (narrowed from `@opencode-ai/plugin`),
+ * Re-exports OpenCode-native types (narrowed from `@opencode/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 }`
+ * subpath — `defineOpenCodePlugin`'s *return value* is the `{ id, setup }`
  * default export a plugin author's own module produces, not something this
  * barrel exports itself.
  * @module

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

@@ -1,30 +1,9 @@
-/**
- * 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
- */
+/** OpenCode V2 plugin authoring helpers. @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;
+import type { OpenCodeHookHandler, PluginInput, PluginModule } from "./types.js";
+/** Validates a V2 plugin definition before OpenCode loads it. */
+export declare function defineOpenCodePlugin(definition: PluginModule): PluginModule;
 /**
  * Tracks OpenCode session parentage and resumption across a plugin's
  * lifetime.

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

@@ -27,4 +27,4 @@ export type { UnexpectedErrorHandler, UnexpectedErrorPolicy };
  * @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>;
+export declare function applyOpenCodeErrorPolicy<TArgs extends unknown[]>(_name: string, handler: (...args: TArgs) => Promise<void> | void, policy: UnexpectedErrorPolicy | undefined, onError?: UnexpectedErrorHandler): (...args: TArgs) => Promise<void> | void;

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

@@ -1,28 +1,22 @@
-/**
- * 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}. */
+/** OpenCode V2 native plugin and domain hook types, derived from the installed SDK. @module */
+import type { Plugin as NativePlugin, PluginOptions } from "@opencode/plugin";
+import type { AISDKHooks } from "@opencode/plugin/promise/aisdk";
+import type { PermissionHooks } from "@opencode/plugin/promise/permission";
+import type { Hooks as DomainHooks } from "@opencode/plugin/promise/registration";
+import type { SessionHooks } from "@opencode/plugin/promise/session";
+import type { ShellHooks } from "@opencode/plugin/promise/shell";
+import type { ToolDomain } from "@opencode/plugin/promise/tool";
+type HookSpec<T> = T extends DomainHooks<infer Spec> ? Spec : never;
+type Prefix<Domain extends string, Spec> = {
+    [Name in keyof Spec as Name extends string ? `${Domain}.${Name}` : never]: (event: Spec[Name]) => Promise<void> | void;
+};
+/** V2 hook callbacks, named by their owning domain and registration name. */
+export type Hooks = Prefix<"aisdk", AISDKHooks> & Prefix<"session", SessionHooks> & Prefix<"permission", PermissionHooks> & Prefix<"shell", ShellHooks> & Prefix<"tool", HookSpec<ToolDomain["hook"]>>;
+/** The V2 setup callback. */
+export type Plugin = NativePlugin.Plugin["setup"];
+export type PluginInput = NativePlugin.Context;
+export type PluginModule = NativePlugin.Plugin;
+export type { PluginOptions };
+export declare const OPENCODE_HOOK_NAMES: readonly ["aisdk.sdk", "aisdk.language", "session.prompt", "session.context", "session.compaction", "session.generate", "session.title", "session.model.request", "session.http.request", "session.http.response", "session.experimental.ws.handshake", "session.experimental.ws.send", "session.experimental.ws.receive", "session.retry", "permission.evaluate", "shell.create.before", "tool.execute.before", "tool.execute.after"];
 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]>;
+export type OpenCodeHookHandler<TName extends OpenCodeHookName> = Hooks[TName];