Just want the answer? Add the plugin and a permission block to opencode.json — the block is what routes tool calls into the plugin's primary hook:
{
"$schema": "https://opencode.ai/config.json",
"plugin": ["acp-opencode"],
"permission": {
"bash": "ask",
"edit": "ask",
"webfetch": "ask"
}
}
Full opencode install guide → · the controls reference → · free up to 5 agents
opencode ships a real permission system — a rule language with allow/ask/deny verdicts and a genuinely well-designed native gate — and, unlike most CLI coding agents, a first-class in-process plugin system that can stand on that permission system directly. That combination is worth a reference of its own: how the `permission` block resolves a verdict, what the ACP plugin's two hooks each see, what degrades if you skip the config, and what changes in a local, credential-free mode.
## The permission block resolves first
Every tool call in opencode is checked against the `permission` block in `opencode.json` before anything else runs. Verdicts are `allow`, `deny`, or `ask`, resolved **last-match-wins** — a broad `"bash": "ask"` followed by a more specific `"git status*": "allow"` quiets the safe case while keeping the prompt for everything riskier. Most tools default to `allow` out of the box; the two things that default to `ask` are `external_directory` (touching paths outside the project) and `doom_loop` (the same call repeated three times with identical input).
This matters for wiring a plugin in, because opencode only exposes one native way for a plugin to intercept the *approval decision itself*: the `permission.ask` hook, and it only fires for a tool call whose permission **already resolved to `"ask"`**. A tool sitting at `allow` in your config never reaches that hook at all.
## The two hooks, and what each one covers
`acp-opencode` registers on four of opencode's hooks; two of them do the interception work:
| Hook | Behavior |
|---|---|
| `permission.ask` | POSTs to `/govern/tool-use`. An ACP `allow` sets the permission status to `allow` — the native prompt is skipped, pre-approved. A `deny` blocks the call outright. An `ask` leaves the status untouched, so opencode's own **once / always / reject** gate fires exactly as it would with no plugin installed. |
| `tool.execute.before` | The deny-only backstop for tool calls that never reach `permission.ask` — anything sitting at `allow` in your `permission` config. An ACP `deny` here throws `[ACP] Denied by policy: