watchmyagents 0.1.0 → 0.2.0

package/README.md

@@ -170,12 +170,35 @@ For added safety, generate a **workspace-scoped** API key with read-only permiss
 
 Report vulnerabilities via [SECURITY.md](./SECURITY.md).
 
+## Shield — real-time policy enforcement
+
+`wma-shield` (shipped in v0.2.0) is the real-time enforcement companion to Watch. It streams agent events live, evaluates them against a local JSON policy file, and blocks tool calls that violate the policy via `user.tool_confirmation` (when the agent has `permission_policy: always_ask` configured) or `user.interrupt` (zero-setup fallback).
+
+```bash
+# Agent-wide mode — attaches to ALL active sessions of the agent automatically.
+# Run under a process supervisor (systemd, pm2, docker) for production.
+wma-shield --agent-id agent_xxx --policy ./policies.json
+```
+
+Shield auto-detects the best enforcement mode at startup:
+- **tool_confirmation** (precise, pre-execution blocking) when at least one tool has `permission_policy: always_ask`
+- **interrupt** (degraded, post-execution termination) otherwise
+
+For the precise mode setup instructions:
+```bash
+wma-shield --setup-guide --agent-id agent_xxx
+```
+
+Decisions are logged to the same NDJSON stream as Watch (`action_type: shield_decision`), so `wma-inspect` surfaces them in its audit summaries.
+
 ## Status
 
-- ✅ Anthropic Managed Agents (post-hoc fetch + audit)
+- ✅ Watch SDK — Anthropic Managed Agents post-hoc fetch + local audit
+- ✅ Shield SDK — real-time enforcement (interrupt mode + tool_confirmation mode)
 - 🚧 Encrypted upload to customer's own cloud (S3/GCS/Azure with `age` public-key encryption)
 - 🚧 Anonymized telemetry to WMA cloud (opt-in, freemium model)
-- 🚧 Shield product — real-time policy gating via `user.tool_confirmation` + `user.interrupt`
+- 🚧 Guardian AI (cloud) — automatic policy suggestions from observed behavior
+- 🚧 Fortress (cloud) — dashboard + human-in-the-loop validation queue
 - 🚧 Adapters for in-process agents (Claude SDK, OpenAI, LangChain, generic) — code present in `src/adapters/` but unverified against the new Modèle C architecture; documentation will follow once re-validated
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watchmyagents",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Security observability for AI agents — local-first NDJSON capture of every agent action (tool calls, prompts, state transitions, errors). Built for security audits, not just token counting.",
   "type": "module",
   "main": "./src/index.cjs",
@@ -19,17 +19,20 @@
     "src/",
     "scripts/inspect.js",
     "scripts/fetch-anthropic.js",
