fix(agent): reduce unnecessary subagent dispatch

[Astro-Han]

Summary

• Tighten PawWork's main tool-collaboration guidance so subagents are used only when they clearly save work over direct tool calls.
• Clarify the agent tool's when-to-use / when-not-to-use rules, including small known areas and ordinary bug-debugging steps.
• Narrow the built-in explore agent description to broad unknown-entry codebase exploration and add an explicit direct-read/search preference for known files or symbols.

Why

Recent session reviews showed the model over-dispatching explore subagents for narrow debugging and known-file lookups. These prompt changes add clearer retrieval budgets, stopping conditions, and negative examples so the model defaults to direct read / glob / grep for small or sequential work.

Related Issue

No issue yet; this came from reviewing exported PawWork sessions that showed excessive subagent fan-out.

Human Review Status

Pending. A human should make the final merge decision after reviewing the final diff and verification evidence.

Review Focus

• Whether the new wording is restrictive enough to reduce unnecessary subagent usage without blocking legitimate broad exploration.
• Whether the guidance stays consistent across PawWork system prompt, agent tool description, and explore agent description.
• Confirm plan-mode wording was intentionally left unchanged.

Risk Notes

Low. This is prompt/tool-description text only. It may make models less likely to delegate exploration; broad exploration remains allowed when clearly beneficial.

How To Verify

Dependency install: bun install --frozen-lockfile completed in the new worktree
Targeted tests: bun test test/tool/agent.test.ts from packages/opencode — 14 passed, 1 skipped, 0 failed
Prompt check: grep confirmed plan-mode guidance remains unchanged by this PR
Diff review: final diff limited to 3 prompt/description files, no generated or dependency files

Screenshots or Recordings

Not applicable; no visible UI changes.

Checklist

• Human review status is stated above as pending, approved, or not required
• I linked the related issue, or stated why there is no issue
• This PR has type, scope, and priority labels, or I requested maintainer labeling
• I described the review focus and any meaningful risks
• I listed the relevant verification steps and the key result for each
• I did not introduce unrelated refactors, dependencies, generated files, or file changes beyond the stated scope
• I manually checked visible UI or copy changes when needed, with screenshots or recordings
• I considered macOS and Windows impact for desktop, packaging, updater, signing, paths, shell, or permissions changes
• I called out docs, release notes, dependencies, permissions, credentials, deletion behavior, generated content, or local file changes when relevant
• I reviewed the final diff for unrelated changes and suspicious dependency changes
• I am targeting dev, and my PR title and commit messages use Conventional Commits in English

Summary by CodeRabbit

• Documentation
  • Clarified explore-agent guidance with explicit criteria for when to invoke or avoid the agent.
  • Added a thoroughness convention for agent investigations: "quick", "medium", "very thorough".
  • Refined agent-dispatch guidance to help decide between a standalone agent investigation and direct tool calls within the current thread.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: ab213458-08a9-47c3-a483-b5dece5d5db7

📥 Commits

Reviewing files that changed from the base of the PR and between 0e513f6 and 3ab7dc8.

📒 Files selected for processing (1)

• packages/opencode/src/agent/agent.ts

✅ Files skipped from review due to trivial changes (1)

• packages/opencode/src/agent/agent.ts

---

📝 Walkthrough

Walkthrough

This PR updates in-repo agent guidance: it refines the explore agent description to warn when not to use it and formalizes a "retrieval budget" (quick, medium, very thorough), and tightens session prompt and tool docs to prefer agent only when a separate investigation clearly saves work versus direct tool calls.

Changes

Agent Usage Guidance Refinement

Layer / File(s)	Summary
Agent Definition packages/opencode/src/agent/agent.ts	Updated the explore agent description to add explicit "don't use when the parent already knows the target" guidance and to formalize retrieval-budget options ("quick", "medium", "very thorough").
Session Dispatch Rules packages/opencode/src/session/prompt/pawwork.txt	Reworded subagent dispatch guidance: require that the agent be used only when a separate, self-contained investigation will clearly save work versus direct tool calls; adjusted examples of when not to use the agent.
Tool Documentation packages/opencode/src/tool/agent.txt	Replaced generic "complex, multistep tasks" guidance with efficiency-based criteria; expanded "When to use" and "When NOT to use" lists; tightened usage notes and removed a prior proactive-trigger instruction.

Estimated Code Review Effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• refactor(agent): remove visible primary-agent mode picker (#239) #242: Edits agent prompts and metadata touching agent.ts and related agent documentation.
• fix(harness): add prompt preamble and stop rules #358: Modifies the PawWork system prompt and agent/tool guidance; overlaps with session prompt wording changes.

Suggested labels

documentation, P3

Poem

🐰 I hop through notes and tidy cues,
I tell the agent when not to choose.
"Quick" or "very thorough"—pick the pace,
Save a call, skip the chase,
Happy hops for clearer rules! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(agent): reduce unnecessary subagent dispatch' is specific and directly reflects the main change across all modified files.
Description check	✅ Passed	The description is comprehensive, covering summary, rationale, related issue, verification steps, risk assessment, and addressing all key checklist items.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch pawwork/tidy-orchid

---

_{Review rate limit: 8/10 reviews remaining, refill in 8 minutes and 24 seconds.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@packages/opencode/src/session/prompt/pawwork.txt`:
- Line 47: Phase 1 still instructs launching up to 3 "explore" subagents which
conflicts with the new global guidance to dispatch agents only when clearly
beneficial (line 47); update the Phase 1 prompt/instruction that spawns multiple
"explore" agents (the block that says "launch up to 3 explore agents" in the
Phase 1 prompt) to either (a) reduce to a single targeted "explore" subagent or
(b) add a strict gating condition so subagents are launched only when the task
cannot be solved by direct reads/grep in-thread, and explicitly preserve
judgment/synthesis in the main thread. Ensure the prompt text and any
variables/constants that reference "explore" or "Phase 1" are changed so both
prompt sources are aligned and do not suggest multi-agent over-dispatch.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: b4c4f727-2b2a-4eaf-9c72-fd0e3bc47a24

📥 Commits

Reviewing files that changed from the base of the PR and between f72018e and 0e513f6.

📒 Files selected for processing (3)

• packages/opencode/src/agent/agent.ts
• packages/opencode/src/session/prompt/pawwork.txt
• packages/opencode/src/tool/agent.txt

[gemini-code-assist]

Code Review

This pull request updates the documentation and descriptions for subagent dispatching across several files, including agent.ts, pawwork.txt, and agent.txt. The changes provide more explicit guidance on when to use subagents—prioritizing broad, independent exploration and parallel research—while discouraging their use for narrow tasks or known file inspections that are more efficient in the main thread. A review comment suggested clarifying the term 'budget' in the agent description to ensure the model understands it refers to the thoroughness level rather than a separate parameter.