fix(agent): reduce unnecessary subagent dispatch

packages/opencode/src/agent/agent.ts

@@ -161,7 +161,7 @@ export namespace Agent {
                 }),
                 user,
               ),
-              description: `Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions.`,
+              description: `Fast agent specialized for broad codebase exploration when the parent does not yet know the right files or symbols to inspect. Use this for unknown-entry searches, cross-directory pattern discovery, or independent research that can return one concise summary. Do not use it when the parent already knows the target file, symbol, or 1-3 likely files; read/search directly instead. When calling this agent, specify the desired thoroughness level (retrieval budget): "quick" for basic searches, "medium" for moderate exploration, or "very thorough" only for genuinely broad analysis across multiple locations and naming conventions.`,
               prompt: PROMPT_EXPLORE,
               options: {},
               mode: "subagent",

packages/opencode/src/session/prompt/pawwork.txt

@@ -44,7 +44,7 @@ Pick the right helper before acting:
 
 - question: when the user faces enumerable options, meaningful trade-offs, or hard-to-reverse choices, use this tool to list real options at the same level of detail and let them pick. Prefer asking over flagging uncertainty in prose.
 - todowrite: use it often, whenever the work has three or more steps that interact with each other or with state outside this thread. Write the list early, mark each item in_progress before starting and completed the moment it is done; never batch updates. The list is a control loop, not a record — every item must drive a real action in this thread. Skip when the steps are trivial sequential mechanics with no decision points (e.g. open a file, read a value, close it), or for true one-shot answers and read-only checks.
-- agent (subagent dispatch): when one self-contained sub-task can be answered by a single artifact or summary — broad multi-file research, parallel exploration, or high-volume scanning — delegate it to a subagent. Keep judgment, synthesis, and user-visible decisions in this main thread.
+- agent (subagent dispatch): use only when a separate, self-contained investigation will clearly save work versus direct tool calls in this thread. Good fits include broad unknown codebase exploration, independent research branches, or high-volume scanning that can return one concise summary. Do not use agent for known files, narrow code questions, package/test/config lookup, or ordinary bug-debugging steps where read/glob/grep in this thread is enough. Prefer one targeted subagent; launch multiple only when the hypotheses are independent and each has a clear stopping condition. Keep judgment, synthesis, and user-visible decisions in this main thread.
 - skill: when a request matches an installed skill, invoke it to load the relevant expertise into the current conversation. Do not invoke for trivial tasks already covered by built-in tools.
 
 If the user has already specified a path, execute it directly without re-asking. Otherwise reach for these helpers only when their specific trigger applies — handle ordinary work in this thread.

packages/opencode/src/tool/agent.txt

@@ -1,19 +1,23 @@
-Launch a new agent to handle complex, multistep tasks autonomously.
+Launch a new agent to handle a self-contained task autonomously when doing so is clearly more efficient than direct tool calls in the current thread.
 
 When using the agent tool, you must specify a subagent_type parameter to select which agent type to use.
 
 When to use the agent tool:
 - When you are instructed to execute custom slash commands. Use the agent tool with the slash command invocation as the entire prompt. The slash command can take arguments. For example: Agent(description="Check the file", prompt="/check-file path/to/file.py")
+- When one broad, independent investigation can be delegated and summarized without requiring continuous parent judgment.
+- When multiple hypotheses are genuinely independent and parallel investigation will reduce latency; each subagent should have a distinct scope and stopping condition.
 
 When NOT to use the agent tool:
 - If you want to read a specific file path, use the Read or Glob tool instead of the agent tool, to find the match more quickly
 - If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
 - If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the agent tool, to find the match more quickly
+- If you are checking package scripts, test setup, config files, or another small known area, inspect it directly in the current thread
+- If you are debugging a bug and already have a plausible next file or command to inspect, continue directly instead of delegating that single step
 - Other tasks that are not related to the available agents
 
 
 Usage notes:
 1. When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result. The output includes a subagent_session_id you can reuse later to continue the same subagent session.
-2. Each agent invocation starts with a fresh context unless you provide subagent_session_id to resume the same subagent session (which continues with its previous messages and tool outputs). When starting fresh, your prompt should contain a highly detailed task description for the agent to perform autonomously and you should specify exactly what information the agent should return back to you in its final and only message to you.
+2. Each agent invocation starts with a fresh context unless you provide subagent_session_id to resume the same subagent session (which continues with its previous messages and tool outputs). When starting fresh, your prompt should be specific and bounded: state the goal, relevant paths or keywords, what to ignore, and exactly what information the agent should return in its final and only message.
 3. Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent. Tell it how to verify its work if possible (e.g., relevant test commands).
-4. If the proactive trigger applies to the available agents, you should try your best to use it without the user having to ask for it first. Use your judgement.
+4. Do not use this tool just because an agent is available. Prefer the current thread for small or sequential work; use agent only when it has a clear advantage.