opencode-forking-agents-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wkronmiller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,32 @@
+# forking-agents-plugin
+
+OpenCode plugin that adds `fork_<agent>` subagents. When you run the **task** tool with `subagent_type` set to `fork_general`, `fork_explore`, or `fork_<name>` for any configured `mode: subagent` agent, the plugin rewrites the call to the base agent and prepends the **parent session transcript** to the task prompt (wrapped in `<parent_session_transcript>`).
+
+## Install
+
+In `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["forking-agents-plugin"]
+}
+```
+
+OpenCode installs npm plugins automatically (see [Plugins](https://opencode.ai/docs/plugins/)).
+
+## Local development
+
+Clone this repo and point `plugin` at the entry file, or use `bun link` / `npm link`.
+
+## Disable
+
+Set `OPENCODE_DISABLE_FORK_SUBAGENT_PLUGIN=1`.
+
+## Requirements
+
+OpenCode must pass **`listSessionMessages`** on the plugin input (session store, no HTTP). This matches `@opencode-ai/plugin` **1.5.0+** in the main OpenCode repo; the published npm plugin package types may lag—runtime behavior follows OpenCode.
+
+## License
+
+MIT

package/bun.lock

@@ -0,0 +1,50 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "forking-agents-plugin",
+      "devDependencies": {
+        "@opencode-ai/plugin": "1.4.3",
+        "@types/bun": "1.2.23",
+        "typescript": "5.9.2",
+      },
+      "peerDependencies": {
+        "@opencode-ai/plugin": ">=1.4.3",
+      },
+    },
+  },
+  "packages": {
+    "@opencode-ai/plugin": ["@opencode-ai/plugin@1.4.3", "", { "dependencies": { "@opencode-ai/sdk": "1.4.3", "zod": "4.1.8" }, "peerDependencies": { "@opentui/core": ">=0.1.97", "@opentui/solid": ">=0.1.97" }, "optionalPeers": ["@opentui/core", "@opentui/solid"] }, "sha512-Ob/3tVSIeuMRJBr2O23RtrnC5djRe01Lglx+TwGEmjrH9yDBJ2tftegYLnNEjRoMuzITgq9LD8168p4pzv+U/A=="],
+
+    "@opencode-ai/sdk": ["@opencode-ai/sdk@1.4.3", "", { "dependencies": { "cross-spawn": "7.0.6" } }, "sha512-X0CAVbwoGAjTY2iecpWkx2B+GAa2jSaQKYpJ+xILopeF/OGKZUN15mjqci+L7cEuwLHV5wk3x2TStUOVCa5p0A=="],
+
+    "@types/bun": ["@types/bun@1.2.23", "", { "dependencies": { "bun-types": "1.2.23" } }, "sha512-le8ueOY5b6VKYf19xT3McVbXqLqmxzPXHsQT/q9JHgikJ2X22wyTW3g3ohz2ZMnp7dod6aduIiq8A14Xyimm0A=="],
+
+    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "@types/react": ["@types/react@19.2.14", "", { "dependencies": { "csstype": "^3.2.2" } }, "sha512-ilcTH/UniCkMdtexkoCN0bI7pMcJDvmQFPvuPvmEaYA/NSfFTAgdUSLAoVjaRJm7+6PvcM+q1zYOwS4wTYMF9w=="],
+
+    "bun-types": ["bun-types@1.2.23", "", { "dependencies": { "@types/node": "*" }, "peerDependencies": { "@types/react": "^19" } }, "sha512-R9f0hKAZXgFU3mlrA0YpE/fiDvwV0FT9rORApt2aQVWSuJDzZOyB5QLc0N/4HF57CS8IXJ6+L5E4W1bW6NS2Aw=="],
+
+    "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
+
+    "csstype": ["csstype@3.2.3", "", {}, "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ=="],
+
+    "isexe": ["isexe@2.0.0", "", {}, "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw=="],
+
+    "path-key": ["path-key@3.1.1", "", {}, "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q=="],
+
+    "shebang-command": ["shebang-command@2.0.0", "", { "dependencies": { "shebang-regex": "^3.0.0" } }, "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA=="],
+
+    "shebang-regex": ["shebang-regex@3.0.0", "", {}, "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A=="],
+
+    "typescript": ["typescript@5.9.2", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-CWBzXQrc/qOkhidw1OzBTQuYRbfyxDXJMVJ1XNwUHGROVmuaeiEm3OslpZ1RV96d7SKKjZKrSJu3+t/xlw3R9A=="],
+
+    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+
+    "which": ["which@2.0.2", "", { "dependencies": { "isexe": "^2.0.0" }, "bin": { "node-which": "./bin/node-which" } }, "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA=="],
+
+    "zod": ["zod@4.1.8", "", {}, "sha512-5R1P+WwQqmmMIEACyzSvo4JXHY5WiAFHRMg+zBZKgKS+Q1viRa0C1hmUKtHltoIFKtIdki3pRxkmpP74jnNYHQ=="],
+  }
+}

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "opencode-forking-agents-plugin",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "OpenCode plugin: fork_* subagents with parent session transcript prepended to task prompts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "peerDependencies": {
+    "@opencode-ai/plugin": ">=1.4.3"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.4.3",
+    "@types/bun": "1.2.23",
+    "typescript": "5.9.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "keywords": ["opencode", "plugin", "subagent", "fork"]
+}

