@agent-guardrails/opencode-shell-warden-hook 0.1.0 → 0.2.1

package/src/config.ts

@@ -1,168 +1,156 @@
-// Shim options validation — docs/policyd-plugin-design/04-shim-config.md
-// Semantics: unknown keys => warn + ignore; budgets out of clamp => warn + clamp;
-// fatal defects (engine.command, protocolVersion, onEngineError:"allow") => plugin disables itself.
-
-export interface ResolvedBudgets {
-  handshakeTimeoutMs: number
-  checkTimeoutMs: number
-  killGraceMs: number
-  maxFrameBytes: number
-  maxInFlight: number
-  maxRequestCommands: number
-  maxViolations: number
-  maxViolationsWindowMs: number
+// Hook options — docs/spec/shell-warden/04-shim-config.md (v2.0, one-shot per-check).
+// Unknown keys ⇒ warn + ignore; clamps warn + apply; ONLY checker.command / sha256 /
+// onCheckerError:"allow" are fatal (plugin disables itself — the honest fail-closed
+// posture for load-time misconfiguration).
+
+type Resolved = { ok: true; config: Opts; warns: string[] } | { ok: false; reason: string }
+
+export interface CheckerOpts {
+  command: string[]
+  sha256: string | null
 }
 
-export interface ResolvedConfig {
-  engine: {
-    command: string[]
-    protocolVersion: number
-    sha256: string | null
-    cwd: string | null
-    restart: { maxBackoffMs: number; windowMs: number; resetAfterMs: number }
-  }
-  budgets: ResolvedBudgets
-  onEngineError: "ask" | "deny"
+export interface BudgetsOpts {
+  checkTimeoutMs: number   // 100..30_000, def 2_000 — verdict deadline (SIGTERM → killGraceMs → SIGKILL)
+  killGraceMs: number      // 50..2_000,  def 250 — SIGTERM → SIGKILL
+  maxRequestCommands: number // 1..128, def 32 — breach ⇒ local degrade, no spawn (02 §2.2)
+  maxConcurrentSpawns: number // 1..64, def 8 — excess ⇒ local degrade, never queued
+}
+
+export interface OptionsOpts {
+  enabled: boolean
+  checker: CheckerOpts
+  budgets: BudgetsOpts
+  onCheckerError: "ask" | "deny"   // degrade verdict; "allow" is not a valid value (I3)
   actions: string[]
-  actionsAll: boolean
-  cache: { enabled: boolean; maxEntries: number; defaultTtlMs: number }
-  observeShell: boolean
+  actionsAll: boolean              // actions includes "*"
+  cache: { enabled: boolean; maxEntries: number; ttlMs: number }
+  rejectBudget: { maxRejections: number; windowMs: number }
+  asConfig: { observeShell: boolean }
+  debug: { enabled: boolean; dir: string | null }
   logLevel: "debug" | "info" | "warn" | "error"
 }
+export type Opts = OptionsOpts
 
-export type ValidateResult =
-  | { ok: true; config: ResolvedConfig; warns: string[] }
-  | { ok: false; reason: string; warns: string[] }
+function isInt(v: unknown): v is number { return typeof v === "number" && Number.isInteger(v) }
 
-const KNOWN_ACTIONS = new Set([
-  "read", "edit", "glob", "grep", "shell", "subagent", "skill", "question",
-  "webfetch", "websearch", "external_directory", "execute",
-])
-
-const KNOWN_KEYS = new Set(["enabled", "engine", "budgets", "onEngineError", "actions", "cache", "observeShell", "logLevel"])
+function clampInt(v: unknown, min: number, max: number, def: number, name: string, warns: string[]): number {
+  let x = isInt(v) ? v : def
+  if (!isInt(v) && v !== undefined) warns.push(`omit/wrong type for ${name}, using ${def}`)
+  if (x < min) { warns.push(`${name} ${x} < ${min}, clamped to ${min}`); x = min }
+  if (x > max) { warns.push(`${name} ${x} > ${max}, clamped to ${max}`); x = max }
+  return x
+}
 
-const clampInt = (v: unknown, min: number, max: number, def: number, label: string, warns: string[]): number => {
-  if (typeof v !== "number" || !Number.isFinite(v)) return def
-  const n = Math.floor(v)
-  if (n < min || n > max) {
-    warns.push(`budgets.${label}: ${n} out of clamp [${min}, ${max}], using ${Math.min(Math.max(n, min), max)}`)
-    return Math.min(Math.max(n, min), max)
-  }
-  return n
+/** "{env:NAME}" member substitution resolved at setup; unresolved is fatal (I2). */
+function substituteEnv(member: string): string | null {
+  const m = /^\{env:([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(member)
+  if (!m) return member
+  const value = process.env[m[1] ?? ""]
+  return value === undefined || value === "" ? null : value
 }
 
-/** Resolves `{env:NAME}` members; returns null when substitution fails. */
-export function resolveEnvMember(s: string): string | null {
-  const m = /^\{env:([A-Za-z_][A-Za-z0-9_]*)\}$/.exec(s)
-  if (!m) return s
-  const v = process.env[m[1] as string]
-  return v === undefined || v === "" ? null : v
+const KNOWN_KEYS = new Set(["enabled", "checker", "budgets", "onCheckerError", "actions", "cache", "rejectBudget", "asConfig", "debug", "logLevel"])
+const CHECKER_KEYS = new Set(["command", "sha256"])
+const BUDGET_KEYS = new Set(["checkTimeoutMs", "killGraceMs", "maxRequestCommands", "maxConcurrentSpawns"])
+const CACHE_KEYS = new Set(["enabled", "maxEntries", "ttlMs"])
+const REJECT_KEYS = new Set(["maxRejections", "windowMs"])
+const ASKEYS = new Set(["observeShell"])
+const DEBUG_KEYS = new Set(["enabled", "dir"])
+
+function warnUnknown(scope: string, keys: object, known: Set<string>, warns: string[]): void {
+  for (const k of Object.keys(keys ?? {})) if (!known.has(k)) warns.push(`${scope}: unknown key "${k}" ignored`)
 }
 
-export function validateOptions(raw: unknown, warn: (m: string) => void = () => {}): ValidateResult {
+export function validateOptions(o: unknown): Resolved {
   const warns: string[] = []
-  if (raw === null || raw === undefined || typeof raw !== "object") {
-    // Empty options are valid: everything defaults except engine.command.
-    raw = {}
-  }
-  const o = raw as Record<string, unknown>
-  for (const key of Object.keys(o)) {
-    if (!KNOWN_KEYS.has(key)) warns.push(`unknown option "${key}" ignored`)
-  }
-  if (o.enabled === false) return { ok: false, reason: "disabled by options.enabled=false", warns }
+  if (o === null || typeof o !== "object" || Array.isArray(o)) o = {}
+  const rec = o as Record<string, unknown>
+  warnUnknown("", rec, KNOWN_KEYS, warns)
+
+  const enabled = rec.enabled === undefined ? true : rec.enabled === true
 
-  // --- engine (fatal on defects) ---
-  const eng = (o.engine ?? {}) as Record<string, unknown>
-  const rawCommand = eng.command
+  // ── checker (fatal on defects) ──
+  const rawChecker = (rec.checker ?? {}) as Record<string, unknown>
+  if (rec.checker !== undefined && (typeof rec.checker !== "object")) return { ok: false, reason: "checker must be an object" }
+  warnUnknown("checker", rawChecker, CHECKER_KEYS, warns)
+  const rawCommand = rawChecker.command
   if (!Array.isArray(rawCommand) || rawCommand.length === 0 || rawCommand.some((m) => typeof m !== "string")) {
-    return { ok: false, reason: 'engine.command must be a non-empty string array', warns }
+    return { ok: false, reason: "checker.command must be a non-empty string array" }
   }
   const command: string[] = []
   for (const member of rawCommand as string[]) {
-    const resolved = resolveEnvMember(member)
-    if (resolved === null) {
-      return { ok: false, reason: `engine.command member "${member}" failed {env:…} substitution`, warns }
-    }
+    const resolved = substituteEnv(member)
+    if (resolved === null) return { ok: false, reason: `checker.command member "${member}" failed {env:…} substitution` }
     command.push(resolved)
   }
-  if (command[0] === "" || !command[0]!.startsWith("/")) {
-    return { ok: false, reason: `engine.command[0] must be an absolute path, got "${command[0]}"`, warns }
-  }
-  const protocolVersion = typeof eng.protocolVersion === "number" ? eng.protocolVersion : 1
-  if (!Number.isInteger(protocolVersion) || protocolVersion < 1) {
-    return { ok: false, reason: `engine.protocolVersion must be a positive integer, got ${String(eng.protocolVersion)}`, warns }
+  if (!command[0]?.startsWith("/")) return { ok: false, reason: `checker.command[0] must be an absolute path, got "${command[0]}"` }
+  const sha256raw = rawChecker.sha256
+  if (sha256raw !== undefined && sha256raw !== null && !/^[0-9a-f]{64}$/.test(String(sha256raw))) {
+    return { ok: false, reason: "checker.sha256 must be null or 64 hex chars" }
   }
-  const sha256 = typeof eng.sha256 === "string" && /^[0-9a-f]{64}$/.test(eng.sha256) ? eng.sha256 : null
-  if (eng.sha256 !== undefined && eng.sha256 !== null && sha256 === null) {
-    return { ok: false, reason: "engine.sha256 must be null or 64 hex chars", warns }
-  }
-  const cwd = typeof eng.cwd === "string" && eng.cwd.startsWith("/") ? eng.cwd : null
-
-  // --- restart (clamp) ---
-  const rs = (eng.restart ?? {}) as Record<string, unknown>
-  const restart = {
-    maxBackoffMs: clampInt(rs.maxBackoffMs, 1_000, 300_000, 30_000, "restart.maxBackoffMs", warns),
-    windowMs: clampInt(rs.windowMs, 10_000, 3_600_000, 300_000, "restart.windowMs", warns),
-    resetAfterMs: clampInt(rs.resetAfterMs, 10_000, 3_600_000, 300_000, "restart.resetAfterMs", warns),
+  const sha256 = sha256raw === undefined ? null : (sha256raw as string | null)
+
+  // ── budgets ──
+  const rawBudgets = (rec.budgets ?? {}) as Record<string, unknown>
+  warnUnknown("budgets", rawBudgets, BUDGET_KEYS, warns)
+  const budgets = {
+    checkTimeoutMs: clampInt(rawBudgets.checkTimeoutMs, 100, 30_000, 2_000, "checkTimeoutMs", warns),
+    killGraceMs: clampInt(rawBudgets.killGraceMs, 50, 2_000, 250, "killGraceMs", warns),
+    maxRequestCommands: clampInt(rawBudgets.maxRequestCommands, 1, 128, 32, "maxRequestCommands", warns),
+    maxConcurrentSpawns: clampInt(rawBudgets.maxConcurrentSpawns, 1, 64, 8, "maxConcurrentSpawns", warns),
   }
 
-  // --- budgets (clamp) ---
-  const b = (o.budgets ?? {}) as Record<string, unknown>
-  const budgets: ResolvedBudgets = {
-    handshakeTimeoutMs: clampInt(b.handshakeTimeoutMs, 100, 60_000, 5_000, "handshakeTimeoutMs", warns),
-    checkTimeoutMs: clampInt(b.checkTimeoutMs, 1, 30_000, 5_000, "checkTimeoutMs", warns),
-    killGraceMs: clampInt(b.killGraceMs, 50, 2_000, 250, "killGraceMs", warns),
-    maxFrameBytes: clampInt(b.maxFrameBytes, 4_096, 1_048_576, 65_536, "maxFrameBytes", warns),
-    maxInFlight: clampInt(b.maxInFlight, 1, 64, 8, "maxInFlight", warns),
-    maxRequestCommands: clampInt(b.maxRequestCommands, 1, 128, 32, "maxRequestCommands", warns),
-    maxViolations: clampInt(b.maxViolations, 1, 10, 3, "maxViolations", warns),
-    maxViolationsWindowMs: clampInt(b.maxViolationsWindowMs, 5_000, 3_600_000, 60_000, "maxViolationsWindowMs", warns),
+  // ── onCheckerError ──
+  const onError = (rec.onCheckerError ?? "ask") as string
+  if (onError === "allow") return { ok: false, reason: "onCheckerError must be 'ask' or 'deny' — never 'allow' (I3)" }
+  if (onError !== "ask" && onError !== "deny") {
+    warns.push(`onCheckerError "${onError}" is not ask|deny, using ask`)
   }
-
-  // --- onEngineError (fatal on "allow") ---
-  const onEngineError = o.onEngineError
-  if (onEngineError === "allow") {
-    return { ok: false, reason: 'onEngineError must be "ask" or "deny" — "allow" is never valid (fail-closed)', warns }
-  }
-  const degrade = onEngineError === "deny" ? "deny" : "ask"
-
-  // --- actions ---
-  let actions: string[] = []
-  let actionsAll = false
-  const rawActions = o.actions
-  if (Array.isArray(rawActions) && rawActions.length > 0) {
-    for (const a of rawActions) {
-      if (a === "*") actionsAll = true
-      else if (typeof a === "string" && KNOWN_ACTIONS.has(a)) actions.push(a)
-      else warns.push(`actions: unknown action "${String(a)}" dropped`)
-    }
+  const onCheckerError: "ask" | "deny" = onError === "deny" ? "deny" : "ask"
+
+  // ── actions ──
+  const actionsAll: boolean = rec.actions === "*" || (Array.isArray(rec.actions) && rec.actions.includes("*"))
+  const actions = Array.isArray(rec.actions)
+    ? (rec.actions as unknown[]).filter((a): a is string => typeof a === "string" && a !== "*")
+    : ["shell"]
+  if (!Array.isArray(rec.actions) && rec.actions !== undefined && rec.actions !== "*") warns.push("actions must be an array, using [shell]")
+
+  // ── cache ──
+  const rawCache = (rec.cache ?? {}) as Record<string, unknown>
+  warnUnknown("cache", rawCache, CACHE_KEYS, warns)
+  const cache = {
+    enabled: rawCache.enabled === undefined ? true : rawCache.enabled === true,
+    maxEntries: clampInt(rawCache.maxEntries, 16, 100_000, 1_024, "cache.maxEntries", warns),
+    ttlMs: clampInt(rawCache.ttlMs, 0, 3_600_000, 0, "cache.ttlMs", warns),
   }
-  if (!actionsAll && actions.length === 0) actions = ["shell"]
 
-  // --- cache ---
-  const c = (o.cache ?? {}) as Record<string, unknown>
-  const cache = {
-    enabled: c.enabled !== false,
-    maxEntries: clampInt(c.maxEntries, 16, 100_000, 1_024, "cache.maxEntries", warns),
-    defaultTtlMs: clampInt(c.defaultTtlMs, 0, 3_600_000, 0, "cache.defaultTtlMs", warns),
+  // ── rejectBudget ──
+  const rawReject = (rec.rejectBudget ?? {}) as Record<string, unknown>
+  warnUnknown("rejectBudget", rawReject, REJECT_KEYS, warns)
+  const rejectBudget = {
+    maxRejections: clampInt(rawReject.maxRejections, 1, 10, 3, "rejectBudget.maxRejections", warns),
+    windowMs: clampInt(rawReject.windowMs, 60_000, 86_400_000, 1_800_000, "rejectBudget.windowMs", warns),
   }
 
-  const logLevel = o.logLevel === "debug" || o.logLevel === "info" || o.logLevel === "error" ? o.logLevel : "warn"
+  // ── asConfig / debug / logLevel ──
+  const rawAs = (rec.asConfig ?? {}) as Record<string, unknown>
+  warnUnknown("asConfig", rawAs, ASKEYS, warns)
+  const asConfig = { observeShell: rawAs.observeShell === true }
+
+  const rawDebug = (rec.debug ?? {}) as Record<string, unknown>
+  warnUnknown("debug", rawDebug, DEBUG_KEYS, warns)
+  let debugDir: string | null = typeof rawDebug.dir === "string" ? rawDebug.dir : null
+  if (debugDir !== null && !debugDir.startsWith("/")) { warns.push("debug.dir must be absolute, ignored"); debugDir = null }
+  const debug = { enabled: rawDebug.enabled === true, dir: debugDir }
 
-  for (const w of warns) warn(`[opencode-shell-warden-hook] ${w}`)
+  const LEVELS = ["debug", "info", "warn", "error"] as const
+  const logLevel = LEVELS.includes(rec.logLevel as (typeof LEVELS)[number]) ? (rec.logLevel as OptionsOpts["logLevel"]) : "warn"
+  if (rec.logLevel !== undefined && !LEVELS.includes(rec.logLevel as (typeof LEVELS)[number])) warns.push("logLevel invalid, using warn")
 
   return {
     ok: true,
     warns,
-    config: {
-      engine: { command, protocolVersion, sha256, cwd, restart },
-      budgets,
-      onEngineError: degrade,
-      actions: actionsAll ? ["*"] : actions,
-      actionsAll,
-      cache,
-      observeShell: o.observeShell === true,
-      logLevel,
-    },
+    config: { enabled, checker: { command, sha256 }, budgets, onCheckerError, actions, actionsAll, cache, rejectBudget, asConfig, debug, logLevel },
   }
 }

package/src/index.ts

@@ -1,29 +1,34 @@
-// opencode-shell-warden-hook — OpenCode V2 plugin entry.
+// opencode-shell-warden-hook — OpenCode V2 plugin entry (two-tier, ADR-0016).
 // Mechanism per ADR-0013: the native substrate is the fail-closed boundary
 // (permissions: shell → ask). The shim listens for published permission
-// requests, consults the shell-warden engine, and replies programmatically:
-// allow → "once", deny → "reject" (with reason), ask → silence (human decides).
-// Fail-closed: with the hook absent every ask reaches the human / headless
-// auto-reject — nothing executes silently.
+// requests, spawns the one-shot shell-warden checker per request
+// (letter in on stdin → verdict out on stdout, 02-letter-verdict v2.0) and
+// replies programmatically:
+//   allow → "once", deny → "reject" (with reason), ask → silence (human decides).
+// Checker defects degrade to onCheckerError ∈ {ask, deny} — never allow.
 
+import { mkdirSync, appendFileSync } from "node:fs"
 import { Plugin } from "@opencode/plugin"
-import { replyDecision, buildCheckRequest, cacheKey, invocationIdOf, type AskData, InvocationRegistry } from "./apply.ts"
+import { replyDecision, buildLetter, cacheKey, invocationIdOf, type AskData } from "./apply.ts"
 import { VerdictCache } from "./cache.ts"
-import { validateOptions } from "./config.ts"
-import { EngineSupervisor, type SupervisorOptions } from "./supervisor.ts"
+import { validateOptions, type Opts } from "./config.ts"
+import { CheckerInvoker, RejectBudgets, verifyPin, type CheckerOptions, type CheckerOutcome } from "./checker.ts"
+import { MAX_LETTER_BYTES, MAX_COMMAND_BYTES } from "./types.ts"
 
-const VERSION = "0.1.0"
 const PLUGIN_ID = "opencode-shell-warden-hook"
 
 export default Plugin.define({
   id: PLUGIN_ID,
   async setup(ctx) {
-    const opts = validateOptions(ctx.options, (m) => console.error(m))
+    const opts = validateOptions(ctx.options)
     if (!opts.ok) {
       console.error(`[${PLUGIN_ID}] Disabled: ${opts.reason}`)
       return
     }
-    const cfg = opts.config
+    const cfg: Opts = opts.config
+    for (const w of opts.warns) console.error(`[${PLUGIN_ID}] warn: ${w}`)
+    if (cfg.enabled === false) return
+
     const LEVELS = { debug: 0, info: 1, warn: 2, error: 3 } as const
     type Level = keyof typeof LEVELS
     const threshold = LEVELS[cfg.logLevel]
@@ -31,29 +36,27 @@ export default Plugin.define({
       if (LEVELS[level] >= threshold) console.error(msg)
     }
 
-    const supOpts: SupervisorOptions = {
-      command: cfg.engine.command,
-      protocolVersion: cfg.engine.protocolVersion,
-      sha256: cfg.engine.sha256,
-      cwd: cfg.engine.cwd,
-      clientVersion: VERSION,
-      budgets: {
-        handshakeTimeoutMs: cfg.budgets.handshakeTimeoutMs,
-        checkTimeoutMs: cfg.budgets.checkTimeoutMs,
-        killGraceMs: cfg.budgets.killGraceMs,
-        maxFrameBytes: cfg.budgets.maxFrameBytes,
-        maxInFlight: cfg.budgets.maxInFlight,
-        maxViolations: cfg.budgets.maxViolations,
-        maxViolationsWindowMs: cfg.budgets.maxViolationsWindowMs,
-        maxBackoffMs: cfg.engine.restart.maxBackoffMs,
-        windowMs: cfg.engine.restart.windowMs,
-        resetAfterMs: cfg.engine.restart.resetAfterMs,
-      },
+    // Debug NDJSON per check (03 §3.5); default dir per 04 §4.2.
+    let debugSink: ((record: Record<string, unknown>) => void) | null = null
+    if (cfg.debug.enabled) {
+      const dir = cfg.debug.dir ?? `${process.env.HOME ?? ""}/.local/state/shell-warden/hook`
+      try { mkdirSync(dir, { recursive: true }) } catch { /* debug is best-effort */ }
+      const file = `${dir}/hook.ndjson`
+      debugSink = (record) => { try { appendFileSync(file, JSON.stringify(record) + "\n") } catch { /* debug is best-effort */ } }
+    }
+
+    const checkerOpts: CheckerOptions = {
+      command: cfg.checker.command,
+      sha256: cfg.checker.sha256,
+      checkTimeoutMs: cfg.budgets.checkTimeoutMs,
+      killGraceMs: cfg.budgets.killGraceMs,
+      maxConcurrentSpawns: cfg.budgets.maxConcurrentSpawns,
       log,
     }
-    const supervisor = new EngineSupervisor(supOpts)
+    verifyPin(checkerOpts)
+    const checker = new CheckerInvoker(checkerOpts)
     const cache = new VerdictCache(cfg.cache.enabled ? cfg.cache.maxEntries : 0)
-    const registry = new InvocationRegistry()
+    const rejectBudgets = new RejectBudgets(cfg.rejectBudget.maxRejections, cfg.rejectBudget.windowMs)
 
     const myLocation = ctx.location?.directory ?? ""
     const reply = (sessionID: string, requestID: string, decision: "once" | "reject", message?: string) =>
@@ -77,8 +80,17 @@ export default Plugin.define({
           try {
             if (!(cfg.actionsAll || cfg.actions.includes(d.action))) continue
             const invocationId = invocationIdOf(d.source, d.sessionID, d.action)
-            const cwd = ""  // v0.1: no OpenCode HTTP calls from the ask handler (deadlock finding). M1: session-event cache
-            const key = cacheKey(d.action, d.resources, cwd)
+            // The ask payload carries no per-command cwd; the permission event's
+            // location is the only directory the shim has. Letters with an empty
+            // commands[].cwd are rejected by the engine, so without one we degrade —
+            // never spawn a letter the engine would refuse.
+            const projectDir = loc || myLocation || ""
+            if (!projectDir) {
+              log("warn", `no project directory for ${invocationId} — degrade (${cfg.onCheckerError})`)
+              if (cfg.onCheckerError === "deny") await reply(d.sessionID, d.id, "reject", undefined).catch(() => {})
+              continue
+            }
+            const key = cacheKey(d.action, d.resources, projectDir)
 
             if (cfg.cache.enabled) {
               const cached = cache.get(key)
@@ -88,35 +100,48 @@ export default Plugin.define({
               }
             }
 
-            if (!cfg.actionsAll && d.resources.length > cfg.budgets.maxRequestCommands) {
-              await reply(d.sessionID, d.id, "reject", "too many commands for one guard evaluation")
+            // Pre-spawn bounds (02 §2.2): breach ⇒ local degrade, no spawn.
+            const letter = buildLetter({ data: d, invocationId, projectDir })
+            const letterBytes = Buffer.byteLength(JSON.stringify(letter))
+            const oversize =
+              letter.commands.length > cfg.budgets.maxRequestCommands ||
+              letterBytes > MAX_LETTER_BYTES ||
+              letter.commands.some((c) => Buffer.byteLength(c.raw) > MAX_COMMAND_BYTES)
+            if (oversize) {
+              log("warn", `letter bounds breach for ${invocationId} — degrade (${cfg.onCheckerError})`)
+              if (cfg.onCheckerError === "deny") await reply(d.sessionID, d.id, "reject", undefined).catch(() => {})
               continue
             }
 
-            const outcome = await supervisor.check(buildCheckRequest({ data: d, invocationId, cwd }))
+            const outcome: CheckerOutcome = await checker.check(letter)
+            debugSink?.({ ts: new Date().toISOString(), invocationId, action: d.action, outcomeOk: outcome.ok })
             if (!outcome.ok) {
               log(cfg.logLevel === "debug" ? "debug" : "warn", `degrade (${outcome.reason}) for ${invocationId}`)
-              // fail-closed: onError → either reject (hard-fail mode) or silence
-              if (cfg.onEngineError === "deny") {
+              if (cfg.onCheckerError === "deny") {
                 await reply(d.sessionID, d.id, "reject", undefined).catch(() => { /* human resolves */ })
               }
               continue
             }
-            const { verdict, message } = outcome.result
-            if (verdict === "allow") {
-              const ttl = outcome.result.commands?.find((c) => c.index === 0)?.cacheTtlMs ?? cfg.cache.defaultTtlMs
-              if (cfg.cache.enabled && ttl > 0) {
-                cache.put(key, ttl, message)
-                registry.remember(invocationId, key)
-              }
+
+            const result = outcome.verdict
+            const decision = replyDecision(result.verdict)
+            if (decision === "once") {
+              if (cfg.cache.enabled && cfg.cache.ttlMs > 0) cache.put(key, cfg.cache.ttlMs, result.message)
               await reply(d.sessionID, d.id, "once")
               continue
             }
-            if (verdict === "deny") {
-              await reply(d.sessionID, d.id, "reject", message)
+            if (decision === "reject") {
+              // Reject budget (ADR-0010, hook-owned): exhausted ⇒ stop answering —
+              // the native ask reaches the human. Never auto-allowed.
+              const ruleId = result.commands?.[0]?.ruleId ?? "unknown"
+              if (!rejectBudgets.trySpend(d.sessionID, ruleId)) {
+                log("info", `reject budget exhausted for ${ruleId} (${invocationId}) — left to the human`)
+                continue
+              }
+              await reply(d.sessionID, d.id, "reject", result.message)
               continue
             }
-            // verdict "ask" → stay silent: the dialog goes to the human (escalation by silence)
+            // verdict "ask" → stay silent: the native dialog goes to the human
           } catch (e) {
             log("warn", `ask handler error: ${String(e).slice(0, 200)} — request left to the human (fail-closed)`)
           }
@@ -126,18 +151,12 @@ export default Plugin.define({
       }
     })()
 
-    if (cfg.observeShell) {
+    if (cfg.asConfig.observeShell) {
       await ctx.shell.hook("create.before", (event) => {
-        supervisor.observe({ phase: "create.before", command: event.command, cwd: event.cwd })
+        debugSink?.({ ts: new Date().toISOString(), phase: "create.before", command: event.command, cwd: event.cwd })
       })
     }
-    await ctx.tool.hook("execute.after", (event) => {
-      const source = (event as { source?: { messageID?: string; id?: string } }).source
-      if (source?.messageID === undefined || source.id === undefined) return
-      const key = registry.keyFor(`${source.messageID}:${source.id}`)
-      if (key !== undefined) registry.remember(`${source.messageID}:${source.id}`, key)
-    })
 
-    return () => { controller.abort(); supervisor.dispose() }
+    return () => { controller.abort() }
   },
 })

package/src/types.ts

@@ -1,77 +1,59 @@
-// Wire protocol types — mirror of docs/policyd-plugin-design/02-protocol.md (v1)
-// and schemas/wire.v1.schema.json. Keep in sync with the schema.
+// Letter & verdict types — mirror of docs/spec/shell-warden/02-letter-verdict.md (v2.0)
+// and schemas/shell-warden.letter.v1.schema.json / shell-warden.verdict.v1.schema.json.
+// Keep in sync with the schemas.
 
 export type Verdict = "allow" | "ask" | "deny"
 
-export interface InitializeParams {
-  protocolVersion: number
-  client: { name: string; version: string; opencode?: string }
+export interface LetterInvocation {
+  id: string                       // `${messageID}:${callID}` — unique per tool call
+  sessionID: string
+  agent?: string
+  projectDir?: string
 }
 
-export interface InitializeResult {
-  protocolVersion: number
-  engine: { name: string; version: string }
-  capabilities?: Record<string, unknown>
-  config?: { source?: string; stages?: string[]; loadedAt?: string }
-}
-
-export interface CheckCommand {
+export interface LetterCommand {
   index: number
-  raw: string
+  raw: string                      // command text exactly as OpenCode produced it, ≤ 8 KiB
   cwd: string
 }
 
-export interface CheckParams {
-  invocation: {
-    id: string
-    sessionID: string
-    agent?: string
-    hook: string
-    projectDir?: string
-    startedAt?: string
-  }
+export interface Letter {
+  version: 1
+  invocation: LetterInvocation
   action: string
-  commands: CheckCommand[]
-  context?: {
-    source?: { type: "tool"; messageID?: string; id?: string }
-    metadata?: Record<string, unknown>
-  }
+  commands: LetterCommand[]
 }
 
-export interface CheckCommandResult {
+export interface LetterCommandVerdict {
   index: number
   verdict: Verdict
-  stage?: string | null
-  ruleId?: string | null
-  reason?: string
+  ruleId?: string
   classification?: "static" | "opaque"
-  cacheTtlMs?: number
+  match?: "argv" | "raw"
+  facts?: Record<string, unknown>
 }
 
-export interface CheckResult {
-  invocationId: string
-  verdict: Verdict
-  message?: string
-  commands?: CheckCommandResult[]
-  engine?: { checkMs?: number }
+export interface LetterVerdict {
+  invocationId: string             // echo of letter.invocation.id
+  verdict: Verdict                 // aggregate — authoritative, hook applies tighten-only
+  message?: string                 // required on deny; ≤ 512 chars
+  commands?: LetterCommandVerdict[]
 }
 
-export type WireMessage =
-  | { jsonrpc: "2.0"; id: number; method: string; params: unknown }
-  | { jsonrpc: "2.0"; id: number; result: unknown }
-  | { jsonrpc: "2.0"; id: number | null; error: { code: number; message: string; data?: { fatal?: boolean } } }
-  | { jsonrpc: "2.0"; method: string; params?: unknown }
+// Bounds from 02-letter-verdict.md §2.2/§2.3 (hook enforces before spawning)
+export const MAX_LETTER_BYTES = 64 * 1024
+export const MAX_COMMAND_BYTES = 8 * 1024
+export const MAX_VERDICT_BYTES = 64 * 1024
+export const MAX_FACTS_BYTES = 16 * 1024
+export const MAX_MESSAGE_CHARS = 512
 
-// OpenCode V2 permission evaluate hook event (mutable: effect, message)
-export interface PermissionEvaluation {
-  readonly sessionID: string
-  readonly agent?: string
-  readonly action: string
-  readonly resources: readonly string[]
-  readonly metadata?: Record<string, unknown>
-  readonly source?: { type: "tool"; messageID: string; id: string }
-  effect: Verdict
-  message?: string
+// OpenCode V2 permission.asked event payload (relevant subset)
+export interface AskData {
+  id: string                          // requestID, assigned at publication
+  sessionID: string
+  action: string
+  resources: readonly string[]
+  source?: { type: "tool"; messageID: string; id: string }
 }
 
 // shell.create.before hook event (audit-only usage)