feat(agents): route plan + build through task tool for cheap-mid-tier execution by iceglober · Pull Request #127 · iceglober/harness-opencode

iceglober · 2026-04-26T20:20:26Z

PRIME delegates Phase 3 execution to @build subagent

Goal

Move PRIME's Phase 3 (plan execution — file edits, per-change lint/tests, acceptance-box checking) off Opus and onto the @build subagent (currently Sonnet mid tier, swappable to Kimi K2 / GLM-4.6 / Haiku via the user's tier mapping). This is the single biggest cost win available in the five-phase workflow: Phase 3 is the highest-volume token consumer, and its work is mechanical — Sonnet-class models handle it at parity with Opus.

To make delegation actually work, @build must gain task-tool visibility. OpenCode supports three agent modes (primary, subagent, all) — "all" is the correct setting, not "subagent": it keeps Tab-cycling + top-level @ invocation intact AND adds task-tool picker visibility. The local commit 75448b9 used mode: "subagent" for @plan, which unnecessarily removed Tab and top-level access. This plan amends that commit to use mode: "all" for @plan, and applies mode: "all" to @build as part of the new Phase 3 delegation work. Commit is local-only, hasn't been pushed — amend is safe per PRIME's amend rules (user explicitly requested; HEAD is mine; not pushed).

Two commits total after this plan:

Amended 75448b9 — @plan mode "subagent" → "all"; plan.md wording reverted back to acknowledge user can still invoke directly AND via task tool; test assertions updated from === "subagent" to !== "primary" (or explicit === "all").
New commit — PRIME Phase 3 rewrite + @build mode → "all" + @build prompt reshape + Context Firewall row + autopilot.md line 76 update + new regression tests.

PRIME keeps ownership of Phase 0 bootstrap, Phase 1 intent triage, Phase 1.5 framing + user interaction, Phase 2 grounding + @plan delegation, Phase 4 QA-reviewer selection/dispatch, and Phase 5 handoff.

Constraints

Zero user-filesystem-writes invariant (root rule 1) — plan only edits files inside src/, test/. No writes to ~/.config/opencode/ or ~/.claude/.
Prompt markdown files are read at runtime via readFileSync; never add static .md imports (root rule 7).
No forbidden paths (~/.claude, home/.claude, ~/.config/opencode, home/.config/opencode) may appear in any edited prompt — CI guard at test/prompts-no-dangling-paths.test.ts fails the build otherwise (root rule 8).
BUILD_PERMISSIONS bash rules untouched — @build still needs general bash + git commit for Phase 3 checkpointing.
mode: "all" preserves BOTH top-level invocation (Tab + @) AND task-tool dispatchability for @plan and @build. No user-visible regression (unlike the mode: "subagent" approach the amendment is correcting).
Phase 2 grounding stays in PRIME (user rejected option D — separate grounding agent — due to latency concerns).
Tier mapping for @build stays at mid (Sonnet-class); nothing in tier fixtures changes.
Amend of 75448b9 is legal per PRIME's amend rules: (a) user explicitly requested, (b) HEAD is mine (Austin Hess <austin@kayn.ai>), (c) not pushed to remote (verified via git status showing "ahead of origin/main by 1 commit").

Acceptance criteria

Part 1 — amend commit 75448b9 (@plan fix correction)

src/agents/index.ts plan entry: mode: "all" (was "subagent" in 75448b9). Other fields unchanged.
src/agents/prompts/plan.md line 3: wording revised to reflect that @plan can be invoked directly by the user OR via the task tool — both work now. Suggested new first sentence: "You can be invoked directly by the user (Tab / @plan) or delegated to by PRIME via the task tool. Either way, your output contract is identical: a written plan in the repo-shared plan directory." Rest of line 3 stays (the "when PRIME delegates, trust the brief..." portion).
test/agents.test.ts regression tests updated for mode: "all":
- plan agent is mode:subagent (task-tool-dispatchable) → renamed plan agent is task-tool-dispatchable (not mode:primary). Assertion changes from mode === "subagent" to mode !== "primary" (accepts either "subagent" or "all").
- pilot-planner description does not collide with plan description — unchanged, still valid.
test/agents.test.ts mode-split tests (has 2 primary / has the 12 subagents) need restructuring: with mode: "all", agents aren't cleanly primary-or-subagent. Two options: (a) change to "is task-tool-dispatchable" and "is top-level-invocable" checks, or (b) keep the mode-split tests but branch on mode === "primary" || mode === "all" for primary-capable, and mode === "subagent" || mode === "all" for subagent-capable. Pick (b) — minimal churn, explicit about dual-capability.
Amend the changeset file .changeset/fix-prime-dispatch-to-plan-agent.md: update the description to reflect mode: "all" (not "subagent"), and mention that top-level @plan invocation is preserved (no user-visible regression).
Amended commit message: keep the original framing but correct the mode value. Preserve the body structure.

