[opencode-agent]

Issue for this PR

Closes #55127

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

The Plan section in agents.mdx said file edits and bash default to ask. That doesn't match plugin/plan.ts:

• Edits/writes/patches are deny outside ~/.opencode/plan/, with no prompt.
• There is no shell rule, so shell commands fall through to the normal permission config.
• question is allowed.

It also documents why #55127 happens: Plan's defaults come before the top-level permission config and the last match wins, so a global "edit": "allow" or "*": "allow" also applies to Plan. The section now shows how to keep Plan read-only (and gate shell) with agent.plan.permission.

It also renames the tool from bash to shell everywhere it's referenced as a tool in the docs, English and translations. That covers permission/tools config keys (JSON, YAML frontmatter, and the managed-config plist), the permission tables and lists, the tools.mdx heading, the custom-tool collision example, the plugin input.tool check, and prose about shell-command permissions. The TUI ! section is now "Shell commands" (#shell-commands). V1 bash keys still migrate to shell, so existing configs keep working.

These still say bash on purpose because they mean the bash program, not the tool: install one-liners (| bash), ```bash fences, "bash profile" instructions, /bin/bash, ~/.bashrc, Git Bash, the bash language server, and .bash file extensions.

How did you verify your code works?

Ran a throwaway core test, not included in this PR, that loads the agent, plan, and config-agent plugins and evaluates Plan's permissions:

• No config: edit outside the plan directory is deny, edit inside ~/.opencode/plan/ is allow, shell is allow, and question is allow.
• Global "edit": "allow" only: edits outside the plan directory are allow (the [Bug] Global/project "edit": "allow" silently overrides built-in plan agent's read-only deny (edit/write/patch modify files in Plan mode) #55127 behavior).
• Global "edit": "allow" plus the documented agent.plan example: edits outside the plan directory are deny, edits in the plan directory are allow, and shell is ask.

For the rename: "shell" keys go through the same V1 normalization (normalizeAction is the identity for shell, and bash maps to shell). After the change, a grep of the docs for bash finds only the program references listed above. Prettier passes on the changed files.

Screenshots / recordings

Not a UI change.

Checklist

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

Requested by: @rekram1-node (Aiden Cline via Slack)

[opencode-agent]

The updated Plan section matches the current code on dev. This is a docs-only change, so there was nothing to run; I checked each claim against the code instead.

• plugin/plan.ts: Plan allows question, denies edit * and allows edit ~/.opencode/plan/*. A blocked edit shows an error message instead of asking. There is no shell rule.
• config/plugin/agent.ts: top-level permissions are added after Plan's own rules, and per-agent rules are added after those. Since evaluate uses the last matching rule, the explanation and the agent.plan.permission example are both right.
• The example works as written: bash is converted to shell, and ~/ in edit paths is expanded to the home folder.

Public API: unchanged.

One thing for maintainers to decide: "Closes #55127" closes a reproduced bug report with the behavior unchanged, which treats it as intended.

Related: #39715, #53955