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

Description

$ ls -la
Error: The bash tool was called with invalid arguments: [
{
"expected": "string",
"code": "invalid_type",
"path": [
"description"
],
"message": "Invalid input: expected string, received undefined"
}
].
Please rewrite the input so it satisfies the expected schema.

Summary

The built-in bash tool has a hidden required parameter description that is not included in the tool schema exposed to the AI model. This causes every single bash command to fail with a Zod validation error, including basic operations like ls -la.

This is a critical/blocking bug — the bash tool is completely unusable until the user discovers and works around this issue.

Severity

Critical / P0 — The bash tool is one of the most fundamental tools. When it doesn't work, the AI agent cannot run any shell commands (git, npm, build, test, etc.), severely crippling its capabilities.

Environment

opencode version: 1.1.56
OS: macOS Darwin 24.5.0 (arm64, Apple Silicon)
Node.js: v20.19.5
Plugin: oh-my-opencode@latest
Binary: /opt/homebrew/lib/node_modules/opencode-ai/node_modules/opencode-darwin-arm64/bin/opencode

Steps to Reproduce

Start an opencode session
Ask the AI to run any bash command, e.g. ls -la
The AI calls the bash tool with the documented parameters:
```
{ "command": "ls -la" }
```

Immediate failure with:

{
  "expected": "string",
  "code": "invalid_type",
  "path": ["description"],
  "message": "Invalid input: expected string, received undefined"
}

Expected Behavior

bash(command="ls -la") should execute successfully and return directory listing.

Actual Behavior

Every bash call fails with a Zod schema validation error because description is required but the AI doesn't know it needs to pass it.

Root Cause Analysis

Found by extracting the tool definition from the compiled binary:

strings /opt/homebrew/lib/node_modules/opencode-ai/node_modules/opencode-darwin-arm64/bin/opencode \
  | grep -A20 'The command to execute'

The bash tool's parameter schema is defined as:

parameters: zod_default.object({
    command: zod_default.string().describe("The command to execute"),
    timeout: zod_default.number().describe("Optional timeout in milliseconds").optional(),
    workdir: zod_default.string().describe("...").optional(),
    description: zod_default.string().describe("Clear, concise description of what this command does in 5-10 words...")
    //          ↑↑↑ NOT marked as .optional() — Zod treats it as REQUIRED
})

The problem: description is defined as a required string() — it lacks .optional(). However, the tool schema exposed to the AI model does not include description as a visible/documented parameter. The AI has no way to know it must pass this field.

Proposed Fix

Option A (Recommended): Make description optional:

- description: zod_default.string().describe("...")
+ description: zod_default.string().describe("...").optional()

Option B: Include description in the tool schema that is exposed to the AI model, so the model knows to pass it.

Current Workaround

Add the following to user-level instructions (~/.claude/CLAUDE.md or equivalent):

# Bash Tool: `description` parameter is required

When calling the `bash` tool, you MUST pass a `description` parameter (5-10 words describing the command), otherwise you'll get a schema validation error.

✅ bash(command="ls -la", description="List current directory files")
❌ bash(command="ls -la")  ← will error with "description" invalid_type


### Plugins

oh-my-opencode

### OpenCode version

1.1.56

### Steps to reproduce

/init 

### Screenshot and/or share link

<img width="2394" height="1802" alt="Image" src="https://github.com/user-attachments/assets/f594826a-65b6-48b1-abb9-25a7ba607205" />

### Operating System

macOS 15.5

### Terminal

iTerm2

What provider are you using?