+    "scripts/shield.js",
     "README.md",
     "SECURITY.md",
     "LICENSE"
   ],
   "bin": {
     "wma-inspect": "scripts/inspect.js",
-    "wma-fetch": "scripts/fetch-anthropic.js"
+    "wma-fetch": "scripts/fetch-anthropic.js",
+    "wma-shield": "scripts/shield.js"
   },
   "scripts": {
     "inspect": "node scripts/inspect.js",
     "fetch": "node scripts/fetch-anthropic.js",
+    "shield": "node scripts/shield.js",
     "example": "node examples/claude-agent/index.js"
   },
   "engines": {

package/scripts/shield.js

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+// wma-shield — real-time policy enforcement for Anthropic Managed Agents.
+//
+// Two modes:
+//
+//   AGENT-WIDE (production)  — wma-shield --agent-id agent_xxx
+//     Attaches to ALL active sessions of the agent. Discovers new sessions
+//     via periodic listSessions polling. Runs forever until SIGINT.
+//
+//   SINGLE-SESSION (testing) — wma-shield --agent-id agent_xxx --session-id sesn_xxx
+//     Attaches to one specific session and exits when that session ends.
+//
+// Within each session, Shield uses one of two enforcement modes auto-detected
+// at startup from the agent config:
+//
+//   tool_confirmation — when at least one tool has permission_policy:always_ask.
+//                       Blocks tool calls BEFORE execution.
+//   interrupt         — when no tool has always_ask. Reactive: terminates the
+//                       session AFTER a violating tool ran. Zero setup required.
+//
+// Setup helper:
+//   wma-shield --setup-guide --agent-id agent_xxx
+//     → prints instructions to upgrade to tool_confirmation mode.
+//
+// ANTHROPIC_API_KEY env var is used if --api-key is omitted.
+
+import { resolve } from 'node:path';
+import { streamWithReconnect } from '../src/shield/stream.js';
+import { loadPolicies, evaluate } from '../src/shield/policy.js';
+import {
+  confirmAllow, confirmDeny, interruptSession,
+  getAgentConfig, detectAlwaysAsk,
+} from '../src/shield/enforce.js';
+import { DecisionLogger } from '../src/shield/decisions.js';
+import { listSessions } from '../src/sources/anthropic-managed.js';
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const k = a.slice(2);
+      const n = argv[i + 1];
+      if (n == null || n.startsWith('--')) out[k] = true;
+      else { out[k] = n; i++; }
+    }
+  }
+  return out;
+}
+
+function die(msg, code = 1) { process.stderr.write(`${msg}\n`); process.exit(code); }
+function info(msg) { process.stdout.write(`[shield] ${msg}\n`); }
+function warn(msg) { process.stderr.write(`[shield] ⚠️  ${msg}\n`); }
+function sinfo(sid, msg) { process.stdout.write(`[shield/${sid.slice(0, 12)}] ${msg}\n`); }
+function swarn(sid, msg) { process.stderr.write(`[shield/${sid.slice(0, 12)}] ⚠️  ${msg}\n`); }
+
+const CACHEABLE_TOOL_TYPES = new Set([
+  'agent.tool_use', 'agent.mcp_tool_use', 'agent.custom_tool_use',
+]);
+
+// Session statuses that mean "still active, worth watching"
+const ACTIVE_STATUSES = new Set(['running', 'idle', 'rescheduled']);
+
+function normalizeForPolicy(rawEvent) {
+  return {
+    action_type: rawEvent.type === 'agent.tool_use' ? 'tool_use'
+               : rawEvent.type === 'agent.mcp_tool_use' ? 'mcp_tool_use'
+               : rawEvent.type === 'agent.custom_tool_use' ? 'custom_tool_use'
+               : 'unknown',
+    tool_name: rawEvent.name || 'unknown',
+    input: rawEvent.input ?? null,
+    _raw_type: rawEvent.type,
+    _raw_id: rawEvent.id,
+  };
+}
+
+function printSetupGuide(agentId) {
+  process.stdout.write(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Shield setup guide — upgrade your agent to precise mode
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Without permission_policy: always_ask configured on your agent's
+tools, Shield runs in DEGRADED mode (interrupts the session AFTER
+a violating tool already executed).
+
+For pre-execution blocking, your agent's "tools" array needs:
+
+  {
+    "type": "agent_toolset_20260401",
+    "default_config": {
+      "permission_policy": { "type": "always_ask" }
+    }
+  }
+
+Anthropic's API does NOT support PATCH on /v1/agents, so options:
+
+  Option A — Edit in the Anthropic Console (recommended):
+    1. Visit https://console.anthropic.com/agents/${agentId}
+    2. Edit the agent
+    3. Set default_config.permission_policy to { "type": "always_ask" }
+    4. Save. NEW sessions use the updated permission policy.
+
+  Option B — Recreate the agent via API (returns a new agent_id):
+    Use POST /v1/agents with your current config + the snippet above.
+
+After either option, restart Shield — it auto-detects the new mode.
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+`);
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Per-session worker — runs one event loop, returns when session ends.
+// ────────────────────────────────────────────────────────────────────────
+async function runSessionWorker({ sessionId, ctx }) {
+  const { apiKey, agentId, ruleset, mode, decisions, signal } = ctx;
+  sinfo(sessionId, `attached (${mode} mode)`);
+
+  let processed = 0, enforced = 0, sessionInterrupted = false;
+  const toolUseCache = new Map();
+
+  try {
+    for await (const rawEvent of streamWithReconnect({
+      apiKey, sessionId, signal, maxAttempts: 3,
+      onReconnect: ({ attempt, backoffMs, error }) => {
+        sinfo(sessionId, `reconnect attempt ${attempt}/3 in ${backoffMs}ms (${error.message})`);
+      },
+    })) {
+      processed++;
+
+      // ── INTERRUPT MODE ──────────────────────────────────────────────
+      if (mode === 'interrupt' && CACHEABLE_TOOL_TYPES.has(rawEvent.type)) {
+        toolUseCache.set(rawEvent.id, rawEvent);
+        const normalized = normalizeForPolicy(rawEvent);
+        const t0 = Date.now();
+        const result = evaluate(normalized, ruleset);
+        const decidedInMs = Date.now() - t0;
+
+        sinfo(sessionId, `${rawEvent.type} tool=${normalized.tool_name} → ${result.decision}${result.rule_id ? ` (${result.rule_id})` : ''}`);
+
+        await decisions(sessionId).record({
+          sourceEvent: rawEvent, decision: result.decision,
+          ruleId: result.rule_id, ruleName: result.rule_name,
+          message: result.message, decidedInMs,
+        });
+
+        if ((result.decision === 'deny' || result.decision === 'interrupt') && !sessionInterrupted) {
+          try {
+            await interruptSession({
+              apiKey, sessionId,
+              followUpMessage: `Shield interrupted: ${result.message || result.rule_name || 'policy violation'}`,
+            });
+            sessionInterrupted = true;
+            enforced++;
+            swarn(sessionId, 'session interrupted — agent loop stopped');
+          } catch (e) {
+            process.stderr.write(`[shield/${sessionId.slice(0, 12)}] interrupt error: ${e.message}\n`);
+          }
+        }
+        continue;
+      }
+
+      // ── TOOL_CONFIRMATION MODE ──────────────────────────────────────
+      if (mode === 'tool_confirmation' && CACHEABLE_TOOL_TYPES.has(rawEvent.type)) {
+        toolUseCache.set(rawEvent.id, rawEvent);
+        continue;
+      }
+
+      if (mode === 'tool_confirmation'
+          && rawEvent.type === 'session.status_idle'
+          && rawEvent.stop_reason?.type === 'requires_action'
+          && Array.isArray(rawEvent.stop_reason.event_ids)) {
+
+        for (const eventId of rawEvent.stop_reason.event_ids) {
+          const sourceEvent = toolUseCache.get(eventId);
+          if (!sourceEvent) {
+            swarn(sessionId, `requires_action for unknown event_id ${eventId} — denying defensively`);
+            try {
+              await confirmDeny({
+                apiKey, sessionId, toolUseId: eventId,
+                denyMessage: 'Shield never saw the original tool_use. Denying defensively.',
+              });
+            } catch (e) {
+              process.stderr.write(`[shield/${sessionId.slice(0, 12)}] enforcement error: ${e.message}\n`);
+            }
+            continue;
+          }
+
+          const normalized = normalizeForPolicy(sourceEvent);
+          const t0 = Date.now();
+          const result = evaluate(normalized, ruleset);
+          const decidedInMs = Date.now() - t0;
+
+          sinfo(sessionId, `requires_action ${sourceEvent.type} tool=${normalized.tool_name} → ${result.decision}${result.rule_id ? ` (${result.rule_id})` : ''}`);
+
+          await decisions(sessionId).record({
+            sourceEvent, decision: result.decision,
+            ruleId: result.rule_id, ruleName: result.rule_name,
+            message: result.message, decidedInMs,
+          });
+
+          try {
+            if (result.decision === 'allow') {
+              await confirmAllow({ apiKey, sessionId, toolUseId: eventId });
+              enforced++;
+            } else if (result.decision === 'deny') {
+              await confirmDeny({
+                apiKey, sessionId, toolUseId: eventId,
+                denyMessage: result.message || `Blocked by ${result.rule_name}`,
+              });
+              enforced++;
+            } else if (result.decision === 'interrupt') {
+              await interruptSession({
+                apiKey, sessionId,
+                followUpMessage: `Shield interrupted: ${result.message || result.rule_name}`,
+              });
+              sessionInterrupted = true;
+              enforced++;
+              break;
+            }
+          } catch (e) {
+            process.stderr.write(`[shield/${sessionId.slice(0, 12)}] enforcement error on event ${eventId}: ${e.message}\n`);
+          }
+
+          toolUseCache.delete(eventId);
+        }
+        continue;
+      }
+
+      // Session ended → exit worker cleanly.
+      if (rawEvent.type === 'session.status_terminated') {
+        sinfo(sessionId, `session terminated: ${rawEvent.stop_reason?.type || 'unknown'}`);
+        break;
+      }
+    }
+  } catch (e) {
+    if (!signal.aborted) {
+      process.stderr.write(`[shield/${sessionId.slice(0, 12)}] worker error: ${e.message}\n`);
+    }
+  }
+
+  sinfo(sessionId, `worker exit — observed ${processed}, enforced ${enforced}`);
+  return { processed, enforced };
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Agent-wide discovery — polls listSessions and spawns workers for new ones.
+// ────────────────────────────────────────────────────────────────────────
+async function runAgentWide(ctx) {
+  const { apiKey, agentId, signal } = ctx;
+  const workers = new Map();      // sessionId → AbortController (active workers)
+  const cooldown = new Map();     // sessionId → unix-ms timestamp when re-attach is allowed
+
+  const POLL_INTERVAL_MS = 10_000;
+  // When a worker exits without seeing any events, the session's SSE stream
+  // closed cleanly with no traffic — Anthropic does this for idle sessions.
+  // Re-attaching every 10s spams the logs and the API for no benefit; cool down
+  // for 60s before trying again. Any real activity invalidates the cooldown.
+  const QUIET_COOLDOWN_MS = 60_000;
+
+  async function discoverAndAttach() {
+    let sessions;
+    try {
+      // Look at sessions from the last 24h (anything older that's still idle
+      // is probably stale; the user can extend the window if needed).
+      const since = new Date(Date.now() - 24 * 3600_000);
+      sessions = await listSessions(apiKey, { agentId, since });
+    } catch (e) {
+      warn(`listSessions failed: ${e.message}`);
+      return;
+    }
+
+    const now = Date.now();
+    for (const s of sessions) {
+      if (!s.id || workers.has(s.id)) continue;
+      const status = s.status?.type || s.status; // tolerate either shape
+      if (!ACTIVE_STATUSES.has(status)) continue;
+
+      // Honor the cooldown for sessions that recently exited quietly.
+      const retryAt = cooldown.get(s.id) || 0;
+      if (now < retryAt) continue;
+
+      // New active session — spawn a worker.
+      const sessionAc = new AbortController();
+      workers.set(s.id, sessionAc);
+      const combined = AbortSignal.any([signal, sessionAc.signal]);
+
+      runSessionWorker({
+        sessionId: s.id,
+        ctx: { ...ctx, signal: combined },
+      }).then((stats) => {
+        // Quiet exit → cooldown so we don't busy-loop reconnecting.
+        // Productive exit (at least one event observed) → clear any cooldown.
+        if (stats && stats.processed === 0) {
+          cooldown.set(s.id, Date.now() + QUIET_COOLDOWN_MS);
+        } else {
+          cooldown.delete(s.id);
+        }
+      }).finally(() => {
+        workers.delete(s.id);
+      });
+    }
+  }
+
+  info(`agent-wide mode — polling for sessions every ${POLL_INTERVAL_MS / 1000}s`);
+  await discoverAndAttach();
+
+  const ticker = setInterval(discoverAndAttach, POLL_INTERVAL_MS);
+
+  // Block until SIGINT/SIGTERM.
+  await new Promise(resolveOuter => {
+    signal.addEventListener('abort', () => {
+      clearInterval(ticker);
+      for (const ac of workers.values()) ac.abort();
+      resolveOuter();
+    });
+  });
+
+  info(`shutdown — drained ${workers.size} remaining workers`);
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Main
+// ────────────────────────────────────────────────────────────────────────
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const apiKey = args['api-key'] || process.env.ANTHROPIC_API_KEY;
+  const agentId = args['agent-id'];
+
+  if (args['setup-guide']) {
+    if (!agentId) die('error: --setup-guide requires --agent-id <id>');
+    printSetupGuide(agentId);
+    process.exit(0);
+  }
+
+  const singleSessionId = args['session-id']; // optional now
+  const policyPath = args.policy;
+  const logDir = resolve(args['log-dir'] || './watchmyagents-logs');
+
+  if (!apiKey) die('error: --api-key or ANTHROPIC_API_KEY required');
+  if (!agentId) die('error: --agent-id required');
+  if (!policyPath) die('error: --policy <path-to-policies.json> required');
+
+  let ruleset;
+  try {
+    ruleset = await loadPolicies(resolve(policyPath));
+  } catch (e) {
+    die(`error loading policies: ${e.message}`);
+  }
+
+  let mode = 'interrupt';
+  let agentMeta = null;
+  try {
+    agentMeta = await getAgentConfig(apiKey, agentId);
+    if (detectAlwaysAsk(agentMeta)) mode = 'tool_confirmation';
+  } catch (e) {
+    warn(`could not fetch agent config (${e.message}). Defaulting to interrupt mode.`);
+  }
+
+  info(`armed — ${ruleset.policies.length} policies loaded from ${policyPath}`);
+  info(`default action when no rule matches: ${ruleset.default.action}`);
+  info(`agent: ${agentId}${agentMeta?.name ? ` "${agentMeta.name}"` : ''}`);
+  info(`enforcement mode: ${mode}`);
+  if (mode === 'interrupt') {
+    warn('DEGRADED mode — Shield will interrupt AFTER a violating tool runs.');
+    warn(`For pre-execution blocking, run: wma-shield --setup-guide --agent-id ${agentId}`);
+  }
+
+  // Per-session DecisionLogger factory (each session gets its own to keep
+  // sequence numbers monotonic per session).
+  const loggers = new Map();
+  const decisions = (sessionId) => {
+    if (!loggers.has(sessionId)) {
+      loggers.set(sessionId, new DecisionLogger({ logDir, agentId, sessionId }));
+    }
+    return loggers.get(sessionId);
+  };
+
+  const ac = new AbortController();
+  process.on('SIGINT',  () => { info('SIGINT received, shutting down…'); ac.abort(); });
+  process.on('SIGTERM', () => { info('SIGTERM received, shutting down…'); ac.abort(); });
+
+  const ctx = { apiKey, agentId, ruleset, mode, decisions, signal: ac.signal };
+
+  if (singleSessionId) {
+    info(`single-session mode — attached to ${singleSessionId}`);
+    await runSessionWorker({ sessionId: singleSessionId, ctx });
+  } else {
+    await runAgentWide(ctx);
+  }
+}
+
+main().catch(e => {
+  process.stderr.write(`error: ${e.stack || e.message}\n`);
+  process.exit(1);
+});

package/src/shield/decisions.js

@@ -0,0 +1,46 @@
+// Shield decisions logger.
+//
+// Writes one NDJSON line per Shield decision into the same daily-rotated
+// file as Watch, with action_type: "shield_decision". This closes the
+// recursive loop trivially — the next wma-fetch / wma-inspect run will
+// surface Shield's actions alongside the agent's actions.
+
+import { Logger } from '../logger.js';
+
+export class DecisionLogger {
+  constructor({ logDir, agentId, sessionId }) {
+    this._logger = new Logger({ logDir, agentId, sessionId, silent: true });
+  }
+
+  // Record a decision Shield made about an upstream event. Shield's own
+  // action_type is 'shield_decision' — this lets aggregations (wma-inspect)
+  // distinguish them from the agent's own actions.
+  async record({
+    sourceEvent,      // the original Anthropic event we decided on (for context)
+    decision,         // 'allow' | 'deny' | 'interrupt'
+    ruleId,
+    ruleName,
+    message,
+    decidedInMs,
+  }) {
+    return this._logger.write({
+      action_type: 'shield_decision',
+      framework: 'anthropic-managed',
+      tool_name: sourceEvent?.name || sourceEvent?.tool_name || null,
+      status: decision === 'deny' || decision === 'interrupt' ? 'error' : 'ok',
+      error: decision === 'deny' || decision === 'interrupt' ? message : null,
+      duration_ms: decidedInMs ?? null,
+      input: {
+        source_event_id: sourceEvent?.id || null,
+        source_event_type: sourceEvent?.type || null,
+        tool_input: sourceEvent?.input ?? null,
+      },
+      output: {
+        decision,
+        rule_id: ruleId,
+        rule_name: ruleName,
+        message,
+      },
+    });
+  }
+}

package/src/shield/enforce.js

@@ -0,0 +1,104 @@
+// Shield enforcement — sends user.tool_confirmation back to Anthropic
+// to allow or deny a pending tool call.
+//
+// Per Anthropic docs (managed-agents-2026-04-01 beta), when a tool requires
+// confirmation (via a permission policy on the agent), the session emits
+// agent.tool_use and then pauses on session.status_idle with
+// stop_reason: requires_action. The user.tool_confirmation event resolves it.
+
+const API_BASE = 'https://api.anthropic.com';
+const BETA = 'managed-agents-2026-04-01';
+const VERSION = '2023-06-01';
+
+function authHeaders(apiKey) {
+  return {
+    'x-api-key': apiKey,
+    'anthropic-version': VERSION,
+    'anthropic-beta': BETA,
+    'content-type': 'application/json',
+  };
+}
+
+// GET /v1/agents/{id} — used at Shield startup to determine which enforcement
+// mode (tool_confirmation vs interrupt) is available.
+export async function getAgentConfig(apiKey, agentId) {
+  const url = `${API_BASE}/v1/agents/${agentId}`;
+  const res = await fetch(url, { headers: authHeaders(apiKey) });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`getAgent failed: HTTP ${res.status}: ${body.slice(0, 300)}`);
+  }
+  return res.json();
+}
+
+// Inspect agent config to determine if any tool/toolset has
+// permission_policy.type === "always_ask". When at least one tool does,
+// Shield can use the precise tool_confirmation flow. Otherwise it falls
+// back to user.interrupt (post-hoc termination).
+export function detectAlwaysAsk(agent) {
+  const tools = agent?.tools || [];
+  const mcp = (agent?.mcp_servers || []).length > 0;
+  for (const t of tools) {
+    if (t?.default_config?.permission_policy?.type === 'always_ask') return true;
+    if (Array.isArray(t?.configs)) {
+      for (const c of t.configs) {
+        if (c?.permission_policy?.type === 'always_ask') return true;
+      }
+    }
+    // MCP toolsets default to always_ask per Anthropic docs (if any MCP server
+    // is attached but no explicit always_allow override is set).
+    if (t?.type === 'mcp_toolset' && !t?.default_config?.permission_policy) {
+      return true;
+    }
+  }
+  // If the agent has MCP servers but no explicit mcp_toolset config, MCP
+  // defaults are always_ask — so we still get requires_action for MCP calls.
+  return mcp;
+}
+
+async function sendEvents(apiKey, sessionId, events) {
+  const url = `${API_BASE}/v1/sessions/${sessionId}/events?beta=true`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: authHeaders(apiKey),
+    body: JSON.stringify({ events }),
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`enforce failed: HTTP ${res.status}: ${body.slice(0, 300)}`);
+  }
+  return res;
+}
+
+// Approve a pending tool_use by its event id.
+export function confirmAllow({ apiKey, sessionId, toolUseId }) {
+  return sendEvents(apiKey, sessionId, [{
+    type: 'user.tool_confirmation',
+    tool_use_id: toolUseId,
+    result: 'allow',
+  }]);
+}
+
+// Deny a pending tool_use with an explanatory message that surfaces to the
+// agent (the agent sees the deny_message in its tool_result).
+export function confirmDeny({ apiKey, sessionId, toolUseId, denyMessage }) {
+  return sendEvents(apiKey, sessionId, [{
+    type: 'user.tool_confirmation',
+    tool_use_id: toolUseId,
+    result: 'deny',
+    deny_message: denyMessage || 'Blocked by Shield policy',
+  }]);
+}
+
+// Interrupt the entire session (stops the agent loop). Used for serious
+// policy violations where letting the agent continue is unsafe.
+export function interruptSession({ apiKey, sessionId, followUpMessage }) {
+  const events = [{ type: 'user.interrupt' }];
+  if (followUpMessage) {
+    events.push({
+      type: 'user.message',
+      content: [{ type: 'text', text: followUpMessage }],
+    });
+  }
+  return sendEvents(apiKey, sessionId, events);
+}

package/src/shield/policy.js

@@ -0,0 +1,112 @@
+// Shield policy engine — JSON parser + match evaluator.
+// Zero dependencies. JSON intentionally over YAML to keep the SDK dep-free.
+//
+// Match spec format (matches the future Fortress JSONB schema):
+//
+//   {
+//     "match": {
+//       "action_type": "tool_use",
+//       "tool_name": { "not_in": ["web_search", "web_fetch"] },
+//       "input.url": { "not_regex": "^https://(github|wikipedia)\\.com/" }
+//     },
+//     "action": "deny",
+//     "message": "..."
+//   }
+//
+// Supported conditions on a field value:
+//   - literal value         → strict equality
+//   - { in: [...] }         → value must be in the list
+//   - { not_in: [...] }     → value must NOT be in the list
+//   - { regex: "..." }      → string match against the regex
+//   - { not_regex: "..." }  → string must NOT match the regex
+//   - { regex_any: [...] }  → string matches at least one of the regexes
+//
+// Field paths use dotted notation (`input.url`, `output.content.text`).
+
+import { readFile } from 'node:fs/promises';
+
+export async function loadPolicies(path) {
+  const raw = await readFile(path, 'utf8');
+  const data = JSON.parse(raw);
+  if (!data.policies || !Array.isArray(data.policies)) {
+    throw new Error(`policy file ${path} has no "policies" array`);
+  }
+  // Pre-compile regex for performance + early failure on bad patterns.
+  for (const p of data.policies) {
+    compileMatchRegexes(p.match || {});
+    if (!['allow', 'deny', 'interrupt'].includes(p.action)) {
+      throw new Error(`policy ${p.id || p.name}: unsupported action "${p.action}"`);
+    }
+  }
+  data.default = data.default || { action: 'allow' };
+  return data;
+}
+
+function compileMatchRegexes(match) {
+  for (const condition of Object.values(match)) {
+    if (condition && typeof condition === 'object') {
+      if (condition.regex) condition._regex = new RegExp(condition.regex);
+      if (condition.not_regex) condition._not_regex = new RegExp(condition.not_regex);
+      if (condition.regex_any) condition._regex_any = condition.regex_any.map(r => new RegExp(r));
+    }
+  }
+}
+
+function getNested(obj, path) {
+  return path.split('.').reduce((o, k) => (o == null ? undefined : o[k]), obj);
+}
+
+function matchValue(value, condition) {
+  // Literal scalar match
+  if (condition === null || typeof condition !== 'object') {
+    return value === condition;
+  }
+  if (Array.isArray(condition)) {
+    return condition.includes(value);
+  }
+  if (condition.in !== undefined) return condition.in.includes(value);
+  if (condition.not_in !== undefined) return !condition.not_in.includes(value);
+  if (condition._regex !== undefined) {
+    return typeof value === 'string' && condition._regex.test(value);
+  }
+  if (condition._not_regex !== undefined) {
+    return typeof value === 'string' && !condition._not_regex.test(value);
+  }
+  if (condition._regex_any !== undefined) {
+    return typeof value === 'string' && condition._regex_any.some(r => r.test(value));
+  }
+  // Unknown condition shape — defensive: fail-closed (no match) so unknown
+  // conditions never silently allow events.
+  return false;
+}
+
+// Evaluate a single policy against an event. Returns true iff every match
+// clause is satisfied. A match clause with an undefined target field still
+// counts as "no match" rather than "any match".
+export function matchesPolicy(event, policy) {
+  for (const [field, condition] of Object.entries(policy.match || {})) {
+    const value = getNested(event, field);
+    if (!matchValue(value, condition)) return false;
+  }
+  return true;
+}
+
+// First-match-wins evaluation. Returns the policy decision and metadata.
+export function evaluate(event, ruleset) {
+  for (const policy of ruleset.policies) {
+    if (matchesPolicy(event, policy)) {
+      return {
+        decision: policy.action,
+        rule_id: policy.id || null,
+        rule_name: policy.name || null,
+        message: policy.message || null,
+      };
+    }
+  }
+  return {
+    decision: ruleset.default?.action || 'allow',
+    rule_id: null,
+    rule_name: '(default)',
+    message: null,
+  };
+}

package/src/shield/stream.js

@@ -0,0 +1,101 @@
+// Anthropic Managed Agents SSE stream client.
+//
+// Opens GET /v1/sessions/{id}/events/stream and yields one parsed event per
+// SSE `data:` line. Handles reconnection on stream drop (exponential backoff,
+// max attempts configurable).
+//
+// Uses built-in fetch + ReadableStream (Node 18+). Zero deps.
+
+const API_BASE = 'https://api.anthropic.com';
+const BETA = 'managed-agents-2026-04-01';
+const VERSION = '2023-06-01';
+
+function authHeaders(apiKey) {
+  return {
+    'x-api-key': apiKey,
+    'anthropic-version': VERSION,
+    'anthropic-beta': BETA,
+    'accept': 'text/event-stream',
+  };
+}
+
+// Async generator that yields parsed event objects from the SSE stream.
+// Caller decides what to do with each (typically: evaluate policy + enforce).
+//
+// On stream end or network error, the generator throws. The caller should
+// wrap it in retry logic if appropriate.
+export async function* openEventStream({ apiKey, sessionId, signal }) {
+  const url = `${API_BASE}/v1/sessions/${sessionId}/events/stream?beta=true`;
+  const res = await fetch(url, { headers: authHeaders(apiKey), signal });
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`stream open failed: HTTP ${res.status}: ${body.slice(0, 300)}`);
+  }
+  if (!res.body) throw new Error('stream open failed: no response body');
+
+  const reader = res.body.getReader();
+  const decoder = new TextDecoder('utf-8');
+  let buffer = '';
+
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+
+      // SSE frames are separated by a blank line ("\n\n"). Each frame may
+      // contain multiple lines; we only care about `data:` lines for now.
+      let nlIdx;
+      while ((nlIdx = buffer.indexOf('\n\n')) !== -1) {
+        const frame = buffer.slice(0, nlIdx);
+        buffer = buffer.slice(nlIdx + 2);
+        const data = parseFrame(frame);
+        if (data) yield data;
+      }
+    }
+    // Stream ended cleanly. Flush any final frame missing trailing \n\n.
+    if (buffer.trim()) {
+      const data = parseFrame(buffer);
+      if (data) yield data;
+    }
+  } finally {
+    try { reader.releaseLock(); } catch {}
+  }
+}
+
+function parseFrame(frame) {
+  // Concatenate all `data:` lines per the SSE spec (multi-line payload).
+  const parts = [];
+  for (const line of frame.split('\n')) {
+    if (line.startsWith('data:')) parts.push(line.slice(5).trim());
+  }
+  if (parts.length === 0) return null;
+  const payload = parts.join('\n');
+  try { return JSON.parse(payload); }
+  catch { return null; }
+}
+
+// High-level wrapper: stream forever, reconnecting on transient errors.
+// Yields events; on fatal/permanent errors throws after maxAttempts.
+export async function* streamWithReconnect({ apiKey, sessionId, signal, maxAttempts = 5, onReconnect }) {
+  let attempt = 0;
+  while (true) {
+    try {
+      for await (const ev of openEventStream({ apiKey, sessionId, signal })) {
+        attempt = 0; // any event resets the backoff
+        yield ev;
+      }
+      // Stream ended without throwing — session likely closed cleanly. Exit.
+      return;
+    } catch (e) {
+      if (signal?.aborted) return;
+      attempt++;
+      if (attempt > maxAttempts) {
+        throw new Error(`stream failed after ${maxAttempts} attempts: ${e.message}`);
+      }
+      const backoffMs = Math.min(30_000, 1000 * 2 ** (attempt - 1));
+      if (onReconnect) onReconnect({ attempt, backoffMs, error: e });
+      await new Promise(r => setTimeout(r, backoffMs));
+    }
+  }
+}