Subagents Keep the Parent Session Small: How OpenCode Child Sessions Protect Your Context Window

OpenCode subagents run in their own child sessions with fresh context, so the search, the test runs, and the review stay out of the parent's window; the catch is that every child pays almost the full fixed opening, so delegation wins only when it keeps a lot out of the parent or when fresh eyes are the point.

Rick Hightower

Cover image for “Subagents Keep the Parent Session Small: How OpenCode Child Sessions Protect Your Context Window” by Rick Hightower

An OpenCode subagent does the reading in its own child session and sends back a report, so the parent spends its window on the fix instead of on the search. It is not free, and knowing when it pays is the whole skill.

You spent three hours hunting a flaky test in one session, it compacted twice, and the one log line the fix depends on is now a paraphrase. The search ate the room you needed for the fix.

In this article: Day 10 of a 17-day guide. Start here writes a read-only reviewer subagent for Ticket Triage, hands it your uncommitted change through build, and checks that the reviewer changed nothing. Going deeper explains how OpenCode subagents work in V2.3.0: why a child session starts with fresh context and what it still costs (16,653 tokens before any work), how background children report back, the two sets of permission rules a child runs under, a tester that may edit only tests, a bug hunt run through children, and a rule of thumb for when delegation costs more than it saves.

Part 9 gave each agent the model its job needs, with explore and title on a cheaper one. Today you write an agent of your own and let build hand it a job.

Start here

By the end of today you have a read-only reviewer subagent in Ticket Triage, and you have watched build hand it your uncommitted change and print its report, while the reviewer changed nothing.

Starting fresh or fell behind? Run git switch -C main opencode/day-09. This replaces your main with the end of Day 9; to keep your own work, run git branch my-backup first.

A subagent is a second session, not a second prompt

An agent is a named set of standing instructions, permission rules, and an optional model. build, the default agent from Part 1, is one, and Part 9 asked build to send the built-in explore agent off on a search. explore is a subagent: an agent that another agent starts for one job.

When build starts a subagent, OpenCode opens a child session for it. A child session is a new session with its own conversation, so it starts with none of the parent's history. The session that started it is the parent. The child reads files, runs the commands its rules allow, and sends a report back to the parent. The file reads and the command output stay in the child; the parent's conversation gains only the request and the report. Part 6 showed that every request carries the whole conversation, so a parent that does not read twenty files does not carry them.

Two facts shape every subagent you write.

  • The child knows only what the parent tells it. build writes a prompt for the child, and that prompt is all the child knows about the task. The child still receives your AGENTS.md, as every new session does.
  • The child runs in the background. In OpenCode 2.3.0, build hears at once that the child is working, and the report arrives when the child finishes. In a headless opencode run, the run waits for that report before it exits.

OpenCode ships two subagents: general, which can edit files and run commands, and explore, which reads and searches. Today you add a third with one narrow job: read the change you are about to commit and say what is wrong with it. A child is not free, because it starts with its own copy of the standing instructions and the tool list. Going deeper explains when a child costs more than it saves.

If you have used Claude Code, a file in .opencode/agents/ plays the role of a file in .claude/agents/.

Write the reviewer

Start from a clean tree, so the check at the end can prove the reviewer changed nothing. If git status --short lists files, commit them first.

cd ~/code/ticket-triage
git status --short

A custom agent is a Markdown file. Project agents live in .opencode/agents/<name>.md, and the file name is the agent's ID. The frontmatter, the block between the two --- lines, "accepts the same fields as an agents configuration entry," and the body becomes the agent's system prompt, its standing instructions. Ticket Triage's reviewer reads the current diff and reports. It may not edit, and its shell is limited to two read-only git commands. Create the file. $EDITOR is the shell variable that names your editor; if it is empty, type nano or code in its place.

mkdir -p .opencode/agents
$EDITOR .opencode/agents/reviewer.md

Paste this into it. Read the permission list in order, because the last matching rule wins.

---
description: Reviews the current diff for correctness, rule order, and missing tests. Read-only.
mode: subagent
steps: 10
permissions:
  - action: edit
    resource: "*"
    effect: deny
  - action: shell
    resource: "*"
    effect: deny
  - action: shell
    resource: "git diff *"
    effect: allow
  - action: shell
    resource: "git status *"
    effect: allow
