pi-opa-net 0.1.0

package/skills/pi-opa-net/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: pi-opa-net
+description: OPA-backed bash command guard for the pi ecosystem. Use when you need to evaluate shell commands against a safety policy and get structured JSON output (decision-output.v1 schema), wire a bash guard into a pi extension, or understand fail-open/fail-closed behavior. NOT for the rego policy authoring itself (edit policy/safety.rego directly).
+---
+
+# pi-opa-net — OPA-backed bash guard
+
+An **agent-agnostic** engine + CLI that evaluates shell commands against an [OPA](https://www.openpolicyagent.org/)/Rego policy and emits a strict, auditable `decision-output.v1` record. Designed as the decision backend for pi extensions, Claude Code hooks, and scripts.
+
+## When to use
+
+- Wiring a bash command guard into a pi extension (the extension shells out to this CLI and parses the JSON).
+- Evaluating a command programmatically and needing rule provenance (`reasons[].rule_id`).
+- Replacing asymmetric allow-silent/deny-string output with a symmetric schema.
+- Detecting rulebook drift via `metadata.rulebook_digest`.
+
+## When NOT to use
+
+- You need the **pi extension tool_call hook itself** — that lives in a separate `pi-opa-net-ext` repo (OT5). This package is the engine + library, not the hook.
+- You want OPA policy for non-bash domains (deploy-gating, k8s, API authz) — out of scope (LD3).
+
+## Quick start
+
+```bash
+# CLI
+bunx pi-opa-net eval "git stash pop" --json   # exit 2 + JSON
+bunx pi-opa-net eval "git stash list"          # exit 0, empty stdout
+
+# Programmatic
+import { configFromEnv, CommandParserCoordinator, OpaCliEngine, DecisionBuilder, RULES, RuleRegistry } from 'pi-opa-net';
+```
+
+## Output shape
+
+Every decision (allow AND deny) emits `decision-output.v1`:
+
+- `decision`: `allow | deny`
+- `source`: `opa | fail-open | fail-closed | cached`
+- `reasons[]`: `{ rule_id, message, family, severity }` — empty on allow
+- `input`: `{ raw, program, subcommand, args, parse_confidence }`
+- `metadata`: `{ engine, opa_version, rulebook_digest, policy_path, hostname, session_id }`
+- `decision_id` (uuid), `evaluated_at` (ISO-8601), `duration_ms`
+
+Exit codes: `0 = allow`, `2 = deny` (Claude Code hook protocol compatible).
+
+## Fail-mode
+
+- `PI_OPA_FAIL_MODE=open` (default) — allow when OPA unreachable, `source: "fail-open"`.
+- `PI_OPA_FAIL_MODE=closed` — deny when OPA unreachable, `source: "fail-closed"`.
+
+The `source` field makes whichever mode fires **observable** per-decision.
+
+## Adding a rule
+
+1. Add a `deny[msg] if { ... }` block to `policy/safety.rego`.
+2. Mirror it in `src/rules/catalog.ts` (same message string).
+3. The catalog↔rego parity test enforces zero drift.
+
+## References
+
+- Schema: [`schemas/decision-output.v1.json`](https://github.com/buihongduc132/pi-opa-net/blob/main/schemas/decision-output.v1.json)
+- Policy: [`policy/safety.rego`](https://github.com/buihongduc132/pi-opa-net/blob/main/policy/safety.rego)
+- Decisions: [`docs/locked-decisions.yaml`](https://github.com/buihongduc132/pi-opa-net/blob/main/docs/locked-decisions.yaml), [`docs/open-threads.yaml`](https://github.com/buihongduc132/pi-opa-net/blob/main/docs/open-threads.yaml)

package/src/cli/run.ts

@@ -0,0 +1,76 @@
+import { resolve } from 'node:path';
+import { configFromEnv } from '../config/Config.ts';
+import { OpaCliEngine, probeOpaVersion } from '../engine/index.ts';
+import { DecisionBuilder } from '../output/DecisionBuilder.ts';
+import { OutputFormatter, validateDecision } from '../output/OutputFormatter.ts';
+import { CommandParserCoordinator } from '../parser/index.ts';
+import { RULES, RuleRegistry } from '../rules/index.ts';
+
+export interface CliOptions {
+  /** Command string to evaluate. If omitted, read from stdin. */
+  readonly command?: string;
+  /** Output mode: json (full schema) | claude-code (suppress allow stdout). */
+  readonly mode: 'json' | 'claude-code';
+  /** Path to the .rego policy. */
+  readonly policyPath: string;
+}
+
+export interface CliResult {
+  readonly stdout: string;
+  readonly exitCode: number;
+}
+
+/**
+ * CLI entrypoint — wires parser → engine → builder → formatter.
+ *
+ * Returns {stdout, exitCode} instead of calling process.exit directly so it
+ * is unit-testable. The bin wrapper calls process.exit with the returned code.
+ */
+export async function runCli(opts: CliOptions): Promise<CliResult> {
+  const raw = resolveRaw(opts);
+  if (raw === '') {
+    return { stdout: '', exitCode: 0 };
+  }
+
+  const config = configFromEnv(opts.policyPath);
+  const parser = new CommandParserCoordinator();
+  const parsed = parser.parse(raw);
+
+  const opaVersion = await probeOpaVersion(config.opaBinary ?? 'opa');
+  const engine = new OpaCliEngine(config, opaVersion);
+  const engineDecision = await engine.evaluate(parsed);
+
+  const builder = new DecisionBuilder({
+    config,
+    registry: new RuleRegistry(RULES),
+    digest: engine.rulebookDigest(),
+  });
+  const output = builder.build(parsed, engineDecision);
+
+  // Hard internal gate: the record MUST validate against the schema before emit.
+  validateDecision(output);
+
+  const formatter = new OutputFormatter();
+  const { stdout, exitCode } = formatter.format(output, opts.mode);
+  return { stdout, exitCode };
+}
+
+function resolveRaw(opts: CliOptions): string {
+  if (opts.command !== undefined && opts.command.length > 0) {
+    return opts.command;
+  }
+  // Read stdin synchronously when no command arg given.
+  try {
+    const fs = require('node:fs') as typeof import('node:fs');
+    return fs.readFileSync(0, 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+
+/** Resolve the default policy path relative to package root. */
+export function defaultPolicyPath(): string {
+  // import.meta.dir is available under Bun; fall back to cwd-relative for Node.
+  const here = (import.meta as { dir?: string }).dir ?? process.cwd();
+  return resolve(here, '../../policy/safety.rego');
+}

package/src/config/Config.ts

@@ -0,0 +1,78 @@
+/**
+ * Fail-mode when the decision engine is unreachable [OT2 resolution].
+ * - `open`: allow the command through (default — matches pi-safety-net fork).
+ * - `closed`: block the command until engine responds.
+ */
+export type FailMode = 'open' | 'closed';
+
+/** Cache TTL in ms. 0 disables caching. */
+export const DEFAULT_CACHE_TTL_MS = 0;
+
+export interface EngineConfig {
+  /** Path to the OPA binary. If unset, auto-discovered via PATH + mise. */
+  readonly opaBinary?: string;
+  /** Path to the .rego policy bundle. */
+  readonly policyPath: string;
+  /** Fail-mode when OPA is unreachable [OT2]. */
+  readonly failMode: FailMode;
+  /** Milliseconds to wait for OPA before treating as unreachable. */
+  readonly timeoutMs: number;
+  /** Cache TTL for identical inputs. 0 = disabled. */
+  readonly cacheTtlMs: number;
+  /** Hostname for metadata. Defaults to os.hostname(). */
+  readonly hostname?: string;
+  /** Calling session ID for metadata (pi/claude session). Empty if none. */
+  readonly sessionId?: string;
+}
+
+const ENV = process.env;
+
+/** Resolve the OPA binary path: explicit → PATH → mise install. */
+export function resolveOpaBinary(explicit?: string): string {
+  if (explicit) return explicit;
+  if (ENV.PI_OPA_BINARY) return ENV.PI_OPA_BINARY;
+  // mise install path (LD2: OPA lazy-loaded on every dev box).
+  const misePath = `${process.env.HOME}/.local/share/mise/installs/opa`;
+  try {
+    const versions = readdirSafe(misePath);
+    // Prefer the most specific semver; fall back to 'latest'.
+    const pick =
+      versions
+        .filter((v) => /^\d+\.\d+\.\d+$/.test(v))
+        .sort()
+        .at(-1) ?? 'latest';
+    const candidate = `${misePath}/${pick}/opa`;
+    return candidate;
+  } catch {
+    return 'opa';
+  }
+}
+
+function readdirSafe(path: string): string[] {
+  try {
+    // Lazy require to avoid fs cost in non-Node runtimes.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const fs = require('node:fs') as typeof import('node:fs');
+    return fs.readdirSync(path);
+  } catch {
+    return [];
+  }
+}
+
+/** Build an EngineConfig from environment + defaults. */
+export function configFromEnv(policyPath: string): EngineConfig {
+  const failMode: FailMode = (ENV.PI_OPA_FAIL_MODE as FailMode) === 'closed' ? 'closed' : 'open';
+  const timeoutMs = ENV.PI_OPA_TIMEOUT_MS ? Number.parseInt(ENV.PI_OPA_TIMEOUT_MS, 10) : 250;
+  const cacheTtlMs = ENV.PI_OPA_CACHE_TTL_MS
+    ? Number.parseInt(ENV.PI_OPA_CACHE_TTL_MS, 10)
+    : DEFAULT_CACHE_TTL_MS;
+  return {
+    opaBinary: resolveOpaBinary(),
+    policyPath,
+    failMode,
+    timeoutMs,
+    cacheTtlMs,
+    hostname: ENV.PI_OPA_HOSTNAME,
+    sessionId: ENV.PI_OPA_SESSION_ID,
+  };
+}

package/src/engine/OpaCliEngine.ts

@@ -0,0 +1,166 @@
+import { execFile } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import type { EngineConfig } from '../config/Config.ts';
+import type { ParsedCommand } from '../parser/types.ts';
+import { sha256Prefix } from '../util/digest.ts';
+import type { DecisionEngine, EngineDecision, RawDeny } from './types.ts';
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * OPA-backed decision engine via the `opa eval` CLI subprocess [LD1][LD2].
+ *
+ * - Spawns `opa eval -d <policy> -i <input.json> data.safety.allow + data.safety.deny`.
+ * - On timeout / non-zero exit / unreachable binary → applies [OT2] fail-mode.
+ * - fail-open: returns allow with source=fail-open.
+ * - fail-closed: returns deny with source=fail-closed.
+ *
+ * Rego returns `deny` as a set of message strings; we map each to a RawDeny.
+ */
+export class OpaCliEngine implements DecisionEngine {
+  readonly name = 'opa-cli';
+  private readonly config: EngineConfig;
+  private readonly digest: string;
+  private readonly opaVersion: string;
+
+  constructor(config: EngineConfig, opaVersion = '') {
+    this.config = config;
+    this.digest = sha256Prefix(this.config.policyPath, this.readFile);
+    this.opaVersion = opaVersion;
+  }
+
+  async evaluate(parsed: ParsedCommand): Promise<EngineDecision> {
+    const input = {
+      program: parsed.program,
+      subcommand: parsed.subcommand,
+      args: parsed.args,
+      raw: parsed.raw,
+    };
+    const inputJson = JSON.stringify(input);
+    const query = '{"allow": data.safety.allow, "deny": data.safety.deny}';
+    const args = ['eval', '--format', 'json', '-d', this.config.policyPath];
+
+    const start = Date.now();
+    let tmpDir: string | null = null;
+    try {
+      tmpDir = mkdtempSync(join(tmpdir(), 'pi-opa-'));
+      const inFile = join(tmpDir, 'in.json');
+      writeFileSync(inFile, inputJson);
+      const fullArgs = [...args, '-i', inFile, query];
+      const { stdout } = await execFileAsync(this.resolveBinary(), fullArgs, {
+        timeout: this.config.timeoutMs,
+        maxBuffer: 4 * 1024 * 1024,
+        env: process.env,
+      });
+      const durationMs = Date.now() - start;
+      const parsedOut = parseOpaOutput(stdout);
+      const denies = extractDenies(parsedOut.deny);
+      const allow = parsedOut.allow === true;
+      return {
+        decision: allow ? 'allow' : 'deny',
+        source: 'opa',
+        reasons: allow ? [] : denies,
+        opaVersion: this.opaVersion,
+        durationMs,
+      };
+    } catch (err) {
+      const durationMs = Date.now() - start;
+      return this.failModeDecision(durationMs, err);
+    } finally {
+      if (tmpDir) {
+        try {
+          rmSync(tmpDir, { recursive: true, force: true });
+        } catch {
+          // best-effort cleanup
+        }
+      }
+    }
+  }
+
+  rulebookDigest(): string {
+    return this.digest;
+  }
+
+  private resolveBinary(): string {
+    return this.config.opaBinary ?? 'opa';
+  }
+
+  // Allow injecting a reader for testability without leaking fs into constructor.
+  private readFile = (path: string): string => {
+    try {
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const fs = require('node:fs') as typeof import('node:fs');
+      return fs.readFileSync(path, 'utf8');
+    } catch {
+      return '';
+    }
+  };
+
+  private failModeDecision(durationMs: number, err: unknown): EngineDecision {
+    const message = err instanceof Error ? err.message : String(err);
+    if (this.config.failMode === 'closed') {
+      return {
+        decision: 'deny',
+        source: 'fail-closed',
+        reasons: [{ message: `OPA unreachable (${this.config.failMode} mode): ${message}` }],
+        opaVersion: '',
+        durationMs,
+      };
+    }
+    return {
+      decision: 'allow',
+      source: 'fail-open',
+      reasons: [],
+      opaVersion: '',
+      durationMs,
+    };
+  }
+}
+
+interface OpaResult {
+  allow?: unknown;
+  deny?: unknown;
+}
+
+function parseOpaOutput(stdout: string): OpaResult {
+  const doc = JSON.parse(stdout) as {
+    result?: Array<{ expressions: Array<{ value: unknown }> }>;
+  };
+  // Single object query → one expression whose value is {allow, deny}.
+  const value = doc.result?.[0]?.expressions?.[0]?.value;
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    const v = value as Record<string, unknown>;
+    return { allow: v.allow, deny: v.deny };
+  }
+  return {};
+}
+
+function extractDenies(denyValue: unknown): RawDeny[] {
+  if (!denyValue || typeof denyValue !== 'object') return [];
+  // When queried inside an object construction ({"deny": data.safety.deny}),
+  // a Rego set serializes as {message: true}. When queried directly it's an
+  // array. Handle both.
+  if (Array.isArray(denyValue)) {
+    return denyValue
+      .filter((m): m is string => typeof m === 'string')
+      .map((message) => ({ message }));
+  }
+  if (denyValue instanceof Object) {
+    return Object.keys(denyValue as Record<string, unknown>).map((message) => ({ message }));
+  }
+  return [];
+}
+
+/** Probe `opa version` once; returns the version string or ''. */
+export async function probeOpaVersion(binary: string): Promise<string> {
+  try {
+    const { stdout } = await execFileAsync(binary, ['version'], { timeout: 2000 });
+    const match = /Version:\s*([0-9][^\s]*)/.exec(stdout);
+    return match ? match[1] : '';
+  } catch {
+    return '';
+  }
+}

package/src/engine/index.ts

@@ -0,0 +1,2 @@
+export { OpaCliEngine, probeOpaVersion } from './OpaCliEngine.ts';
+export type { DecisionEngine, EngineDecision, RawDeny } from './types.ts';

package/src/engine/types.ts

@@ -0,0 +1,35 @@
+import type { ParsedCommand } from '../parser/types.ts';
+
+/**
+ * Raw deny reasons from the engine (before provenance enrichment).
+ * OPA returns a set of message strings; richer engines may return structured.
+ */
+export interface RawDeny {
+  readonly message: string;
+}
+
+/** Outcome of an engine evaluation. */
+export interface EngineDecision {
+  /** Verdict. */
+  readonly decision: 'allow' | 'deny';
+  /** Where the decision came from: opa | fail-open | fail-closed | cached. */
+  readonly source: 'opa' | 'fail-open' | 'fail-closed' | 'cached';
+  /** Fired deny reasons (empty on allow). */
+  readonly reasons: readonly RawDeny[];
+  /** OPA version string (empty when not from live OPA). */
+  readonly opaVersion: string;
+  /** Wall-clock duration in ms. */
+  readonly durationMs: number;
+}
+
+/**
+ * Decision engine interface [LD1: OPA].
+ * OpaCliEngine is the reference implementation; the interface allows fakes/mocks.
+ */
+export interface DecisionEngine {
+  readonly name: string;
+  /** Evaluate the parsed command against the policy. */
+  evaluate(parsed: ParsedCommand): Promise<EngineDecision>;
+  /** SHA-256 prefix (12 hex) of the active policy bundle — for drift detection. */
+  rulebookDigest(): string;
+}

package/src/index.ts

@@ -0,0 +1,32 @@
+// Public API for pi-opa-net — agent-agnostic engine + structured output.
+//
+// Consumers: pi extension (future pi-opa-net-ext), scripts, other agents.
+// CLI entrypoint lives in src/cli/run.ts.
+
+export { configFromEnv, resolveOpaBinary } from './config/Config.ts';
+export type { EngineConfig, FailMode } from './config/Config.ts';
+
+export { CommandParserCoordinator, RegexFallbackParser, ShellQuoteParser } from './parser/index.ts';
+export type { CommandParser, ParseConfidence, ParsedCommand } from './parser/index.ts';
+
+export { OpaCliEngine, probeOpaVersion } from './engine/index.ts';
+export type { DecisionEngine, EngineDecision, RawDeny } from './engine/index.ts';
+
+export { RULES, RuleRegistry, inferFamilyFromProgram } from './rules/index.ts';
+export type { RuleFamily, RuleMeta } from './rules/index.ts';
+
+export {
+  DecisionBuilder,
+  OutputFormatter,
+  isValidDecision,
+  validateDecision,
+} from './output/index.ts';
+export type {
+  DecisionMetadata,
+  DecisionOutput,
+  EvaluatedInput,
+  OutputMode,
+  Reason,
+} from './output/index.ts';
+
+export { sha256Prefix } from './util/digest.ts';

package/src/output/DecisionBuilder.ts

@@ -0,0 +1,163 @@
+import { randomUUID } from 'node:crypto';
+import { hostname as osHostname } from 'node:os';
+import type { EngineConfig } from '../config/Config.ts';
+import type { EngineDecision, RawDeny } from '../engine/types.ts';
+import type { ParsedCommand } from '../parser/types.ts';
+import { type RuleMeta, type RuleRegistry, inferFamilyFromProgram } from '../rules/index.ts';
+
+/** The schema-compliant decision output (decision-output.v1). */
+export interface DecisionOutput {
+  readonly schema_version: '1.0';
+  readonly decision: 'allow' | 'deny';
+  readonly action: 'allow' | 'block' | 'prompt_user' | 'log_only';
+  readonly source: 'opa' | 'fail-open' | 'fail-closed' | 'cached';
+  readonly reasons: readonly Reason[];
+  readonly input: EvaluatedInput;
+  readonly summary: string;
+  readonly suggestions: string[];
+  readonly metadata: DecisionMetadata;
+  readonly evaluated_at: string;
+  readonly decision_id: string;
+  readonly duration_ms: number;
+}
+
+export interface Reason {
+  readonly rule_id: string;
+  readonly message: string;
+  readonly family: string;
+  readonly severity: 'block' | 'warn' | 'info';
+}
+
+export interface EvaluatedInput {
+  readonly raw: string;
+  readonly program: string;
+  readonly subcommand: string;
+  readonly args: string[];
+  readonly parse_confidence: 'full' | 'partial' | 'regex-only' | 'failed';
+}
+
+export interface DecisionMetadata {
+  readonly engine: 'opa';
+  readonly opa_version: string;
+  readonly rulebook_digest: string;
+  readonly policy_path: string;
+  readonly hostname: string;
+  readonly session_id: string;
+}
+
+export interface DecisionBuilderDeps {
+  readonly config: EngineConfig;
+  readonly registry: RuleRegistry;
+  readonly digest: string;
+  /** Inject now() for deterministic tests. */
+  readonly now?: () => Date;
+  /** Inject uuid for deterministic tests. */
+  readonly uuid?: () => string;
+}
+
+/**
+ * Builds the decision-output.v1 record from engine result + parsed input.
+ *
+ * OOP: this class owns the schema-shape assembly. It does NOT decide — it
+ * translates an EngineDecision + ParsedCommand into the auditable record.
+ * DRY: provenance lookup (registry), summary formatting, and suggestion
+ * aggregation each happen in exactly one place.
+ */
+export class DecisionBuilder {
+  private readonly deps: DecisionBuilderDeps;
+
+  constructor(deps: DecisionBuilderDeps) {
+    this.deps = deps;
+  }
+
+  build(parsed: ParsedCommand, engine: EngineDecision): DecisionOutput {
+    const reasons = engine.decision === 'deny' ? this.buildReasons(engine.reasons, parsed) : [];
+    const suggestions = this.collectSuggestions(reasons);
+    const action = engine.decision === 'allow' ? 'allow' : 'block';
+    return {
+      schema_version: '1.0',
+      decision: engine.decision,
+      action,
+      source: engine.source,
+      reasons,
+      input: {
+        raw: parsed.raw,
+        program: parsed.program,
+        subcommand: parsed.subcommand,
+        args: [...parsed.args],
+        parse_confidence: parsed.parseConfidence,
+      },
+      summary: this.summary(engine, parsed, reasons),
+      suggestions,
+      metadata: {
+        engine: 'opa',
+        opa_version: engine.opaVersion,
+        rulebook_digest: this.deps.digest,
+        policy_path: this.deps.config.policyPath,
+        hostname: this.deps.config.hostname ?? osHostname(),
+        session_id: this.deps.config.sessionId ?? '',
+      },
+      evaluated_at: (this.deps.now ?? (() => new Date()))().toISOString(),
+      decision_id: (this.deps.uuid ?? randomUUID)(),
+      duration_ms: engine.durationMs,
+    };
+  }
+
+  private buildReasons(raw: readonly RawDeny[], parsed: ParsedCommand): Reason[] {
+    return raw.map((d) => {
+      const meta = this.deps.registry.lookup(d);
+      return {
+        rule_id: meta.ruleId,
+        message: meta.message,
+        family: this.resolveFamily(meta, parsed),
+        severity: 'block' as const,
+      };
+    });
+  }
+
+  /** Use registered family; fall back to program-inferred family for sprintf rules. */
+  private resolveFamily(meta: RuleMeta, parsed: ParsedCommand): string {
+    if (meta.family !== 'custom') return meta.family;
+    const inferred = inferFamilyFromProgram(parsed.program);
+    return inferred;
+  }
+
+  private collectSuggestions(reasons: readonly Reason[]): string[] {
+    const out: string[] = [];
+    const seen = new Set<string>();
+    for (const r of reasons) {
+      const meta = this.findMetaByMessage(r.message);
+      if (meta?.suggestions) {
+        for (const s of meta.suggestions) {
+          if (!seen.has(s)) {
+            seen.add(s);
+            out.push(s);
+          }
+        }
+      }
+    }
+    return out;
+  }
+
+  private findMetaByMessage(message: string): RuleMeta | undefined {
+    // Registry exposes lookup via RawDeny; reuse isKnown + synthesize-free path.
+    const synth = this.deps.registry.lookup({ message });
+    return synth.ruleId.startsWith('custom:') ? undefined : synth;
+  }
+
+  private summary(
+    engine: EngineDecision,
+    parsed: ParsedCommand,
+    reasons: readonly Reason[],
+  ): string {
+    if (engine.decision === 'allow') {
+      if (engine.source === 'fail-open' || engine.source === 'fail-closed') {
+        return `ALLOWED (${engine.source}: OPA unreachable for ${engine.durationMs}ms)`;
+      }
+      return '';
+    }
+    const first = reasons[0];
+    const rule = first ? ` (rule: ${first.rule_id})` : '';
+    return `BLOCKED: ${parsed.raw}${rule}`;
+  }
+}

package/src/output/OutputFormatter.ts

@@ -0,0 +1,43 @@
+import addFormats from 'ajv-formats';
+import Ajv2020 from 'ajv/dist/2020.js';
+import schemaJson from '../../schemas/decision-output.v1.json' with { type: 'json' };
+import type { DecisionOutput } from './DecisionBuilder.ts';
+
+const ajv = new Ajv2020({ allErrors: true, strict: true });
+addFormats(ajv);
+const validateFn = ajv.compile(schemaJson);
+
+/** Validate a DecisionOutput against decision-output.v1. Throws on invalid. */
+export function validateDecision(output: DecisionOutput): void {
+  if (!validateFn(output)) {
+    const errs =
+      validateFn.errors?.map((e) => `${e.instancePath}: ${e.message}`).join('; ') ?? 'unknown';
+    throw new Error(`decision-output schema violation: ${errs}`);
+  }
+}
+
+/** Returns true if valid, false otherwise (no throw). */
+export function isValidDecision(output: DecisionOutput): boolean {
+  return validateFn(output) === true;
+}
+
+export type OutputMode = 'json' | 'claude-code';
+
+/**
+ * Formats a decision for emission. Owns the stdout/exit-code strategy [D6][CA2].
+ *
+ * - `json` mode: always emit the full schema record on stdout.
+ * - `claude-code` mode: suppress stdout on allow (Claude Code hook protocol
+ *   expects empty stdout for allowed commands); emit JSON only on deny.
+ *
+ * Exit codes: 0=allow, 2=deny (backward-compat with Claude Code hook protocol).
+ */
+export class OutputFormatter {
+  format(output: DecisionOutput, mode: OutputMode): { stdout: string; exitCode: number } {
+    const exitCode = output.decision === 'allow' ? 0 : 2;
+    if (mode === 'claude-code' && output.decision === 'allow') {
+      return { stdout: '', exitCode };
+    }
+    return { stdout: JSON.stringify(output), exitCode };
+  }
+}

package/src/output/index.ts

@@ -0,0 +1,9 @@
+export { DecisionBuilder } from './DecisionBuilder.ts';
+export { OutputFormatter, isValidDecision, validateDecision } from './OutputFormatter.ts';
+export type {
+  DecisionMetadata,
+  DecisionOutput,
+  EvaluatedInput,
+  Reason,
+} from './DecisionBuilder.ts';
+export type { OutputMode } from './OutputFormatter.ts';