@mortz.prk/opencode-auto-mode 1.0.0 → 1.0.2

package/README.md

@@ -28,19 +28,38 @@ needed:
 }
 ```
 
-Restart OpenCode after saving:
-
-```sh
-opencode service restart
-```
+OpenCode watches configuration files and reloads plugins after a save, so no
+restart is needed. If a change does not take effect, run `/reload` in the TUI to
+force a full reload.
 
 There is no default review pipeline, and empty options are invalid. Add at least
 one review entry. Built-in checks deny dangerous shell commands, allow common
-read-only commands, and leave everything else as `ask`.
+read-only commands, and send other parsed commands to the configured reviewers.
+Dynamic syntax such as command substitution, nested shells, and stateful builtins
+still requires manual approval.
 
 The snippets below change parts of that configuration; keep your `classifiers`
 list when adding other options.
 
+### How a shell command is classified
+
+Commands are parsed before they are judged, so text that merely mentions a
+dangerous word — a commit message, a search pattern, a heredoc body — is not
+treated as a dangerous operation. Denials apply to the parsed executable and its
+arguments, and nested shells are inspected recursively.
+
+Read-only allowlisting checks the executable **and** its flags. Options that
+write files or run programs (`rg --pre`, `sort -o`, `tree -o`, `file -C`,
+`bat --pager`, `hostname NAME`, `uniq IN OUT`) are handed to the reviewers
+instead of being auto-approved.
+
+A shell result is final when it is `deny` or `ask`: `ask` means manual approval,
+even if a model reviewer is configured. Read-only auto-approval is narrower than
+the pipeline: for shell actions, the static stage auto-approves only commands the
+guard recognizes as read-only. Every other parsed command that is not denied —
+including a write such as `pwd > marker` — goes to the configured reviewers, and a
+model reviewer may allow it. With no reviewer configured, it stays `ask`.
+
 ## Add a typed decision model
 
 ```jsonc
@@ -101,8 +120,31 @@ Entries run in order. Add as many as you need:
 }
 ```
 
-An entry can allow, deny, or ask, which stops the pipeline. If it abstains or
-fails, the next entry runs. If nothing decides, the action remains `ask`.
+An entry can allow, deny, or ask, which stops the pipeline. An entry that abstains
+hands the action to the next entry. If nothing decides, the action remains `ask`.
+
+## Time limit and failures
+
+A review never blocks a permission prompt indefinitely. One deadline covers every
+entry in the pipeline, including both model calls of an `llm` entry:
+
+```jsonc
+{ "options": { "reviewTimeoutMs": 60000 } }
+```
+
+`reviewTimeoutMs` accepts 1000–120000 and defaults to 60000. When the deadline
+passes, provider and context requests are aborted and the action is asked with
+`Auto-mode review deadline exceeded`. Interrupting a session also abandons its
+review, so a stopped turn cannot later receive an automatic approval.
+
+Failures are reported with a bounded cause — `deadline`, `timeout`, `cancelled`,
+`provider`, `invalid-output`, or `context` — in the audit log and in OTLP
+(`error.kind`), while the user-facing message stays generic.
+
+A typed decision reviewer that is unavailable or returns a malformed response
+abstains, so the next entry runs. An `llm` entry behaves differently: a timeout
+or provider error abstains, but an unparseable final answer is an `ask` (manual
+approval) with `invalid-output`, and the pipeline stops there.
 
 ## Use it for specific agents
 
@@ -125,7 +167,40 @@ permissions and leave global permissions unchanged:
 
 A passive indicator shows when the plugin is reviewing the current session.
 It is enabled by default. Set `tui: false` in plugin options to hide it.
-OpenCode's own permission dialog handles manual approvals.
+Invalid options show `auto-mode: invalid config` in the same place and raise an
+error toast when the configuration is loaded. OpenCode's own permission dialog
+handles manual approvals.
+
+The indicator window is longer than the maximum review deadline, so a slow
+review stays visible until it resolves.
+
+## Desktop app (preview)
+
+OpenCode 2.2.0+ can load the plugin's GUI entry in the desktop app. It adds a
+composer pill and an **Auto-mode** side panel showing whether the current session
+is being reviewed and how recent actions were decided, plus a command-palette
+entry to open the panel.
+
+The GUI only reads state. Every permission decision still comes from the server
+part, so disabling the GUI never disables automatic review.
+
+The GUI is loaded from the desktop app's own background server and reads that
+server's auto-mode state. If you connect the app to another server, that server's
+reviews do not appear in the panel.
+
+The desktop app reads plugins only from the **global** `opencode.json(c)`. If
+your TUI configuration lives in `cli.json`, add the package to the global file as
+well:
+
+```jsonc
+{
+  "plugins": [{ "package": "@mortz.prk/opencode-auto-mode", "options": { "classifiers": [{ "type": "static" }] } }]
+}
+```
+
+Turn the GUI off without removing the plugin in **Settings → Extensions →
+Plugins**. The GUI plugin API is experimental and may change between OpenCode
+releases; the server and TUI parts do not depend on it.
 
 ## Review options
 
@@ -153,6 +228,59 @@ Each LLM or typed decision reviewer can have its own policy:
 policy; an empty list clears that list. Policies are independent between
 reviewers and do not apply to static checks or replace OpenCode permissions.
 
+## All plugin options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `classifiers` | — | Ordered review entries; at least one is required. |
+| `reviewTimeoutMs` | `60000` | Deadline for one complete review (1000–120000). |
+| `auditLog` | off | `true` writes the default JSONL file; a string sets the path. |
+| `otlp` | off | `true` uses OpenCode's OTLP environment; an object sets `endpoint`, `headers`, and `timeoutMs`. |
+| `tui` | on | Set `false` to hide the TUI indicator. |
+
+Static entries accept `allowInProjectEdits`. Decision entries accept
+`minConfidence`, `timeoutMs`, `apiKeyEnv`, and `endpoint` (loopback `laya` only;
+defaults to `http://127.0.0.1:8000/v1/systemone`). OpenCode reloads the plugin
+when you save, so option changes apply without a restart; run `/reload` in the
+TUI if a change does not take effect. Invalid options disable automatic approval
+and are reported in the TUI and over the status RPC.
+
+## Data that leaves the machine
+
+Reviewers see the proposed action, its resources, the session directory, the
+requesting agent, the pending permission `metadata` and `source`, and a bounded
+transcript of recent user messages and tool inputs (12 KB, with the head and tail
+of each tool input). Nothing else about the session is sent.
+
+* A model reviewer receives that material through OpenCode's own session model or
+  the `model` you configure.
+* A typed decision reviewer receives it at the configured provider endpoint.
+* Audit records and OTLP log records keep the action, agent, up to 16 resources,
+  a short reason, and, on failure, a short error detail. Both pass the record
+  through one sanitizer, which bounds these fields — 128 characters for the
+  action and agent, 64 for the stage, 512 for each resource, reason, and error
+  detail — but does **not** redact text.
+* OTLP exports logs and traces as separate streams (`/v1/logs` and `/v1/traces`).
+  Trace root attributes use the same sanitizer, so their action, agent, and stage
+  are bounded like the log fields. Each reviewer attempt adds a child span with
+  its model and outcome; the `model` attribute is not clipped. Traces do not
+  include resources, reasons, or error-detail text.
+* Text in every stream is unredacted, including the action and agent. Traces
+  carry the action and agent; logs carry those plus resources, reasons, and
+  error details. These fields may be sensitive, and resources or reasons can
+  contain inline file contents or shell commands, including credentials such as
+  an `Authorization` header. Audit JSONL keeps the same unredacted fields as OTLP
+  logs. Enable `auditLog` or `otlp` only if you are comfortable storing or
+  exporting that material.
+* Records do not include the reviewer prompt, the session transcript, or API keys
+  configured for providers.
+
+## Platform limits
+
+* Windows always asks for shell actions; the guard only parses POSIX syntax.
+* Reviews happen inside the OpenCode server, so a headless or remote TUI behaves
+  the same as a local one. The desktop GUI needs OpenCode 2.2.0+.
+
 ## Auditing
 
 Enable the audit log in plugin options:
@@ -167,7 +295,8 @@ Enable the audit log in plugin options:
 
 Decisions are appended as JSON lines to
 `$XDG_STATE_HOME/opencode-auto-mode/decisions.jsonl`. Replay recorded tool calls
-without executing anything:
+without executing anything (run from a checkout; it reads the OpenCode database
+read-only and needs `--config` if your global config is not at a default path):
 
 ```sh
 bun scripts/replay.ts [--days 14] [--session ID] [--agent build|any] [--json]
@@ -192,9 +321,13 @@ bun install
 bun test
 bun run lint
 bun run typecheck
+bun run build:gui
 bun run test:integration
 ```
 
