Description

The bash tool description can reference file-editing tools that are not actually available to the model.

Regardless of the permissions actually granted to the agent, or the tools actually exposed to the model, opencode unconditionally adds the following guidance to the bash tool description.

Note: I am using Windows / PowerShell, so this is the PowerShell-specific wording I observed.

## Avoid PowerShell file/content cmdlets

Avoid using Shell with PowerShell file/content cmdlets unless explicitly instructed, or unless these cmdlets are truly necessary for the task.

Instead, always prefer the dedicated tools:

File search: use Glob, not Get-ChildItem
Content search: use Grep, not Select-String
Read files: use Read, not Get-Content
Edit files: use Edit, not Set-Content
Write files: use Write, not Set-Content, Out-File, or here-strings
Communication: output text directly, not Write-Output or Write-Host

The problematic parts are especially:

• Edit files: use Edit
• Write files: use Write

1. Read-only agents

This is especially noticeable when using weaker LLMs.

For example, when an agent does not have edit / write permissions, I have observed cases where the model appears to reason roughly like this:

• The agent wants to edit a file.
• The prompt says to use Edit.
• However, the Edit tool is not available.
• Set-Content is also discouraged.
• So it tries to write the file using Node.js instead.

In other words, because this guidance exists, I believe a read-only agent may become more likely to attempt file modifications than it would without this guidance.

This is difficult to measure precisely, but I have observed this behavior in practice.

2. GPT-based models

When using GPT-based models, edit / write are not exposed, and apply_patch is the only file-editing tool provided.

However, the guidance above still says to use Edit / Write, which creates an unnecessary conflict in the prompt. This may cause wasted reasoning or tool-selection confusion.

GPT-based models are usually smart enough to eventually use apply_patch, so the issue is less likely to surface as an obvious failure. Still, the prompt guidance itself is inconsistent.

Verification of the Behavior Above

I verified the bash tool description by dumping it through the tool.definition plugin hook. The quoted text appears in the bash tool description (output.description).

Plugins

No response

OpenCode version

v1.17.7

Steps to reproduce

1. Select the Plan agent.

2. Ask the agent whether edit and write are available as tools.

3. The Plan agent says that they are not available as tools, but that the prompt still instructs it to use them.

Screenshot and/or share link

Expected Behavior

opencode should check the permissions granted to the agent, and also whether the selected model is GPT-based, then dynamically generate the use Edit / use Write guidance in the bash tool description accordingly.

Only tools that are actually available to the model should be referenced in the tool description.

Note: I have only verified the PowerShell wording, since I am using a PowerShell environment. However, similar use Edit / use Write guidance appears to exist for other shells as well.

Related issues / why this is not a duplicate

Related:

• New PowerShell tool confuses agents #20527: This is related to PowerShell-specific prompt confusion, but this issue is narrower. The problem here is that the Bash/PowerShell tool description recommends Edit / Write even when those tools are not actually exposed to the model.

• [FEATURE]: Shell-aware Bash tool prompt for Windows (Git Bash / cmd.exe / PowerShell) #16479: This proposes making the Bash tool prompt shell-aware on Windows. That is related, but this issue is not mainly about shell syntax or Git Bash / cmd.exe / PowerShell differences. The problem here is that the tool description can reference unavailable tools.

• Bash tool on Windows: silent command corruption on both Git Bash (backslash paths) and cmd.exe (multiline, quoting, variables) #15810: This reports Windows shell command corruption caused by the static Bash tool description. This issue is different: even outside the shell-syntax problem, the description may tell the model to use Edit or Write when those tools are absent.

• todowrite tool not registered in v1.15.10 despite permission configuration #29118: This is structurally similar because a tool appears to be referenced in prompt context while not being available in the actual tool list. However, todowrite tool not registered in v1.15.10 despite permission configuration #29118 is about todowrite, while this issue is specifically about file-editing guidance inside the Bash/PowerShell tool description.

• Gemini doesn't find edit tool #4200: This also involves the model trying to use an unavailable edit tool. However, this issue is about the prompt/tool-description source that can encourage such behavior when Edit / Write are not exposed.

• Plan mode: agent executes file-creation commands via bash tool directly (no sub-agent bypass) #19094: This is about Plan mode allowing file creation through Bash as a write-permission bypass. This issue is different: it does not primarily report a Bash write bypass, but rather misleading guidance in the Bash/PowerShell tool description.

• OpenAI-compatible models can call write/edit with invalid schema arguments #29142: This is about write / edit tool calls with invalid schema arguments. This issue is different because the problem occurs before schema validation: the model is instructed to prefer Edit / Write even when those tools may not be available at all.

Operating System

Windows11

Terminal

Windows Terminal