---

Review the current changes in this repository. Start with `git status` and `git diff`.
List findings in severity order with file and line references. Check that every keyword
added to src/classify.js has a test that uses it, and that a damage ticket with a
money-back request still routes to refund. If the diff is clean, say "No findings".
Do not propose a rewrite; report what is wrong and why.

Four fields do the work.

  • description is what build reads when it picks a subagent, so it names the job in the words a request would use.
  • mode: subagent lets another agent start it. Without this line, a new custom agent is a primary agent, one you switch to yourself.
  • steps: 10 caps the number of model steps, so a lost review stops instead of wandering.
  • permissions are the ordered rules from Part 4, and the last matching rule wins. The shell rules deny everything, then allow git diff and git status back, so the reviewer can see the change and cannot run anything else, including npm test.

Check that OpenCode sees it

opencode debug agents, from Part 9, prints every agent and its rules as JSON. The grep keeps two lines per agent: its ID and its mode.

opencode debug agents | grep -E '^    "(id|mode)"'

The list includes the built-in agents, in name order, and among them the new one:

    "id": "reviewer",
    "mode": "subagent",

If reviewer is missing, check the folder name: .opencode/agents/, plural. If its mode says primary, check the mode line in the frontmatter.

Give it a change to review

The damage check does not know the word "dented" yet, so "The lid arrived dented" lands in other. Add the keyword by hand. In src/classify.js, find the line that checks for crushed, broken, and "in pieces", and add || t.includes("dented") before its closing parenthesis. With the wording from Part 3, the line becomes this; if your line looks different, add the same check to it.

  if (t.includes("crushed") || t.includes("broken") || t.includes("in pieces") || t.includes("dented")) return "shipping"

AGENTS.md says every keyword gets a test. Add two tests that pin the rule order on the new keyword: damage alone goes to shipping, and damage with a money-back request goes to refund.

cat >> test/classify.test.js <<'EOF'
test("dented lid", () => assert.equal(classify("The lid arrived dented"), "shipping"))
test("dented lid, money back", () => assert.equal(classify("The lid arrived dented and I want my money back"), "refund"))
EOF
npm test
git status --short

The test summary shows fail 0, and pass is two higher than before. The status lists three entries: M marks a tracked file you changed, and ?? marks a folder git does not track yet.

 M src/classify.js
 M test/classify.test.js
?? .opencode/

Hand the review to the subagent

Ask build to delegate. The model is the one you connected in Part 1, google/gemini-4-hydrogen (tested on OpenCode 2.3.0 on November 16, 2026).

opencode run -m google/gemini-4-hydrogen "Use the reviewer subagent to review my current changes."

build calls its subagent tool, names reviewer, and writes a prompt for it. The tool answers at once that the subagent is working in the background, and build says it launched the reviewer. Then the run waits. The reviewer runs git status and git diff in its own child session, reads the files it needs, and goes idle. build then prints the report. Expect file and line references for the new keyword and the two new tests, a check that a dented lid with a money-back request still routes to refund, and either findings in severity order or "No findings". build may also run npm test itself, because the first line of AGENTS.md asks for it.

The tested run printed this report, with one bullet trimmed. Its line numbers and test count are updated to match the opencode/day-10 files. Your model words it differently, and your line numbers depend on your file.

The `reviewer` subagent completed its review with no findings:

- Keyword test coverage: The only keyword added in `src/classify.js:6` is "dented", and
  `test/classify.test.js:17-18` adds tests exercising it ("dented lid" and
  "dented lid, money back").
- Rule order & correctness: `src/classify.js:5` checks "refund" and "money back" before
  `src/classify.js:6` checks damage keywords ("crushed", "broken", "in pieces", "dented"),
  so a damage ticket requesting money back still routes to "refund" (verified in
  `test/classify.test.js:18`).
- Working tree note: `git status` shows an untracked `.opencode/` directory.

Because the `reviewer` subagent is read-only and could not run shell commands, I ran
`npm test` directly: all 9/9 tests passed.