Part 2 — new commit (Phase 3 delegation + @build → mode:all)

Part 3 — verification (both parts together)

bun test passes (all existing tests plus the new guards).
bun run typecheck passes.
bun run build succeeds (dist output refreshed).
git log --oneline origin/main..HEAD shows exactly 2 commits: the amended 75448b9 (different SHA after amend) and the new Phase 3 commit.

File-level changes

src/agents/index.ts

Change (Part 1 — amended commit ccd1761): plan entry mode flipped "primary" → "all" (was "subagent" in the original 75448b9; corrected during amend). Other fields unchanged.
Change (Part 2 — new commit 170b800): build entry mode flipped "primary" → "all". BUILD_PERMISSIONS block otherwise untouched; question: "allow" permission stays (reversed from the original plan's "deny" decision — rationale in AC items 50 and in the Open questions resolution below).
Why: mode: "all" is how OpenCode surfaces an agent to BOTH primary-mode user invocation (Tab + @name) AND the task-tool subagent picker. That's the correct fix for both @plan and @build — preserves top-level invocation while adding task-tool visibility. The earlier mode: "subagent" approach would have removed Tab/top-level access unnecessarily.
Risk: low. No runtime wiring depends on either agent being mode: "primary" specifically. BUILD_PERMISSIONS and PLAN_PERMISSIONS blocks unchanged.

src/agents/prompts/pilot-planner.md

Change (Part 1 — amended commit ccd1761): frontmatter description: rewritten to remove the "Interactive planner for the pilot subsystem." prefix that collided with @plan's "Interactive planner. Orchestrates gap analysis..." — the collision was misleading PRIME's task-tool picker into dispatching to pilot-planner when users wanted a normal plan. New description starts with "Pilot-subsystem YAML plan generator."
Why: Even after @plan became task-tool-visible (via mode: "all"), the description collision could still mislead the picker. Sharpening pilot-planner's description makes the disambiguation unambiguous.
Risk: none. Pure description wording change — permissions, mode, prompt body all unchanged.

src/agents/prompts/plan.md

Change (Part 1 — amended commit ccd1761): first sentence on line 3 revised from "You are always invoked via the task tool..." (the stale wording from the earlier mode: "subagent" version) to "You can be invoked directly by the user (Tab / @plan) or delegated to by PRIME via the task tool." — reflects the dual invocation shape enabled by mode: "all".
Why: @plan's prompt body had briefly asserted subagent-only invocation during the original 75448b9 commit; after the amend to mode: "all", that wording became incorrect. This revision matches the actual behavior.
Risk: none. Sentence-level prompt edit; no behavioral claim added or removed.

src/agents/prompts/prime.md

Change (Part 2 — new commit 170b800): Phase 3 (lines 261-285 in base) rewritten so PRIME delegates execution to @build via the task tool. New Phase 3 body instructs PRIME to pass the absolute plan path to @build, verify git diff --stat on return matches the plan's ## File-level changes, handle STOP payloads (three classes: cosmetic/approach/scope-expansion), verify pre-existing-failure logging, then proceed to Phase 4. Trivial-work carve-out (no-plan requests): PRIME still edits directly.
Change (Part 2): Context Firewall table gains one new row (PRE-pended, not appended): | Phase 3 plan execution (any multi-file edit against a plan) | @build | Phase 3 is mechanical — Sonnet/Kimi/GLM can do it; Opus time is expensive |. Existing rows unchanged.
Change (Part 2): Subagent reference list gains a @build bullet directly after the @plan bullet: - @build — executes a written plan file-by-file. Runs per-file lint/tests inline, checks acceptance boxes, commits locally. Returns a structured payload with commit SHAs, plan mutations, and any STOP conditions. PRIME delegates Phase 3 execution here.
Why: Phase 3 is where the Opus token cost is concentrated. Delegating to @build (mid-tier, swappable to Kimi/GLM/Haiku) is the single biggest cost reduction achievable without compromising correctness. The Context Firewall row makes delegation mandatory so future prompt edits can't drift back to inline execution. The subagent-reference bullet ensures PRIME's picker has the agent described in prompt context.
Risk: medium. Phase 3 behavior changes shape. Mitigations: (1) STOP-class rubric preserved from the old Phase 3's "plan is wrong" section so correctness-critical stop conditions remain; (2) PRIME re-validates git diff --stat on @build's return so silent scope drift is caught; (3) regression guard prime prompt delegates Phase 3 to @build fails the build if the old inline-execution text sneaks back.

src/agents/prompts/build.md

Change (Part 2): "How to ask the user" section (lines 3-7 in base) rewritten. New text is shape-aware: when @build is invoked as a subagent by PRIME, the question tool is forbidden — @build STOPs with a structured blocker payload PRIME relays. When @build is invoked top-level by the user (@build <plan-path>), the question tool is allowed (same rules as other primaries). Workflow-mechanics exception preserved verbatim.
Change (Part 2): Section 2 renamed "Confirm understanding" → "Prepare the return summary". Body reframed: prepare a brief summary (file count, acceptance criteria, unknowns) for the return payload. Subagent invocations: PRIME relays; no direct user narration. Top-level invocations: print summary to chat.
Change (Part 2): Section 4 "Final verification" body trimmed. Old: "Run the full test suite. It must pass. Run lint. It must pass." Removed. New body: all AC boxes [x], tsc_check clean on edited files, git diff --stat matches plan's File-level changes. Per-file tests during section 3 are expected; full-suite run belongs to PRIME's Phase 4.
Change (Part 2): Section 5 replaced wholesale. Old "QA review" (which instructed @build to delegate to @qa-reviewer) removed. New "Return payload" section specifies what @build returns to its caller: (a) plan path, (b) commit SHAs, (c) plan mutations absorbed silently, (d) unusual conditions (pre-existing failures logged to plan's Open questions, scope expansions, STOP conditions). STOP payloads have a structured format so PRIME recognizes them as blockers.
Change (Part 2): Sections 1 (Read and validate the plan) and 3 (Execute task by task) untouched. Hard rules untouched.
Why: Moving Phase 3 off PRIME only works if @build stays in its lane (doesn't duplicate QA dispatch), returns a summary PRIME can relay without re-expanding context, and handles both invocation shapes gracefully. Section 4's full-suite requirement was a primary-era holdover; removing it avoids duplicating Phase 4's qa-reviewer work. Section 5's rewrite formalizes the delegation contract.
Risk: medium. @build prompt is reshaped substantially. Mitigations: (1) core execution logic (section 3) untouched; (2) return-payload contract is explicit so the delegation seam is legible; (3) regression guard build prompt does not re-run full test suite flags any revert to the old shape.

src/commands/prompts/autopilot.md

Change (Part 2): line 76 replaced. Old: - **Phase 3 (Execute).** File-by-file. Check off acceptance criteria as you go — boxes are the signal both to the user and to the autopilot plugin.. New: - **Phase 3 (Execute).** Delegate to @build. @buildexecutes file-by-file and returns a summary; PRIME relays progress. Acceptance boxes get checked during@build's execution.
Why: Autopilot runs PRIME's normal five-phase workflow. Its Phase 3 bullet must reflect the new delegation model, otherwise the autopilot path would contradict prime.md.
Risk: none. Pure documentation alignment.

test/agents.test.ts

Change (Part 1 — amended): agent-count comment rewritten to describe dual-mode setup. has 2 primary agents test → has 2 primary-capable agents besides plan (prime, build; mode=primary or mode=all): accepts ["primary", "all"] via toContain. has the 12 subagents test → has 13 subagent-capable agents (mode=subagent or mode=all) with plan and build added to the list (both mode: "all"); accepts ["subagent", "all"]. Existing regression test renamed from plan agent is mode:subagent (task-tool-dispatchable) → plan agent is task-tool-dispatchable (not mode:primary); assertion changed from .toBe("subagent") to .not.toBe("primary") (accepts "subagent" or "all").
Change (Part 2): three new regression guards appended:
1. build agent is task-tool-dispatchable (not mode:primary) — asserts agents["build"]!.mode !== "primary". Comment cites ccd1761 precedent and explains that mode:primary silently kills the Phase 3 delegation path.
2. prime prompt delegates Phase 3 to @build — asserts prime prompt contains "Delegate to \@build`"(matches the backtick-wrapped code reference in the rewritten Phase 3) AND does NOT contain"For each item in the plan's `## File-level changes`:"` (the old inline-execution loop header). Would fail if the old inline Phase 3 sneaks back.
3. build prompt does not re-run full test suite (PRIME's Phase 4 owns it) — asserts build prompt does NOT contain "Run the full test suite. It must pass." nor "Run lint. It must pass.". Catches a revert that re-embeds the duplicate full-suite run.
Why: The mode-split tests needed restructuring because mode: "all" means plan and build aren't cleanly primary-or-subagent. The three new guards lock in the behavioral claims the prompt edits make: task-tool-dispatchability (catches index.ts reversion), Phase 3 delegation wording (catches prime.md reversion), no-duplicate-testing (catches build.md reversion).
Risk: low. Mechanical test restructuring; assertion semantics are strictly broader (.not.toBe("primary") accepts more valid modes than .toBe("subagent")), so no false failures. The three new guards match the pattern of the existing plan agent is task-tool-dispatchable guard.

.changeset/fix-prime-dispatch-to-plan-agent.md (Part 1)

Change (Part 1 — amended): created. Patch bump. Description reflects the mode: "all" decision (no user-visible regression) and references the dispatch-to-pilot-planner bug + description collision fix.
Why: Every user-visible PR requires a changeset per CONTRIBUTING.md; this is a user-visible behavior fix.
Risk: none.

.changeset/prime-delegates-phase3-to-build.md (Part 2)

Change (Part 2 — new): created. Patch bump. Description explains the Phase 3 delegation motivation (mid-tier model cost savings via Kimi/GLM/Haiku swap) and the @build reshape.
Why: Same changeset requirement; Part 2 is a separately-landable behavioral change and deserves its own changelog entry.
Risk: none.

Test plan

Execute in order:

bun run typecheck — must pass. Catches any type-surface regression from the mode string-literal change on plan and build.
bun test test/agents.test.ts — must pass. Specifically:
- returns exactly 14 agents (unchanged count).
- has 2 primary-capable agents besides plan (prime, build; mode=primary or mode=all) (restructured).
- has 13 subagent-capable agents (mode=subagent or mode=all) (restructured, includes plan and build).
- plan agent is task-tool-dispatchable (not mode:primary) (existing guard, renamed).
- build agent is task-tool-dispatchable (not mode:primary) (new guard).
- prime prompt delegates Phase 3 to @build (new guard).
- build prompt does not re-run full test suite (PRIME's Phase 4 owns it) (new guard).
- pilot-planner description does not collide with plan description (existing guard, unchanged).
- build has correct model and temperature — must still pass; model/temperature unchanged.
- build bash object-form includes enumerated allow-list — must still pass; BUILD_PERMISSIONS bash block untouched.
- build bash object-form keeps destructive denies — must still pass.
- build agent keeps object-form destructive denies — must still pass.
bun test test/harness-models.test.ts — must pass. build stays mid tier; no change expected.
bun test test/prompts-no-dangling-paths.test.ts — must pass. No forbidden paths introduced.
bun test — full suite must pass. Catches any cross-file regression.
bun run build — must succeed. Refreshes dist/ output including the edited prompts so downstream users pick up the new behavior on next bun update.

Manual smoke checks (optional but recommended before merge)

Install the local build into a test OpenCode session (bunx @glrs-dev/harness-opencode install pointing at the local dist/), open a real task, confirm PRIME invokes the task tool with agent: "build" during Phase 3.
Confirm that @build <plan-path> at the top level of an OpenCode session STILL works (expected — mode: "all" preserves top-level invocation). Same for @plan.

Out of scope

Do NOT change BUILD_PERMISSIONS bash rules (CORE_BASH_ALLOW_LIST, CORE_DESTRUCTIVE_BASH_DENIES, "git clean *": "deny", "git reset --hard*": "ask"). Permissions work identically for primary and subagent. @build still needs general bash + git commit for Phase 3 checkpointing. question: "allow" also stays — see Open questions resolution below.
Do NOT extract Phase 2 grounding to a separate agent. User rejected option D due to latency concerns.
Do NOT change PRIME's Phase 0, 1, 1.5, 2, 4, or 5. Only Phase 3 changes.
Do NOT change @plan's prompt body beyond the Part 1 amend (line 3 dual-invocation revision). Its workflow (Interview / Ground / Gap analysis / Write / Adversarial review / Report) is out of scope here.
Do NOT change @qa-reviewer / @qa-thorough / @plan-reviewer / @code-searcher / @gap-analyzer prompts. Their references to "the build agent" stay semantically correct — @build still executes plans, @qa-reviewer still reviews its output.
Do NOT touch src/agents/prompts/architecture-advisor.md line 13 ("The build agent has failed at the same task twice") — trigger condition doesn't depend on @build's mode.
Do NOT touch docs/archive/claude-code-fallbacks.md — archived per root rule guidance.
Do NOT touch src/agents/AGENTS.md tier comment at line 25 (mid — Sonnet-class (@qa-reviewer, @plan-reviewer, @build)) — tier isn't changing.
Do NOT add new slash commands. Phase 3 delegation happens via the task tool, not a user-facing command.
Do NOT change the pilot subsystem (pilot-builder, pilot-plugin.ts, anything under src/pilot/). The pilot-planner.md description rewrite in Part 1 is a user-facing prompt disambiguation (not a pilot-subsystem behavior change) and is explicitly in scope for Part 1.
Do NOT change src/harness-models.ts tier mapping. @build stays mid.

Open questions

None. The original question PRIME flagged ("should the question tool path stay on @build?") was resolved during execution: with @build at mode: "all" (invocable top-level), the question tool is scoped via prompt-level guidance rather than permission-level deny. Subagent invocations STOP with a structured blocker payload PRIME relays; top-level invocations may use the question tool as primaries do. BUILD_PERMISSIONS.question stays "allow" to enable the top-level path.

@plan

… execution PRIME now delegates Phase 2 (plan authoring) to @plan AND Phase 3 (plan execution) to @build via the task tool — moving the highest-volume token consumers off Opus and onto the mid tier. Users running Kimi K2, GLM-4.6, Haiku, or any other cheap mid-tier model for the `mid` tier see a significant cost reduction on substantial work. Two coupled fixes: 1. Task-tool routing. Both @plan and @build were registered as mode:"primary" — invisible to other agents' task-tool picker. PRIME's Phase 2 'delegate to @plan' and Phase 3 'delegate to @build' instructions silently fell through to pilot-planner (whose description also led with 'Interactive planner…') or general. Per OpenCode's docs (opencode.ai/docs/agents/#mode), mode:"all" means the agent is BOTH primary (Tab-cycleable, top-level @-mention works) AND subagent (visible to other agents' task-tool picker). That's the correct setting for both agents — full dispatchability with no user-visible regression. Also rewrite pilot-planner's description lead phrase to 'Pilot-subsystem YAML plan generator.' to eliminate the description-prefix collision that misled the picker. 2. Phase 3 delegation. PRIME's Phase 3 is rewritten to delegate execution to @build via the task tool, validate diff on return, handle STOP payloads (cosmetic/approach/scope-expansion classes), and proceed to Phase 4. @build's prompt is reshaped for dual invocation: Section 4 no longer runs full test suite / lint (PRIME's Phase 4 owns QA), Section 5 becomes a structured Return payload contract, 'How to ask the user' scoped (question tool for top-level only, STOP-to-PRIME for subagent invocations). Context Firewall gains a mandatory Phase 3 delegation row. autopilot.md Phase 3 bullet aligned. Five regression tests lock the fix: - plan agent is task-tool-dispatchable (not mode:primary) - build agent is task-tool-dispatchable (not mode:primary) - pilot-planner description does not collide with plan description - prime prompt delegates Phase 3 to @build - build prompt does not re-run full test suite (PRIME's Phase 4 owns it) Mode-split tests restructured: primary-capable accepts mode:"primary" or "all"; subagent-capable accepts mode:"subagent" or "all". Plan: ~/.glorious/opencode/harness-opencode/plans/prime-delegates-phase3-to-build.md

iceglober merged commit afe4f8e into main Apr 26, 2026
2 checks passed

harness-opencode-ci Bot mentioned this pull request Apr 26, 2026

chore: version packages #126

Merged

iceglober mentioned this pull request Apr 26, 2026

port(harness-opencode): bring in 0.16.1 + 0.16.2 from archived iceglober/harness-opencode iceglober/glrs#1

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(agents): route plan + build through task tool for cheap-mid-tier execution#127

feat(agents): route plan + build through task tool for cheap-mid-tier execution#127
iceglober merged 1 commit into
mainfrom
fix/plan-agent-dispatch

iceglober commented Apr 26, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

iceglober commented Apr 26, 2026

PRIME delegates Phase 3 execution to @build subagent

Goal

Constraints

Acceptance criteria

Part 1 — amend commit 75448b9 (@plan fix correction)

Part 2 — new commit (Phase 3 delegation + @build → mode:all)

Part 3 — verification (both parts together)

File-level changes

src/agents/index.ts

src/agents/prompts/pilot-planner.md

src/agents/prompts/plan.md

src/agents/prompts/prime.md

src/agents/prompts/build.md

src/commands/prompts/autopilot.md

test/agents.test.ts

.changeset/fix-prime-dispatch-to-plan-agent.md (Part 1)

.changeset/prime-delegates-phase3-to-build.md (Part 2)

Test plan

Manual smoke checks (optional but recommended before merge)

Out of scope

Open questions

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant