OpenCode Permission Reviewer

[!NOTE]
This is an unofficial community plugin for OpenCode. It is not affiliated
with or endorsed by Anomaly.

A tool-free AI reviewer for every ask permission. It reads the request,
your policy, and the session context, then allows once, denies with
feedback, or escalates to you — so safe actions don't wait for a keystroke,
and genuinely risky ones still get blocked or surfaced.

OpenCode pauses on every ask permission and waits for a keystroke — even
for safe, routine actions. This plugin adds a Codex-Guardian-style reviewer: a
dedicated, tool-free model session reads the pending request, bounded
transcript evidence, recovered user intent, and a tenant policy you control,
then allows once, denies with rationale, or escalates to you.
Critical risk is never allowed, and anything broken or uncertain
fails safe to manual review.

• Preserves your policy — allow continues, deny stays blocked; neither
  ever reaches the reviewer.
• Isolated, tool-free reviewer session — the reviewer runs in a scratch
  directory outside your project (no AGENTS.md, project instructions, or
  project MCP servers) with every tool denied through a wildcard session
  permission rule, so it can neither call tools (MCP included) nor request
  permissions recursively.
• Read-only enrichment — bounded, sanitized SSH / local-script / Git
  evidence for the reviewer; the filesystem is never modified.
• Auditable — one JSONL record per review, with remote commands stored as
  SHA-256, not plaintext.
• Optional TUI overlay — shows review state and gets out of the way of your
  native approval controls.

Policy adapted from OpenAI Codex Guardian
— the reviewer policy text in this project derives from Codex's auto-review
policy (Apache-2.0). The implementation is independent. See NOTICE.

Quickstart

Requirements

• Bun ≥ 1.3.0 (CI runs 1.3.0 and 1.3.5)
• OpenCode ≥ 1.18.11 and < 2 (tested with 1.18.25)
• git on PATH (only used for read-only Git-state enrichment; missing git
  degrades gracefully)
• A model provider configured in OpenCode, exposing a model that follows JSON
  schemas reliably (see Choosing the reviewer model)
• A permission policy with at least one ask rule — if nothing is ask, the
  plugin never activates (everything is already allow/deny).

See Supported versions for the full matrix.

Install

The package is published to npm. Install it as a dependency, or clone and
build when you want to run from a checkout:

# From npm
bun add opencode-permission-reviewer   # or: npm install opencode-permission-reviewer

# From a checkout (development)
git clone https://github.com/Warc0s/opencode-permission-reviewer.git
cd opencode-permission-reviewer
bun install && bun run build

What ships in dist/:

