open-guardian

LLM permission judge for OpenCode. Inspired by Codex Guardian: instead of approving every escalated action by hand, a fast model reviews each one against a written policy and the session transcript, then allows it, denies it, or escalates to you.

Every verdict scores two independent axes before deriving an outcome:

• risk_level — intrinsic risk of the exact action (low / medium / high / critical)
• user_authorization — whether trusted user messages authorize that specific action (unknown / low / medium / high)

Only user messages count as trusted evidence. Assistant output, tool results, and quoted file contents can never expand approval scope, which blunts prompt injection through poisoned context.

risk	authorization	effect
low	any	allow
medium	medium / high	allow
medium	low / unknown	ask
high	medium / high	ask
high	low / unknown	deny
critical	any	deny

Judge errors, timeouts, and unparseable verdicts always fall back to ask, so a broken judge degrades to OpenCode's normal permission prompt, never to silent approval.

Install

// opencode.jsonc
{
  "plugins": ["open-guardian"]
}

The judge only sees decisions that resolve to ask, so pair it with a permissions floor. Route what you want judged to ask, keep the non-negotiables as deny (a configured deny is final — the judge cannot override it):

{
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "shell", "resource": "git status *", "effect": "allow" },
    { "action": "shell", "resource": "git diff *", "effect": "allow" },
    { "action": "read", "resource": "*.env", "effect": "deny" },
    { "action": "read", "resource": "*.env.*", "effect": "deny" },
    { "action": "read", "resource": "*.env.example", "effect": "allow" },
    { "action": "shell", "resource": "git push --force*", "effect": "deny" }
  ]
}

Options

{
  "plugins": [
    {
      "package": "open-guardian",
      "options": {
        "model": "openai/gpt-5.6-luna",   // judge model, "provider/model-id[#variant]"
        "timeout": 15000,                  // ms before falling back to ask
        "actions": ["shell"],              // permission actions to judge
        "policy": "/path/to/policy.md",    // replace the bundled policy entirely
        "rules": "Deny anything touching production databases.", // append inline rules
        "log": false                       // decision log path, or false to disable
      }
    }
  ]
}

Defaults: judge shell only, 15s timeout, bundled policy.md, decisions logged to ~/.local/share/opencode/guardian/decisions.jsonl.

Customizing the policy

Three layers, from broadest to narrowest:

1. policy option — path to a file that replaces the bundled policy. Start from policy.md and edit; keep the output contract section intact.
2. rules option — inline text appended to the policy as an extra section. Good for a personal rule or two without maintaining a file.
3. .opencode/guardian.md — if this file exists in the project, its contents are appended as project rules. Commit it so the whole team's judge enforces repo-specific constraints (deploy commands, migration safety, protected infrastructure).

Later sections take precedence when they conflict, but no layer can weaken the critical category: secret exfiltration and irreversible destruction stay denied.

Decision log

Each judged action appends one JSON line with the resources, both axis scores, the effect, and the reason:

{"time":"...","action":"shell","resources":["rm -rf ~/Documents/backups"],"verdict":{"effect":"deny","risk":"high","authorization":"unknown","reason":"Irreversibly deletes a potentially important directory without trusted user authorization."}}

Use it to audit the judge and tune the policy.

Policy

The bundled policy.md defines evidence-handling rules, the risk taxonomy, authorization scoring, and the derivation table. Point the policy option at your own file to customize any of it.

Caveats

• OpenCode shell commands run with your full user authority and no sandbox. Keep destructive non-negotiables as static deny rules; the judge is a convenience layer above that floor, not a substitute for it.
• The judge sees session context. The trusted/untrusted evidence split mitigates prompt injection but is not a proof; critical-category actions are denied regardless of claimed authorization for that reason.
• Verdicts are cached per session and command, so a repeated command reuses its verdict without a second model call.