pi-agent-supervisor 1.0.0

package/AGENTS.md

@@ -0,0 +1,56 @@
+# Agent Supervisor — Agent Usage Guide
+
+> You are an AI agent. The supervisor is ALWAYS watching. It blocks dangerous operations automatically. You cannot disable it.
+
+## What the Supervisor Does
+
+The supervisor runs passively on every tool call you make. It:
+
+1. **Blocks dangerous commands** — `rm -rf /`, `git push --force`, `sudo`, fork bombs
+2. **Protects sensitive files** — can't write to `.env`, credentials, SSH keys
+3. **Enforces rate limits** — warns at 50 calls/min, blocks at 80
+4. **Tracks errors** — escalates to human after 3 consecutive errors
+5. **Records everything** — append-only audit log in `.supervisor/audit.log`
+
+## When You Get Blocked
+
+If a command is blocked, you have two options:
+
+1. **Find an alternative** — use a safer approach
+2. **Request override** — call `supervisor_override(reason)` to ask the human
+
+```
+→ supervisor_override(reason="Need to force push the rebased feature branch")
+```
+
+The human will see the request and can approve or deny.
+
+## Checking Status
+
+```
+supervisor_status()
+```
+
+Shows:
+- Current tool call rate
+- Error count and consecutive errors
+- Number of blocked calls
+- Audit log location
+
+## Reading the Audit Log
+
+```
+supervisor_log(tail=20)
+```
+
+Reads the last 20 lines of the audit log. This is **read-only** — you cannot modify it.
+
+## What NOT to Do
+
+| Don't | Why |
+|---|---|
+| Don't try `rm -rf /` or `sudo rm` | Blocked — use `rm` without `-rf /` |
+| Don't write to `.env` directly | Blocked — use the proper secrets management |
+| Don't spam tool calls | Rate limited — batch operations when possible |
+| Don't ignore 3+ errors in a row | Escalation triggered — fix the root cause |
+| Don't try to delete `.supervisor/` | Protected directory |

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nandal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+# Agent Supervisor for Pi
+
+[![npm version](https://img.shields.io/npm/v/pi-agent-supervisor)](https://www.npmjs.com/package/pi-agent-supervisor)
+[![license](https://img.shields.io/npm/l/pi-agent-supervisor)](./LICENSE)
+
+> Runtime safety net for AI agents — blocks dangerous commands, protects sensitive files, enforces rate limits, and records sessions to an append-only audit log.
+
+## Philosophy
+
+The other three gates handle *what* agents do (contrib, review, project). The supervisor handles *how* agents do it — in real-time, while they work.
+
+## Install
+
+```bash
+pi install npm:pi-agent-supervisor
+```
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `supervisor_status()` | Show session stats — rate, errors, blocked calls |
+| `supervisor_log(tail)` | Read audit log (read-only, last N lines) |
+| `supervisor_override(reason)` | Request human override for blocked operation |
+
+## Runtime Protections
+
+These run **passively on every tool call** — no agent action needed:
+
+| Protection | Default | Behavior |
+|---|---|---|
+| Dangerous commands | 12 patterns | Blocks `rm -rf /`, `git push --force`, `sudo`, fork bombs, etc. |
+| File protection | 6 files + 5 patterns | Blocks writes to `.env`, credentials, SSH keys, secrets |
+| Rate limiting | 50/min warn, 80/min block | Pauses agent if tool call rate exceeds threshold |
+| Error escalation | 3 consecutive | Alerts human after 3+ consecutive errors |
+| Audit logging | Enabled | Append-only log of all tool calls, errors, blocks |
+
+## Configuration
+
+Create `.supervisorrc.yml`:
+
+```yaml
+# Blocked command patterns (comma-separated regex)
+blockedPatterns: "rm\\s+-rf\\s+/,rm\\s+-rf\\s+~,git\\s+push\\s+.*--force,sudo,chmod\\s+777"
+
+# Protected files (write blocked)
+protectedFiles: ".env,.env.local,credentials.json,.claude/settings.local.json,.git/config"
+
+# Protected file patterns (glob)
+protectedPatterns: "*.pem,*.key,id_rsa*,*secret*,*credential*"
+
+# Rate limiting
+rateLimitPerMinute: 50     # Warn threshold
+rateLimitHardBlock: 80     # Block threshold
+
+# Error escalation
+maxConsecutiveErrors: 3    # Escalate after this many consecutive errors
+
+# Audit log
+enableAuditLog: true
+auditLogPath: ".supervisor/audit.log"
+```
+
+## Audit Log
+
+Every action is recorded to an append-only log:
+
+```
+[2026-05-14T04:00:00.000Z] SESSION_START host=macbook cwd=/project
+[2026-05-14T04:00:01.000Z] CALL bash (rate: 1/min)
+[2026-05-14T04:00:02.000Z] CALL edit (rate: 2/min)
+[2026-05-14T04:00:03.000Z] BLOCK dangerous-cmd: rm -rf /tmp/*
+[2026-05-14T04:00:04.000Z] ERROR bash: command not found (consecutive: 1)
+[2026-05-14T04:00:05.000Z] SESSION_END calls=15 errors=1 blocked=1
+```
+
+The log is **append-only** — agents cannot modify or delete it.
+
+## Examples
+
+### Blocked: Dangerous Command
+
+```
+→ bash("sudo rm -rf /")
+⛔ Dangerous command blocked (pattern: "sudo")
+→ supervisor_override(reason="Need to clean deployment directory")
+Human confirmation required...
+```
+
+### Blocked: Protected File
+
+```
+→ write(".env", "SECRET=xyz")
+⛔ Write to protected file blocked: .env
+```
+
+### Rate Limited
+
+```
+⚠️ High tool call rate (55/50 calls/min). Slow down.
+⛔ Rate limit exceeded (85/80 calls/min). Paused.
+```
+
+## Integration
+
+Install all four gates for full agent governance:
+
+```bash
+pi install npm:pi-contrib-gate
+pi install npm:pi-review-gate
+pi install npm:pi-project-gate
+pi install npm:pi-agent-supervisor
+```
+
+## License
+
+MIT © [nandal](https://github.com/nandal)

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "pi-agent-supervisor",
+  "version": "1.0.0",
+  "description": "Runtime safety net for AI agents — blocks dangerous commands, protects files, enforces rate limits, and records sessions.",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "governance",
+    "safety",
+    "supervisor",
+    "rate-limiting",
+    "audit-log"
+  ],
+  "author": "nandal <nandal@users.noreply.github.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nandal/pi-ext",
+    "directory": "supervisor"
+  },
+  "homepage": "https://github.com/nandal/pi-ext/tree/main/supervisor",
+  "bugs": {
+    "url": "https://github.com/nandal/pi-ext/issues"
+  },
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "AGENTS.md",
+    "LICENSE"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  }
+}

package/src/index.ts

@@ -0,0 +1,477 @@
+/**
+ * pi-agent-supervisor — Runtime Safety Net
+ *
+ * Watches agents while they work. Blocks dangerous commands, protects
+ * sensitive files, enforces rate limits, tracks context budget, records
+ * sessions to an append-only log, and escalates on consecutive errors.
+ *
+ * Tools:
+ *   supervisor_status()         → show session stats (rate, errors, context)
+ *   supervisor_log(tail)        → read session log (read-only)
+ *   supervisor_override(reason) → request human override for blocked operation
+ *
+ * Config: .supervisorrc.yml
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+// ── Types ──
+
+interface SupervisorConfig {
+  /** Blocked command patterns */
+  blockedPatterns: string[];
+  /** Protected file paths (write blocked) */
+  protectedFiles: string[];
+  /** Protected file patterns (glob-like, write blocked) */
+  protectedPatterns: string[];
+  /** Max tool calls per minute before warning */
+  rateLimitPerMinute: number;
+  /** Max tool calls per minute before blocking */
+  rateLimitHardBlock: number;
+  /** Max consecutive errors before escalation */
+  maxConsecutiveErrors: number;
+  /** Whether to record session to audit log */
+  enableAuditLog: boolean;
+  /** Audit log path */
+  auditLogPath: string;
+  /** Context budget warning threshold (percentage) */
+  contextWarnThreshold: number;
+  /** Context budget critical threshold (percentage) */
+  contextCriticalThreshold: number;
+  /** Whether to block at critical context */
+  blockAtCriticalContext: boolean;
+}
+
+const DEFAULT_CONFIG: SupervisorConfig = {
+  blockedPatterns: [
+    "rm\\s+-rf\\s+/",
+    "rm\\s+-rf\\s+~",
+    "rm\\s+-rf\\s+\\*",
+    "git\\s+push\\s+.*--force",
+    "git\\s+push\\s+.*-f\\b",
+    "sudo\\s+",
+    "chmod\\s+777",
+    ">\\s*/dev/sd[a-z]",
+    "dd\\s+if=",
+    "mkfs\\.",
+    ":(){ :|:& };:", // fork bomb
+    ">\\s*\\.env",
+    ">\\s*\\.git",
+  ],
+  protectedFiles: [
+    ".env",
+    ".env.local",
+    ".env.production",
+    "credentials.json",
+    "serviceAccountKey.json",
+    ".claude/settings.local.json",
+    ".git/config",
+  ],
+  protectedPatterns: [
+    "*.pem",
+    "*.key",
+    "id_rsa*",
+    "*secret*",
+    "*credential*",
+  ],
+  rateLimitPerMinute: 50,
+  rateLimitHardBlock: 80,
+  maxConsecutiveErrors: 3,
+  enableAuditLog: true,
+  auditLogPath: ".supervisor/audit.log",
+  contextWarnThreshold: 70,
+  contextCriticalThreshold: 90,
+  blockAtCriticalContext: false,
+};
+
+// ── Config ──
+
+function loadConfig(cwd: string): SupervisorConfig {
+  const configPath = path.join(cwd, ".supervisorrc.yml");
+  if (!fs.existsSync(configPath)) return { ...DEFAULT_CONFIG };
+  try {
+    const content = fs.readFileSync(configPath, "utf-8");
+    const result: Record<string, unknown> = {};
+    for (const line of content.split("\n")) {
+      const m = line.match(/^\s*([\w][\w.]*):\s*(.+)$/);
+      if (m) result[m[1]] = m[2].trim();
+    }
+    return {
+      blockedPatterns: result["blockedPatterns"]
+        ? (result["blockedPatterns"] as string).split(",").map(s => s.trim()).filter(Boolean)
+        : DEFAULT_CONFIG.blockedPatterns,
+      protectedFiles: result["protectedFiles"]
+        ? (result["protectedFiles"] as string).split(",").map(s => s.trim()).filter(Boolean)
+        : DEFAULT_CONFIG.protectedFiles,
+      protectedPatterns: result["protectedPatterns"]
+        ? (result["protectedPatterns"] as string).split(",").map(s => s.trim()).filter(Boolean)
+        : DEFAULT_CONFIG.protectedPatterns,
+      rateLimitPerMinute: parseInt(result["rateLimitPerMinute"] as string) || DEFAULT_CONFIG.rateLimitPerMinute,
+      rateLimitHardBlock: parseInt(result["rateLimitHardBlock"] as string) || DEFAULT_CONFIG.rateLimitHardBlock,
+      maxConsecutiveErrors: parseInt(result["maxConsecutiveErrors"] as string) || DEFAULT_CONFIG.maxConsecutiveErrors,
+      enableAuditLog: result["enableAuditLog"] !== "false",
+      auditLogPath: (result["auditLogPath"] as string) || DEFAULT_CONFIG.auditLogPath,
+      contextWarnThreshold: parseInt(result["contextWarnThreshold"] as string) || DEFAULT_CONFIG.contextWarnThreshold,
+      contextCriticalThreshold: parseInt(result["contextCriticalThreshold"] as string) || DEFAULT_CONFIG.contextCriticalThreshold,
+      blockAtCriticalContext: result["blockAtCriticalContext"] === "true",
+    };
+  } catch {
+    return { ...DEFAULT_CONFIG };
+  }
+}
+
+// ── Session state ──
+
+interface SessionState {
+  toolCalls: Array<{ tool: string; timestamp: number }>;
+  errorCount: number;
+  consecutiveErrors: number;
+  blockedCount: number;
+  lastEscalation: number;
+  contextBudget: { used: number; total: number } | null;
+}
+
+let state: SessionState = {
+  toolCalls: [],
+  errorCount: 0,
+  consecutiveErrors: 0,
+  blockedCount: 0,
+  lastEscalation: 0,
+  contextBudget: null,
+};
+
+// ── Audit log ──
+
+function getAuditLogPath(baseDir: string, config: SupervisorConfig): string {
+  return path.join(baseDir, config.auditLogPath);
+}
+
+function appendToAuditLog(baseDir: string, config: SupervisorConfig, entry: string): void {
+  if (!config.enableAuditLog) return;
+  const logPath = getAuditLogPath(baseDir, config);
+  const dir = path.dirname(logPath);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+  // Append-only — use O_APPEND flag
+  const timestamp = new Date().toISOString();
+  const line = `[${timestamp}] ${entry}\n`;
+  fs.appendFileSync(logPath, line, { encoding: "utf-8" });
+}
+
+// ── Rate limiting ──
+
+function getCurrentRate(config: SupervisorConfig): number {
+  const now = Date.now();
+  const oneMinuteAgo = now - 60000;
+  // Keep only calls from the last minute
+  state.toolCalls = state.toolCalls.filter(c => c.timestamp > oneMinuteAgo);
+  return state.toolCalls.length;
+}
+
+// ── Command pattern matching ──
+
+function matchBlockedCommand(cmd: string, config: SupervisorConfig): string | null {
+  for (const pattern of config.blockedPatterns) {
+    try {
+      if (new RegExp(pattern, "i").test(cmd)) {
+        return pattern;
+      }
+    } catch {
+      // Invalid regex, skip
+    }
+  }
+  return null;
+}
+
+// ── File protection ──
+
+function isProtectedFile(filePath: string, config: SupervisorConfig): boolean {
+  const basename = path.basename(filePath);
+
+  // Exact file match
+  if (config.protectedFiles.some(f => filePath.includes(f) || basename === f)) {
+    return true;
+  }
+
+  // Glob pattern match
+  for (const pattern of config.protectedPatterns) {
+    // Simple glob: convert * to regex
+    const regexStr = pattern
+      .replace(/\./g, "\\.")
+      .replace(/\*/g, ".*");
+    try {
+      if (new RegExp(`^${regexStr}$`, "i").test(basename)) {
+        return true;
+      }
+    } catch {
+      // Invalid regex, skip
+    }
+  }
+
+  return false;
+}
+
+function detectFileWrite(cmd: string): string | null {
+  // Detect patterns like: > file, write to file, edit file, cat > file
+  const redirectMatch = cmd.match(/>\s*(\S+)/);
+  if (redirectMatch) return redirectMatch[1];
+
+  const writeMatch = cmd.match(/(?:write|edit)\s+["']?([^\s"']+)["']?/i);
+  if (writeMatch) return writeMatch[1];
+
+  return null;
+}
+
+// ── Extension ──
+
+export default function (pi: ExtensionAPI) {
+  // ═══════════════════════════════════════
+  // Runtime monitoring — intercept ALL tool calls
+  // ═══════════════════════════════════════
+  pi.on("tool_call", async (event, ctx) => {
+    const config = loadConfig(ctx.cwd);
+    const now = Date.now();
+
+    // Track call for rate limiting
+    state.toolCalls.push({ tool: event.toolName, timestamp: now });
+    const rate = getCurrentRate(config);
+
+    // Log the call
+    appendToAuditLog(ctx.cwd, config, `CALL ${event.toolName} (rate: ${rate}/min)`);
+
+    // ── Rate limiting ──
+    if (rate > config.rateLimitHardBlock) {
+      const msg = `⛔ Rate limit exceeded (${rate}/${config.rateLimitHardBlock} calls/min). Paused.`;
+      ctx.ui.notify(msg, "error");
+      appendToAuditLog(ctx.cwd, config, `BLOCK rate-limit: ${rate}/min`);
+      state.blockedCount++;
+      return { block: true, reason: msg };
+    }
+    if (rate > config.rateLimitPerMinute) {
+      ctx.ui.notify(
+        `⚠️ High tool call rate (${rate}/${config.rateLimitPerMinute} calls/min). Slow down.`,
+        "warning",
+      );
+    }
+
+    // ── Dangerous command blocking (bash only) ──
+    if (event.toolName === "bash" && typeof event.input.command === "string") {
+      const cmd = event.input.command;
+
+      // Check blocked patterns
+      const blockedPattern = matchBlockedCommand(cmd, config);
+      if (blockedPattern) {
+        const msg = `⛔ Dangerous command blocked (pattern: "${blockedPattern}")`;
+        ctx.ui.notify(msg, "error");
+        appendToAuditLog(ctx.cwd, config, `BLOCK dangerous-cmd: ${cmd.substring(0, 100)}`);
+        state.blockedCount++;
+        return { block: true, reason: msg };
+      }
+
+      // Check file protection
+      const writtenFile = detectFileWrite(cmd);
+      if (writtenFile && isProtectedFile(writtenFile, config)) {
+        const msg = `⛔ Write to protected file blocked: ${writtenFile}`;
+        ctx.ui.notify(msg, "error");
+        appendToAuditLog(ctx.cwd, config, `BLOCK protected-file: ${writtenFile}`);
+        state.blockedCount++;
+        return { block: true, reason: msg };
+      }
+    }
+
+    // ── File operation protection (write/edit tools) ──
+    if ((event.toolName === "write" || event.toolName === "edit") && event.input.path) {
+      const filePath = event.input.path as string;
+      if (isProtectedFile(filePath, config)) {
+        const msg = `⛔ Write to protected file blocked: ${filePath}`;
+        ctx.ui.notify(msg, "error");
+        appendToAuditLog(ctx.cwd, config, `BLOCK protected-file: ${filePath}`);
+        state.blockedCount++;
+        return { block: true, reason: msg };
+      }
+    }
+  });
+
+  // ── Error tracking ──
+  pi.on("tool_error", async (event, ctx) => {
+    const config = loadConfig(ctx.cwd);
+    state.errorCount++;
+    state.consecutiveErrors++;
+
+    appendToAuditLog(ctx.cwd, config,
+      `ERROR ${event.toolName}: ${String(event.error).substring(0, 200)} (consecutive: ${state.consecutiveErrors})`,
+    );
+
+    if (state.consecutiveErrors >= config.maxConsecutiveErrors) {
+      const msg = `🚨 ${state.consecutiveErrors} consecutive errors — escalation triggered. Pausing for human review.`;
+      ctx.ui.notify(msg, "error");
+      appendToAuditLog(ctx.cwd, config, `ESCALATE consecutive-errors: ${state.consecutiveErrors}`);
+      state.lastEscalation = Date.now();
+    }
+  });
+
+  // ── Track successes to reset error counter ──
+  pi.on("tool_result", async (event, ctx) => {
+    state.consecutiveErrors = 0; // Reset on success
+  });
+
+  // ═══════════════════════════════════════
+  // Tool: supervisor_status
+  // ═══════════════════════════════════════
+  pi.registerTool({
+    name: "supervisor_status",
+    label: "Supervisor Status",
+    description: "Show supervisor session stats — rate, errors, blocked calls, context budget.",
+    parameters: Type.Object({}),
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const config = loadConfig(ctx.cwd);
+      const rate = getCurrentRate(config);
+
+      const lines: string[] = [];
+      lines.push("🛡 Supervisor Status");
+      lines.push("");
+      lines.push(`📊 Tool calls: ${state.toolCalls.length} total (${rate}/min current)`);
+      lines.push(`   Rate limit: ${config.rateLimitPerMinute}/min warn, ${config.rateLimitHardBlock}/min block`);
+      lines.push(`❌ Errors: ${state.errorCount} total, ${state.consecutiveErrors} consecutive`);
+      lines.push(`   Escalation at: ${config.maxConsecutiveErrors} consecutive errors`);
+      lines.push(`🚫 Blocked: ${state.blockedCount} calls blocked`);
+      lines.push(`📝 Audit log: ${config.enableAuditLog ? config.auditLogPath : "disabled"}`);
+      lines.push(`🔒 Protected files: ${config.protectedFiles.length} exact, ${config.protectedPatterns.length} patterns`);
+
+      if (state.lastEscalation > 0) {
+        const escTime = new Date(state.lastEscalation).toISOString();
+        lines.push(`🚨 Last escalation: ${escTime}`);
+      }
+
+      return {
+        content: [{ type: "text", text: lines.join("\n") }],
+        details: {
+          rate,
+          errors: state.errorCount,
+          consecutiveErrors: state.consecutiveErrors,
+          blocked: state.blockedCount,
+          lastEscalation: state.lastEscalation,
+        },
+      };
+    },
+  });
+
+  // ═══════════════════════════════════════
+  // Tool: supervisor_log
+  // ═══════════════════════════════════════
+  pi.registerTool({
+    name: "supervisor_log",
+    label: "View Audit Log",
+    description: "Read the supervisor audit log (read-only, last N lines).",
+    parameters: Type.Object({
+      tail: Type.Optional(Type.Number({ description: "Number of recent lines to show (default: 50)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const config = loadConfig(ctx.cwd);
+      const logPath = getAuditLogPath(ctx.cwd, config);
+      const tail = params.tail || 50;
+
+      if (!fs.existsSync(logPath)) {
+        return {
+          content: [{ type: "text", text: "No audit log found. Session hasn't been recorded yet." }],
+          details: {},
+        };
+      }
+
+      const content = fs.readFileSync(logPath, "utf-8");
+      const lines = content.split("\n").filter(Boolean);
+      const recent = lines.slice(-tail);
+
+      // Highlight blocked/escalation entries
+      const formatted = recent.map(line => {
+        if (line.includes("BLOCK")) return `🚫 ${line}`;
+        if (line.includes("ESCALATE")) return `🚨 ${line}`;
+        if (line.includes("ERROR")) return `❌ ${line}`;
+        return `   ${line}`;
+      });
+
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `📝 Audit Log (last ${recent.length} of ${lines.length} entries)`,
+            `   Path: ${logPath}`,
+            "",
+            ...formatted,
+          ].join("\n"),
+        }],
+        details: { totalLines: lines.length, shown: recent.length, path: logPath },
+      };
+    },
+  });
+
+  // ═══════════════════════════════════════
+  // Tool: supervisor_override
+  // ═══════════════════════════════════════
+  pi.registerTool({
+    name: "supervisor_override",
+    label: "Request Override",
+    description: "Request human override for a blocked operation. Requires explicit confirmation.",
+    parameters: Type.Object({
+      reason: Type.String({ description: "Why the blocked operation should be allowed" }),
+      command: Type.Optional(Type.String({ description: "The specific command that was blocked (if applicable)" })),
+    }),
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const config = loadConfig(ctx.cwd);
+
+      const cmdInfo = params.command ? `\n\nBlocked command: ${params.command}` : "";
+      const msg = `Override requested${cmdInfo}\n\nReason: ${params.reason}\n\nAllow this operation?`;
+
+      const allowed = await ctx.ui.confirm("Supervisor Override", msg);
+
+      if (allowed) {
+        appendToAuditLog(ctx.cwd, config,
+          `OVERRIDE allowed: ${params.reason}${params.command ? ` (cmd: ${params.command.substring(0, 80)})` : ""}`,
+        );
+        return {
+          content: [{ type: "text", text: "✅ Override granted. Proceed with the operation." }],
+          details: { override: true, reason: params.reason },
+        };
+      } else {
+        appendToAuditLog(ctx.cwd, config,
+          `OVERRIDE denied: ${params.reason}`,
+        );
+        return {
+          content: [{ type: "text", text: "❌ Override denied. Operation remains blocked." }],
+          isError: true,
+          details: { override: false, reason: params.reason },
+        };
+      }
+    },
+  });
+
+  // ═══════════════════════════════════════
+  // Session lifecycle
+  // ═══════════════════════════════════════
+  pi.on("session_start", async (_event, ctx) => {
+    const config = loadConfig(ctx.cwd);
+    appendToAuditLog(ctx.cwd, config, `SESSION_START host=${os.hostname()} cwd=${ctx.cwd}`);
+
+    // Reset state for new session
+    state = {
+      toolCalls: [],
+      errorCount: 0,
+      consecutiveErrors: 0,
+      blockedCount: 0,
+      lastEscalation: 0,
+      contextBudget: null,
+    };
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    const config = loadConfig(ctx.cwd);
+    appendToAuditLog(ctx.cwd, config,
+      `SESSION_END calls=${state.toolCalls.length} errors=${state.errorCount} blocked=${state.blockedCount}`,
+    );
+  });
+}