Read the report the way you would read a teammate's review: as claims you can check against the diff. In the tested run, the reviewer also tried to run npm test, and its own rules denied it, as they should.

Check what the reviewer changed

The reviewer had no edit rights, and the check proves it.

git status --short

The output is the same three lines as before the review. Today's win is that report and this unchanged status: a second session read your change and reported on it, and the only changes in the tree are the ones you made. Commit them.

git add .opencode/agents/reviewer.md src/classify.js test/classify.test.js
git commit -m "Add a read-only reviewer subagent and the dented keyword with two tests"

You can stop here. Going deeper explains why this works and where it breaks.

Going deeper

This section is for readers who want the measured cost of a child session, the background rules, the two sets of permissions a child runs under, a second agent that may edit tests, and the cases where delegating costs more than it saves. It assumes you finished Start here in this part and in Parts 1 to 9.

The flaky test that ate the afternoon

A teammate reports that a shipping test "fails sometimes" in CI. You open an OpenCode session in build and ask it to find out why. It reads the classifier, then every file in test/, then the CI log you paste in. It runs npm test again and again, and each run prints Node's full TAP output into the session: a TAP version 13 header, one line per test, and a summary block. You paste a second log, then a third. Every result stays in the conversation.

By mid-afternoon the session has compacted twice. The summary holds three hours of dead ends in the summarizer's words, and the exact failing line from the second log, the one detail the fix depends on, is gone or paraphrased. You still have no fix, and the window is mostly full of the search for one. This is a scenario, not a recorded run. Ticket Triage's tests are deterministic, so the scenario never finds a flaky cause; it is here to show where the reading lands, not to solve a real flaky test.

Scene: a frustrated developer at a desk in mid-afternoon, scratching their head at a session that has compacted twice and still has no fix for a flaky test

The scene shows the moment the problem becomes visible: a terminal full of repeated test output and pasted logs, no fix in sight, and a session that has already summarized away the line that mattered.

The model is not the problem, and neither are the compaction settings. The search and the fix shared one window. A search reads a lot and keeps little; a fix needs a few exact lines and room to work. OpenCode subagents put the search in a child session that starts fresh and returns only a report. This article shows how they work, what they cost, and how to write your own.

What a child session receives

The OpenCode agents page says it in one line: "Subagents run with fresh context in their own child sessions." A child does not get the parent's conversation. It starts from its own opening, makes its own tool calls, and fills its own window. The parent receives a report when the child goes idle, and the file reads, the TAP output, and the dead ends stay in the child.

Two ways to hunt a flaky test: one session that reads, reruns tests, pastes logs, and compacts twice, beside a parent that writes a complete prompt for a child, which searches with fresh context and returns file and line references so the parent keeps room for the fix

Every OpenCode request has a fixed opening (system prompt, tool definitions, instruction files) followed by the conversation. A subagent leaves the parent's opening alone and keeps its conversation short: the parent's history gains one subagent tool call and a report, not every file and log line behind the report. Compaction protects the conversation by shrinking it. A subagent protects it by moving work out of it.

The child pays its own opening, though, and the author measured it on OpenCode 2.3.0. The test put one unique line in the project's AGENTS.md, "The project codename is BLUE-HERON-7," and denied read on *AGENTS.md, all grep, and all shell, so no tool could reveal it. Then it asked build to start the built-in general subagent and ask for the codename. The child answered BLUE-HERON-7 with no tool calls, so the line reached it through its instructions. Its single request sent 16,653 input tokens. The run used google/gemini-3.5-flash-lite, and the parent figure below came from google/gemini-3.5-flash, a model Google's models page no longer lists. The floor differs from model to model, but every child pays its own.

Infographic: a child saves history, not the floor. A general child on OpenCode 2.3.0 sent 16,653 input tokens with no tool calls, close to a parent's 18,247-token first request, because it received the system prompt, tool definitions, and AGENTS.md

A parent session's first request in an earlier measured run sent 18,247 input tokens; the general child that answered a one-line question sent 16,653, because it too received a system prompt, the tool definitions, and AGENTS.md. What the child saves is everything the parent would otherwise pile up: file reads, test output, and dead ends. Both runs had the author's 56 personal skills in view, which Part 6 shows add about 12,000 tokens to every request. In a clean home folder on google/gemini-4-hydrogen, the Start here parent sent 5,935 tokens on its first request and the reviewer child sent 5,233 on its first. The floor is smaller, and every child still pays its own.

