opencode-forking-agents-plugin

OpenCode plugin that adds namespaced subagent tools for synchronous runs, background delegation, optional forked parent-session context, and explicit model selection.

Install

In opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-forking-agents-plugin"]
}

OpenCode installs npm plugins automatically. For local development, point plugin at ./src/index.ts.

Tools

| Tool | Purpose | | --- | --- | | subagents_run | Run a subagent synchronously and return the result. | | subagents_delegate | Start a read-only background subagent and return a delegation ID. | | subagents_read | Read a persisted background delegation result. | | subagents_list | List background delegations for the plugin instance. | | subagents_cancel | Cancel a running background delegation. | | subagents_models | List available models with providerID, modelID, and provider/model references. |

Forking

Forking means the parent session transcript is prepended to the child prompt in <parent_session_transcript>.

fork is a boolean tool argument. If omitted, the plugin uses config defaults:

• true by default for most agents
• false by default for review-like agents such as review and code-review
• explicit tool arguments always win

Example:

{
  "prompt": "Find where auth is implemented",
  "agent": "explore",
  "fork": true
}

Model Selection

Models can be selected either as model: "provider/model" or explicit providerID and modelID fields.

Explicit fields win, and both must be supplied together:

{
  "prompt": "Review this change",
  "agent": "code-review",
  "providerID": "anthropic",
  "modelID": "claude-sonnet-4-5"
}

Use subagents_models to inspect available model IDs.

Configuration

Plugin options can tune defaults:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    [
      "opencode-forking-agents-plugin",
      {
        "fork": {
          "default": true,
          "reviewDefault": false,
          "agents": {
            "code-review": false,
            "explore": true
          }
        },
        "model": {
          "agents": {
            "explore": "anthropic/claude-sonnet-4-5",
            "code-review": {
              "providerID": "openai",
              "modelID": "gpt-5.5"
            }
          }
        },
        "background": {
          "timeoutMs": 900000,
          "allowWriteCapable": false
        },
        "transcript": {
          "maxChars": 400000,
          "redact": false
        }
      }
    ]
  ]
}

Safety

Background delegation rejects write-capable agents by default because background sessions run outside normal parent-session undo flow. Use subagents_run for write-capable work, or explicitly set background.allowWriteCapable after accepting that risk.

Optional transcript redaction can reduce accidental propagation of common token/password patterns into forked subagent prompts.

Disable

Set OPENCODE_DISABLE_FORK_SUBAGENT_PLUGIN=1.

Release to npm

This package is configured for public npm publishing with provenance. The workflow supports either npm trusted publishing or an NPM_TOKEN repository secret.

1. In npm, enable trusted publishing for the GitHub repository wkronmiller/forking-agents-plugin and workflow filename release.yml.
2. If trusted publishing is not enabled, add a GitHub Actions secret named NPM_TOKEN with publish access to opencode-forking-agents-plugin.
3. Ensure package.json has the release version and publishConfig.access is public.
4. Push a matching version tag, for example v0.2.0 for package version 0.2.0.
5. The release workflow runs tests, typecheck, and npm publish --access public --provenance.

The workflow can also be run manually with a tag input, but the tag must exist and match package.json.

For local publishing, authenticate first with npm login; unauthenticated local publishes fail even when the package is public.

License

MIT