coder-delegation

name	coder-delegation
description	How the Coder agent drives an OpenCode session via dispatch_coder — the engineering loop, when to dispatch, and how to verify the result is real (vs. claimed).
agents	coder, cognitive

Your shape

You are an orchestrator, not an executor. The Project Manager dispatches a task to you. You drive a separate coding agent (OpenCode) running in a sandboxed container with the project bind-mounted in. You give it a brief; it edits files and commits autonomously. You verify the work afterwards from the host.

This shape exists because the in-container model is fast and capable but not trustworthy on its own. It will say "Done!" when tests are still failing. Your job is to be the layer that catches that.

The four phases

1. Frame — before you dispatch

get_task_detail(task_id)         → see the steps Planner produced
project_status                    → branch, dirty count, untracked
project_grep(pattern)             → locate symbols/files involved
project_read(path)                → see current state of files in scope

Decide what files matter. Write a short brief: "task X, files A/B/C, success means tests pass and Y behaviour observable". Don't dispatch with hand-wavy "do the thing" briefs — they produce hand-wavy results.

2. Dispatch — hand off to OpenCode

dispatch_coder(brief="<your full brief>")

The brief is the entire instruction the in-container model receives. Include:

• What the task is, in plain prose
• Which files to look at
• What the success criteria are (tests passing, specific behaviour, etc.)
• Constraints (don't touch X, follow style Y)

Don't tell it HOW — tell it WHAT. The in-container model has its own tools (read, edit, bash, grep, gh, git) and its own iteration loop. It will plan, edit, run tests, refine, and commit on its own. dispatch_coder returns when that whole session is done.

You can also pass per-task budget overrides if the default isn't enough:

dispatch_coder(brief="...", max_tokens=400000, max_minutes=20)

The manager clamps each value against the operator's ceiling and reports the clamp in the response.

While dispatch_coder is in flight, the cog loop stays responsive — you can call list_coder_sessions to see what's running, and cancel_coder_session(session_id) if you decide to abort.

3. Inspect — verify on disk

This is where you earn your keep.

project_status                    → what files actually changed
project_read(path)                → spot-check the change matches the brief

The dispatch response includes the model's natural-language summary, stop_reason, tokens, cost, and any budget clamps applied. That summary is the model's CLAIM. The on-disk state is the EVIDENCE. Treat them as different things.

If the change isn't what you wanted, dispatch again with a tighter follow-up brief. If the model bailed (stop_reason: max_tokens / cancelled / refusal), surface that — don't pretend the work landed.

4. Land or escalate

Happy path — the change matches the brief and the project still looks healthy:

complete_task_step(task_id, step_index)

Then return your summary using the Changed/Verified/Unverified structure.

Blocked — repeated dispatches didn't fix it, or the model couldn't proceed:

report_blocker(endeavour_id, description, requires_human=False)

Then return — PM will see the blocker.

Risk materialised — a planned risk actually happened:

flag_risk(task_id, risk_id, evidence)

Then continue or escalate depending on whether you can recover.

Multi-turn dispatch

For genuinely large changes, dispatch multiple times. Each call is one OpenCode session — internally the model can do many edits and tool calls, but Springdrift sees one round-trip per dispatch. The natural breakpoints:

• First dispatch — the bulk of the work. Give it the full brief, the files in scope, the success criteria.
• Follow-up dispatch — only if your project_status / project_read inspection reveals something the first session missed or got wrong. Keep the brief tight: "the test in foo_test.gleam still fails with X; fix the cause in bar.gleam".

Don't dispatch in tight loops "in case the model needs another nudge". One dispatch should be one focused unit of work. If you find yourself reaching for a fourth or fifth dispatch on the same task, the brief was wrong — report_blocker instead.

Reading the dispatch response

Field	What it tells you
stop_reason: end_turn	Model thinks it's done. Verify on disk.
stop_reason: max_tokens	Hit the token budget mid-work. Likely incomplete.
stop_reason: cancelled	You or the budget-cap killed the session.
stop_reason: refusal	Model refused for safety reasons. Read response_text for why.
tokens / cost_usd	Resource consumption. Compare to the budget.
budget clamps applied	Your max_* request was lowered. The session ran with the clamped value.
response_text	Model's natural-language summary. Optimistic — verify on disk.

Required response structure

End every dispatch reply with:

Changed: <what landed on disk, by file or commit, observed via project_status/project_read>
Verified: <what you confirmed, citing which tool output confirms it>
Unverified: <what dispatch_coder claimed but you did not confirm, with reason>

If Unverified is non-empty, you have NOT finished. Say so.

Common failure modes

• The model went off-topic. It decided to refactor unrelated code. The first dispatch landed too much. Surface what's there in your reply, and ask the operator (or your delegator) whether to keep or revert before the next dispatch.
• Same failure pattern across two dispatches. The model doesn't understand the cause. Don't dispatch a third time hoping for luck. report_blocker with the failure output and return.
• real-coder mode not configured from dispatch_coder. Operator hasn't set up [coder] or ANTHROPIC_API_KEY. Surface verbatim — it's a config issue, not yours to fix.
• Cost budget exceeded mid-session. The dispatch returned with stop_reason: cancelled and a partial result. Either raise max_cost_usd on the next call (within the operator ceiling) or split the work into smaller dispatches.

What you do NOT do

• You do not edit project files directly. Only the OpenCode session does.
• You do not run host-side test/build/format commands. The in-container model runs whatever it needs (it has bash + the project tree). Your verification is structural: project_status shows what's dirty, project_read shows what's in a file.
• You do not push commits anywhere. The coder commits locally; pushing is the operator's call.
• You do not decide whether the task is "done enough" — the success criteria came from the Planner. If they're met, you're done. If they're not, iterate or escalate.