The plan agent wrote the file. note.txt held keep-me. After one tool call it held changed. The same call, pointed at a home that did not set edit to ask, exited 1 and left x where it was. The refusal named a rule. The write did not.
That split is what OpenCode 1.19.4 did on 19 November 2026. opencode --version printed 1.19.4. The package on disk was opencode-ai at that version. The host was Linux x86_64. Each home was a new directory passed as HOME, with XDG_CONFIG_HOME pointed at that home’s config directory. No login was run. No model call was made. The operator OpenCode config directory was not one of those homes, and its timestamp did not move.
A second binary, opencode from @opencode/cli 2.3.2, was installed under a lab prefix and was not placed on the operator path. opencode --version on that binary printed opencode v2.3.2. The package also exposes the name opencode2 for the same file. The permission page fetched the same night is written for that generation. The binary already on the path is not that generation. The files below were read by both.
Two calls, one agent name
Plan is the agent whose built-in rules are supposed to refuse edits. The debug command runs one tool as that agent and prints the result. It does not open a session and it does not ask a model what to do.
From the project that held both config files, and from the home whose global file set edit to ask:
opencode debug agent plan --tool edit --params '{"filePath":"note.txt","oldString":"keep-me","newString":"changed"}' --pure
Exit 0. The file content was changed.
From a second home whose only global field was a username, and from a directory that had note.txt and no opencode.json:
opencode debug agent plan --tool edit --params '{"filePath":"note.txt","oldString":"x","newString":"y"}' --pure
Exit 1. The first sentence of the error was that a rule prevents that tool call. The file was still x.
The agent name did not change. The tool name did not change. The difference was a later edit rule in the resolved list. If you treat the word plan as a write lock, this binary will not keep that promise once a broader edit ask is in the merged config.
The object that merged
The global file and the project file did not say the same thing, and the resolved file was not either of them.
The global file:
{
"$schema": "https://opencode.ai/config.json",
"username": "global-user",
"permission": {
"bash": {
"*": "deny",
"git status *": "allow"
},
"edit": "ask"
}
}
The project file, in the directory where the write happened:
{
"$schema": "https://opencode.ai/config.json",
"username": "project-user",
"permission": {
"bash": {
"git push *": "deny"
}
}
}
opencode debug config --pure printed one object. The username was project-user. The bash object held three keys: star deny, git status * allow, and git push * deny. Edit was still ask.
A scalar field was replaced. The bash object was not. The project file named one bash pattern and the resolved object kept the two patterns it did not name. A reader who puts a project permission.bash in a repository to express the whole shell policy has not replaced the global shell policy. The missing keys survive.
That is not what the built-in skill text on this binary says if you stop at the short sentence. opencode debug skill --pure prints a skill named customize-opencode whose location is <built-in>. That text says configs from each scope are deep-merged and that project overrides global. Deep-merge is the sentence that matches the bash object. Override is the sentence that matches the username. Both sentences are in the same skill. They are not the same operation. The printed config is the check. The sentence is not.
OPENCODE_DISABLE_PROJECT_CONFIG=1 on the same directory restored global-user and dropped git push *. The star deny and the status allow remained. The flag skips the project file. It does not skip the global file. Use it when you need to see which keys came from the home, not as a way to disable shell rules.
What build actually ran
The build agent is the default agent. Its resolved bash rules, after the merge, were star deny, then git status * allow, then git push * deny. The built-in skill says the last matching rule wins, and that insertion order matters. The three calls below are that claim, executed.
opencode debug agent build --tool bash --params '{"command":"true"}' --pure
Exit 1. The error said a rule prevents the tool call.
opencode debug agent build --tool bash --params '{"command":"git status --short"}' --pure
Exit 0. The tool ran. The command output was:
fatal: not a git repository (or any of the parent directories): .git
The permission result and the git result are different. Allow means the shell tool was permitted to start git. It does not mean the repository was valid. A later check that only looks for exit 0 will treat a missing .git as a passed permission test, which it was, and as a passed status check, which it was not.
opencode debug agent build --tool bash --params '{"command":"git push"}' --pure
Exit 1. Same class of refusal as true. The project key was present in the merged object, and it was the last match for that command. The global star deny would also have refused git push if the project key had been absent. The useful observation is the other direction: adding git push * deny did not remove git status * allow. The status command still ran.
The pattern git status * matched git status --short. The star is not limited to a missing argument list. true did not match that pattern, so it fell through to star deny.
Plan deny is not the last edit rule
On the home that set edit to ask, opencode debug agent plan --pure printed the edit rules in this order: star deny, an allow for .opencode/plans/*.md, an allow whose pattern began home/ with no leading slash, then star ask. The bash rules from the merge were in that list as well. The ask was last among the edit star rules.
The permission page fetched the same night says the last matching rule wins, and that agent rules are appended after global rules rather than replacing them. The built-in skill on 1.19.4 also says the last matching rule wins. A later sentence in that skill says per-agent permission overrides top-level permission, and that plan mode lives on the plan agent’s edit deny. Those two sentences cannot both describe the list this binary printed. The deny was earlier. The ask, which came from the top-level global file, was later.
The write is what that order did. The control, with no edit key in either file, stopped at the deny. The file with the ask in the resolved list did not stop. The debug runner did not print a prompt and wait. It applied the edit and exited 0. An interactive client might still show an ask. This runner did not. A headless check that uses debug agent is not a prompt. If the resolved list ends in ask, this command treats the edit as something it may perform.
The allow patterns were not the path under test. note.txt sits in the project directory. It matches edit star, not the plans glob. One of the printed allows on 1.19.4 lacked a leading slash. That pattern was not used for the write, and a path match against it was not measured. Do not read a printed allow as proof that the path exists or that the glob matches a real file.
On 2.3.2 the plan list for the same two files also places an edit star deny before an edit star ask. The ask is the translated global rule. The permission page says that order is the order that wins. The write itself was not repeated on 2.3.2. The 1.19.4 write is the execution result. The 2.3.2 list is the resolution result. They are the same shape. They are not the same test.
What 2.3.2 reports for the old key
opencode debug config on 2.3.2 does not print one merged object. It prints a list of sources. For the same two files it reported two documents. The global document’s permission object had become a permissions array whose actions were shell and edit. Star deny and git status * allow were shell rules. Edit ask was an edit rule with resource star. The project document contributed one shell rule, git push * deny. The username fields stayed on their own documents. A schema-only opencode.jsonc in the global directory contributed no rules. The v1 key permission and the v1 tool name bash were not what the report contained.
opencode debug agents --standalone on that directory resolved the build agent’s shell and edit rules as shell star deny, shell git status * allow, edit star ask, then shell git push * deny. Plan’s list kept its own edit star deny ahead of that edit star ask, then included the same shell rules. A search of the resolved list for the action bash does not find the deny that 1.19.4 enforced under that name. The deny is present under shell.
That rewrite is not symmetric. A project whose file already used the v2 array, with action set to bash and effect set to deny, was accepted by 2.3.2. debug agents --standalone kept the action name bash and did not add a shell deny. The old object is renamed on the way in. A new array that still says bash is left as bash. This run did not send a shell command through 2.3.2, so it does not say whether an action named bash matches the shell tool on that binary. It does say that the resolved list will not show a shell deny unless the action string is shell. If you are checking 2.3.2, look for the name the binary stored, not the name the older file used.
The current permission page uses permissions, action, resource, and effect, and its shell examples use the action shell. That is the 2.3.2 shape. It is not the shape 1.19.4 will load.
The page the installed binary refuses
A project file written the way that page is written:
{
"$schema": "https://opencode.ai/config.json",
"permissions": [
{ "action": "shell", "resource": "*", "effect": "deny" }
],
"username": "v2-key-user"
}
On 1.19.4, opencode debug config --pure exited 1. The error was:
Configuration is invalid at <project>/opencode.json
V2 permissions are not supported by OpenCode V1. Use V1 "permission" rules or run opencode2. permissions
The same exit happened for debug agent build --tool bash. The tool did not run. The config load failed first. The field name at the end of the error is permissions. The message tells you to use the v1 permission object, or to run opencode2.
The 2.3.2 package provides opencode2 as a second name for its binary. The installed opencode-ai 1.19.4 package does not. Following the error’s second suggestion on a host that only has 1.19.4 produces a missing command, not a second policy. Following the first suggestion means writing permission, with bash as a key inside that object, and then reading debug config to see the merge.
On 2.3.2 the same v2-shaped file loaded. debug config reported the shell star deny. debug agents --standalone put that deny on the build agent. The page and that binary agree with each other. They do not agree with 1.19.4.
npm listed opencode-ai 1.19.6 as a published version during this run. The binary under test was 1.19.4. Nothing here was repeated on 1.19.6, and the installed package was not upgraded. The 2.3.2 release notes published on 18 November 2026 describe prompt caching and compaction. They do not describe this key split. The split showed up when the same files were handed to both binaries.
Skills the project file never named
The project opencode.json did not name a skill. opencode debug skill --pure still listed skills from outside that file.
A skill at ~/.agents/skills/agents-only/SKILL.md was listed, with that path as its location. A skill at .claude/skills/proj-claude/SKILL.md was listed. A skill with no description, at .opencode/skills/nodesc/SKILL.md, was listed too. The built-in skill text says a skill without a description is filtered out and never surfaced to the model. debug skill is not that model list. This run did not start a model session, so it does not say the model received nodesc. It does say the debug inventory is not the filter the skill text describes.
The same name does not mean both files are visible. A home skill at ~/.claude/skills/claude-only/SKILL.md and a project skill at .opencode/skills/claude-only/SKILL.md shared the name claude-only. The inventory printed the project path and the project description. The home body was not the body in that row.
OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 dropped proj-claude and left agents-only. The flag name says Claude. The agents directory is not Claude, and the flag did not drop it. OPENCODE_DISABLE_EXTERNAL_SKILLS=1 dropped both agents-only and proj-claude, and left the skills under .opencode/skills. Neither flag is a substitute for reading the inventory. A permission review that only opens the project opencode.json will not see these directories, and a deny on the skill action was not part of this test. The load happened before any skill permission rule was written.
Verify the binary you will launch
Start with the version line. opencode --version on the path you will actually use is the binary the job will load. A lab prefix does not change that path. If the line is 1.19.4, do not paste the current permission page into opencode.json. Write a permission object. Use bash as the key if you mean the shell tool. Then print the merge.
opencode debug config --pure
opencode debug agent plan --pure
opencode debug agent build --pure
Read the edit rules from top to bottom. If star ask or star allow appears after the plan deny, plan is not a write lock on this binary. Read the bash rules the same way. A project file that names one pattern has not deleted the patterns above it.
Run one command that should be refused and one that should be allowed, through debug agent, before you trust the list. On this binary the refused call exits 1 and says a rule prevents the tool call. The allowed call exits 0 even when the command itself fails, as git status --short did outside a repository. Match the error text, not only the exit code.
If the file must use the permissions array, run the 2.3.2 binary, including the opencode2 name if that is what the package installed, and read debug agents --standalone. Confirm the action string is shell when you meant the shell tool. A rule that still says bash inside a v2 array was stored as bash on 2.3.2. Do not assume the loader renamed it. This run did not execute that rule.
OPENCODE_DISABLE_PROJECT_CONFIG=1 is the control for the project file. The global keys remain. opencode debug skill --pure is the control for skill directories the project file does not name. OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1 does not cover ~/.agents/skills on 1.19.4. OPENCODE_DISABLE_EXTERNAL_SKILLS=1 did, in this home.
Do not point any of these commands at a home whose sessions or config you need to keep until you have read opencode debug paths and confirmed the config directory. The homes in this run were disposable. The operator directory was not one of them.
The plan write happened because edit ask was later than edit deny, and the debug runner performed the edit. The same two files are a shell policy on 2.3.2, and the page that documents that policy stops 1.19.4 before either tool runs. Check the version, then the resolved list, then one refused call and one allowed call.
Sources
- OpenCode 1.19.4, package
opencode-ai, version line1.19.4, Linux x86_64, 19 November 2026.debug config,debug skill,debug agent, anddebug agent --toolran withHOMEandXDG_CONFIG_HOMEset to disposable directories. No login was run. No model call was made. - OpenCode 2.3.2, package
@opencode/cli, version lineopencode v2.3.2, installed under a lab prefix the same night.debug configanddebug agents --standaloneread the same v1 files and a separate v2-shaped file. The edit write was not repeated on this binary. - Built-in skill
customize-opencodeprinted byopencode debug skill --pureon 1.19.4. It says project overrides global, that the last matching permission rule wins, and that plan mode lives on the plan agent’s edit deny. - OpenCode permissions, fetched 19 November 2026. The page uses a
permissionsarray, the actionshell, and last-match evaluation. It says agent rules are appended after global rules and that plan denies edits except under~/.opencode/plan. - OpenCode skills, fetched 19 November 2026. The discovery table includes
~/.claude/skills,~/.agents/skills, and project.opencode/skills. - OpenCode v2.3.2 release, published 18 November 2026. The notes cover prompt caching and compaction. They do not describe the v1
permissionkey or the plan edit order measured here.