package/src/index.ts

@@ -0,0 +1,132 @@
+import type { Config, Hooks, PluginInput } from "@opencode-ai/plugin"
+
+/** OpenCode passes this once `@opencode-ai/plugin` 1.5.0 ships; expressed locally until then. */
+type Msg = { info: { role: string }; parts: Array<{ type: string; text?: string }> }
+export type ForkPluginInput = PluginInput & {
+  listSessionMessages: (input: { sessionID: string }) => Promise<Msg[]>
+}
+
+const PREFIX = "fork_"
+const SVC = "plugin.forking-agents"
+const PREVIEW = 4000
+const CAP = 400_000
+
+function plog(
+  client: PluginInput["client"],
+  level: "debug" | "info" | "error" | "warn",
+  message: string,
+  extra?: Record<string, unknown>,
+) {
+  void client.app.log({
+    body: { service: SVC, level, message, extra },
+  })
+}
+
+function bases(cfg: Config) {
+  const out = new Set<string>(["general", "explore"])
+  for (const [k, v] of Object.entries(cfg.agent ?? {})) {
+    if (v?.disable) continue
+    if (k.startsWith(PREFIX)) continue
+    if (v?.mode === "subagent") out.add(k)
+  }
+  if (cfg.agent?.general?.disable) out.delete("general")
+  if (cfg.agent?.explore?.disable) out.delete("explore")
+  return [...out]
+}
+
+function clip(txt: string) {
+  if (txt.length <= CAP) return txt
+  return `${txt.slice(0, CAP)}\n\n[truncated ${txt.length - CAP} chars]`
+}
+
+function line(msg: Msg) {
+  const chunks = msg.parts
+    .filter((p) => p.type === "text" && typeof p.text === "string" && p.text.trim())
+    .map((p) => p.text!)
+  if (chunks.length === 0) return ""
+  return `${msg.info.role.toUpperCase()}:\n${chunks.join("\n\n")}\n`
+}
+
+function transcript(msgs: Msg[]) {
+  return clip(msgs.map(line).filter(Boolean).join("\n"))
+}
+
+/**
+ * Adds `fork_<name>` subagents for each subagent (built-in general/explore plus any `mode: subagent` in config).
+ * When the task tool runs with `subagent_type` `fork_*`, rewrites to the base agent and prepends the parent session transcript to the task prompt.
+ *
+ * Requires OpenCode with plugin input `listSessionMessages`. Set `OPENCODE_DISABLE_FORK_SUBAGENT_PLUGIN=1` to disable.
+ */
+export default async function forkSubagentPlugin(input: ForkPluginInput): Promise<Hooks> {
+  if (process.env.OPENCODE_DISABLE_FORK_SUBAGENT_PLUGIN === "1") return {}
+
+  const { client, directory, listSessionMessages } = input
+
+  return {
+    async config(cfg) {
+      cfg.agent ??= {}
+      for (const base of bases(cfg)) {
+        const fork = `${PREFIX}${base}`
+        if (cfg.agent[fork] !== undefined) continue
+        cfg.agent[fork] = {
+          mode: "subagent",
+          hidden: true,
+          description: `Fork of @${base}: parent session transcript is prepended before your task prompt.`,
+        }
+      }
+    },
+    "tool.execute.before": async (hook, out) => {
+      if (hook.tool !== "task" || !out.args || typeof out.args !== "object") return
+      const args = out.args as { subagent_type?: string; prompt?: string }
+      const sub = args.subagent_type
+      if (typeof sub !== "string" || !sub.startsWith(PREFIX)) return
+      const base = sub.slice(PREFIX.length)
+      if (!base) return
+      plog(client, "info", "fork task rewrite", {
+        sessionID: hook.sessionID,
+        callID: hook.callID,
+        from: sub,
+        to: base,
+        directory,
+      })
+      args.subagent_type = base
+      const task = typeof args.prompt === "string" ? args.prompt : ""
+      let block = ""
+      try {
+        const list = await listSessionMessages({ sessionID: hook.sessionID })
+        plog(client, "info", "fork parent messages loaded", {
+          sessionID: hook.sessionID,
+          messageCount: list.length,
+        })
+        plog(client, "info", "fork parent messages", {
+          sessionID: hook.sessionID,
+          messageCount: list.length,
+          transcriptChars: list.length === 0 ? 0 : transcript(list).length,
+        })
+        const t = list.length === 0 ? "" : transcript(list)
+        plog(client, "debug", "fork transcript preview", {
+          head: t.slice(0, PREVIEW),
+        })
+        if (list.length === 0) block = "[fork-subagent: empty parent transcript]\n\n"
+        else block = `<parent_session_transcript>\n${t}\n</parent_session_transcript>\n\n`
+      } catch (err) {
+        plog(client, "error", "fork parent messages failed", {
+          error: err instanceof Error ? err.message : JSON.stringify(err),
+          sessionID: hook.sessionID,
+          directory,
+        })
+        block = "[fork-subagent: failed to load parent transcript]\n\n"
+      }
+      args.prompt = `${block}<task>\n${task}\n</task>`
+      plog(client, "info", "fork child prompt built", {
+        sessionID: hook.sessionID,
+        totalChars: args.prompt.length,
+        hasParentBlock: args.prompt.includes("<parent_session_transcript>"),
+        preview500: args.prompt.slice(0, 500),
+      })
+      plog(client, "debug", "fork child prompt preview", {
+        head: args.prompt.slice(0, PREVIEW),
+      })
+    },
+  }
+}

