Skip to content

Commit d21f9b1

Browse files
committed
fix: plan-agent tool-use — mandate exploration + reword misleading warning
When the plan agent runs on a tool-capable but compliant model (e.g. GPT-5.5 via `altimate-default`), it often emits a plan from prompt context alone without ever reading the repo. The existing safety net in `processor.ts` catches this and surfaces a warning suggesting the user "switch to a model with stronger tool-use via /model". That diagnosis is misleading — the model IS tool-capable; it's a prompt-engineering issue, not a capability issue. This patch addresses both halves of the problem: - **`plan.txt`**: adds a `## Investigate before drafting (REQUIRED)` section that explicitly mandates at least one read-only tool call (`read`/`grep`/`glob`/`list`/`explore`/read-only `bash`) before any plan content. Stronger Claude models already infer this; weaker compliant models need it spelled out. Includes an explicit escape hatch for the trivial-task case so the rule doesn't fire spuriously. - **`processor.ts`**: rewords the synthetic warning to describe the observed behavior (`produced a plan without first reading any files`) and offer two concrete remedies — reply asking it to explore first, or `/model` to a more eager-to-investigate tier (Claude Sonnet/Opus). No longer blames "tool-use capability." - **`plan-reminder-anthropic.txt`**: deleted. The file was never imported anywhere in the codebase — it was an upstream OpenCode artifact that survived the rename in commit `a4eba2e6e` ("tweak: plan prompt"). Removing dead config. - Regression test in `plan-layer-e2e.test.ts` locks the explore-first contract into the prompt so a future cleanup can't silently delete it. All 160 affected tests pass; typecheck clean.
1 parent cdf89a6 commit d21f9b1

4 files changed

Lines changed: 36 additions & 70 deletions

File tree

‎packages/opencode/src/session/processor.ts‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -381,9 +381,12 @@ export namespace SessionProcessor {
381381
type: "text",
382382
synthetic: true,
383383
text:
384-
`⚠️ altimate-code: the \`plan\` agent is running on \`${input.model.providerID}/${input.model.id}\`, ` +
385-
`which returned text without calling any tools. If you expected the plan agent to explore the ` +
386-
`codebase, try switching to a model with stronger tool-use via \`/model\`.`,
384+
`⚠️ altimate-code: the \`plan\` agent on \`${input.model.providerID}/${input.model.id}\` ` +
385+
`produced a plan without first reading any files. Plans written from prompt context alone ` +
386+
`often miss existing patterns and reference files that may not exist. To get an investigated ` +
387+
`plan, either reply asking it to explore the codebase first (\`read\`/\`grep\`/\`glob\`/\`explore\`), ` +
388+
`or use \`/model\` to switch to a model that is more eager to investigate before drafting ` +
389+
`(e.g. a Claude Sonnet/Opus tier).`,
387390
time: { start: Date.now(), end: Date.now() },
388391
})
389392
}

‎packages/opencode/src/session/prompt/plan-reminder-anthropic.txt‎

Lines changed: 0 additions & 67 deletions
This file was deleted.

‎packages/opencode/src/session/prompt/plan.txt‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,22 @@ Ask the user clarifying questions or ask for their opinion when weighing tradeof
2020

2121
---
2222

23+
// altimate_change start — mandatory exploration before drafting
24+
## Investigate before drafting (REQUIRED)
25+
26+
Before you write any plan content — outline OR full plan — you MUST call at least one read-only investigation tool against the actual codebase. Acceptable first moves:
27+
28+
- `read` / `grep` / `glob` / `list` on relevant files
29+
- launching one or more `explore` subagents in parallel for broader sweeps
30+
- `bash` for read-only inspection (e.g. `git log`, `git diff`, `ls`)
31+
32+
Plans written from the prompt alone — without inspecting the repo — are guesswork. They reference files that may not exist, miss existing patterns, and waste the user's time. If the task is trivial enough that you genuinely have everything needed (e.g. the user pasted the exact file contents inline), say so explicitly before drafting.
33+
34+
This applies on the very first step. Do not produce a plan, an outline, or a "summary of approach" as your first action.
35+
// altimate_change end
36+
37+
---
38+
2339
// altimate_change start — two-step plan approach with refinement loop
2440
## Two-Step Plan Approach
2541

‎packages/opencode/test/session/plan-layer-e2e.test.ts‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -434,6 +434,20 @@ describe("plan prompt safety", () => {
434434
expect(planTxt.length).toBeLessThan(5000) // Not bloated
435435
})
436436

437+
test("plan.txt mandates investigation before drafting", async () => {
438+
// Regression guard: weaker non-Anthropic tool-capable models (e.g. GPT-5.5 via
439+
// altimate-default) often skip exploration and write plans from prompt context
440+
// alone. The prompt must explicitly require a read-only tool call before any
441+
// plan content. If this contract is removed, the plan-no-tool warning in
442+
// processor.ts fires more often and plan quality degrades silently.
443+
const planTxt = await fs.readFile(
444+
path.join(__dirname, "../../src/session/prompt/plan.txt"),
445+
"utf-8",
446+
)
447+
expect(planTxt).toMatch(/investigate before drafting|before you write any plan/i)
448+
expect(planTxt).toMatch(/read|grep|glob|explore/i)
449+
})
450+
437451
test("plan.txt does not contain debug or TODO markers", async () => {
438452
const planTxt = await fs.readFile(
439453
path.join(__dirname, "../../src/session/prompt/plan.txt"),

0 commit comments

Comments
 (0)