A subagent saves the parent's history; it does not save the fixed floor. It also means a general child receives your AGENTS.md, so every line you trim from that file is a line every child stops paying for.

The fresh start has one more consequence. The subagent tool takes an agent ID, a short description, and "a complete prompt." The parent writes that prompt, and it is all the child knows. A parent that delegates "check the thing we discussed" sends a child into the repository with no idea what was discussed. When you ask build to delegate, name the files, the question, and the shape of the answer you want back.

The two built-in subagents

OpenCode ships four visible agents. Two are primary agents you work in, and two are subagents the model can launch. The tool docs draw the boundary: "Only subagent-mode agents can be used."

Table: Agent, Mode, What it may do, When to use it. Rows: build; plan; general; explore.

The four built-in agents differ in whether a parent can launch them and how much they can do once running. Agent names each one, Mode says primary or subagent, "What it may do" summarizes its built-in permissions as opencode debug agents prints them, and "When to use it" gives its purpose from the agents page.

  • build is primary, may do everything in the base policy plus ask questions, and has no browser. It cannot be a child, but it launches children, and its own subagent rules decide which.
  • plan is primary, may do everything in the base policy including shell, and edits only plan files under ~/.opencode/plan/. Its rules do not deny subagent, so a planning session can send explore to read for it.
  • general is a subagent with broad tools, including edits and shell, but no questions and no children of its own. It is a second build that cannot ask you anything, so a rule about what an agent must not touch belongs in permissions, not in an AGENTS.md line that says "ask first."
  • explore is a subagent limited to shell, read, grep, glob, webfetch, websearch, and external_directory, built for searching code or the web. Its rules start with a *:* deny and allow reading actions back, but its shell is still allowed, so "read-only" depends on the prompt for shell commands. A small model such as anthropic/claude-haiku-5-5 suits it, because the parent checks what it finds.

The hidden compaction, summary, and title agents are primary agents that "perform maintenance and cannot be selected directly."

Background subagents by default in OpenCode 2.3.0

OpenCode 2.3.0 shipped on November 13, 2026, under the changelog title "Background Subagents by Default," and the GitHub release says the same. The tool docs describe it: "Subagents always run in the background. The call returns immediately with a sessionID, and the parent receives a <subagent> message when the child goes idle, and again after each later round of work, so it can keep working or end its turn without waiting."

In the author's 2.3.0 tests, the prompt "Use the explore subagent to find which file defines the ticket priority rules" made the subagent tool return at once with this text.

The subagent is working in the background (sessionID: ...). You will receive a <subagent> message when it goes idle

The parent then ended its turn. Because the test ran headless through opencode run, the JSON event stream showed run emit a background_wait event and resume the parent when the child went idle.

Sequence of a background subagent: the parent calls the subagent tool with an agent ID, description, and complete prompt, the tool returns a sessionID at once, the child works in its own window, a subagent report arrives when it goes idle, and a follow-up with the same sessionID joins the same child

Four rules shape what you can do with a running child.

  • The parent is free while the child works. It can keep working or end its turn. The commands page says the same of a command that runs in a child: "The parent stays available and keeps its agent and model."
  • Reports arrive more than once. A <subagent> message arrives when the child goes idle "and again after each later round of work."
  • A follow-up continues the same child. "Pass the returned sessionID to continue that same child conversation." If a report is thin, follow up instead of starting a new child; the old one still has its reads.
  • Nesting stops at one level. "The default nesting depth is one," so a child cannot start its own child. The knob is experimental.subagent_depth, and the configuration page warns that experimental settings "may change, break, or be removed in any release without notice."

The keybinds page lists session.child.first (default down, "Toggle subagent picker") and session.parent (up, "Go to parent session"), and in the picker Ctrl+D is listed as "Interrupt subagent." Remember that last one: a child that has wandered off costs tokens every step until it goes idle.

Gotcha: background means parallel. If build starts three children for three searches, three sessions run at once, each on its own model and each billed.

Two sets of rules: who may launch, and what the child may do

A subagent involves two permission questions, and the permissions page states the key fact directly: "A custom subagent uses its own permissions, not a subset of its parent's permissions."

How a child's permissions resolve: the parent's subagent rules decide whether the child starts at all; once it runs, project and global rules come first and the child's own rules are appended, so the last matching rule, often the child's, decides

  • The parent's subagent rules decide whether a child may start. The resource is the target agent ID. The base policy allows every action, so build may launch any subagent until you deny subagent for * and allow the IDs you want.
  • The child's own rules decide what it may do once it runs. A child does not inherit the parent's restrictions or its freedoms; explore runs with explore's list even when build launched it.
  • Project and global rules come first for every agent. "Agent rules are appended after global rules," and the last matching rule wins, so a child rule that matches the same action and resource beats your project rule.

The last bullet is where projects get surprised. In one of the author's 2.3.0 tests, with every action denied on *.env*, every grep denied, and --auto on, the model started explore, whose built-in list ends its read rules with read *.env ask. The ask came after the project's deny, replaced it, and --auto approved it. The subagent turned a project deny into a question.

The author then tested giving explore the deny itself under agents.explore.permissions. With that in place, inside the child read .env failed with "Permission denied: read" and shell cat .env failed with "Permission denied: shell." Then the child called grep with pattern: TRIAGE_TOKEN and path: .env. The grep resource is the regular expression, not the path, so no path rule matched, and the parent reported the value. The per-agent deny is not a fix for the leak: it closes the read tool, not grep, and not the shell, because a shell command can print a file without naming it.

Infographic: two rule sets govern every child. The parent's subagent rules decide who may launch, the child's own rules decide what it may do and are not a subset of the parent's, project and global rules apply first, and the last match wins

A child raises two questions: whether it may start, which the parent's rules decide, and what it may do, which its own appended rules decide. A child's ask can override a project deny, and a child's own deny can close the read route.

Per-agent rules are necessary for subagents, and they still cannot stop that grep. A secret belongs outside the project directory; rules make the wrong path harder, not impossible.

The reviewer, field by field

Start here created .opencode/agents/reviewer.md. Global agents live in ~/.config/opencode/agents/<name>.md, and a nested path such as .opencode/agents/team/reviewer.md becomes the ID team/reviewer.

Shell patterns ending in * also match the bare command, so git diff with no arguments is allowed too. A compound command such as git status && git diff is split, and each part is checked against the rules, which is why the Start here reviewer could run both at once. In that run, the reviewer's own shell deny also refused its npm test call with "Permission denied: shell," although the project's rules allow npm test for build. The reviewer still receives AGENTS.md: its body replaces only the provider's base prompt, and "Project instructions, skills, references, and other instruction sources are still added."

Two frontmatter fields deserve a second look. Forget mode: subagent and the agent becomes a primary agent that you can switch to with Shift+Tab but that the model cannot launch. Leave out model and the child inherits the parent session's model; giving the reviewer a different model later is a good upgrade, because the session that wrote the code is a poor judge of it. Two more fields exist that people misread. steps caps the loop, and "on the final step, OpenCode removes tools and asks the model to summarize in text," so you still get a report. hidden removes an agent from listings, but "This controls visibility, not security. Use permissions to restrict behavior."

If you learned V1: maxSteps became steps, prompt became system, and the permission map with task became the ordered permissions list with the subagent action, as the migration guide lists. V1 frontmatter is still "translated automatically," one format per file.

Write a tester that cannot touch source

The tester is the agent that may change something, so its rules matter more. It may edit only files under test/ and may run only npm test.

$EDITOR .opencode/agents/tester.md

The permission list follows the same shape as the reviewer's: a broad deny first, then the exceptions.

---
description: Writes focused tests under test/ and runs npm test. Cannot edit source files.  # ①
mode: subagent
steps: 15  # ②
permissions:
  - action: edit  # ③
    resource: "*"
    effect: deny
  - action: edit
    resource: "test/*"  # ④
    effect: allow
  - action: shell  # ⑤
    resource: "*"
    effect: deny
  - action: shell
    resource: "npm test *"  # ⑥
    effect: allow
