Tool descriptions are too verbose — agent needs decision-focused descriptions to autonomously prefer pty_spawn over bash #48

Problem

Currently, the 5 tool description files (spawn.txt, read.txt, write.txt, list.txt, kill.txt) read like tutorial/reference docs. They explain how to use each tool in detail, but give the AI agent almost no guidance on when to choose pty_spawn over the built-in bash tool.

The agent defaults to the built-in bash for everything unless the user explicitly says the magic word "session". This defeats the purpose of the plugin — users expect that installing opencode-pty automatically makes the agent smarter about background/long-running tasks.

Root Cause

The tool() function in the plugin SDK only has a single description: string field — there is no separate instructions or notes field for agent guidance. All communication about the tool goes through this one string.

Proposed Solution

Rewrite the .txt files to be short, decision-focused descriptions (2-5 lines each) instead of verbose usage docs. The critical one is spawn.txt — it should lead with explicit criteria for when to use pty_spawn vs the built-in bash tool.

Something like:

When to use this tool INSTEAD of the built-in bash tool:
Use pty_spawn for any task that needs to run in the background, is long-running, requires interactive input later, or should persist beyond the current response. Examples: dev servers, watch modes, REPLs, builds, database servers.
Use the built-in bash tool ONLY for quick synchronous commands that complete immediately (ls, git status, cat, echo, etc.).

The verbose usage/example text currently in the descriptions is redundant — the parameter schemas (Zod) already describe each parameter, and examples are rarely useful for LLMs.

Files to Change

• src/plugin/pty/tools/spawn.txt — add decision criteria + shorten significantly
• src/plugin/pty/tools/read.txt — shorten
• src/plugin/pty/tools/write.txt — shorten
• src/plugin/pty/tools/list.txt — shorten
• src/plugin/pty/tools/kill.txt — shorten

Verification

Checked the plugin SDK docs (@opencode-ai/plugin) — there is no hook for injecting separate agent instructions beyond the description field on tool(). Modifying the descriptions is the only viable approach within the current SDK constraints.