@amsterdamdatalabs/enact-extensions 0.1.42 → 0.1.47

package/dist/create/opencode.js

@@ -0,0 +1,696 @@
+import { MANIFEST_FIELDS } from "../internal/platform.js";
+import { pickManifestFields, withPlatformKeyword } from "../internal/pick.js";
+import { withHostFlag } from "../internal/hooks.js";
+// ---------------------------------------------------------------------------
+// OpenCode manifest descriptor (DERIVERS entry)
+// ---------------------------------------------------------------------------
+/**
+ * Derive the OpenCode descriptor (`.opencode-plugin/plugin.json`) from the
+ * canonical Enact manifest. OpenCode has no documented plugin manifest file of
+ * its own — this descriptor is Enact-internal bookkeeping (validated by
+ * spec/opencode.json) that records project metadata plus the canonical
+ * `hooks`/`mcpServers` SOURCE PATHS (not their resolved content). A future
+ * installer reads those paths, loads the referenced JSON, and calls
+ * {@link deriveOpenCodeMcp} / {@link deriveOpenCodePlugin} to generate the
+ * real OpenCode artifacts: a root `opencode.json` MCP fragment and a
+ * `.opencode/plugins/<name>.ts` file.
+ */
+export function deriveOpenCodeManifest(enact) {
+    const picked = pickManifestFields(enact, MANIFEST_FIELDS.opencode);
+    return {
+        ...picked,
+        description: (typeof picked.description === "string" ? picked.description : undefined) ??
+            `${enact.name} plugin for OpenCode.`,
+        keywords: withPlatformKeyword(Array.isArray(picked.keywords) ? picked.keywords : undefined, "opencode"),
+    };
+}
+/**
+ * Project a canonical `.mcp.json` document
+ * (`{mcpServers:{name:{command,args,env,cwd?}}}`) into OpenCode's root
+ * `opencode.json` MCP fragment.
+ *
+ * Source (verified 2026-09-14, this session): https://opencode.ai/docs —
+ * OpenCode MCP servers are declared directly under `"mcp"` in `opencode.json`
+ * as `{"<name>": {"type":"local", "command":["cmd", ...args],
+ * "environment": {...}, "cwd": "...", "enabled": true}}`. There is no
+ * `servers` wrapper (unlike the canonical `mcpServers` key) and no `disabled`
+ * key — OpenCode uses `enabled` and we always emit `enabled: true` for a
+ * server the canonical manifest declares (a disabled server simply would not
+ * be declared).
+ *
+ * Servers without a `command` (e.g. a remote/HTTP-only definition) have no
+ * documented OpenCode "local" equivalent here and are skipped rather than
+ * guessed at.
+ */
+export function deriveOpenCodeMcp(canonicalMcp) {
+    const doc = canonicalMcp && typeof canonicalMcp === "object" && !Array.isArray(canonicalMcp)
+        ? canonicalMcp
+        : {};
+    const servers = doc.mcpServers && typeof doc.mcpServers === "object" && !Array.isArray(doc.mcpServers)
+        ? doc.mcpServers
+        : {};
+    const mcp = {};
+    for (const [name, def] of Object.entries(servers)) {
+        if (!def || typeof def !== "object" || Array.isArray(def))
+            continue;
+        const command = typeof def.command === "string" ? def.command : undefined;
+        if (!command)
+            continue;
+        const args = Array.isArray(def.args) ? def.args.map((a) => String(a)) : [];
+        const entry = {
+            type: "local",
+            command: [command, ...args],
+            enabled: true,
+        };
+        if (def.env && typeof def.env === "object" && !Array.isArray(def.env)) {
+            const environment = {};
+            for (const [k, v] of Object.entries(def.env)) {
+                environment[k] = String(v);
+            }
+            entry.environment = environment;
+        }
+        if (typeof def.cwd === "string" && def.cwd.trim()) {
+            entry.cwd = def.cwd;
+        }
+        mcp[name] = entry;
+    }
+    return { mcp };
+}
+// ---------------------------------------------------------------------------
+// OpenCode hooks + MCP + skills -> ONE project plugin
+// ---------------------------------------------------------------------------
+//
+// Owner decision (Tarun, 2026-09-14): OpenCode output is a SINGLE real plugin
+// (`.opencode/plugins/<name>.ts`) that carries hooks, MCP servers AND skills
+// together — not three separate artifacts. This reflects live evidence
+// gathered against a real OpenCode 1.18.29 install (see
+// .scratch/opencode-plugin-example/ and .scratch/opencode-probe/ in this
+// repo) plus the official @opencode-ai/plugin `Hooks` interface:
+//
+//   - `config(input)` mutation adds `mcp` servers and `skills.paths` —
+//     confirmed via `opencode debug config` / `opencode mcp list` /
+//     `opencode debug skill` against a live install. A same-named MCP server
+//     already present in the user's config is left untouched (skip + log to
+//     stderr) — user config survives.
+//   - `session.created` / `session.idle` are NOT top-level Hooks keys (an
+//     earlier version of this generator emitted them as top-level object
+//     keys, which never fired — a real bug the current tests catch). They
+//     only arrive via the generic `event({event})` hook, dispatched on
+//     `event.type`.
+//   - Pushing a synthetic text part onto `chat.message`'s `output.parts` was
+//     tried and PASSED without throwing, but broke every subsequent real
+//     `opencode run` call with `UnknownError: Unexpected server error` (live
+//     A/B evidence, .scratch/opencode-probe/log.jsonl). Context injection
+//     instead: `chat.message` runs the UserPromptSubmit command and stores
+//     its context keyed by `input.sessionID`; `experimental.chat.system.transform`
+//     (confirmed firing on every request, carrying `sessionID`) appends that
+//     stored context to `output.system` for the MATCHING session only.
+//   - `tool.execute.before` (throw to block) / `tool.execute.after` are real
+//     top-level keys, live-confirmed to block a bash call.
+//   - Plugin root is resolved from the `directory` the OpenCode runtime
+//     passes into the plugin factory (the project root) — never from
+//     `${CLAUDE_PLUGIN_ROOT}`, which OpenCode does not set.
+//
+// Event mapping (table-driven, same pattern as CURSOR_HOOK_EVENT_MAP in
+// src/internal/agents.ts). The map value is either a literal OpenCode Hooks
+// key ("tool.execute.before", "chat.message", ...) or, for the two events
+// that only exist as `event.type` values, a synthetic "event:<type>" key
+// meaning "dispatched inside the shared `event` hook when event.type equals
+// <type>":
+//
+//   PreToolUse    -> tool.execute.before   (throw to block; deny contract below)
+//   PostToolUse   -> tool.execute.after    (cannot block: the call already ran)
+//   UserPromptSubmit -> chat.message       (+ experimental.chat.system.transform
+//                                            pairing — see context-injection
+//                                            note above; this used to fall
+//                                            back onto SessionStart because no
+//                                            direct equivalent was known. It
+//                                            is now a NATIVE mapping.)
+//   SessionStart  -> event:session.created
+//   SessionIdle   -> event:session.idle
+//   PreCompact    -> experimental.session.compacting
+//
+// Left UNMAPPED on purpose (never invented — surfaced as `warnings` instead):
+//   - Stop: no documented "main agent turn finished" event distinct from
+//     session.idle (which already covers SessionIdle).
+//   - SubagentStart / SubagentStop: no documented subagent lifecycle hook.
+//
+// Fallback (owner rule, Tarun): when a host has no equivalent of a canonical
+// event, its hooks run on a documented substitute event instead:
+//   - SessionEnd -> SessionIdle: OpenCode has no session-end event, so
+//     canonical SessionEnd hooks run on `event:session.idle` (folded into the
+//     same bucket as native SessionIdle hooks, running after them, each
+//     command still carrying its own `fallback_for: "SessionEnd"` tag).
+//     Accepted consequence: they fire after every response, not only at true
+//     session end.
+const OPENCODE_HOOK_EVENT_MAP = {
+    PreToolUse: "tool.execute.before",
+    PostToolUse: "tool.execute.after",
+    UserPromptSubmit: "chat.message",
+    SessionStart: "event:session.created",
+    SessionIdle: "event:session.idle",
+    PreCompact: "experimental.session.compacting",
+};
+/**
+ * Table-driven fallback for canonical events with no documented OpenCode
+ * equivalent of their own.
+ *
+ *   - SessionEnd -> SessionIdle (owner rule, Tarun): OpenCode has no
+ *     session-end event, so canonical SessionEnd hooks run on SessionIdle
+ *     instead — attaching to the `event:session.idle` bucket. Accepted
+ *     consequence: they fire after every response, not only at true session
+ *     end.
+ *
+ * Fallback commands run AFTER any native commands already targeting that
+ * same bucket, each still honoring its own `timeout`. The stdin payload for a
+ * fallback command stays truthful about which event actually fired
+ * (`hook_event_name` is the FALLBACK TARGET's canonical name) plus
+ * `fallback_for` naming the originating canonical event — and never
+ * fabricates fields that don't exist for the target event.
+ */
+const OPENCODE_HOOK_EVENT_FALLBACK = {
+    SessionEnd: "SessionIdle",
+};
+/** OpenCode Hooks keys whose handler receives the tool call as `(input, output)`. */
+const OPENCODE_TOOL_EVENTS = new Set(["tool.execute.before", "tool.execute.after"]);
+/**
+ * Canonical (Claude-style, cross-host) tool-name token -> real OpenCode tool
+ * id. Canonical `hooks.json` matchers (see
+ * `extensions/enact-repo/hooks/hooks.json`) are written in Claude's
+ * PascalCase vocabulary plus a handful of other hosts' own names
+ * (`str_replace_editor` is Codex's editor tool, `edit_file` is Cursor's,
+ * `create_file`/`write_file` appear in some agent SDKs) -- none of which
+ * match OpenCode's OWN tool ids.
+ *
+ * Source of truth: live `GET /experimental/tool/ids` against a real
+ * `opencode serve` 1.18.18 instance (verified 2026-09-14, this session,
+ * `.scratch/toolid-probe/`), which returned exactly:
+ *   ["invalid","question","bash","read","glob","grep","edit","write","task",
+ *    "webfetch","todowrite","websearch","skill","apply_patch"]
+ * Notably: OpenCode tool ids are lowercase and single-word; there is no
+ * "list" tool, and the apply-a-raw-patch tool is "apply_patch", not "patch".
+ */
+const CANONICAL_TO_OPENCODE_TOOL = {
+    bash: "bash",
+    shell: "bash",
+    read: "read",
+    write: "write",
+    writefile: "write",
+    write_file: "write",
+    createfile: "write",
+    create_file: "write",
+    edit: "edit",
+    multiedit: "edit",
+    strreplace: "edit",
+    str_replace: "edit",
+    str_replace_editor: "edit",
+    edit_file: "edit",
+    replace_in_file: "edit",
+    grep: "grep",
+    glob: "glob",
+    webfetch: "webfetch",
+    websearch: "websearch",
+    todowrite: "todowrite",
+    task: "task",
+    skill: "skill",
+    apply_patch: "apply_patch",
+    patch: "apply_patch",
+    question: "question",
+};
+/**
+ * Project a canonical matcher (e.g. `"Bash"`, or
+ * `"Write|Edit|MultiEdit|StrReplace|str_replace_editor|..."`) into an
+ * OpenCode-tool-id alternation (e.g. `"bash"`, `"write|edit"`), deduping
+ * repeated targets. A token with no known canonical mapping is kept
+ * (lowercased) as a passthrough rather than dropped -- combined with the
+ * case-insensitive ANCHORED matching {@link emitToolMethod} generates, this
+ * is a safety net that still matches an already-OpenCode-shaped or unknown
+ * matcher instead of silently never firing.
+ */
+export function projectMatcherToOpenCode(matcher) {
+    const tokens = matcher
+        .split("|")
+        .map((t) => t.trim())
+        .filter(Boolean);
+    const projected = [];
+    for (const token of tokens) {
+        const key = token.toLowerCase().replace(/[^a-z0-9_]/g, "");
+        const mapped = CANONICAL_TO_OPENCODE_TOOL[key] ?? token.toLowerCase();
+        if (!projected.includes(mapped))
+            projected.push(mapped);
+    }
+    return projected.join("|");
+}
+function asCanonicalHooksDoc(canonicalHooks) {
+    if (!canonicalHooks || typeof canonicalHooks !== "object")
+        return {};
+    const doc = canonicalHooks;
+    return doc.hooks && typeof doc.hooks === "object" && !Array.isArray(doc.hooks) ? doc.hooks : {};
+}
+function flattenCanonicalEvent(entries, fallbackFor) {
+    if (!Array.isArray(entries))
+        return [];
+    const flat = [];
+    for (const entry of entries) {
+        const matcher = typeof entry.matcher === "string" && entry.matcher.trim() ? entry.matcher : undefined;
+        for (const inner of entry.hooks ?? []) {
+            const command = typeof inner.command === "string" ? inner.command : undefined;
+            if (!command)
+                continue;
+            const flatCommand = { command: withHostFlag(command, "opencode") };
+            if (matcher)
+                flatCommand.matcher = projectMatcherToOpenCode(matcher);
+            if (typeof inner.timeout === "number" && Number.isFinite(inner.timeout)) {
+                flatCommand.timeoutMs = Math.round(inner.timeout * 1000);
+            }
+            if (fallbackFor)
+                flatCommand.fallbackFor = fallbackFor;
+            flat.push(flatCommand);
+        }
+    }
+    return flat;
+}
+/**
+ * Return canonical hook events that declare active commands but have no
+ * documented OpenCode equivalent in {@link OPENCODE_HOOK_EVENT_MAP} AND no
+ * entry in {@link OPENCODE_HOOK_EVENT_FALLBACK} (a fallback-projected event
+ * is not "unmapped" — see {@link fallbackOpenCodeHookEvents}).
+ */
+export function unmappedOpenCodeHookEvents(canonicalHooks) {
+    const sourceHooks = asCanonicalHooksDoc(canonicalHooks);
+    const unmapped = [];
+    for (const [event, entries] of Object.entries(sourceHooks)) {
+        if (OPENCODE_HOOK_EVENT_MAP[event])
+            continue;
+        if (OPENCODE_HOOK_EVENT_FALLBACK[event])
+            continue;
+        if (flattenCanonicalEvent(entries).length > 0)
+            unmapped.push(event);
+    }
+    return unmapped;
+}
+/**
+ * Return the canonical hook events projected via
+ * {@link OPENCODE_HOOK_EVENT_FALLBACK} that declare active commands — e.g.
+ * `[{from:"SessionEnd", to:"SessionIdle"}]`. These are NOT reported by
+ * {@link unmappedOpenCodeHookEvents}: they run, just on a substitute event.
+ */
+export function fallbackOpenCodeHookEvents(canonicalHooks) {
+    const sourceHooks = asCanonicalHooksDoc(canonicalHooks);
+    const fallbacks = [];
+    for (const [from, to] of Object.entries(OPENCODE_HOOK_EVENT_FALLBACK)) {
+        if (flattenCanonicalEvent(sourceHooks[from]).length > 0)
+            fallbacks.push({ from, to });
+    }
+    return fallbacks;
+}
+function toIdentifier(pluginName) {
+    const parts = pluginName.split(/[^a-zA-Z0-9]+/).filter(Boolean);
+    if (parts.length === 0)
+        return "plugin";
+    const [first, ...rest] = parts;
+    return (first.toLowerCase() +
+        rest.map((p) => p.charAt(0).toUpperCase() + p.slice(1).toLowerCase()).join(""));
+}
+function emitCommandArray(name, commands) {
+    const lines = commands.map((c) => {
+        const fields = [`command: ${JSON.stringify(c.command)}`];
+        if (c.matcher)
+            fields.push(`matcher: ${JSON.stringify(c.matcher)}`);
+        if (c.timeoutMs !== undefined)
+            fields.push(`timeoutMs: ${c.timeoutMs}`);
+        if (c.fallbackFor)
+            fields.push(`fallbackFor: ${JSON.stringify(c.fallbackFor)}`);
+        return `  { ${fields.join(", ")} },`;
+    });
+    return `const ${name}: HookCommandSpec[] = [\n${lines.join("\n")}\n];`;
+}
+function emitConfigMethod(hasMcp, hasSkills) {
+    const mcpBlock = hasMcp
+        ? `    input.mcp = input.mcp || {};
+    for (const [name, def] of Object.entries(CONFIG_MCP_SERVERS)) {
+      if (Object.prototype.hasOwnProperty.call(input.mcp, name)) {
+        // OpenCode re-invokes config() on every config reload. If WE added
+        // this server on a previous call, seeing it again here is not a
+        // real conflict -- do not warn about our own injection. Only a
+        // same-named entry this plugin never added is a genuine
+        // user-defined conflict worth logging.
+        if (!enactInjectedMcpServers.has(name)) {
+          console.error("[" + PLUGIN_NAME + "] config: mcp server " + name + " already defined in user config -- skipping");
+        }
+        continue;
+      }
+      input.mcp[name] = def;
+      enactInjectedMcpServers.add(name);
+    }`
+        : "";
+    const skillsBlock = hasSkills
+        ? `    input.skills = input.skills || {};
+    input.skills.paths = Array.isArray(input.skills.paths) ? input.skills.paths : [];
+    const skillsDirAbs = join(directory, CONFIG_SKILLS_DIR);
+    if (!input.skills.paths.includes(skillsDirAbs)) {
+      input.skills.paths.push(skillsDirAbs);
+    }`
+        : "";
+    const body = [mcpBlock, skillsBlock].filter(Boolean).join("\n");
+    return `  async config(input: any) {
+${body}
+  },`;
+}
+function emitChatMessageMethod(constName) {
+    return `  "chat.message": async (input: any, output: any) => {
+    const parts = output && Array.isArray(output.parts) ? output.parts : [];
+    const promptText = parts.filter((p: any) => p && p.type === "text").map((p: any) => p.text).join(" ");
+    let context: string | undefined;
+    for (const spec of ${constName}) {
+      const payload = {
+        hook_event_name: "UserPromptSubmit",
+        prompt: promptText,
+        cwd: directory,
+        session_id: input && input.sessionID,
+      };
+      const result = await runHookCommand(spec, payload, directory);
+      const extracted = extractHookContext(result);
+      if (extracted) context = context ? context + " " + extracted : extracted;
+    }
+    const sessionID = input && input.sessionID;
+    if (sessionID) {
+      if (context) enactPromptContext.set(sessionID, context);
+      else enactPromptContext.delete(sessionID);
+    }
+  },`;
+}
+function emitChatSystemTransformMethod() {
+    return `  "experimental.chat.system.transform": async (input: any, output: any) => {
+    const sessionID = input && input.sessionID;
+    if (!sessionID) return;
+    const context = enactPromptContext.get(sessionID);
+    if (context && output && Array.isArray(output.system)) {
+      output.system.push(context);
+    }
+  },`;
+}
+function emitToolMethod(opencodeEvent, constName, canonicalEvent, canBlock) {
+    return `  ${JSON.stringify(opencodeEvent)}: async (input: ToolHookInput, output: ToolHookOutput) => {
+    for (const spec of ${constName}) {
+      if (spec.matcher && !new RegExp("^(?:" + spec.matcher + ")$", "i").test(input.tool)) continue;
+      const payload = {
+        hook_event_name: ${JSON.stringify(canonicalEvent)},
+        tool_name: input.tool,
+        tool_input: output.args,
+        cwd: directory,
+        session_id: input.sessionID,
+      };
+      const result = await runHookCommand(spec, payload, directory);
+      ${canBlock ? "const reason = denyReason(result);\n      if (reason) throw new Error(reason);" : "// PostToolUse cannot block: the tool call already completed."}
+    }
+  },`;
+}
+function emitEventMethod(hasCreated, hasIdle, createdConstName, idleConstName) {
+    const createdBlock = hasCreated
+        ? `    if (event && event.type === "session.created") {
+      for (const spec of ${createdConstName}) {
+        const payload = {
+          hook_event_name: "SessionStart",
+          cwd: directory,
+          session_id: event.properties && (event.properties.sessionID || (event.properties.info && event.properties.info.id)),
+        };
+        await runHookCommand(spec, payload, directory);
+      }
+    }`
+        : "";
+    const idleBlock = hasIdle
+        ? `    if (event && event.type === "session.idle") {
+      for (const spec of ${idleConstName}) {
+        const payload = {
+          hook_event_name: "SessionIdle",
+          cwd: directory,
+          session_id: event.properties && (event.properties.sessionID || (event.properties.info && event.properties.info.id)),
+          ...(spec.fallbackFor ? { fallback_for: spec.fallbackFor } : {}),
+        };
+        await runHookCommand(spec, payload, directory);
+      }
+    }`
+        : "";
+    const body = [createdBlock, idleBlock].filter(Boolean).join("\n");
+    return `  event: async ({ event }: { event: any }) => {
+${body}
+  },`;
+}
+function emitCompactingMethod(constName) {
+    return `  "experimental.session.compacting": async (input: any) => {
+    for (const spec of ${constName}) {
+      const payload = {
+        hook_event_name: "PreCompact",
+        cwd: directory,
+        session_id: input && input.sessionID,
+      };
+      await runHookCommand(spec, payload, directory);
+    }
+  },`;
+}
+/**
+ * Generate the TypeScript source for a SINGLE OpenCode project plugin
+ * (`.opencode/plugins/<pluginName>.ts`) that carries a bundle's hooks, MCP
+ * servers AND skills together — see the module-level owner-decision comment
+ * above for the live-evidence basis of every mapping choice below.
+ *
+ * Runtime choice: OpenCode plugins run on Bun. This generated file uses
+ * `Bun.spawn` rather than the Bun Shell `$` helper because `Bun.spawn` has a
+ * documented `timeout` + `killSignal` option
+ * (https://bun.com/docs/api/spawn, verified 2026-09-14) needed to honor each
+ * canonical hook command's `timeout` (seconds), and gives direct access to
+ * `stdin`, `exitCode`, `stdout`/`stderr` text.
+ *
+ * Truthful failures: a hook command that crashes (e.g. `Bun.spawn` itself
+ * throws) or exits non-zero for a reason other than a PreToolUse deny is
+ * logged to stderr with the plugin's name — never silently swallowed, and
+ * never treated as a block (fail open). The PreToolUse deny throw itself
+ * happens OUTSIDE any try/catch in the generated code, so it can never be
+ * caught and swallowed by error handling elsewhere in the same method.
+ *
+ * PreToolUse (`tool.execute.before`) deny contract: the configured command
+ * receives `{hook_event_name, tool_name, tool_input, cwd, session_id}` as
+ * JSON on stdin. The call is blocked (the generated hook throws) when the
+ * command exits with code 2, or its stdout parses as JSON with
+ * `hookSpecificOutput.permissionDecision === "deny"`.
+ *
+ * UserPromptSubmit (`chat.message` + `experimental.chat.system.transform`):
+ * the configured command receives `{hook_event_name:"UserPromptSubmit",
+ * prompt, cwd, session_id}` as JSON on stdin. Its `hookSpecificOutput.additionalContext`
+ * (or, failing that, its raw stdout) is stored keyed by session id and
+ * injected into `output.system` the next time `experimental.chat.system.transform`
+ * fires for that same session — see the module comment for why this replaced
+ * a direct `output.parts` push.
+ *
+ * Canonical events with no documented OpenCode equivalent and no fallback are
+ * NOT wired into any hook; call {@link unmappedOpenCodeHookEvents} to get
+ * that list. Events projected via {@link OPENCODE_HOOK_EVENT_FALLBACK} (e.g.
+ * SessionEnd -> SessionIdle) ARE wired in, under their fallback target's
+ * bucket; call {@link fallbackOpenCodeHookEvents} to get that list.
+ */
+export function deriveOpenCodePlugin(source, pluginName) {
+    const sourceHooks = asCanonicalHooksDoc(source?.hooks);
+    // Keyed by the OpenCode Hooks method this bucket attaches to (or, for
+    // SessionStart/SessionIdle, the synthetic "event:<event.type>" dispatch
+    // key), but each entry keeps the ORIGINATING canonical event name too: the
+    // JSON payload's `hook_event_name` must stay the canonical PascalCase name
+    // (PreToolUse, SessionStart, ...) so a command written against the
+    // canonical hook contract (Claude/Codex/Cursor-style) sees the name it
+    // expects, not OpenCode's own event naming.
+    const byOpenCodeEvent = new Map();
+    for (const [canonicalEvent, opencodeEvent] of Object.entries(OPENCODE_HOOK_EVENT_MAP)) {
+        const flat = flattenCanonicalEvent(sourceHooks[canonicalEvent]);
+        if (flat.length > 0)
+            byOpenCodeEvent.set(opencodeEvent, { canonicalEvent, commands: flat });
+    }
+    // Fold fallback-projected events (OPENCODE_HOOK_EVENT_FALLBACK) into their
+    // target's bucket, AFTER any native commands already collected above, so
+    // e.g. SessionEnd commands run after native SessionIdle commands under the
+    // same "event:session.idle" bucket.
+    for (const [fallbackEvent, targetCanonicalEvent] of Object.entries(OPENCODE_HOOK_EVENT_FALLBACK)) {
+        const opencodeEvent = OPENCODE_HOOK_EVENT_MAP[targetCanonicalEvent];
+        if (!opencodeEvent)
+            continue; // defensive: fallback target must itself be a mapped event
+        const flat = flattenCanonicalEvent(sourceHooks[fallbackEvent], fallbackEvent);
+        if (flat.length === 0)
+            continue;
+        const existing = byOpenCodeEvent.get(opencodeEvent);
+        if (existing) {
+            existing.commands = [...existing.commands, ...flat];
+        }
+        else {
+            byOpenCodeEvent.set(opencodeEvent, { canonicalEvent: targetCanonicalEvent, commands: flat });
+        }
+    }
+    const warnings = unmappedOpenCodeHookEvents(source?.hooks);
+    const fallbacks = fallbackOpenCodeHookEvents(source?.hooks);
+    const identifier = toIdentifier(pluginName);
+    const mcpAdditions = deriveOpenCodeMcp(source?.mcpServers).mcp;
+    const hasMcp = Object.keys(mcpAdditions).length > 0;
+    const skillsDir = typeof source?.skillsDir === "string" && source.skillsDir.trim() ? source.skillsDir : undefined;
+    const hasConfig = hasMcp || Boolean(skillsDir);
+    const hasChatMessage = byOpenCodeEvent.has("chat.message");
+    const hasToolBefore = byOpenCodeEvent.has("tool.execute.before");
+    const hasToolAfter = byOpenCodeEvent.has("tool.execute.after");
+    const hasSessionCreated = byOpenCodeEvent.has("event:session.created");
+    const hasSessionIdle = byOpenCodeEvent.has("event:session.idle");
+    const hasEvent = hasSessionCreated || hasSessionIdle;
+    const hasCompacting = byOpenCodeEvent.has("experimental.session.compacting");
+    const hasAnyHookExec = hasChatMessage || hasToolBefore || hasToolAfter || hasEvent || hasCompacting;
+    const isEmpty = !hasConfig && !hasAnyHookExec;
+    const constNameFor = (key) => `HOOKS_${key.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+    const constDecls = [];
+    for (const [key, { commands }] of byOpenCodeEvent.entries()) {
+        constDecls.push(emitCommandArray(constNameFor(key), commands));
+    }
+    if (hasMcp) {
+        constDecls.push(`const CONFIG_MCP_SERVERS: Record<string, any> = ${JSON.stringify(mcpAdditions, null, 2)};`);
+        // Tracks MCP server names THIS plugin instance has injected into
+        // input.mcp, across repeated config() calls (OpenCode re-invokes
+        // config() on every config reload) -- see emitConfigMethod.
+        constDecls.push(`const enactInjectedMcpServers = new Set<string>();`);
+    }
+    if (skillsDir) {
+        constDecls.push(`const CONFIG_SKILLS_DIR = ${JSON.stringify(skillsDir)};`);
+    }
+    const methods = [];
+    if (hasConfig)
+        methods.push(emitConfigMethod(hasMcp, Boolean(skillsDir)));
+    if (hasChatMessage) {
+        methods.push(emitChatMessageMethod(constNameFor("chat.message")));
+        methods.push(emitChatSystemTransformMethod());
+    }
+    if (hasToolBefore) {
+        methods.push(emitToolMethod("tool.execute.before", constNameFor("tool.execute.before"), byOpenCodeEvent.get("tool.execute.before").canonicalEvent, true));
+    }
+    if (hasToolAfter) {
+        methods.push(emitToolMethod("tool.execute.after", constNameFor("tool.execute.after"), byOpenCodeEvent.get("tool.execute.after").canonicalEvent, false));
+    }
+    if (hasEvent) {
+        methods.push(emitEventMethod(hasSessionCreated, hasSessionIdle, constNameFor("event:session.created"), constNameFor("event:session.idle")));
+    }
+    if (hasCompacting)
+        methods.push(emitCompactingMethod(constNameFor("experimental.session.compacting")));
+    const warningsComment = warnings.length > 0
+        ? `//\n// Unmapped canonical events with active commands (no documented OpenCode\n// equivalent — see OPENCODE_HOOK_EVENT_MAP in src/create/opencode.ts):\n${warnings.map((w) => `//   - ${w}`).join("\n")}\n`
+        : "";
+    const fallbackComment = fallbacks.length > 0
+        ? `//\n// Projected via fallback (owner rule: an event with no documented OpenCode\n// equivalent runs on a substitute event instead — see\n// OPENCODE_HOOK_EVENT_FALLBACK in src/create/opencode.ts):\n${fallbacks.map((f) => `//   - ${f.from} -> ${f.to}`).join("\n")}\n`
+        : "";
+    // `join` is only actually referenced by the skills.paths block, not by the
+    // MCP block, so import it only when a skills dir was provided.
+    const importsBlock = skillsDir ? `import { join } from "node:path";\n\n` : "";
+    // PLUGIN_NAME is referenced both by config()'s same-named-server skip log
+    // and by runHookCommand's truthful-failure logging -- emit it whenever
+    // EITHER needs it, not only when hooks execute (a config-only plugin, with
+    // MCP servers but no hooks, still needs it for the skip log).
+    const needsPluginName = hasMcp || hasAnyHookExec;
+    const pluginNameConst = needsPluginName ? `const PLUGIN_NAME = ${JSON.stringify(pluginName)};\n\n` : "";
+    const sharedHelpers = hasAnyHookExec
+        ? `async function runHookCommand(
+  spec: HookCommandSpec,
+  payload: Record<string, unknown>,
+  cwd: string,
+): Promise<{ exitCode: number | null; stdout: string; stderr: string }> {
+  try {
+    const proc = Bun.spawn(["/bin/sh", "-c", spec.command], {
+      cwd,
+      stdin: "pipe",
+      stdout: "pipe",
+      stderr: "pipe",
+      ...(spec.timeoutMs ? { timeout: spec.timeoutMs, killSignal: "SIGTERM" } : {}),
+    });
+    proc.stdin.write(JSON.stringify(payload));
+    proc.stdin.end();
+    const [stdout, stderr] = await Promise.all([
+      new Response(proc.stdout).text(),
+      new Response(proc.stderr).text(),
+    ]);
+    await proc.exited;
+    if (proc.exitCode !== 0 && proc.exitCode !== 2) {
+      console.error("[" + PLUGIN_NAME + "] hook command exited " + proc.exitCode + ": " + spec.command);
+    }
+    return { exitCode: proc.exitCode, stdout, stderr };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error("[" + PLUGIN_NAME + "] hook command crashed: " + spec.command + " -- " + message);
+    return { exitCode: null, stdout: "", stderr: message };
+  }
+}
+`
+        : "";
+    const denyHelper = hasToolBefore
+        ? `
+function denyReason(result: { exitCode: number | null; stdout: string; stderr: string }): string | undefined {
+  if (result.exitCode === 2) {
+    return result.stderr.trim() || "PreToolUse hook denied the call (exit code 2)";
+  }
+  try {
+    const parsed = JSON.parse(result.stdout) as {
+      hookSpecificOutput?: { permissionDecision?: string; permissionDecisionReason?: string };
+    };
+    if (parsed?.hookSpecificOutput?.permissionDecision === "deny") {
+      return parsed.hookSpecificOutput.permissionDecisionReason || "PreToolUse hook denied the call";
+    }
+  } catch {
+    // stdout was not JSON -- not a deny signal.
+  }
+  return undefined;
+}
+`
+        : "";
+    const chatContextHelper = hasChatMessage
+        ? `
+const enactPromptContext = new Map<string, string>();
+
+function extractHookContext(result: { exitCode: number | null; stdout: string; stderr: string }): string | undefined {
+  const trimmed = result.stdout.trim();
+  if (!trimmed) return undefined;
+  try {
+    const parsed = JSON.parse(trimmed) as { hookSpecificOutput?: { additionalContext?: string } };
+    const additional = parsed?.hookSpecificOutput?.additionalContext;
+    if (typeof additional === "string" && additional.trim()) {
+      return additional.trim();
+    }
+  } catch {
+    // stdout was not JSON -- treat it as plain-text context.
+  }
+  return trimmed;
+}
+`
+        : "";
+    return `// AUTO-GENERATED by enact-extensions (deriveOpenCodePlugin). Do not edit by hand.
+// Source: canonical hooks.json + .mcp.json + skills dir -> ONE OpenCode project plugin.
+${warningsComment}${fallbackComment}
+${importsBlock}interface HookCommandSpec {
+  command: string;
+  matcher?: string;
+  timeoutMs?: number;
+  fallbackFor?: string;
+}
+
+interface ToolHookInput {
+  tool: string;
+  sessionID?: string;
+  callID?: string;
+}
+
+interface ToolHookOutput {
+  args: Record<string, unknown>;
+}
+
+${constDecls.join("\n\n") || "// No canonical hook event maps to a documented OpenCode hook for this plugin, and no MCP servers or skills dir were provided."}
+
+${pluginNameConst}
+${sharedHelpers}${denyHelper}${chatContextHelper}
+export const ${identifier}Plugin = async ({ directory }: { directory: string }) => {
+  return {
+${methods.join("\n") || "    // No mapped hooks."}
+  };
+};
+
+export default ${identifier}Plugin;
+`;
+}
+//# sourceMappingURL=opencode.js.map