• Server — main / ./server → dist/index.js (bundled).
• TUI overlay — ./tui → dist/tui/tui.tsx (raw TSX, not a JS bundle).
  OpenCode's host compiles that entry with its own Solid/OpenTUI pipeline and
  rewrites solid-js / @opentui/* onto the host runtime. A prebundled
  dist/tui.js loads but never paints the overlay.
• CLI — ./cli / bin → dist/explain.js.

The CLI can register the plugin for you (--tui also writes tui.json;
--npm emits an npm package name instead of a path; it never clobbers an
existing entry):

bunx opencode-permission-reviewer init --npm --tui --yes

Configure

Register the plugin in your opencode.json (project or
~/.config/opencode/opencode.json). Use an absolute path to a checkout, or the
npm package name after bun add / npm install:

// opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    [
      "/absolute/path/to/opencode-permission-reviewer",
      // or: "opencode-permission-reviewer"
      {
        "model": "openai/gpt-5.6-luna", // default reviewer; override with any provider/model
        "variant": "max",
        "timeoutMs": 120000,
      },
    ],
  ],
  "permission": {
    "bash": "ask", // at least one ask rule, or the plugin is a no-op
  },
}

For the optional TUI overlay, register the same plugin block in your
tui.json (~/.config/opencode/tui.json). Keep model, variant, and
timeoutMs identical in both files so the watchdog and server agree:

// tui.json
{
  "$schema": "https://opencode.ai/tui.json",
  "plugin": [
    [
      "/absolute/path/to/opencode-permission-reviewer",
      { "model": "openai/gpt-5.6-luna", "variant": "max", "timeoutMs": 120000 },
    ],
  ],
}

Restart OpenCode fully after install or rebuild. The host imports the plugin
once at startup; a live session keeps the previous code in memory and will not
show a rebuilt overlay.

Then ask the agent to run something safe, e.g. printf hello. An auto-approved
ask resolves itself with once and the tool runs normally — without
injecting rationale into the agent context. Denials still return a short reason
the agent can act on.

Cost note: every ask action now spawns one extra child-session model
call (up to timeoutMs). Your model spend scales with how much your policy
asks. Lower the reasoning variant or raise confidenceThreshold to taste.

Choosing the reviewer model

The reviewer is a normal OpenCode model invocation (every tool denied at the
session-permission level), so it can
be any model from any provider you have configured. Three options,
identical in both config files:

• model — in provider/model form. Must match a configured provider and
  a model that provider exposes.
• variant — reasoning effort the model supports (max, high, medium,
  low, none). Passed straight through to OpenCode.
• outputFormat — how the reviewer returns its decision: json_schema
  (default; uses OpenCode's structured output, needs provider support) or
  text (ask the model to emit JSON in plain text and parse it locally). Use
  text for models that reject the json_schema format, e.g.
  opencode-go/deepseek-v4-flash.
• timeoutMs — review timeout; must match across files.

The default reviewer is openai/gpt-5.6-luna (max reasoning) — a real
model that follows JSON schemas well. Override model to use any other
provider/model you have configured; whichever you pick should follow structured
output reliably, because weaker models just produce more escalations (safe, but
noisier). Higher reasoning variants give better safety judgments at higher
cost/latency.

Reviewer models without structured-output support

Some models (for example opencode-go/deepseek-v4-flash) do not support
OpenCode's json_schema structured-output format and fail with a format error
when it is requested. For those, set "outputFormat": "text" so the reviewer
asks the model to emit its decision as plain JSON and parses it locally. This
needs the flag set identically in both opencode.json and tui.json:

{
  "model": "opencode-go/deepseek-v4-flash",
  "variant": "high",
  "outputFormat": "text",
  "timeoutMs": 120000,
}

Text mode is safe but noisier: without host-side schema enforcement the
plugin re-prompts the reviewer once if the response is unparseable (mirroring
the auto-retry that json_schema mode gets from OpenCode), and a response that
is still invalid escalates to a human rather than being auto-approved. Parsing
is deliberately strict and fail-closed: the entire response must be exactly one
JSON object (optionally wrapped in a single Markdown code fence). Prose around
the object, multiple objects, multiple fences, or any other ambiguity escalates
to a human — the parser never guesses which candidate the model meant. Every
parsed decision still passes the same strict parseDecision validation and
enforceDecision invariants (critical risk is never approved, etc.), so text
mode cannot approve anything that structured mode would not.

One caveat applies to any output format: the deterministic gates check the
decision's consistency, not its semantic correctness. A reviewer model that
misclassifies an unsafe action as low risk can produce an unsafe allow in
either mode, so pick as strong a reviewer model as your budget allows.

All configuration options

Every option is optional. Numeric/string options are clamped to safe bounds.

Config is layered: built-in defaults ← global
~/.config/opencode/permission-reviewer.jsonc ← project
.opencode/permission-reviewer.jsonc ← inline plugin options (later wins).
The project layer crosses a trust boundary: it can only tighten
security-sensitive fields, and its hardening survives even when a trusted layer
set the same field. The project layer cannot choose the reviewer model or
replace the policy text (both decide where code/context travels and what the
reviewer enforces), cannot redirect auditPath, grant actorProfiles, set
repositoryTrust: "trusted", downgrade a global enforcementMode: "enforce",
or relax a trusted escalationMode: "deny" / failure-mode deny knob /
confidenceThreshold / riskPolicy. Project values of the wrong type
(including null) are ignored, never normalized back to defaults.

A config file that exists but cannot be honored fails CLOSED on the trusted
side: a malformed or unreadable global config, or trusted policyRules
dropped by validation, marks the run degraded — reviews still run, but
automatic approval stays off (everything escalates) until the file is fixed,
and the degradation is reported on stderr. A malformed project file is
reported and ignored (the untrusted layer adds nothing anyway).

In declarative policyRules, a when condition with an unknown key (a typo),
a false flag, or an empty object drops the whole rule — a mistyped rule must
never degrade into a universal match. Catch-all rules are spelled explicitly:
omit when entirely, or use "when": { "always": true } (valid only alone).
When a catch-all comes from the trusted global config it simply matches
everything; project-sourced allow rules are still rejected outright.

Interactive vs autonomous

For unattended agents, set fail-closed in global config (not in the repo):

// ~/.config/opencode/permission-reviewer.jsonc
{
  "escalationMode": "deny",
}

Optional fine-grained hardening under interactive mode (only their own cases):

{
  "riskPolicy": {
    "onInvalidDecision": "deny", // invalid structured output → reject
    "onReviewerFailure": "deny", // timeout / transport failure → reject
  },
}

escalationMode: "deny" hardens every escalate path globally. Restrictive
settings can only block more, never relax security.

audit defaults to true. Each completed review appends one JSON object to
the audit path with mode 0600 (schemaVersion: 2): outcome, decision source,
rationale, risk, authorization, confidence, per-phase latency, reviewer model,
optional reviewerOutcome / escalationDisposition (to distinguish an explicit
deny from fail-closed escalate→deny), and a bounded SSH summary. Remote commands
are stored as SHA-256, never in clear text. Set audit: false to disable.

What you'll see

✓ Review approved · bash · rm -rf /tmp/scratch-cache
Narrowly scoped temp cleanup; matches user intent.

While reviewing, the optional TUI overlay covers the native approval controls
with Reviewing this permission and No action needed, plus the action,
reviewer model, and elapsed time. Once resolved, the overlay becomes a compact
status strip below the session: one line for the result and a second for its
rationale, with long text truncated. The review keymap is released immediately
so you can resume typing while the result stays visible for 5 s. OpenCode still
hides its editor while a permission is pending. On a technical failure or
escalation, the overlay is removed and OpenCode's native approval controls
become available with a manual review required warning. A broken TUI
transport never changes the safety decision.

How it works

1. OpenCode emits permission.asked for any ask-classified action.
2. A deterministic emergency brake rejects unmistakable root destruction and
   direct credential export before any model call. It is wrapper-aware
   (sudo, doas, env, command, nice, nohup, …), so sudo rm -rf /,
   env VAR=x rm -rf /, /bin/rm -rf /, sh -c 'rm -rf /', ssh host rm -rf /,
   and busybox rm -rf / are all caught.
3. The plugin builds bounded evidence: recent transcript, recovered user
   intent, and optional read-only enrichment for SSH commands, local
   interpreter scripts, and Git state. Intent attribution uses a single origin
   rule: synthetic/host-flagged parts are never human intent, and in a
   delegated (subagent) session no user-role message counts as human
   authorization — the initial briefing and every later task_id follow-up
   are agent-authored and surface only as labeled delegation context.
   Common credential formats are always redacted from this evidence
   (Bearer, AWS / GitHub / OpenAI / Anthropic / Slack / Google / Stripe /
   GitLab keys, JWTs, private keys, URL userinfo, cookies, and
   credential-bearing assignments) so a secret you once pasted into the
   session never travels to the reviewer's provider.
4. An isolated, tool-free reviewer session runs the reviewer model with a
   strict JSON schema and returns { outcome, risk_level, user_authorization, rationale, confidence }. The session is created in a scratch directory
   outside your project so the host does not prepend repository instructions
   (AGENTS.md, project config instructions, project MCP context) to the
   reviewer's system prompt — only your trusted global instructions remain.
   Tool denial is a wildcard session permission rule, which takes precedence
   over agent-config allows and therefore also covers MCP tools and MCP
   resource tools. If the host refuses the isolated directory, the review is
   not run in the project directory: it escalates to the human as a reviewer
   failure instead, so isolation is never silently degraded.
5. Decisions are enforced with invariants: critical risk is never approved,
   high risk with low/unknown authorization is escalated, medium risk
   with unknown authorization is escalated, low confidence is escalated,
   invalid output is escalated, errors and timeouts are escalated. Two
   deterministic blocks also apply regardless of model confidence: a degraded
   trusted config (see above) and evidence where a material part of the action
   itself was elided or truncated — neither can auto-approve. A single
   enforcement boundary then disposes every internal escalate according to
   escalationMode (manual → human; deny → reject with the original reason).
6. Approved actions get once (never always) and execute silently — the
   tool output is not annotated, so approval rationale never contaminates the
   primary agent context (rationale still lands in audit, TUI, and debug logs).
   Denials return a short actionable rationale as tool feedback. A manual reply
   that arrives mid-review supersedes the automatic one (no double reply).

By default everything fails safe to manual review. With
escalationMode: "deny", uncertainty fails closed to a reject with reason
instead — suitable for non-interactive agents.

Evidence enrichment

The reviewer never sees the raw filesystem — only bounded, sanitized evidence.
Enrichment is deliberately conservative and never makes an approval decision
by itself (one narrow deterministic exception exists for SSH, below).

• SSH commands are parsed into destination, options, remote command,
  environment/mutation/secret/stdin signals, and bounded stdin content for the
  common cat script | ssh ... python - pattern. Sensitive paths,
  credential-like literal content, binary files, unresolved shell expressions,
  and symlinks escaping approved roots are excluded.
• Local interpreter commands (Python, Node, Bun, shell, Ruby, Perl, and
  compound commands that first activate an environment) get the same bounded
  inspection when they name an explicit script. Inline code, modules, stdin
  programs, dynamic paths, and remote-only SSH arguments are not misidentified
  as local files.
• Git operations (add, commit, checkout, restore, rm) get a
  read-only pre-command snapshot: current branch, files already staged before
  the command, unstaged/untracked files, planned targets, unresolved
  shell-expanded paths, and a bounded numstat for changes that would be
  discarded. Snapshots use fixed non-interactive Git queries with locking and
  hooks disabled, a two-second timeout, and bounded output. The repository is
  never modified. Repository-configured conversion filters (clean,
  smudge, process) and diff textconv drivers are enumerated before every
  snapshot and neutralized with config overrides (including dotted names); if
  the configuration cannot be fully verified — too many filters, or the config
  scan itself fails — the snapshot is withheld rather than risk executing
  repository-configured commands. Verification and inspection are still two
  distinct moments: a filter configured between them is a residual race the
  snapshot does not claim to eliminate.

Only regular text files inside the working directory, the worktree, or
/tmp/opencode can be included. Missing, blocked, and truncated executable
stdin is explicitly identified so the reviewer fails safe.

The only deterministic SSH preflight rejection is an executable stdin file
that still does not exist after a 100 ms recheck — the primary agent gets an
actionable instruction to create it and retry. Every other SSH case (sensitive,
binary, blocked, or truncated evidence) remains a reviewer decision.

Safety properties

• Responds only to permission.asked.
• Critical-risk actions cannot be approved, even if model output says
  allow.
• High-risk actions with low or unknown authorization, and medium-risk
  actions with unknown authorization, are deterministically escalated — the
  model cannot auto-approve them by labeling a contradictory combination.
• Invalid, low-confidence, or inconsistent output is escalated to the user.
• Common credential formats are always redacted from the evidence before
  reaching the reviewer, so credentials never leak to the reviewer's provider.
• Reviewer sessions cannot request permissions recursively; every tool is
  denied by a wildcard session permission rule that also covers MCP tools and
  takes precedence over agent-config allows.
• The reviewer session runs outside the project directory, so repository
  instructions (AGENTS.md and project-config instructions) are not part of
  its system prompt; if the isolated directory cannot be established, the
  review escalates to the human as a reviewer failure rather than running
  with degraded isolation.
• A narrow deterministic emergency brake rejects unmistakable root destruction
  (including privilege-prefixed and command-string forms such as
  sudo rm -rf /, sh -c 'rm -rf /', ssh host rm -rf /) and direct
  credential-file export before any model call.
• A manual reply that arrives while a review is in flight supersedes it: the
  reviewer stops without replying or resurrecting a UI state.
• Approvals are silent to the primary agent (no tool-result annotation); denials
  return the rationale as feedback. Rationale remains in audit/TUI/debug.
• SSH commands and executable stdin receive bounded, untrusted action
  enrichment; enrichment never makes an approval decision on its own.
• Long-session user intent is recovered separately from recent operational
  context; later explicit requests supersede conflicting older ones.
• Synthetic compaction/control messages are excluded from authorization
  evidence.
• Audit failures never affect or relax the safety decision.
• UI status messages are versioned, request-scoped, bounded, and transported
  through OpenCode's own workspace TUI event channel.

Supported versions

• TUI overlay ships as raw TSX (dist/tui/tui.tsx). The host compiles
  it against its embedded Solid/OpenTUI runtime. A prebundled TUI entry loads
  but never paints. The server half does not depend on the overlay.
• Server half replies through an isolated transport chosen once at startup:
  public SDK reply with feedback message → public reply plus a separate
  feedback channel → authenticated raw HTTP
  (/permission/{requestID}/reply via input.client._client.post) → refuse
  startup. On OpenCode 1.18.x the message-bearing reply is only reachable via
  the raw transport, so the chain resolves there. That raw field is not part
  of OpenCode's public plugin API and can change without notice. If startup
  fails with "authenticated SDK transport is unavailable", file an issue
  rather than downgrading.
• OpenCode v2-generation hosts are detected at startup and refused until
  their reply contract is verified.
• Full enrichment assumes a Unix-like system (macOS/Linux). On Windows, SSH and
  Git enrichment degrade gracefully toward fail-safe manual review.
• retainReviewSessions: keep it false in normal use. Set true only to
  debug the known json_schema structured-output serialization bug in OpenCode
  1.18.11 — it keeps the child session on disk so you can inspect the malformed
  response; it does not fix the bug.
• Run opencode-permission-reviewer doctor to compare installed versions
  against the ranges above.

Troubleshooting

Enable "debug": true for verbose stderr logs while investigating. TUI load
errors ([tui.plugin] …) are printed on the TUI process console, not in
~/.local/share/opencode/log/opencode.log.

Development

bun install
bun run check          # format + lint + typecheck + tests + build (must pass before any push)
bun run test:stress    # stress suite only
bun run test:package   # npm pack ship-set smoke (raw TUI + server bundle)

bun run build bundles the server/CLI with tsup, then copies the slim TUI
source graph into dist/tui/ as raw TSX (scripts/copy-tui.ts). Do not add a
prebundled TUI entry — it will not render on the host.

The live end-to-end harness in tests/live-harness.ts runs against a real
OpenCode server + model and is not part of bun test; see
CONTRIBUTING.md.

Attribution

The reviewer policy and prompt text in src/policy.ts are adapted from
OpenAI Codex Guardian
(Apache-2.0). See NOTICE for full attribution and license details.

License

Apache License 2.0 © 2026 Warc0s