+`build:gui` writes `dist/gui-experimental.cjs`, the file the `./gui-experimental`
+export points at. It runs automatically before publishing.
+
 ## Credit
 
 Created originally by [Andrew Mellen (mellena1)](https://github.com/mellena1) in

package/dist/gui-experimental.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const t=require("solid-js/web"),c=require("solid-js"),u=require("@opencode/plugin/gui"),C=require("@opencode/plugin/rpc"),q={type:"object",properties:{enabled:{type:"boolean"},configError:{type:"string"},classifiers:{type:"array",items:{type:"string"}},reviewTimeoutMs:{type:"number"},reviewing:{type:"array",items:{type:"object",properties:{sessionID:{type:"string"},reviewID:{type:"string"},startedAt:{type:"number"}},required:["sessionID","reviewID","startedAt"],additionalProperties:!1}},recent:{type:"array",items:{type:"object",properties:{reviewID:{type:"string"},sessionID:{type:"string"},action:{type:"string"},decision:{type:"string"},stage:{type:"string"},reason:{type:"string"},durationMs:{type:"number"},at:{type:"number"},errorKind:{type:"string"}},required:["reviewID","sessionID","action","decision","stage","reason","durationMs","at"],additionalProperties:!1}}},required:["enabled","classifiers","reviewTimeoutMs","reviewing","recent"],additionalProperties:!1},$={type:"object",properties:{reviewID:{type:"string"},sessionID:{type:"string"},action:{type:"string"},decision:{type:"string"},stage:{type:"string"},reason:{type:"string"},durationMs:{type:"number"},at:{type:"number"},errorKind:{type:"string"}},required:["reviewID","sessionID","action","decision","stage","reason","durationMs","at"],additionalProperties:!1},j=C.Rpc.define({id:"opencode-auto-mode",methods:{status:{input:{type:"object",properties:{sessionID:{type:"string"}},additionalProperties:!1},output:q},decisions:{input:{type:"object",properties:{sessionID:{type:"string"},limit:{type:"number"}},additionalProperties:!1},output:{type:"array",items:$}}},events:{decision:{schema:$}}});function K(e){return e===void 0?void 0:{key:e.key,sessionID:e.id,ownServer:e.server.builtin}}function T(){let e,i=0,l=0,s=0;return{select(o){return o===e?!1:(e=o,l=i,s=0,!0)},begin(o){if(o===e)return++i},accept(o){return o<=l||o<=s?!1:(s=o,!0)}}}function k(e,i){const l=T();return async s=>{if(l.select(s?.key)&&i(void 0),s===void 0||!s.ownServer)return;const o=l.begin(s.key);if(o!==void 0)try{const v=await e(s.sessionID);l.accept(o)&&i(v)}catch{}}}function y(e){return e?.recent.at(-1)}function A(e){return e===void 0||e.reviewing.length===0&&e.recent.length===0?"empty":"entries"}function L(e){if(e===void 0)return;if(e.reviewing.length>0)return"auto-mode reviewing…";const i=y(e);if(i!==void 0)return i.errorKind!==void 0?`auto-mode ${i.decision}: ${i.errorKind}`:`auto-mode ${i.decision}`}function O(e,i,l){if(e===void 0||e.reviewing.length>0)return!1;const s=y(e);return s!==void 0&&i-s.at>l}var E=t.template('<div style="padding:8px 12px;font-size:12px;display:flex;flex-direction:column;gap:6px">'),_=t.template("<div>"),N=t.template("<div> "),F=t.template("<div style=display:flex;flex-direction:column;gap:2px><span style=font-weight:600> · </span><span></span><span style=opacity:0.6> · <!>ms · ");const R=3e3,x=3e4,D={allow:"success",ask:"warning",deny:"danger"},z=u.Plugin.define({i18n:{en:{"command.open":"Open auto-mode decisions","panel.title":"Auto-mode","panel.empty":"No decisions in this session yet.","panel.disabled":"Auto-mode has no valid configuration; automatic review is disabled. Host permissions still apply.","panel.reviewing":"Reviewing…","pill.title":"Auto-mode decisions"}},setup(e){const[i,l]=c.createSignal(void 0),s=k(r=>e.client.rpc(j).status({sessionID:r}),l),o=()=>K(e.sessions.current()),[v,I]=c.createSignal(Date.now()),m=()=>{I(Date.now()),s(o())};u.createKeyed(()=>o()?.key,m,{otherwise:m});const S=setInterval(m,R);c.onCleanup(()=>clearInterval(S));const M={id:"decisions",get title(){return e.t("panel.title")},closable:"compact",fallback:!0};e.add(u.Panel,{id:"decisions",region:"side",mobile:{get title(){return e.t("panel.title")},order:60,kind:"menu",icon:"shield"},list:r=>r.open.includes("decisions")?[M]:[],render:()=>(()=>{var r=E();return t.insert(r,(()=>{var p=t.memo(()=>i()?.enabled===!1);return()=>p()?(()=>{var n=_();return t.insert(n,()=>e.t("panel.disabled")),n})():null})(),null),t.insert(r,(()=>{var p=t.memo(()=>A(i())==="empty");return()=>p()?(()=>{var n=_();return t.insert(n,()=>e.t("panel.empty")),n})():[t.createComponent(c.For,{get each(){return[...i()?.reviewing??[]]},children:n=>(()=>{var a=N(),d=a.firstChild;return t.insert(a,()=>e.t("panel.reviewing"),d),t.insert(a,()=>n.reviewID,null),a})()}),t.createComponent(c.For,{get each(){return[...i()?.recent??[]].reverse()},children:n=>(()=>{var a=F(),d=a.firstChild,f=d.firstChild,w=d.nextSibling,g=w.nextSibling,b=g.firstChild,h=b.nextSibling;return h.nextSibling,t.insert(d,()=>n.decision,f),t.insert(d,(()=>{var P=t.memo(()=>n.errorKind===void 0);return()=>P()?"":` (${n.errorKind})`})(),f),t.insert(d,()=>n.action,null),t.insert(w,()=>n.reason),t.insert(g,()=>n.stage,b),t.insert(g,()=>Math.round(n.durationMs),h),t.insert(g,()=>new Date(n.at).toLocaleTimeString(),null),a})()})]})(),null),r})()}),e.add(u.Command,()=>({id:"open",title:e.t("command.open"),group:"tools",run:()=>{const r=e.sessions.current();r&&e.layout.toggle(`${e.id}:decisions`,r)}})),e.add(u.ComposerPill,{id:"status",order:20,show:()=>{const r=i(),p=L(r);if(p===void 0||O(r,v(),x))return;const n=(r?.reviewing.length??0)>0;return{label:p,tone:n?"warning":D[y(r)?.decision??"allow"],title:e.t("pill.title"),rows:(r?.recent??[]).slice(-5).reverse().map(a=>({id:a.reviewID,label:`${a.decision} · ${a.action}`,tone:D[a.decision],detail:a.reason}))}}})}});exports.default=z;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mortz.prk/opencode-auto-mode",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Configurable automatic permission review for OpenCode v2.",
   "author": {
     "name": "Andrew Mellen",
@@ -17,7 +17,8 @@
   "type": "module",
   "license": "MIT",
   "files": [
-    "src"
+    "src",
+    "dist"
   ],
   "exports": {
     ".": {
@@ -27,38 +28,47 @@
     "./tui": {
       "import": "./src/tui.tsx",
       "types": "./src/tui.tsx"
-    }
+    },
+    "./rpc": {
+      "import": "./src/rpc.ts",
+      "types": "./src/rpc.ts"
+    },
+    "./gui-experimental": "./dist/gui-experimental.cjs"
   },
   "scripts": {
     "lint": "eslint . --max-warnings=0",
     "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "test:integration": "bun run integration/opencode.ts"
+    "test:integration": "bun run integration/opencode.ts",
+    "build:gui": "vite build",
+    "prepublishOnly": "bun run build:gui"
   },
   "dependencies": {
     "@opencode/ai": "2.0.30",
-    "@opencode/plugin": "^2.0.14",
-    "@opencode/schema": "^2.0.30",
+    "@opencode/plugin": "2.2.0",
+    "@opencode/schema": "2.2.0",
     "effect": "4.0.1",
     "shell-quote": "1.12.0"
   },
   "peerDependencies": {
-    "@opentui/core": ">=0.5.10",
-    "@opentui/solid": ">=0.5.10",
+    "@opentui/core": ">=0.6.6",
+    "@opentui/solid": ">=0.6.6",
     "solid-js": ">=1.9.0"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@opencode/theme": "^2.0.14",
-    "@opentui/core": "0.6.6",
+    "@opencode/theme": "2.2.0",
+    "@opentui/core": "0.7.0",
     "@opentui/keymap": "^0.6.6",
-    "@opentui/solid": "0.6.6",
+    "@opentui/solid": "0.7.0",
     "@types/node": "^26.6.4",
     "@types/shell-quote": "1.7.5",
     "@typescript/native": "npm:typescript@^7.0.2",
     "eslint": "^10.12.0",
-    "solid-js": "1.9.17",
+    "solid-js": "1.9.12",
     "typescript": "npm:@typescript/typescript6@^6.0.2",
-    "typescript-eslint": "^8.71.1"
+    "typescript-eslint": "^8.71.1",
+    "vite": "^7.0.0",
+    "vite-plugin-solid": "^2.11.0"
   }
 }

package/src/audit.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import type { ReviewErrorKind } from "./errors.js";
 
 export interface AuditRecord {
   ts: string;
@@ -15,6 +16,7 @@ export interface AuditRecord {
   reason: string;
   durationMs: number;
   error?: boolean;
+  errorKind?: ReviewErrorKind;
   errorDetail?: string;
   traceID?: string;
   spanID?: string;
@@ -26,6 +28,10 @@ const MAX_BYTES = 10 * 1024 * 1024;
 const MAX_RESOURCES = 16;
 const MAX_RESOURCE_CHARS = 512;
 const MAX_REASON_CHARS = 512;
+const MAX_ACTION_CHARS = 128;
+const MAX_AGENT_CHARS = 128;
+const MAX_STAGE_CHARS = 64;
+const ERROR_KINDS: readonly ReviewErrorKind[] = ["deadline", "timeout", "cancelled", "provider", "invalid-output", "context"];
 
 export function defaultAuditPath(): string {
   const base = process.env.XDG_STATE_HOME || path.join(os.homedir(), ".local", "state");
@@ -36,6 +42,23 @@ function clip(value: string, max: number): string {
   return value.length > max ? `${value.slice(0, max - 1)}…` : value;
 }
 
+/**
+ * Bounds every exported record. Local audit and OTLP must describe the same
+ * payload, so both call this before serialising anything.
+ */
+export function sanitizeRecord(record: AuditRecord): AuditRecord {
+  return {
+    ...record,
+    action: clip(record.action, MAX_ACTION_CHARS),
+    resources: record.resources.slice(0, MAX_RESOURCES).map((resource) => clip(resource, MAX_RESOURCE_CHARS)),
+    reason: clip(record.reason, MAX_REASON_CHARS),
+    stage: clip(record.stage, MAX_STAGE_CHARS),
+    ...(record.agent === undefined ? {} : { agent: clip(record.agent, MAX_AGENT_CHARS) }),
+    ...(record.errorKind === undefined ? {} : { errorKind: ERROR_KINDS.includes(record.errorKind) ? record.errorKind : "provider" }),
+    ...(record.errorDetail === undefined ? {} : { errorDetail: clip(record.errorDetail, MAX_REASON_CHARS) }),
+  };
+}
+
 export function createAuditLog(setting: boolean | string | undefined): AuditLog | undefined {
   if (setting === undefined || setting === false) return undefined;
   const file = typeof setting === "string" ? setting : defaultAuditPath();
@@ -46,13 +69,7 @@ export function createAuditLog(setting: boolean | string | undefined): AuditLog
         fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
         try { if (fs.statSync(file).size > MAX_BYTES) fs.renameSync(file, `${file}.1`); } catch { /* no file yet */ }
         fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_APPEND | fs.constants.O_NOFOLLOW, 0o600);
-        const safe: AuditRecord = {
-          ...record,
-          resources: record.resources.slice(0, MAX_RESOURCES).map((resource) => clip(resource, MAX_RESOURCE_CHARS)),
-          reason: clip(record.reason, MAX_REASON_CHARS),
-          ...(record.errorDetail === undefined ? {} : { errorDetail: clip(record.errorDetail, MAX_REASON_CHARS) }),
-        };
-        fs.writeSync(fd, `${JSON.stringify(safe)}\n`);
+        fs.writeSync(fd, `${JSON.stringify(sanitizeRecord(record))}\n`);
       } catch {
         // Auditing is best effort and must not interrupt permission review.
       } finally { if (fd !== undefined) fs.closeSync(fd); }

package/src/classifier.ts

@@ -2,6 +2,7 @@ import { classify } from "./tiers.js";
 import type { ClassifierStage } from "./config.js";
 import type { PermissionRequest, ReviewResult, StageResult } from "./reviewer.js";
 import { guardShell } from "./shell.js";
+import type { ReviewErrorKind } from "./errors.js";
 
 export async function compositeDecision(
   stages: ClassifierStage[],
@@ -15,8 +16,14 @@ export async function compositeDecision(
     const result = classify(request.action, request.resources);
     if (result.tier === "auto-deny") return { decision: "deny", reason: result.reason, stage: "static" };
   }
-  if (shellResult) return { ...shellResult, stage: "shell-guard" };
+  if (shellResult) {
+    // Parsed read-only results feed the static stage, but never bypass a model-only pipeline.
+    const hasStatic = stages.some((stage) => stage.type === "static");
+    if (shellResult.decision !== "allow" || hasStatic)
+      return { ...shellResult, stage: shellResult.decision === "allow" ? "static" : "shell-guard" };
+  }
   let abstained: string | undefined;
+  let abstainedKind: ReviewErrorKind | undefined;
   for (const stage of stages) {
     if (stage.type === "static") {
       const result = classify(request.action, request.resources, {
@@ -25,13 +32,22 @@ export async function compositeDecision(
       if (result.tier === "auto-allow") return { decision: "allow", reason: result.reason, stage: "static" };
     } else {
       const result = await review(stage);
-      if (result.decision === "abstain") { abstained = result.reason; continue; }
-      return { decision: result.decision, reason: result.reason, stage: result.stage ?? stage.type };
+      if (result.decision === "abstain") {
+        abstained = result.reason;
+        abstainedKind ??= result.errorKind;
+        continue;
+      }
+      const terminal: ReviewResult = {
+        decision: result.decision, reason: result.reason, stage: result.stage ?? stage.type,
+        ...(result.errorKind === undefined ? {} : { errorKind: result.errorKind }),
+      };
+      return terminal;
     }
   }
   return {
     decision: "ask",
     reason: abstained ? `No classifier made a decision (${abstained})` : "No classifier made a decision",
     stage: "none",
+    ...(abstainedKind === undefined ? {} : { errorKind: abstainedKind }),
   };
 }

package/src/config.ts

@@ -27,8 +27,13 @@ export interface AutoModeOptions {
   tui?: boolean;
   auditLog?: boolean | string;
   otlp?: boolean | OtlpOptions;
+  reviewTimeoutMs?: number;
 }
 
+/** Longest a single review may block the permission prompt, across every stage. */
+export const DEFAULT_REVIEW_TIMEOUT_MS = 60_000;
+export const MAX_REVIEW_TIMEOUT_MS = 120_000;
+
 export function object(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -115,9 +120,13 @@ function stage(value: unknown): value is ClassifierStage {
 
 export function parseOptions(value: unknown): AutoModeOptions {
   if (!object(value)) throw new Error("Invalid auto-mode options");
-  if (!only(value, ["classifiers", "tui", "auditLog", "otlp"]))
+  if (!only(value, ["classifiers", "tui", "auditLog", "otlp", "reviewTimeoutMs"]))
     throw new Error("Unknown auto-mode option");
   if (value.tui !== undefined && typeof value.tui !== "boolean") throw new Error("Invalid TUI setting");
+  if (value.reviewTimeoutMs !== undefined &&
+      (typeof value.reviewTimeoutMs !== "number" || !Number.isInteger(value.reviewTimeoutMs) ||
+       value.reviewTimeoutMs < 1_000 || value.reviewTimeoutMs > MAX_REVIEW_TIMEOUT_MS))
+    throw new Error("Invalid review timeout");
   if (value.auditLog !== undefined && typeof value.auditLog !== "boolean" && !text(value.auditLog))
     throw new Error("Invalid audit log");
   if (value.otlp !== undefined && typeof value.otlp !== "boolean" && !otlp(value.otlp)) throw new Error("Invalid OTLP options");

package/src/decisions.ts

@@ -12,6 +12,7 @@ import { AIError, InvalidProviderOutputError, ModelID } from "@opencode/ai";
 import { localEndpoint, parseReviewerModel, type DecisionStage } from "./config.js";
 import { buildReviewPrompt, type Decision, type PermissionRequest, type StageResult } from "./reviewer.js";
 import type { ReviewPolicy } from "./policy.js";
+import { errorKindOf, ReviewFailure } from "./errors.js";
 
 const choices = {
   allow: "The whole action is safe and authorized by the user for this exact scope.",
@@ -19,6 +20,8 @@ const choices = {
   ask: "Authorization, evidence, or impact is uncertain; the human must decide.",
 } as const;
 const MAX_BYTES = 65_536;
+/** Bounds one typed provider request so a hung provider cannot hold the review. */
+export const DEFAULT_DECISION_TIMEOUT_MS = 10_000;
 const SYSTEM_ONE_URL = "https://api.typesafe.ai/v1/systemone";
 const LOCAL_SYSTEM_ONE_URL = "http://127.0.0.1:8000/v1/systemone";
 const OPENAI_URL = "https://api.openai.com/v1/decisions";
@@ -28,7 +31,13 @@ const API_KEY_ENV = {
   openai: "OPENAI_API_KEY",
 } as const;
 
-type RuntimeDecisionStage = DecisionStage & { readonly apiKey?: string };
+type RuntimeDecisionStage = DecisionStage & { readonly apiKey?: string; readonly signal?: AbortSignal };
+
+/** Per-request abort signal: the stage timeout bound by the overall review deadline. */
+function abortSignal(stage: RuntimeDecisionStage): AbortSignal {
+  const timeout = AbortSignal.timeout(stage.timeoutMs ?? DEFAULT_DECISION_TIMEOUT_MS);
+  return stage.signal === undefined ? timeout : AbortSignal.any([timeout, stage.signal]);
+}
 
 function probability(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
@@ -41,14 +50,14 @@ function object(value: unknown): value is Record<string, unknown> {
 function answer(value: unknown, stage: RuntimeDecisionStage): StageResult {
   if (!object(value) || value.type !== "choice" || typeof value.choice !== "string" || !Object.hasOwn(choices, value.choice) ||
       !probability(value.confidence) || !object(value.probabilities))
-    throw new Error("Invalid decision response");
+    throw new ReviewFailure("invalid-output", "Invalid decision response");
   const entries = Object.entries(value.probabilities);
   if (entries.length !== 3 || entries.some(([key, value]) => !Object.hasOwn(choices, key) || !probability(value)))
-    throw new Error("Invalid decision probabilities");
+    throw new ReviewFailure("invalid-output", "Invalid decision probabilities");
   const probabilities = value.probabilities as Record<Decision, number>;
   if (Math.abs(Object.values(probabilities).reduce((a, b) => a + b, 0) - 1) > 0.01 ||
       probabilities[value.choice as Decision] < Math.max(...Object.values(probabilities)))
-    throw new Error("Inconsistent decision probabilities");
+    throw new ReviewFailure("invalid-output", "Inconsistent decision probabilities");
   if (value.choice === "ask") return { decision: "ask", reason: `${stage.model} requested human review` };
   const threshold = stage.minConfidence ?? 0.9;
   if (value.confidence < threshold || probabilities[value.choice as Decision] < threshold) {
@@ -58,6 +67,11 @@ function answer(value: unknown, stage: RuntimeDecisionStage): StageResult {
   return { decision: value.choice as Decision, reason: `${stage.model} decision (confidence ${value.confidence})` };
 }
 
+function parseJSON(value: string): unknown {
+  try { return JSON.parse(value); }
+  catch (error) { throw new ReviewFailure("invalid-output", "Decision response is not valid JSON", { cause: error }); }
+}
+
 async function readJSON(response: Response): Promise<unknown> {
   if (!response.ok || !response.body) throw new Error("Decision provider failed");
   const reader = response.body.getReader();
@@ -68,10 +82,10 @@ async function readJSON(response: Response): Promise<unknown> {
       const { done, value } = await reader.read();
       if (done) break;
       size += value.length;
-      if (size > MAX_BYTES) throw new Error("Decision response too large");
+      if (size > MAX_BYTES) throw new ReviewFailure("invalid-output", "Decision response too large");
       chunks.push(value);
     }
-    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    return parseJSON(Buffer.concat(chunks).toString("utf8"));
   } finally {
     await reader.cancel().catch(() => {});
     reader.releaseLock();
@@ -89,8 +103,10 @@ function systemOneEndpoint(stage: RuntimeDecisionStage): string {
 }
 
 function evaluationChoice(value: unknown): EvaluationAnswer {
-  if (!object(value) || value.type !== "choice" || typeof value.choice !== "string") throw new Error("Invalid System One answer");
-  if (!object(value.probabilities) || !probability(value.confidence)) throw new Error("Invalid System One answer");
+  if (!object(value) || value.type !== "choice" || typeof value.choice !== "string")
+    throw new ReviewFailure("invalid-output", "Invalid System One answer");
+  if (!object(value.probabilities) || !probability(value.confidence))
+    throw new ReviewFailure("invalid-output", "Invalid System One answer");
   return {
     type: "choice",
     choice: value.choice,
@@ -107,7 +123,7 @@ function systemOneRoute(stage: RuntimeDecisionStage, modelID: string, url: strin
         const payload = JSON.stringify({ model: modelID, state: request.state, questions: request.questions });
         if (Buffer.byteLength(payload) > MAX_BYTES) throw new Error("Decision request too large");
         const response = await fetcher(url, {
-          method: "POST", redirect: "error", signal: AbortSignal.timeout(stage.timeoutMs ?? 10_000),
+          method: "POST", redirect: "error", signal: abortSignal(stage),
           headers: { "Content-Type": "application/json", ...(stage.apiKey === undefined ? {} : { Authorization: `Bearer ${stage.apiKey}` }) },
           body: payload,
         });
@@ -172,21 +188,22 @@ async function openAIDecision(
   const payload = JSON.stringify(body);
   if (Buffer.byteLength(payload) > MAX_BYTES) throw new Error("Decision request too large");
   const response = await fetcher(OPENAI_URL, {
-    method: "POST", redirect: "error", signal: AbortSignal.timeout(stage.timeoutMs ?? 10_000),
+    method: "POST", redirect: "error", signal: abortSignal(stage),
     headers: { "Content-Type": "application/json", Authorization: `Bearer ${stage.apiKey}` },
     body: payload,
   });
   const parsed = await readJSON(response);
   if (!object(parsed) || !Array.isArray(parsed.answers) || parsed.answers.length !== 1 || !object(parsed.answers[0]) ||
-      parsed.answers[0].name !== "permission") throw new Error("Invalid OpenAI answer");
+      parsed.answers[0].name !== "permission") throw new ReviewFailure("invalid-output", "Invalid OpenAI answer");
   const selected = parsed.answers[0];
   if (selected.type === "refusal") return { decision: "abstain", reason: `${stage.model} declined the decision` };
   if (!Array.isArray(selected.probabilities) || selected.probabilities.length !== 3)
-    throw new Error("Invalid OpenAI probabilities");
+    throw new ReviewFailure("invalid-output", "Invalid OpenAI probabilities");
   const distribution: Record<string, unknown> = {};
   for (const entry of selected.probabilities) {
     if (!object(entry) || typeof entry.value !== "string" || !Object.hasOwn(choices, entry.value) ||
-        Object.hasOwn(distribution, entry.value)) throw new Error("Invalid OpenAI probability entry");
+        Object.hasOwn(distribution, entry.value))
+      throw new ReviewFailure("invalid-output", "Invalid OpenAI probability entry");
     distribution[entry.value] = entry.probability;
   }
   return answer({ ...selected, probabilities: distribution }, stage);
@@ -197,6 +214,7 @@ export async function decisionStage(
   request: PermissionRequest,
   policy: ReviewPolicy,
   fetcher: typeof fetch = fetch,
+  signal?: AbortSignal,
 ): Promise<StageResult> {
   try {
     const ref = parseReviewerModel(input.model);
@@ -204,10 +222,15 @@ export async function decisionStage(
     const stage: RuntimeDecisionStage = {
       ...input,
       apiKey: process.env[input.apiKeyEnv ?? API_KEY_ENV[ref.providerID as keyof typeof API_KEY_ENV]],
+      signal,
     };
     return ref.providerID === "openai" ? await openAIDecision(stage, request, policy, fetcher) :
       await systemOneDecision(stage, request, policy, fetcher);
-  } catch {
-    return { decision: "abstain", reason: `${input.model} unavailable or returned an invalid decision` };
+  } catch (error) {
+    return {
+      decision: "abstain",
+      reason: `${input.model} unavailable or returned an invalid decision`,
+      errorKind: errorKindOf(error),
+    };
   }
 }

package/src/errors.ts

@@ -0,0 +1,39 @@
+/** Stable, bounded categories for a review that could not reach a confident decision. */
+export type ReviewErrorKind = "deadline" | "timeout" | "cancelled" | "provider" | "invalid-output" | "context";
+
+export class ReviewFailure extends Error {
+  constructor(readonly kind: ReviewErrorKind, message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = "ReviewFailure";
+  }
+}
+
+/** Finds an explicit category even when a provider library wraps our failure. */
+function explicitKind(error: unknown): ReviewErrorKind | undefined {
+  let current = error;
+  for (let depth = 0; depth < 4; depth++) {
+    if (current instanceof ReviewFailure) return current.kind;
+    if (typeof current !== "object" || current === null) return undefined;
+    const cause = (current as { cause?: unknown }).cause;
+    if (cause === undefined || cause === current) return undefined;
+    current = cause;
+  }
+  return undefined;
+}
+
+/** Maps arbitrary thrown values to a bounded category without exposing provider text. */
+export function errorKindOf(error: unknown): ReviewErrorKind {
+  // Only ReviewFailure marks malformed reviewer output. Provider text such as
+  // "Invalid API key" stays a provider failure even when a wrapper reuses it.
+  const explicit = explicitKind(error);
+  if (explicit !== undefined) return explicit;
+  const name = error instanceof Error ? error.name : "";
+  const message = error instanceof Error ? error.message : "";
+  // AbortSignal.timeout() aborts with a TimeoutError whose message also says
+  // "aborted"; a provider's own timeout is not a user interruption.
+  if (name === "TimeoutError" ||
+      (typeof DOMException === "function" && error instanceof DOMException && error.code === DOMException.TIMEOUT_ERR)) return "timeout";
+  if (name === "AbortError" || /abort|cancel/i.test(message)) return "cancelled";
+  if (/timeout|timed out/i.test(message)) return "timeout";
+  return "provider";
+}