# 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`:

```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:

```json
{
  "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:

```json
{
  "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:

```json
{
  "$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