pi-opa-net 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.2] - 2026-07-23
+
+### Fixed
+
+- CRITICAL: compound commands (e.g. `export FOO=bar; git stash pop`) now have EACH segment evaluated against the OPA policy. Previously the parser only saw the first command (`export`), which is always allowed, so dangerous commands after `;` were silently evaluated. This was the root cause of pi-opa-net appearing to never block commands in live pi sessions (pi-bash-guard prepends env exports to every command).
+
+## [0.3.1] - 2026-07-23
+
+### Fixed
+
+- CRITICAL: declared `pi.extensions` in package.json so pi-coding-agent's extension loader can discover the `tool_call` hook. Without this, the entire safety guard was a silent no-op (extension loaded but hook never registered).
+
 ## [0.2.0] - 2026-07-20
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-opa-net",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "OPA-backed bash command guard for the pi ecosystem — structured decision-output.v1 JSON, fail-open default, Claude Code hook protocol compatible. Agent-agnostic engine + CLI.",
   "type": "module",
   "main": "src/index.ts",
@@ -45,6 +45,9 @@
     "unlock-keys"
   ],
   "pi": {
+    "extensions": [
+      "./src/pi/index.ts"
+    ],
     "skills": [
       "./skills"
     ]

package/src/cli/run.ts

@@ -1,8 +1,14 @@
 import { resolve } from 'node:path';
-import { configFromEnv } from '../config/Config.ts';
-import { OpaCliEngine, probeOpaVersion } from '../engine/index.ts';
+import { type EngineConfig, configFromEnv } from '../config/Config.ts';
+import {
+  type DecisionEngine,
+  type EngineDecision,
+  OpaCliEngine,
+  probeOpaVersion,
+} from '../engine/index.ts';
 import { DecisionBuilder, type DecisionOutput } from '../output/DecisionBuilder.ts';
 import { OutputFormatter, validateDecision } from '../output/OutputFormatter.ts';
+import type { CommandParser, ParsedCommand } from '../parser/index.ts';
 import { CommandParserCoordinator } from '../parser/index.ts';
 import { RULES, RuleRegistry } from '../rules/index.ts';
 import { SaltResolver } from '../unlock/SaltResolver.ts';
@@ -63,11 +69,8 @@ export async function runCli(opts: CliOptions): Promise<CliResult> {
   const hasKeys = unlockKeys.length > 0;
 
   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,
@@ -75,6 +78,98 @@ export async function runCli(opts: CliOptions): Promise<CliResult> {
     digest: engine.rulebookDigest(),
   });
 
+  // Compound commands (joined by ';'): split and evaluate EACH segment.
+  // If ANY segment is denied, the whole command is denied. This catches
+  // env-prefixed commands like `export FOO=bar; git stash pop` where
+  // pi-bash-guard prepends env exports to every bash invocation.
+  const output = await evaluatePossiblyCompound(raw, {
+    parser,
+    engine,
+    config,
+    builder,
+    unlockKeys,
+    hasKeys,
+  });
+
+  // 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 };
+}
+
+/**
+ * Evaluate a possibly-compound raw command string. If it contains ';',
+ * evaluate each segment and return deny if ANY segment is denied.
+ * Single commands (no ';') take the existing fast path unchanged.
+ */
+async function evaluatePossiblyCompound(
+  raw: string,
+  deps: {
+    parser: CommandParser;
+    engine: DecisionEngine;
+    config: EngineConfig;
+    builder: DecisionBuilder;
+    unlockKeys: readonly string[];
+    hasKeys: boolean;
+  },
+): Promise<DecisionOutput> {
+  const { parser, engine, config, builder, unlockKeys, hasKeys } = deps;
+
+  // Split on ';' but only treat as compound if more than one non-empty segment.
+  const segments = raw
+    .split(';')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+
+  if (segments.length <= 1) {
+    // Single command path — unchanged behavior.
+    const parsed = parser.parse(raw);
+    const engineDecision = await engine.evaluate(parsed);
+    return buildDecision(parsed, engineDecision, { config, builder, unlockKeys, hasKeys });
+  }
+
+  // Compound path: evaluate each segment, deny wins.
+  let denyOutput: DecisionOutput | undefined;
+  for (const segment of segments) {
+    const parsed = parser.parse(segment);
+    const engineDecision = await engine.evaluate(parsed);
+    const output = buildDecision(parsed, engineDecision, { config, builder, unlockKeys, hasKeys });
+    if (output.decision === 'deny' && output.action === 'block') {
+      denyOutput = output;
+      break; // first deny wins
+    }
+  }
+
+  if (denyOutput) {
+    return denyOutput;
+  }
+
+  // All segments allowed — return an allow decision based on the first segment.
+  const firstParsed = parser.parse(segments[0] ?? '');
+  const firstEngineDecision = await engine.evaluate(firstParsed);
+  return buildDecision(firstParsed, firstEngineDecision, {
+    config,
+    builder,
+    unlockKeys,
+    hasKeys,
+  });
+}
+
+/** Build a DecisionOutput from a parsed command + engine decision, applying unlock keys. */
+function buildDecision(
+  parsed: ParsedCommand,
+  engineDecision: EngineDecision,
+  deps: {
+    config: EngineConfig;
+    builder: DecisionBuilder;
+    unlockKeys: readonly string[];
+    hasKeys: boolean;
+  },
+): DecisionOutput {
+  const { config, builder, unlockKeys, hasKeys } = deps;
+
   let output: DecisionOutput;
 
   if (engineDecision.source === 'fail-open' && hasKeys) {
@@ -111,12 +206,7 @@ export async function runCli(opts: CliOptions): Promise<CliResult> {
     }
   }
 
-  // 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 };
+  return output;
 }
 
 function resolveRaw(opts: CliOptions): string {

package/src/hermes/audit.ts

@@ -0,0 +1,81 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { DecisionOutput } from '../output/DecisionBuilder.ts';
+
+/**
+ * Redact common secret patterns from a command string before audit.
+ * - Bearer tokens / Authorization headers
+ * - API keys (sk-... long hex/alnum)
+ */
+export function redactSecrets(text: string): string {
+  let out = text;
+  // Authorization: Bearer <token>
+  out = out.replace(/(Bearer\s+)([A-Za-z0-9._\-]+)/gi, '$1[REDACTED]');
+  // Generic sk-<token> (Stripe/Anthropic/etc API keys)
+  out = out.replace(/\bsk-[A-Za-z0-9_\-]{6,}/g, 'sk-[REDACTED]');
+  return out;
+}
+
+/**
+ * Audit sink bridge — writes one JSONL line per decision.
+ *
+ * Test/unit injectable: tests pass an `auditSink` with a captured `write`.
+ * Production wires this to a real filesystem sink (JSONL append).
+ */
+export interface AuditSink {
+  write: (entry: unknown) => Promise<void>;
+}
+
+export interface WriteAuditEntryInput {
+  sessionId: string | undefined;
+  decision: Pick<
+    DecisionOutput,
+    'decision' | 'source' | 'reasons' | 'input' | 'evaluated_at' | 'decision_id'
+  >;
+  auditSink: AuditSink;
+}
+
+interface AuditEntry {
+  decision_id: string;
+  decision: string;
+  source: string;
+  command: string;
+  rule_ids: string[];
+  evaluated_at: string;
+}
+
+export async function writeAuditEntry(input: WriteAuditEntryInput): Promise<void> {
+  if (!input.sessionId) return;
+
+  const entry: AuditEntry = {
+    decision_id: input.decision.decision_id,
+    decision: input.decision.decision,
+    source: input.decision.source,
+    command: redactSecrets(input.decision.input.raw),
+    rule_ids: input.decision.reasons.map((r) => r.rule_id),
+    evaluated_at: input.decision.evaluated_at,
+  };
+
+  await input.auditSink.write(entry);
+}
+
+/**
+ * Default filesystem audit sink — appends JSONL to `${cwd}/.opa-net/audit/${decision_id}.jsonl`.
+ * Production wires this when ctx.auditSink is not injected.
+ */
+export function createFilesystemAuditSink(cwd: string): AuditSink {
+  const auditDir = resolve(cwd, '.opa-net', 'audit');
+  return {
+    write: async (entry: unknown) => {
+      try {
+        mkdirSync(auditDir, { recursive: true });
+        const decisionId = (entry as { decision_id?: string }).decision_id ?? 'unknown';
+        const logPath = resolve(auditDir, `${decisionId}.jsonl`);
+        appendFileSync(logPath, `${JSON.stringify(entry)}\n`);
+      } catch {
+        // Audit write failure is non-fatal — log to stderr and continue.
+        console.error('[opa-net] audit write failed, continuing without audit');
+      }
+    },
+  };
+}

package/src/hermes/index.ts

@@ -0,0 +1,46 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { registerPreToolCallHook } from './tool-call.ts';
+
+type HermesPluginCtx = {
+  register_hook: (hook: string, callback: (kwargs: Record<string, unknown>) => unknown) => void;
+};
+
+/**
+ * Auto-discover the rule/policy config for the Hermes agent.
+ *
+ * Priority:
+ *   1. HERMES_OPA_NET_HOME env alias → PIOPANET_HOME (always honored if set)
+ *   2. HERMES_HOME env → check for <HERMES_HOME>/opa-net/rules/ existence
+ *      → set PIOPANET_HOME only if candidate exists (never bogus)
+ *
+ * Mirrors src/pi/index.ts autoDiscoverOpaNetHome but adapted for Hermes.
+ */
+function autoDiscoverOpaNetHome(): void {
+  // Honor explicit alias first (no existence check — user explicitly set it).
+  const alias = process.env.HERMES_OPA_NET_HOME;
+  if (alias) {
+    process.env.PIOPANET_HOME = alias;
+    return;
+  }
+
+  if (process.env.PIOPANET_HOME) return;
+
+  // Auto-discover from HERMES_HOME.
+  const hermesHome = process.env.HERMES_HOME;
+  if (!hermesHome) return;
+
+  const candidate = join(hermesHome, 'opa-net');
+  if (existsSync(join(candidate, 'rules'))) {
+    process.env.PIOPANET_HOME = candidate;
+  }
+}
+
+export default function hermesOpaNetExtension(ctx: HermesPluginCtx): void {
+  autoDiscoverOpaNetHome();
+  registerPreToolCallHook(ctx);
+}
+
+// Re-export for direct unit-test access.
+export { handleHermesToolCall, registerPreToolCallHook } from './tool-call.ts';
+export type { HermesToolCallContext, HermesToolCallResult } from './tool-call.ts';

package/src/hermes/tool-call.ts

@@ -0,0 +1,222 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { DecisionOutput } from '../output/DecisionBuilder.ts';
+import { type AuditSink, createFilesystemAuditSink, writeAuditEntry } from './audit.ts';
+
+/** Fail-closed block reason — mirrors pi-safety-net's REASON_SAFETY_NET_FAILED_CLOSED. */
+export const REASON_OPA_NET_FAILED_CLOSED =
+  'OPA-Net fail-closed: command evaluation failed unexpectedly.';
+
+/** Reason prefix for malformed shell tool input. */
+const REASON_MALFORMED_SHELL_INPUT =
+  'OPA-Net fail-closed: shell tool call input missing required command field.';
+
+type HermesApi = {
+  register_hook: (
+    hook: 'pre_tool_call',
+    handler: (kwargs: Record<string, unknown>) => Promise<HermesToolCallResult>,
+  ) => void;
+};
+
+export type EvalOpts = { cwd?: string; env?: NodeJS.ProcessEnv };
+
+export type HermesToolCallContext = {
+  cwd: string;
+  sessionManager: {
+    getSessionFile: () => string | undefined;
+  };
+  /**
+   * Inject-able eval function. Unit tests pass a stub. Production wires this
+   * to the real `bin/pi-opa-net.js eval` subprocess.
+   */
+  opaNetEvalCommand?: (command: string, opts?: EvalOpts) => Promise<DecisionOutput>;
+  /** Optional audit sink for test capture. Production wires filesystem sink. */
+  auditSink?: AuditSink;
+  /** Reserved for future config passthrough. */
+  opaNetConfigOptions?: Record<string, unknown>;
+};
+
+/**
+ * Hermes-canonical block directive. Hermes plugins.py @2101-2175 expects
+ * `{action: 'block', message: string}` to veto a tool call.
+ */
+export type HermesToolCallResult = { action: 'block'; message: string } | undefined;
+
+type HermesToolCallEvent = {
+  tool_name?: string;
+  tool_call_id?: string;
+  args?: Record<string, unknown>;
+};
+
+type HermesShellToolAdapter = {
+  commandField: string;
+  cwdField?: string;
+};
+
+/**
+ * Hermes shell tool adapters. Hermes uses 'terminal' as the canonical shell
+ * tool name, but also accepts 'bash' for backward compat. The command lives
+ * in args.command, cwd in args.cwd (or args.working_directory for Grok compat).
+ */
+const HERMES_SHELL_TOOL_ADAPTERS: Partial<Record<string, HermesShellToolAdapter>> = {
+  terminal: { commandField: 'command', cwdField: 'cwd' },
+  bash: { commandField: 'command', cwdField: 'cwd' },
+  shell: { commandField: 'command', cwdField: 'working_directory' },
+};
+
+type HermesShellToolCall = { command: string; cwd: string } | { malformed: true };
+
+/**
+ * Register the pre_tool_call hook on a Hermes plugin ctx.
+ *
+ * Hermes's dispatcher invokes the callback with a SINGLE kwargs object
+ * ({tool_name, args, tool_call_id, session_id, ...}) — NOT (event, ctx).
+ * This wrapper bridges that to handleHermesToolCall(event, ctx) by building
+ * the context from process state (cwd, HERMES_SESSION_FILE env).
+ */
+export function registerPreToolCallHook(api: HermesApi): void {
+  const wrapped = (kwargs: Record<string, unknown>): Promise<HermesToolCallResult> => {
+    const ctx: HermesToolCallContext = {
+      cwd: process.cwd(),
+      sessionManager: {
+        getSessionFile: () => process.env.HERMES_SESSION_FILE,
+      },
+    };
+    return handleHermesToolCall(kwargs, ctx);
+  };
+  api.register_hook('pre_tool_call', wrapped);
+}
+
+function isStrictMode(): boolean {
+  return process.env.PIOPANET_STRICT === '1';
+}
+
+/**
+ * Default subprocess eval — spawns `bin/pi-opa-net.js eval "<cmd>" --json`
+ * and parses stdout as DecisionOutput. This is the production bridge:
+ * without this, the handler has no way to evaluate commands.
+ *
+ * Mirrors pi-safety-net's `?? analyzeCommand` default.
+ */
+async function defaultEvalCommand(command: string, opts?: EvalOpts): Promise<DecisionOutput> {
+  const binPath = resolve(fileURLToPath(import.meta.url), '../../../bin/pi-opa-net.js');
+  const cwd = opts?.cwd ?? process.cwd();
+
+  return new Promise((accept, reject) => {
+    const child = spawn('bun', [binPath, 'eval', command, '--json'], {
+      cwd,
+      env: opts?.env ?? process.env,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d: Buffer) => {
+      stdout += d.toString();
+    });
+    child.stderr.on('data', (d: Buffer) => {
+      stderr += d.toString();
+    });
+    child.on('error', reject);
+    child.on('close', (code: number | null) => {
+      if (code !== 0 && code !== 2) {
+        // Exit code 0 = allow, 2 = deny. Anything else = subprocess error.
+        reject(new Error(`pi-opa-net eval exited ${code}: ${stderr}`));
+        return;
+      }
+      try {
+        const decision = JSON.parse(stdout.trim()) as DecisionOutput;
+        accept(decision);
+      } catch (err) {
+        reject(
+          new Error(`pi-opa-net eval non-JSON stdout: ${stdout.slice(0, 200)}\nstderr: ${stderr}`),
+        );
+      }
+    });
+  });
+}
+
+/** @internal — exported for test coverage */
+export async function handleHermesToolCall(
+  event: Record<string, unknown>,
+  ctx: HermesToolCallContext,
+): Promise<HermesToolCallResult> {
+  const shellToolCall = getHermesShellToolCall(event, ctx);
+  if (!shellToolCall) return undefined;
+
+  if ('malformed' in shellToolCall) {
+    return blockHermesToolCall(REASON_MALFORMED_SHELL_INPUT);
+  }
+
+  const { command, cwd } = shellToolCall;
+
+  // Use injected eval OR default subprocess eval.
+  const evalCommand = ctx.opaNetEvalCommand ?? defaultEvalCommand;
+
+  let decision: DecisionOutput;
+  try {
+    decision = await evalCommand(command, { cwd });
+  } catch {
+    // Fork fail-open default: do not brick the agent on eval errors.
+    if (isStrictMode()) {
+      return blockHermesToolCall(REASON_OPA_NET_FAILED_CLOSED, command);
+    }
+    return undefined;
+  }
+
+  // Allow + log_only: proceed (with audit).
+  // opa-unlocked: engine already filtered — plugin trusts it.
+  // fail-open / cached: degraded paths — proceed silently.
+  if (
+    decision.decision === 'allow' ||
+    decision.action === 'allow' ||
+    decision.action === 'log_only'
+  ) {
+    return undefined;
+  }
+
+  // Deny + block: translate + audit + block.
+  if (decision.decision === 'deny' && decision.action === 'block') {
+    const sessionId = ctx.sessionManager.getSessionFile();
+    if (sessionId) {
+      const auditSink = ctx.auditSink ?? createFilesystemAuditSink(cwd);
+      await writeAuditEntry({
+        sessionId,
+        decision,
+        auditSink,
+      });
+    }
+    return blockHermesToolCall(formatBlockMessage(decision), command);
+  }
+
+  // prompt_user (reserved v2) — treat as allow for now.
+  return undefined;
+}
+
+function getHermesShellToolCall(
+  event: Record<string, unknown>,
+  ctx: HermesToolCallContext,
+): HermesShellToolCall | undefined {
+  const toolCall = event as HermesToolCallEvent;
+  if (typeof toolCall.tool_name !== 'string') return undefined;
+
+  const adapter = HERMES_SHELL_TOOL_ADAPTERS[toolCall.tool_name];
+  if (!adapter) return undefined;
+  if (!toolCall.args || typeof toolCall.args !== 'object') return { malformed: true };
+
+  const command = toolCall.args[adapter.commandField];
+  if (typeof command !== 'string') return { malformed: true };
+
+  const cwdInput = adapter.cwdField ? toolCall.args[adapter.cwdField] : undefined;
+  const cwd = typeof cwdInput === 'string' ? resolve(ctx.cwd, cwdInput) : ctx.cwd;
+  return { command, cwd };
+}
+
+function formatBlockMessage(decision: DecisionOutput): string {
+  const reasons = decision.reasons.map((r) => `${r.rule_id}: ${r.message}`).join('; ');
+  const header = decision.summary || 'BLOCKED by OPA-Net';
+  return `${header}\nReason: ${reasons}\nRule family: ${decision.reasons[0]?.family ?? 'unknown'}`;
+}
+
+function blockHermesToolCall(message: string, _command?: string): HermesToolCallResult {
+  return { action: 'block', message };
+}

package/src/zcode/audit.ts

@@ -0,0 +1,81 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { DecisionOutput } from '../output/DecisionBuilder.ts';
+
+/**
+ * Redact common secret patterns from a command string before audit.
+ * - Bearer tokens / Authorization headers
+ * - API keys (sk-... long hex/alnum)
+ */
+export function redactSecrets(text: string): string {
+  let out = text;
+  // Authorization: Bearer <token>
+  out = out.replace(/(Bearer\s+)([A-Za-z0-9._\-]+)/gi, '$1[REDACTED]');
+  // Generic sk-<token> (Stripe/Anthropic/etc API keys)
+  out = out.replace(/\bsk-[A-Za-z0-9_\-]{6,}/g, 'sk-[REDACTED]');
+  return out;
+}
+
+/**
+ * Audit sink bridge — writes one JSONL line per decision.
+ *
+ * Test/unit injectable: tests pass an `auditSink` with a captured `write`.
+ * Production wires this to a real filesystem sink (JSONL append).
+ */
+export interface AuditSink {
+  write: (entry: unknown) => Promise<void>;
+}
+
+export interface WriteAuditEntryInput {
+  sessionId: string | undefined;
+  decision: Pick<
+    DecisionOutput,
+    'decision' | 'source' | 'reasons' | 'input' | 'evaluated_at' | 'decision_id'
+  >;
+  auditSink: AuditSink;
+}
+
+interface AuditEntry {
+  decision_id: string;
+  decision: string;
+  source: string;
+  command: string;
+  rule_ids: string[];
+  evaluated_at: string;
+}
+
+export async function writeAuditEntry(input: WriteAuditEntryInput): Promise<void> {
+  if (!input.sessionId) return;
+
+  const entry: AuditEntry = {
+    decision_id: input.decision.decision_id,
+    decision: input.decision.decision,
+    source: input.decision.source,
+    command: redactSecrets(input.decision.input.raw),
+    rule_ids: input.decision.reasons.map((r) => r.rule_id),
+    evaluated_at: input.decision.evaluated_at,
+  };
+
+  await input.auditSink.write(entry);
+}
+
+/**
+ * Default filesystem audit sink — appends JSONL to `${cwd}/.opa-net/audit/<decision_id>.jsonl`.
+ * Production wires this when ctx.auditSink is not injected.
+ */
+export function createFilesystemAuditSink(cwd: string): AuditSink {
+  const auditDir = resolve(cwd, '.opa-net', 'audit');
+  return {
+    write: async (entry: unknown) => {
+      try {
+        mkdirSync(auditDir, { recursive: true });
+        const decisionId = (entry as { decision_id?: string }).decision_id ?? 'unknown';
+        const logPath = resolve(auditDir, `${decisionId}.jsonl`);
+        appendFileSync(logPath, `${JSON.stringify(entry)}\n`);
+      } catch {
+        // Audit write failure is non-fatal — log to stderr and continue.
+        console.error('[opa-net] audit write failed, continuing without audit');
+      }
+    },
+  };
+}

package/src/zcode/index.ts

@@ -0,0 +1,96 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { type ZcodeToolCallContext, handleZcodeToolCall } from './tool-call.ts';
+
+/**
+ * Auto-discover the rule/policy config for the ZCode agent.
+ *
+ * Priority:
+ *   1. ZCODE_OPA_NET_HOME env alias → PIOPANET_HOME (always honored if set)
+ *   2. ZCODE_HOME env → check for <ZCODE_HOME>/opa-net/rules/ existence
+ *      → set PIOPANET_HOME only if candidate exists (never bogus)
+ *
+ * Mirrors src/hermes/index.ts autoDiscoverOpaNetHome but adapted for ZCode.
+ */
+export function autoDiscoverOpaNetHome(): void {
+  // Honor explicit alias first (no existence check — user explicitly set it).
+  const alias = process.env.ZCODE_OPA_NET_HOME;
+  if (alias) {
+    process.env.PIOPANET_HOME = alias;
+    return;
+  }
+
+  if (process.env.PIOPANET_HOME) return;
+
+  // Auto-discover from ZCODE_HOME.
+  const zcodeHome = process.env.ZCODE_HOME;
+  if (!zcodeHome) return;
+
+  const candidate = join(zcodeHome, 'opa-net');
+  if (existsSync(join(candidate, 'rules'))) {
+    process.env.PIOPANET_HOME = candidate;
+  }
+}
+
+/**
+ * Build the ZCode tool-call context from process state.
+ * cwd from process.cwd(); sessionManager reads ZCODE_SESSION_FILE env.
+ */
+function buildContext(): ZcodeToolCallContext {
+  return {
+    cwd: process.cwd(),
+    sessionManager: {
+      getSessionFile: () => process.env.ZCODE_SESSION_FILE,
+    },
+  };
+}
+
+/**
+ * Run the ZCode PreToolUse hook script.
+ *
+ * ZCode dispatches command-type hooks by spawning the hook command and piping
+ * a JSON payload on stdin. This function:
+ *   1. Reads stdin (the PreToolUse payload)
+ *   2. Calls handleZcodeToolCall(payload, ctx)
+ *   3. Writes the result JSON to stdout (or {} on allow / error)
+ *
+ * Failure isolation: on ANY error, emit {} (never block the turn, never emit
+ * invalid JSON). Mirrors ZCode's own hook conventions.
+ */
+export async function runHookScript(): Promise<void> {
+  autoDiscoverOpaNetHome();
+
+  let payload: Record<string, unknown> = {};
+  try {
+    const chunks: Buffer[] = [];
+    for await (const chunk of process.stdin) {
+      chunks.push(chunk as Buffer);
+    }
+    const raw = Buffer.concat(chunks).toString('utf8').trim();
+    if (raw) {
+      payload = JSON.parse(raw);
+    }
+  } catch {
+    // Malformed stdin — emit {} and let the tool call proceed.
+    process.stdout.write('{}');
+    return;
+  }
+
+  try {
+    const result = await handleZcodeToolCall(payload, buildContext());
+    process.stdout.write(result ? JSON.stringify(result) : '{}');
+  } catch {
+    // Failure isolation — never break the agent turn.
+    process.stdout.write('{}');
+  }
+}
+
+// Default export: object (ZCode uses command hooks, not callback registration).
+export default {
+  runHookScript,
+  autoDiscoverOpaNetHome,
+};
+
+// Re-export for direct unit-test access.
+export { handleZcodeToolCall } from './tool-call.ts';
+export type { ZcodeToolCallContext, ZcodeToolCallResult } from './tool-call.ts';

package/src/zcode/tool-call.ts

@@ -0,0 +1,195 @@
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { DecisionOutput } from '../output/DecisionBuilder.ts';
+import { type AuditSink, createFilesystemAuditSink, writeAuditEntry } from './audit.ts';
+
+/** Fail-closed block reason — mirrors pi-safety-net's REASON_SAFETY_NET_FAILED_CLOSED. */
+export const REASON_OPA_NET_FAILED_CLOSED =
+  'OPA-Net fail-closed: command evaluation failed unexpectedly.';
+
+/** Reason prefix for malformed shell tool input. */
+const REASON_MALFORMED_SHELL_INPUT =
+  'OPA-Net fail-closed: shell tool call input missing required command field.';
+
+export type EvalOpts = { cwd?: string; env?: NodeJS.ProcessEnv };
+
+export type ZcodeToolCallContext = {
+  cwd: string;
+  sessionManager: {
+    getSessionFile: () => string | undefined;
+  };
+  /**
+   * Inject-able eval function. Unit tests pass a stub. Production wires this
+   * to the real `bin/pi-opa-net.js eval` subprocess (shared engine CLI).
+   */
+  opaNetEvalCommand?: (command: string, opts?: EvalOpts) => Promise<DecisionOutput>;
+  /** Optional audit sink for test capture. Production wires filesystem sink. */
+  auditSink?: AuditSink;
+  /** Reserved for future config passthrough. */
+  opaNetConfigOptions?: Record<string, unknown>;
+};
+
+/**
+ * ZCode-canonical block directive (verified against zcode.cjs bundle).
+ * permissionDecision enum: "allow" | "ask" | "deny".
+ */
+export type ZcodeToolCallResult =
+  | {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'deny';
+        permissionDecisionReason: string;
+      };
+    }
+  | undefined;
+
+type ZcodePreToolUsePayload = {
+  hookEventName?: string;
+  toolName?: string;
+  tool_name?: string;
+  toolInput?: Record<string, unknown>;
+  tool_input?: Record<string, unknown>;
+};
+
+/**
+ * ZCode shell tool names. ZCode is Claude-Code-compatible, so the canonical
+ * shell tool is "Bash" (capitalized). "terminal" is an alias.
+ */
+const ZCODE_SHELL_TOOL_NAMES = new Set(['Bash', 'bash', 'terminal', 'shell', 'Shell']);
+
+type ZcodeShellToolCall = { command: string } | { malformed: true };
+
+function isStrictMode(): boolean {
+  return process.env.PIOPANET_STRICT === '1';
+}
+
+/**
+ * Default subprocess eval — spawns `bin/pi-opa-net.js eval "<cmd>" --json`
+ * (shared engine CLI) and parses stdout as DecisionOutput. This is the
+ * production bridge.
+ */
+async function defaultEvalCommand(command: string, opts?: EvalOpts): Promise<DecisionOutput> {
+  const binPath = resolve(fileURLToPath(import.meta.url), '../../../bin/pi-opa-net.js');
+  const cwd = opts?.cwd ?? process.cwd();
+
+  return new Promise((accept, reject) => {
+    const child = spawn('bun', [binPath, 'eval', command, '--json'], {
+      cwd,
+      env: opts?.env ?? process.env,
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout.on('data', (d: Buffer) => {
+      stdout += d.toString();
+    });
+    child.stderr.on('data', (d: Buffer) => {
+      stderr += d.toString();
+    });
+    child.on('error', reject);
+    child.on('close', (code: number | null) => {
+      if (code !== 0 && code !== 2) {
+        // Exit code 0 = allow, 2 = deny. Anything else = subprocess error.
+        reject(new Error(`pi-opa-net eval exited ${code}: ${stderr}`));
+        return;
+      }
+      try {
+        const decision = JSON.parse(stdout.trim()) as DecisionOutput;
+        accept(decision);
+      } catch (err) {
+        reject(
+          new Error(`pi-opa-net eval non-JSON stdout: ${stdout.slice(0, 200)}\nstderr: ${stderr}`),
+        );
+      }
+    });
+  });
+}
+
+/** @internal — exported for test coverage */
+export async function handleZcodeToolCall(
+  payload: Record<string, unknown>,
+  ctx: ZcodeToolCallContext,
+): Promise<ZcodeToolCallResult> {
+  const shellToolCall = getZcodeShellToolCall(payload);
+  if (!shellToolCall) return undefined;
+
+  if ('malformed' in shellToolCall) {
+    return blockZcodeToolCall(REASON_MALFORMED_SHELL_INPUT);
+  }
+
+  const { command } = shellToolCall;
+
+  // Use injected eval OR default subprocess eval.
+  const evalCommand = ctx.opaNetEvalCommand ?? defaultEvalCommand;
+
+  let decision: DecisionOutput;
+  try {
+    decision = await evalCommand(command, { cwd: ctx.cwd });
+  } catch {
+    // Fail-open default: do not brick the agent on eval errors.
+    if (isStrictMode()) {
+      return blockZcodeToolCall(REASON_OPA_NET_FAILED_CLOSED);
+    }
+    return undefined;
+  }
+
+  // Allow + log_only: proceed (with audit).
+  // opa-unlocked: engine already filtered — plugin trusts it.
+  // fail-open / cached: degraded paths — proceed silently.
+  if (
+    decision.decision === 'allow' ||
+    decision.action === 'allow' ||
+    decision.action === 'log_only'
+  ) {
+    return undefined;
+  }
+
+  // Deny + block: translate + audit + block.
+  if (decision.decision === 'deny' && decision.action === 'block') {
+    const sessionId = ctx.sessionManager.getSessionFile();
+    if (sessionId) {
+      const auditSink = ctx.auditSink ?? createFilesystemAuditSink(ctx.cwd);
+      await writeAuditEntry({
+        sessionId,
+        decision,
+        auditSink,
+      });
+    }
+    return blockZcodeToolCall(formatBlockMessage(decision));
+  }
+
+  // prompt_user (reserved v2) — treat as allow for now.
+  return undefined;
+}
+
+function getZcodeShellToolCall(payload: Record<string, unknown>): ZcodeShellToolCall | undefined {
+  const event = payload as ZcodePreToolUsePayload;
+  const toolName = event.toolName ?? event.tool_name;
+  if (typeof toolName !== 'string') return undefined;
+
+  if (!ZCODE_SHELL_TOOL_NAMES.has(toolName)) return undefined;
+
+  const toolInput = event.toolInput ?? event.tool_input;
+  if (!toolInput || typeof toolInput !== 'object') return { malformed: true };
+
+  const command = toolInput.command;
+  if (typeof command !== 'string') return { malformed: true };
+
+  return { command };
+}
+
+function formatBlockMessage(decision: DecisionOutput): string {
+  const reasons = decision.reasons.map((r) => `${r.rule_id}: ${r.message}`).join('; ');
+  const header = decision.summary || 'BLOCKED by OPA-Net';
+  return `${header}\nReason: ${reasons}\nRule family: ${decision.reasons[0]?.family ?? 'unknown'}`;
+}
+
+function blockZcodeToolCall(reason: string): ZcodeToolCallResult {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}