---

Write focused tests under test/ with Node's built-in runner and node:assert/strict.
Run npm test after every change. Report the exact summary lines from the test output
(tests, pass, fail) and the name of every failing test. Never change a test's expected
value to make it pass; if a test fails, report it and stop. <!-- ⑦ -->

① The description tells the parent that this agent writes tests and cannot edit source files.

② steps: 15 gives the tester more room than the reviewer, because it edits files and reruns tests.

③ Every edit is denied first.

④ The test/* allow comes after the deny and wins for any path under test/, nested ones included, because * also matches /.

⑤ The shell deny keeps the tester from inheriting the project's shell * ask, so a background child never stalls on a prompt.

⑥ npm test is the one command allowed back.

⑦ The last prompt line states the intent from Part 7's experiment: report a failing test instead of rewriting its expected value.

Note: The full extracted listing at code/opencode/part-10-subagents/listings/02-tester-agent.md holds the complete .opencode/agents/tester.md file.

In permission matching, * covers "zero or more characters, including /," and the edit action covers the edit, write, and patch tools together. A deny on every other shell command matters for a background child: an ask would wait for you while you are busy elsewhere, and a deny returns at once with Permission denied: shell, which the child can put in its report. The body's last line cannot stop a bad test edit, because no rule can tell a good edit from a bad one, but it states the intent, and the reviewer checks for it.

Notice what the tester cannot do: touch src/classify.js. If a new test fails, the fix comes back to the parent, where the decision about rule order belongs.

Wire the agents into opencode.jsonc

The two Markdown files are enough for OpenCode to find the agents. Two more decisions belong in opencode.jsonc: which children build may launch, and the per-agent .env deny for explore. The model IDs below are current as of November 16, 2026; opencode models lists what your providers offer today.

{
  "$schema": "https://opencode.ai/config.json",

  "model": "anthropic/claude-sonnet-5-5",

  "agents": {
    // build may launch the read-only explorer and the two project agents, nothing else.
    "build": {
      "permissions": [
        { "action": "subagent", "resource": "*", "effect": "deny" },  // ①
        { "action": "subagent", "resource": "explore", "effect": "allow" },  // ②
        { "action": "subagent", "resource": "reviewer", "effect": "allow" },
        { "action": "subagent", "resource": "tester", "effect": "allow" },
      ],
    },
    "plan": { "model": "anthropic/claude-sonnet-5-5#high" },
    // explore's built-in .env ask comes after project rules; repeat the deny after it.
    "explore": {
      "model": "anthropic/claude-haiku-5-5",
      "permissions": [
        { "action": "*", "resource": "*.env*", "effect": "deny" },  // ③
        { "action": "*", "resource": "*.env.example", "effect": "allow" },
      ],
    },
    "title": { "model": "anthropic/claude-haiku-5-5" },
    "compaction": { "model": "anthropic/claude-sonnet-5-5" },
  },

  "compaction": {  // ④
    "auto": true,
    "keep": { "tokens": 20000 },
    "buffer": "20%",
  },

  "references": {  // ⑤
    "policies": {
      "path": "../support-policies",
      "description": "Support team routing policies. Use when deciding which category a ticket belongs in.",
    },
  },

  "permissions": [  // ⑥
    { "action": "external_directory", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "shell", "resource": "npm test *", "effect": "allow" },
    { "action": "shell", "resource": "git push *", "effect": "deny" },
    { "action": "*", "resource": "*.env*", "effect": "deny" },
    { "action": "*", "resource": "*.env.example", "effect": "allow" },
  ],
}

① The build override starts by denying every subagent, so general and any agent you add later are off the list by default.

② The allows that follow reopen explore, reviewer, and tester; they come later, so they win for those three IDs.

③ explore gets the per-agent .env deny, appended after its built-in .env ask so that the deny is the last match. It closes the read tool, not grep.

④ The compaction block from Part 7 is unchanged.

⑤ The policies reference from Part 5 is unchanged.

⑥ Part 4's eight project permission rules are unchanged, and each agent's own rules append after them.

Note: The full extracted listing at code/opencode/part-10-subagents/listings/03-opencode-config-subagents.jsonc holds the complete opencode.jsonc from this step.

The build entry uses the documented override, "Override a built-in by using the same ID." Denying general is a choice for this repository: general can edit and run shell, and the tester already covers the edits worth delegating. Check that OpenCode sees the result.

opencode debug config
opencode debug agents

opencode debug agents should list reviewer and tester with mode subagent, and the end of explore's rule list should show the two .env rules after its built-in .env ask rules. If a custom agent is missing, check the folder name: .opencode/agents/, plural.

Run the bug hunt through children

Now replay the opening's search with the parent doing none of the reading. Ticket Triage has no flaky test, so the children will not find one; the replay shows where the reading goes. Start a fresh session in build, so the parent's history begins empty, and send the search to explore with a complete prompt and a limit on the answer.

Use the explore subagent. Prompt for it: "In this repository, find every test in test/ that expects shipping, every place a shipping keyword list is defined or changed, and any value two tests share. Report file and line for each, in at most 15 lines. Do not paste file contents."

When the <subagent> report arrives, read it the way the parent will: file and line references you can check, not a verdict you have to trust. Next, hand the repetitive part to tester, so three runs of TAP output land in a child and three summary lines land in the parent.

Use the tester subagent. Prompt for it: "Run npm test three times. For each run, report the tests, pass, and fail counts and the name of any failing test. Then add two tests to test/classify.test.js: 'The lid arrived dented' expects shipping, and 'The lid arrived dented and I want my money back' expects refund. Run npm test again and report the result."

The two new tests pin the rule order: damage routes to shipping unless the customer also asks for money back. If the second one fails, you have found a real bug, and the fix belongs to the parent. If Start here already added these two tests, ask the tester for two other damage sentences instead. Then ask for a review in a separate child, and run the gate yourself in the parent.

Use the reviewer subagent to review my current changes.
!npm test

The bug hunt run through children: the parent sends explore to find shipping tests and keyword lists, tester to run npm test three times and add two dented-lid tests, and reviewer to read git diff with fresh eyes, each returning a short report, before the parent runs npm test itself

The reviewer did not write the tests and did not read the parent's reasoning. It sees the change the way a teammate does, through git diff. Afterward, check what each session cost. The author's 2.3.0 tests found that opencode session export prints a session as JSON with an info object holding the agent, model, cost, tokens, outcome, and parentID.

opencode session list
opencode session export ses_parent | jq '.info'
opencode session export ses_child | jq '.info'

The parent should be smaller than a session that did the same search itself. The total across parent and children may not be.

Gotcha: read the child's outcome with care. In the author's 2.3.0 test, an explore child on a local ollama/llama3.2:latest model globbed for **/src/main.ts, a file the project does not have, matched nothing twice, wrote a tool call as plain text for a tool that does not exist, and stopped. Its session still recorded "outcome": "succeeded". The parent, on google/gemini-3.5-flash, then did the search itself and answered src/classify.js. "Succeeded" meant the child finished, not that it found anything. A report that is wrong but confident is harder to catch.

