refactor: shorten tool descriptions to focus on when-to-use instead of how-to-use

[danieliyahu1]

Problem

The 5 tool description files (spawn.txt, read.txt, write.txt, list.txt, kill.txt) contained verbose usage instructions, parameter docs, and examples — 171 lines total. The AI agent doesn't need to re-read tutorial material on every turn; the Zod parameter schemas already describe each parameter.

More importantly, the descriptions gave the agent no guidance on when to choose pty_spawn over the built-in bash tool, forcing users to use the magic keyword "session" to trigger the right behavior.

Changes

All 5 files reduced from 171 lines to 10 lines total:

• spawn.txt — now leads with explicit decision criteria: when to use pty_spawn vs the built-in bash tool
• read.txt, write.txt, list.txt, kill.txt — trimmed to 1-3 lines focused purely on tool purpose

Why

The tool() function in the plugin SDK only has a single description: string field — there is no separate instructions or notes field. All communication about the tool goes through this one string. These descriptions should tell the agent what the tool is and when to use it, not how it works under the hood.

Before/After

File	Before	After
spawn.txt	52 lines	5 lines
read.txt	39 lines	3 lines
write.txt	28 lines	3 lines
list.txt	22 lines	1 line
kill.txt	25 lines	3 lines

[14ag]

indeed functionality is still intact

[14ag]

on the same topic of token savings, i used a wording that is more strict to the NOTIFY_ON_EXIT_REMINDER in read.ts, read.js, spawn.ts and spawn.js
it prevents deepseek flash from making pings after using the notifyOnExit=true flag

const NOTIFY_ON_EXIT_REMINDER = [
    `<system_reminder>`,
    `This session was started with \`notifyOnExit=true\`.`,
    `Completion signal is the future \`<pty_exited>\` message, STRICTLY do not make any \`pty_read\` call in this terminal session.`,
    `after starting a session with \`notifyOnExit=true\` end your turn in the conversation and wait for completion signal`,
    `Do not use sleep plus \`pty_read\` loops to check completion.`,
    `Use \`pty_read\` only when the user explicitly asks for logs, progress or the exit notification reports a non-zero status and you need to investigate.`,
    `</system_reminder>`,
].join('\n');

would you like to add this to your pr?

[danieliyahu1]

Good idea - but that's a separate concern from tool descriptions, so I'd rather keep this PR scoped to the *.txt description files. Could you open a separate PR for the stricter NOTIFY_ON_EXIT_REMINDER wording? Happy to review it.