This is the schema of the tool:

  {
            "name": "bash",
            "description": "Executes a given bash command in a persistent shell session with optional timeout, ensuring proper handling and security measures.\n\nAll commands run in /Users/aidencline/development/models.dev by default. Use the `workdir` parameter if you need to run a command in a different directory. AVOID using `cd <directory> && <command>` patterns - use `workdir` instead.\n\nIMPORTANT: This tool is for terminal operations like git, npm, docker, etc. DO NOT use it for file operations (reading, writing, editing, searching, finding files) - use the specialized tools for this instead.\n\nBefore executing the command, please follow these steps:\n\n1. Directory Verification:\n   - If the command will create new directories or files, first use `ls` to verify the parent directory exists and is the correct location\n   - For example, before running \"mkdir foo/bar\", first use `ls foo` to check that \"foo\" exists and is the intended parent directory\n\n2. Command Execution:\n   - Always quote file paths that contain spaces with double quotes (e.g., rm \"path with spaces/file.txt\")\n   - Examples of proper quoting:\n     - mkdir \"/Users/name/My Documents\" (correct)\n     - mkdir /Users/name/My Documents (incorrect - will fail)\n     - python \"/path/with spaces/script.py\" (correct)\n     - python /path/with spaces/script.py (incorrect - will fail)\n   - After ensuring proper quoting, execute the command.\n   - Capture the output of the command.\n\nUsage notes:\n  - The command argument is required.\n  - You can specify an optional timeout in milliseconds. If not specified, commands will time out after 120000ms (2 minutes).\n  - It is very helpful if you write a clear, concise description of what this command does in 5-10 words.\n  - If the output exceeds 2000 lines or 51200 bytes, it will be truncated and the full output will be written to a file. You can use Read with offset/limit to read specific sections or Grep to search the full content. Because of this, you do NOT need to use `head`, `tail`, or other truncation commands to limit output - just run the command directly.\n\n  - Avoid using Bash with the `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or when these commands are truly necessary for the task. Instead, always prefer using the dedicated tools for these commands:\n    - File search: Use Glob (NOT find or ls)\n    - Content search: Use Grep (NOT grep or rg)\n    - Read files: Use Read (NOT cat/head/tail)\n    - Edit files: Use Edit (NOT sed/awk)\n    - Write files: Use Write (NOT echo >/cat <<EOF)\n    - Communication: Output text directly (NOT echo/printf)\n  - When issuing multiple commands:\n    - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. For example, if you need to run \"git status\" and \"git diff\", send a single message with two Bash tool calls in parallel.\n    - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together (e.g., `git add . && git commit -m \"message\" && git push`). For instance, if one operation must complete before another starts (like mkdir before cp, Write before Bash for git operations, or git add before git commit), run these operations sequentially instead.\n    - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail\n    - DO NOT use newlines to separate commands (newlines are ok in quoted strings)\n  - AVOID using `cd <directory> && <command>`. Use the `workdir` parameter to change directories instead.\n    <good-example>\n    Use workdir=\"/foo/bar\" with command: pytest tests\n    </good-example>\n    <bad-example>\n    cd /foo/bar && pytest tests\n    </bad-example>\n\n# Committing changes with git\n\nOnly create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:\n\nGit Safety Protocol:\n- NEVER update the git config\n- NEVER run destructive/irreversible git commands (like push --force, hard reset, etc) unless the user explicitly requests them\n- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it\n- NEVER run force push to main/master, warn the user if they request it\n- Avoid git commit --amend. ONLY use --amend when ALL conditions are met:\n  (1) User explicitly requested amend, OR commit SUCCEEDED but pre-commit hook auto-modified files that need including\n  (2) HEAD commit was created by you in this conversation (verify: git log -1 --format='%an %ae')\n  (3) Commit has NOT been pushed to remote (verify: git status shows \"Your branch is ahead\")\n- CRITICAL: If commit FAILED or was REJECTED by hook, NEVER amend - fix the issue and create a NEW commit\n- CRITICAL: If you already pushed to remote, NEVER amend unless user explicitly requests it (requires force push)\n- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive.\n\n1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel, each using the Bash tool:\n  - Run a git status command to see all untracked files.\n  - Run a git diff command to see both staged and unstaged changes that will be committed.\n  - Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.\n2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:\n  - Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. \"add\" means a wholly new feature, \"update\" means an enhancement to an existing feature, \"fix\" means a bug fix, etc.).\n  - Do not commit files that likely contain secrets (.env, credentials.json, etc.). Warn the user if they specifically request to commit those files\n  - Draft a concise (1-2 sentences) commit message that focuses on the \"why\" rather than the \"what\"\n  - Ensure it accurately reflects the changes and their purpose\n3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands:\n   - Add relevant untracked files to the staging area.\n   - Create the commit with a message\n   - Run git status after the commit completes to verify success.\n   Note: git status depends on the commit completing, so run it sequentially after the commit.\n4. If the commit fails due to pre-commit hook, fix the issue and create a NEW commit (see amend rules above)\n\nImportant notes:\n- NEVER run additional commands to read or explore code, besides git bash commands\n- NEVER use the TodoWrite or Task tools\n- DO NOT push to the remote repository unless the user explicitly asks you to do so\n- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.\n- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit\n\n# Creating pull requests\nUse the gh command via the Bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases. If given a GitHub URL use the gh command to get the information needed.\n\nIMPORTANT: When the user asks you to create a pull request, follow these steps carefully:\n\n1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel using the Bash tool, in order to understand the current state of the branch since it diverged from the main branch:\n   - Run a git status command to see all untracked files\n   - Run a git diff command to see both staged and unstaged changes that will be committed\n   - Check if the current branch tracks a remote branch and is up to date with the remote, so you know if you need to push to the remote\n   - Run a git log command and `git diff [base-branch]...HEAD` to understand the full commit history for the current branch (from the time it diverged from the base branch)\n2. Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request!!!), and draft a pull request summary\n3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands in parallel:\n   - Create new branch if needed\n   - Push to remote with -u flag if needed\n   - Create PR using gh pr create with the format below. Use a HEREDOC to pass the body to ensure correct formatting.\n<example>\ngh pr create --title \"the pr title\" --body \"$(cat <<'EOF'\n## Summary\n<1-3 bullet points>\n</example>\n\nImportant:\n- DO NOT use the TodoWrite or Task tools\n- Return the PR URL when you're done, so the user can see it\n\n# Other common operations\n- View comments on a GitHub PR: gh api repos/foo/bar/pulls/123/comments\n",
            "input_schema": {
                "$schema": "https://json-schema.org/draft/2020-12/schema",
                "type": "object",
                "properties": {
                    "command": {
                        "description": "The command to execute",
                        "type": "string"
                    },
                    "timeout": {
                        "description": "Optional timeout in milliseconds",
                        "type": "number"
                    },
                    "workdir": {
                        "description": "The working directory to run the command in. Defaults to /Users/aidencline/development/models.dev. Use this instead of 'cd' commands.",
                        "type": "string"
                    },
                    "description": {
                        "description": "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'",
                        "type": "string"
                    }
                },
                "required": [
                    "command",
                    "description"
                ],
                "additionalProperties": false
            }
        },