package/test/fork-subagent.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from "bun:test"
+import forkSubagentPlugin, { type ForkPluginInput } from "../src/index.js"
+
+function ctx(over: Partial<ForkPluginInput> = {}): ForkPluginInput {
+  return {
+    client: {
+      app: { log: () => Promise.resolve({} as never) },
+    },
+    directory: "/tmp",
+    worktree: "/tmp",
+    project: {} as never,
+    serverUrl: new URL("http://localhost:4096"),
+    $: undefined as never,
+    listSessionMessages: async () => [],
+    ...over,
+  } as ForkPluginInput
+}
+
+describe("forkSubagentPlugin", () => {
+  test("config adds fork_* agents for builtins and configured subagents", async () => {
+    const hooks = await forkSubagentPlugin(ctx())
+    const cfg: { agent?: Record<string, { mode?: string; description?: string; hidden?: boolean }> } = {
+      agent: {
+        zebra: { mode: "subagent", description: "Zebra" },
+      },
+    }
+    await hooks.config?.(cfg as never)
+    expect(cfg.agent?.fork_general?.mode).toBe("subagent")
+    expect(cfg.agent?.fork_explore?.hidden).toBe(true)
+    expect(cfg.agent?.fork_zebra?.mode).toBe("subagent")
+    expect(cfg.agent?.fork_zebra?.description).toContain("Fork of @zebra")
+  })
+
+  test("config does not replace an existing fork entry", async () => {
+    const hooks = await forkSubagentPlugin(ctx())
+    const cfg = {
+      agent: {
+        fork_general: { mode: "subagent" as const, description: "custom" },
+      },
+    }
+    await hooks.config?.(cfg as never)
+    expect(cfg.agent.fork_general.description).toBe("custom")
+  })
+
+  test("tool.execute.before rewrites fork_* and prepends transcript", async () => {
+    const hooks = await forkSubagentPlugin(
+      ctx({
+        directory: "/proj",
+        worktree: "/proj",
+        listSessionMessages: async () => [
+          {
+            info: { role: "user" },
+            parts: [{ type: "text", text: "hello" }],
+          },
+          {
+            info: { role: "assistant" },
+            parts: [{ type: "text", text: "hi" }],
+          },
+        ],
+      }),
+    )
+    const fn = hooks["tool.execute.before"]
+    expect(fn).toBeDefined()
+    const out = {
+      args: {
+        subagent_type: "fork_explore",
+        prompt: "find foo",
+      },
+    }
+    await fn!({ tool: "task", sessionID: "sess-1", callID: "c1" } as never, out as never)
+    expect(out.args.subagent_type).toBe("explore")
+    expect(out.args.prompt).toContain("<parent_session_transcript>")
+    expect(out.args.prompt).toContain("USER:\nhello")
+    expect(out.args.prompt).toContain("<task>")
+    expect(out.args.prompt).toContain("find foo")
+  })
+})

package/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "skipLibCheck": true,
+    "noEmit": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}