When a subagent costs more than it saves

The child's fresh context is the whole benefit, and it is also the cost. At 16,653 input tokens for a general child that made no tool calls, a child costs about as much to start as a new session does. In the hunt above, three children each pay roughly that floor on their first request and resend their opening on every later step of their own loops. On a three-file service, the reading the parent avoided may be only a few thousand tokens, so delegating everything can cost more in total. On a real repository, where one search reads dozens of files that the parent would otherwise carry through every later step, the trade turns.

Table: Situation, Better choice, Why. Rows: A search across many files whose raw output you will not need again; A two-line answer the parent needs for its very next step; Long, repetitive output such as several test runs; A review that should not share the author's reasoning; Several…

Seven common situations each get a recommended choice. The Situation column describes the task in front of the parent, "Better choice" says whether to delegate and to which child, and Why names the cost or benefit that decides it.

  • A search across many files whose raw output you will not need again goes to an explore child, because the reading stays there and the parent gets only file and line references.
  • A two-line answer the parent needs for its very next step stays inline with @file or a direct question, because paying a floor of about 16,000 tokens to save a few hundred is a loss.
  • Long, repetitive output such as several test runs goes to a tester child, which absorbs the output and returns the summary lines.
  • A review that should not share the author's reasoning goes to a reviewer child, where fresh context is the point: a reviewer that never saw the argument for a change cannot be persuaded by it.
  • Several independent searches at once can run as a few children in parallel, remembering that each is billed its own floor and its own steps; opencode stats --models --cost shows where the tokens went.
  • A thin report from a child that just finished calls for a follow-up to the same sessionID, since that child still has its reads and a new one starts from zero.
  • An open-ended search on a small local model should move to a capable model, because the local explore in the 2.3.0 test failed and the parent redid the search at hosted prices.