And this is not a "hidden field"

Most likely your provider or model is confused or not great and perhaps we need to tweak to make it perform better

@rekram1-node

@rekram1-node These kind of issues happen with pretty much every model if you use ollama.
For example glm-4.7-flash. And this model at least does something, most other models seem to be completely incompatible with all kinds of agents, including opencode.

fix(bash): make description parameter optional in bash tool

Any update on this? Is entirely annoying!

FWIW I'm seeing this a lot using qwen3-coder-next through AWS Bedrock and LiteLLM.

Maybe it would help if the description property would be moved ahead of the optional properties, and/or explicitly mentioning the fact that it's required in the property's description?

fix: make bash tool description parameter optional

fix(opencode): add critical tool schema rules

To stay organized issues are automatically closed after 60 days of no activity. If the issue is still relevant please open a new one.

fix(opencode): resolve MCP env placeholders and unbreak the bash tool…

Navigation Menu

Repository navigation

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

Description

Summary

Severity

Environment

Steps to Reproduce

Expected Behavior

Actual Behavior

Root Cause Analysis

Proposed Fix

Current Workaround

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

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

Description

Description

Summary

Severity

Environment

Steps to Reproduce

Expected Behavior

Actual Behavior

Root Cause Analysis

Proposed Fix

Current Workaround

Activity

daheli commented on Feb 11, 2026

rekram1-node commented on Feb 11, 2026

allarac commented on Feb 13, 2026

xochilpili commented on Feb 25, 2026

mszepieniec commented on Mar 4, 2026

github-actions commented on Jul 3, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

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