{"id":"be1fc513-5ec1-49c3-b2e1-a8770cc39ea8","slug":"opencode-subagent-tools","kind":"skill","name":"opencode-subagent-tools","summary":"OpenCode V2 plugin that gives the agent tools to list, inspect, cancel, steer, queue, and inject context into its subagent sessions without interrupting the parent.","owner":"FINNSEEFLY","repoUrl":"https://github.com/FINNSEEFLY/opencode-subagent-tools","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"skill","createdAt":"2026-10-19T19:16:25.000Z","addedAt":"2026-11-08T07:21:45.362Z","logoUrl":"https://avatars.githubusercontent.com/u/43048277?u=fa735af37997cdf4d80da895b8a96cd6354d46b1&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["memory-knowledge"],"tags":["agent-tools","opencode-v2","opencode-v2-plugin","subagent-orchestration"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-11-08T07:24:32.485Z","sample":false,"url":"https://conduits.dev/tools/opencode-subagent-tools","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# opencode-subagent-tools\n\nSeven tools for OpenCode V2 that let an agent inspect and control subagent\nsessions: list children and usage, cancel one session or the caller's running\ndescendants, steer or queue messages, and inject context.\n\n> Plugin ID: `subagent-tools`. Default tool namespace: `subagent`.\n\nRequires OpenCode 2.2.5+ with `ctx.session.list`.\n\n## Quick start\n\n```sh\nopencode plugin add opencode-subagent-tools\n```\n\nGitHub:\n\n```sh\nopencode plugin add github:finnseefly/opencode-subagent-tools\n```\n\nAfter install, run `opencode reload` and ask the agent to call `subagent_list`.\nFor manual/local installation, see [installation](docs/installation.md).\n\n## Tools\n\n| Tool                          | What it does                                                 |\n| ----------------------------- | ------------------------------------------------------------ |\n| `subagent_list`               | List child sessions with status, age, cost, and token usage. |\n| `subagent_usage`              | Read cost, tokens, and current context for a session.        |\n| `subagent_cancel`             | Stop one session.                                            |\n| `subagent_cancel_descendants` | Stop running descendants of the calling session.             |\n| `subagent_steer`              | Send an instruction at the child's next model request.       |\n| `subagent_queue`              | Queue a message as the next independent turn.                |\n| `subagent_context`            | Inject a synthetic context message without starting a turn.  |\n\nThe plugin also registers a `subagent-tools` skill with operational guidance.\nSee the [tool reference](docs/reference.md#text-vs-json) for output formats and\nper-tool defaults. Set `allowedOutputFormats` to `[\"text\"]` or `[\"json\"]` to\nallow only one format; the default `[\"text\", \"json\"]` enables the per-call\n`format` choice.\n\nTool names above use the default `subagent` namespace. Change the `namespace`\noption to use a different prefix. Nested subagents require\n`experimental.subagent_depth` to be at least `2` in OpenCode; this is an OpenCode\nsetting, not a plugin option.\n\n## Configuration\n\nOne power-user example; every option is optional. The values below are the\ndefaults. See [configuration](docs/configuration.md) for ranges and examples.\n\n```jsonc\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"plugins\": [\n    {\n      \"package\": \"opencode-subagent-tools\",\n      \"options\": {\n        \"namespace\": \"subagent\", // tool prefix\n        \"enforcePermissions\": true, // check mutations with subagent.control\n        \"sessionControlPolicy\": \"descendants\", // mutations only; reads are unrestricted\n        \"allowedOutputFormats\": [\"text\", \"json\"], // or [\"text\"] / [\"json\"]\n        \"registerSkill\": true, // register SKILL.md as a skill\n        \"limits\": {\n          \"maxDiscoveryNodes\": 200,\n          \"maxDiscoveryDepth\": 8,\n          \"maxDiscoveryPages\": 5,\n          \"maxListRows\": 20,\n          \"maxCancelBatch\": 20,\n          \"maxTextLength\": 16000,\n        },\n      },\n    },\n  ],\n}\n```\n\nMutations call the `subagent.control` permission action. Setting\n`enforcePermissions: true` by itself does not prompt; add an `ask` or `deny` rule\nto be asked or blocked. See [security model](docs/security-model.md).\n\n## Pitfalls\n\n- **Foreground children block the parent.** If you want to control a child while\n  it runs, launch it as a background subagent.\n- **`cancel` is a soft interrupt.** It does not cascade. A long tool call may\n  finish first, and jobs owned by an idle session keep running.\n- **Discovery stops at 200 nodes, 8 levels, or 5 pages by default.** Raise them\n  for large trees. An empty or partial list is not proof that no subagents\n  exist. See [limitations](docs/limitations.md).\n- **Usage can lag while a child is running.** Values are persisted at step\n  boundaries; `usageMayLag` means re-query after the step or after cancellation.\n- **`cancel_descendants` stops up to `maxCancelBatch` running descendants per\n  call.** It only touches the caller's subtree; use `cursor` to continue. Nested\n  cancellation can wake an intermediate parent.\n- **Permissions are not prompted by default.** Add an `ask` or `deny` rule for\n  `subagent.control` if you rely on approval.\n\n## Documentation\n\n- [Installation](docs/installation.md)\n- [Configuration](docs/configuration.md)\n- [Tool reference](docs/reference.md)\n- [Security model](docs/security-model.md)\n- [Security policy](SECURITY.md)\n- [Limitations](docs/limitations.md)\n- [Development](docs/development.md)\n- [Changelog](CHANGELOG.md)\n\n## License\n\nMIT. See [LICENSE](./LICENSE).\n"}