Tool descriptions are too verbose — agent needs decision-focused descriptions to autonomously prefer pty_spawn over bash
Los mantenedores suelen responder en 1 día
Nadie ha tomado este issue todavía.
Evaluación
- Dificultad
- 2/5
- Tiempo estimado
- 1-3 horas
- Aptitud para principiantes
- 78/100
- Tipo de issue
- Documentación
- Claridad
- Bien especificado
- Estado de actividad
- Tranquilo
- Stack tecnológico
- typescript
- Área
- tooling
Línea de trabajo
Comienza con los cinco archivos de src/plugin/pty/tools/: spawn.txt, read.txt, write.txt, list.txt y kill.txt, y revisa cómo se pasa su texto a través del campo de descripción de SDK tool(). Acorta cada uno a 2–5 líneas centradas en la toma de decisiones, haciendo que spawn.txt explique cuándo usar pty_spawn en lugar de bash. La tarea está terminada cuando las cinco descripciones sean concisas y se respete la limitación del SDK.
Escrito por el modelo de indexación a partir del texto del issue.
Descripción
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:
Usepty_spawnfor 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-inbashtool 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.
- Lenguaje dominante
- TypeScript
- Estrellas
- 601
- Forks
- 66
- Merge medio
- 1 d 20 h
- PR fusionados (30 d)
- 3
Preparar el entorno
Este proyecto no incluye contenedor de desarrollo, Dockerfile ni guía de contribución, así que la configuración corre por tu cuenta: empieza por su README y consulta nuestra guía para la primera contribución para los pasos generales.
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Más de shekohex/opencode-pty
-
[Bug]: exit notification delivery failures are silently swallowed — agent never wakes, no diagnosticAbierto
Dificultad 2/5 1-3 horas Aptitud para principiantes 78/100
shekohex/opencode-pty#54 ·
Los mantenedores suelen responder en 1 día
-
Dificultad 4/5 3-5 días Aptitud para principiantes 25/100
shekohex/opencode-pty#83 · 1 comentario ·
Los mantenedores suelen responder en 1 día
-
bug
Dificultad 3/5 1-2 días Aptitud para principiantes 64/100
shekohex/opencode-pty#82 ·
Los mantenedores suelen responder en 1 día
-
enhancement
Dificultad 3/5 1-2 días Aptitud para principiantes 67/100
shekohex/opencode-pty#81 ·
Los mantenedores suelen responder en 1 día
-
Dificultad 4/5 3-5 días Aptitud para principiantes 46/100
shekohex/opencode-pty#80 ·
Los mantenedores suelen responder en 1 día
Todos los issues de shekohex/opencode-pty
Issues similares
-
community first-timers-only good first issue hacktoberfest help wanted low hanging fruit up-for-grabs
Dificultad 1/5 Menos de una hora Aptitud para principiantes 90/100
lingdojo/kana-dojo#32663 · 1 comentario · 5 reacciones ·
Los mantenedores suelen responder en 1 día
-
Admin: Title Separator field can't be cleared (input falls back to "|")Posiblemente ocupada @emdashbot la tomó hoy. Abiertobot:bug bot:in-review
Dificultad 2/5 1-3 horas Aptitud para principiantes 80/100
emdash-cms/emdash#4236 · 3 comentarios ·
Los mantenedores suelen responder en 1 día
-
PHP workflow streaming requests buffer the full SSE responsePosiblemente ocupada @Winoren la tomó hoy. Abiertoreview: medium
Dificultad 2/5 1-3 horas Aptitud para principiantes 84/100
langgenius/dify#44270 · 1 comentario · 1 reacción ·
Los mantenedores suelen responder en 1 día
-
area:holodeck review-finding
Dificultad 2/5 1-3 horas Aptitud para principiantes 62/100
hyperdrive-technology/holodeck#142 ·
Los mantenedores suelen responder en 1 día
-
session-worker-compile.yml uses a floating oven-sh/setup-bun@v2 tag instead of the pinned SHAAbierto
Dificultad 1/5 Menos de una hora Aptitud para principiantes 90/100
code-yeongyu/senpi#3573 ·
Los mantenedores suelen responder en 1 día