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 significantlysrc/plugin/pty/tools/read.txt — shortensrc/plugin/pty/tools/write.txt — shortensrc/plugin/pty/tools/list.txt — shortensrc/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.
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 choosepty_spawnover the built-inbashtool.The agent defaults to the built-in
bashfor everything unless the user explicitly says the magic word "session". This defeats the purpose of the plugin — users expect that installingopencode-ptyautomatically makes the agent smarter about background/long-running tasks.Root Cause
The
tool()function in the plugin SDK only has a singledescription: stringfield — there is no separateinstructionsornotesfield for agent guidance. All communication about the tool goes through this one string.Proposed Solution
Rewrite the
.txtfiles to be short, decision-focused descriptions (2-5 lines each) instead of verbose usage docs. The critical one isspawn.txt— it should lead with explicit criteria for when to usepty_spawnvs the built-inbashtool.Something like:
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 significantlysrc/plugin/pty/tools/read.txt— shortensrc/plugin/pty/tools/write.txt— shortensrc/plugin/pty/tools/list.txt— shortensrc/plugin/pty/tools/kill.txt— shortenVerification
Checked the plugin SDK docs (
@opencode-ai/plugin) — there is no hook for injecting separate agent instructions beyond thedescriptionfield ontool(). Modifying the descriptions is the only viable approach within the current SDK constraints.