← anomalyco/opencode

#18392 · @danielcherubini · opened Mar 20, 2026 at 1:19 PM UTC · last updated Mar 21, 2026 at 10:12 AM UTC

fix: make bash tool description parameter optional

appfix
83
+7−51 files

Score breakdown

Impact

10.0

Clarity

9.0

Urgency

10.0

Ease Of Review

8.0

Guidelines

9.0

Readiness

9.0

Size

10.0

Trust

5.0

Traction

7.0

Summary

This PR makes the "description" parameter optional for the "bash" tool, preventing critical failures when AI models omit it. It addresses a core usability blocker and infinite loop scenarios with various models, particularly smaller ones.

Open in GitHub

Description

Issue for this PR

Closes #13146

Also:

  • #17415 — same error, Ubuntu
  • #14519 — both command and description undefined, Windows
  • #10213 — same error
  • #5662 — shell hangs with "undefined"

Related (local/small model tool schema issues):

  • #6649 — local model tool call parsing
  • #6918 — Qwen3-Coder edit tool fails
  • #18131 — Qwen 3.5 35B write tool fails
  • #16488 — Qwen 3 vLLM silent crash

Type of change

  • [x] Bug fix
  • [ ] New feature
  • [ ] Refactor / code improvement
  • [ ] Documentation

What does this PR do?

The description parameter on the bash tool is required but some models (especially smaller/local models) don't always include it in tool calls, causing "Invalid input: expected string, received undefined" errors that loop indefinitely. Make it optional and fall back to the command string when not provided.

If you paste a large clearly AI generated description here your PR may be IGNORED or CLOSED!

How did you verify your code works?

I ran opencode in two different repos, using small and larger models and found no issue with the error I have seen in issue #13146

Screenshots / recordings

<img width="961" height="1157" alt="image" src="https://github.com/user-attachments/assets/8532dc33-dfa3-4f9f-bee7-e677172a0f65" /> <img width="1111" height="1157" alt="image" src="https://github.com/user-attachments/assets/3fa5409e-19e5-440a-aae7-0894f9cab4db" />

Checklist

  • [x] I have tested my changes locally
  • [x] I have not included unrelated changes in this PR

If you do not follow this template your PR will be automatically rejected.

Linked Issues

#13146 Bash(ls -la) tool `description` parameter is required but not exposed in tool schema — breaks all bash calls

View issue

Comments

No comments.

Changed Files

packages/opencode/src/tool/bash.ts

+7−5
@@ -73,9 +73,11 @@ export const BashTool = Tool.define("bash", async () => {
.string()
.describe(
"Clear, concise description of what this command does in 5-10 words. Examples:\nInput: ls\nOutput: Lists files in current directory\n\nInput: git status\nOutput: Shows working tree status\n\nInput: npm install\nOutput: Installs package dependencies\n\nInput: mkdir foo\nOutput: Creates directory 'foo'",
),
)
.optional(),
}),
async execute(params, ctx) {
const description = params.description ?? params.command
const cwd = params.workdir || Instance.directory
if (params.timeout !== undefined && params.timeout < 0) {
throw new Error(`Invalid timeout value: ${params.timeout}. Timeout must be a positive number.`)
@@ -182,7 +184,7 @@ export const BashTool = Tool.define("bash", async () => {
ctx.metadata({
metadata: {
output: "",
description: params.description,
description: description,
},
})
@@ -192,7 +194,7 @@ export const BashTool = Tool.define("bash", async () => {
metadata: {
// truncate the metadata to