Decision flow for delegation: delegate large output you will not need again to explore or tester, stay inline for a two-line answer, use a reviewer child when fresh context is the point, follow up on a thin report with the same sessionID, and keep searches off small local models

Infographic: delegate the bulk, keep the answers. Delegate wide searches, repeated test runs, and fresh-eyes reviews; keep short answers in the parent; follow up on a thin report with the same sessionID; and watch for a small local model that quietly fails

The decision has four parts: what to hand to a child, what to keep in the parent, what to do with a thin report, and why the model behind a child matters as much as the choice to delegate.

If you already use Claude Code: .claude/agents/<name>.md maps to .opencode/agents/<name>.md, with the same frontmatter-plus-body shape, as Claude Code's subagents page shows. Three habits misfire. OpenCode restricts a subagent with an ordered permissions list, not a tools list, and agent rules come after your project's. Its model takes a full provider/model#variant, where Claude Code takes sonnet, opus, haiku, fable, a full model ID such as claude-opus-5-5, or inherit. And OpenCode stops nesting at one level by default, while since Claude Code 2.1.219 a Claude Code subagent can start subagents of its own, up to three levels below the main conversation. The two explorers agree on the model: Claude Code's Explore has used the parent conversation's model since Claude Code 2.1.198, and OpenCode's explore reads on your session model until you set agents.explore.model. In the author's 2.3.0 test, the general child received AGENTS.md and paid for it. Timing is not a difference: both tools start subagents in the background, and in OpenCode 2.3.0 every child does.

Do this today

Everyone

  • Repeat the review. With a small uncommitted change in Ticket Triage, confirm reviewer is listed, delegate the review, and check that the tree did not change.

    opencode debug agents | grep -E '^    "(id|mode)"'
    opencode run -m google/gemini-4-hydrogen "Use the reviewer subagent to review my current changes."
    git status --short
    
  • Start one habit: delegate the review, keep the decision. Before each commit this week, ask build to use the reviewer, then read the report against git diff yourself.

If you read Going deeper

  • Write one read-only reviewer. Copy the reviewer file, change the body's checks to the two things your team's reviews always catch, and confirm it with opencode debug agents.

  • Run it on your current diff. Keep a small uncommitted change, open the TUI in build, and ask: "Use the reviewer subagent to review my current changes."

  • Compare the parent's tokens before and after. Export the parent session before you delegate and after the report arrives, and compare the info blocks. Export the child too, and check its agent, model, cost, and parentID.

  • Decide which children build may launch. Deny subagent for * in agents.build.permissions, allow the agents you use, and commit the agents, the config, and any tests the tester added.

    git add .opencode/agents opencode.jsonc test/classify.test.js
    git commit -m "Add reviewer and tester subagents and dented-lid tests; limit build's subagents"
    

Send the reading away

The flaky-test afternoon did not fail because the model was weak or the compaction settings were wrong. It failed because a search that reads everything and a fix that needs three exact lines were fighting over one window, and the search always wins that fight.

OpenCode subagents end the fight by giving the search its own session. The child reads, reruns, and wanders; the parent gets a report and keeps its room for the decision. The price is a fresh opening for every child, close to what a new session costs, so delegation pays when it keeps a lot out of the parent or when fresh eyes are the point, and it loses when the answer is two lines long.

Send the reading away. Keep the thinking at home.


This is Part 10 of "OpenCode, Day-to-Day," a 17-part guide to using OpenCode V2 as a daily, provider-neutral coding agent.