watchmyagents 1.1.2 → 1.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "watchmyagents",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Security observability + real-time policy enforcement for AI agents. Local-first NDJSON capture with a continuous Watch daemon that auto-uploads anonymized signals, Shield CLI that blocks policy violations live (with policies pulled from Fortress cloud), anonymizer producing signals-only payloads, bidirectional sync with WatchMyAgents Fortress, and one-command install as an always-on launchd/systemd service — closing the recursive Watch→Guardian→Shield security loop.",
   "type": "module",
   "files": [

package/scripts/shield.js

@@ -214,15 +214,27 @@ async function runSessionWorker({ sessionId, ctx }) {
         const result = evaluate(normalized, ctx.ruleset);
         const decidedInMs = Date.now() - t0;
 
-        sinfo(sessionId, `${rawEvent.type} tool=${normalized.tool_name} → ${result.decision}${result.rule_id ? ` (${result.rule_id})` : ''}`);
+        // v1.1.3 Phase 1.D — mode badge in the log line for operator visibility.
+        const modeTag = result.mode === 'shadow' ? ' [SHADOW]' : '';
+        sinfo(sessionId, `${rawEvent.type} tool=${normalized.tool_name} → ${result.decision}${modeTag}${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,
+          mode: result.mode,
         });
         fireToFortress(rawEvent, normalized, result, decidedInMs);
 
+        // v1.1.3 Phase 1.D — in shadow mode, the decision is COMPUTED + LOGGED
+        // but NOT enforced. The rule's "would_deny" / "would_interrupt"
+        // outcome flows to Fortress for Platt-scaling calibration + diff-in-diff
+        // efficacy measurement (Guardian Core hardening axes 1 + 4), but the
+        // agent's session continues uninterrupted. Promote to enforce only
+        // after calibration confidence + lifecycle gates (Guardian Core spec
+        // observe → shadow → enforce → retired).
+        if (result.mode === 'shadow') continue;
+
         if ((result.decision === 'deny' || result.decision === 'interrupt') && !sessionInterrupted) {
           try {
             await interruptSession({
@@ -271,15 +283,34 @@ async function runSessionWorker({ sessionId, ctx }) {
           const result = evaluate(normalized, ctx.ruleset);
           const decidedInMs = Date.now() - t0;
 
-          sinfo(sessionId, `requires_action ${sourceEvent.type} tool=${normalized.tool_name} → ${result.decision}${result.rule_id ? ` (${result.rule_id})` : ''}`);
+          // v1.1.3 Phase 1.D — mode badge in the log line for operator visibility.
+          const modeTag = result.mode === 'shadow' ? ' [SHADOW]' : '';
+          sinfo(sessionId, `requires_action ${sourceEvent.type} tool=${normalized.tool_name} → ${result.decision}${modeTag}${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,
+            mode: result.mode,
           });
           fireToFortress(sourceEvent, normalized, result, decidedInMs);
 
+          // v1.1.3 Phase 1.D — shadow mode in tool_confirmation: we MUST
+          // still send confirmAllow even when the rule said deny/interrupt,
+          // otherwise the agent hangs waiting for our response. The
+          // decision is logged with mode=shadow so calibration can compare
+          // what the rule said vs what was enforced (which is "nothing"
+          // here). For mode=enforce, the original branching below stands.
+          if (result.mode === 'shadow') {
+            try {
+              await confirmAllow({ apiKey, sessionId, toolUseId: eventId });
+              // No enforced++ — shadow doesn't enforce by definition.
+            } catch (e) {
+              process.stderr.write(`[shield/${sessionId.slice(0, 12)}] shadow confirmAllow error: ${e.message}\n`);
+            }
+            continue;
+          }
+
           try {
             if (result.decision === 'allow') {
               await confirmAllow({ apiKey, sessionId, toolUseId: eventId });

package/src/anonymizer.js

@@ -109,6 +109,53 @@ export function normalizeToolName(toolName, salt) {
   return 'tool_hash:' + createHash('sha256').update(salt).update(s).digest('hex').slice(0, 32);
 }
 
+// ── Tool input field normalization (Phase 1.A L-2, v1.1.3) ──────────────
+//
+// HASHABLE_INPUT_FIELDS is the canonical set of input field names the
+// anonymizer knows how to hash. These names came from the Anthropic tool
+// shape (`web_fetch.url`, `web_search.query`, `bash.command`, file tools).
+// Other frameworks use different native names — OpenAI function tools
+// have arbitrary user-defined argument names, LangGraph tools use the
+// `tools[].args` shape, CrewAI uses `task.context`, etc.
+//
+// To avoid silent IoC loss when a new adapter lands, adapters can call
+// `normalizeToolInput()` BEFORE yielding their WMAAction to map their
+// native tool argument names to the canonical set. The function takes
+// the raw input object and an alias map `{nativeName: canonicalName}`
+// and returns a new object where canonical names are populated from
+// the corresponding native fields (without losing the originals — both
+// are kept so the local NDJSON preserves full fidelity).
+//
+// Example for a future OpenAI function tool that exposes `endpoint_url`:
+//   yield {
+//     ...,
+//     action_type: 'custom_tool_use',
+//     tool_name: 'fetch_remote',
+//     input: normalizeToolInput(rawInput, { endpoint_url: 'url' }),
+//   };
+// Now `entry.input.url` is populated → the anonymizer's IoC hashing
+// fires → Fortress receives a hashed signal as expected.
+//
+// Adapters that already use canonical names (Anthropic) can skip the
+// helper — it's a no-op when no aliases match.
+export function normalizeToolInput(rawInput, aliases = {}) {
+  if (rawInput == null || typeof rawInput !== 'object') return rawInput;
+  const out = { ...rawInput };
+  for (const [nativeName, canonicalName] of Object.entries(aliases)) {
+    if (!HASHABLE_INPUT_FIELDS.includes(canonicalName)) {
+      throw new Error(`normalizeToolInput: "${canonicalName}" is not a canonical hashable field (must be one of: ${HASHABLE_INPUT_FIELDS.join(', ')})`);
+    }
+    if (out[canonicalName] == null && rawInput[nativeName] != null) {
+      out[canonicalName] = rawInput[nativeName];
+    }
+  }
+  return out;
+}
+
+// Re-export the canonical hashable-fields list so adapter authors can
+// programmatically reference the contract.
+export { HASHABLE_INPUT_FIELDS };
+
 // ── Single-entry extractor: what hashable IoCs are in this entry? ────────
 
 function extractIocs(entry, salt) {

package/src/shield/decisions.js

@@ -22,13 +22,22 @@ export class DecisionLogger {
     ruleName,
     message,
     decidedInMs,
+    mode,             // v1.1.3 Phase 1.D: 'enforce' | 'shadow' (default 'enforce' if absent)
   }) {
+    // In shadow mode the decision is computed and logged but NOT enforced.
+    // status must reflect what actually happened on the wire: shadow + deny
+    // didn't actually block, so status='ok' keeps Watch's aggregations honest.
+    // output.mode is what calibration reads to compare would-have-blocked vs
+    // did-block.
+    const effectiveMode = mode || 'enforce';
+    const enforced = effectiveMode === 'enforce'
+      && (decision === 'deny' || decision === 'interrupt');
     return this._logger.write({
       action_type: 'shield_decision',
       provider: 'anthropic-managed',
       tool_name: sourceEvent?.name || sourceEvent?.tool_name || null,
-      status: decision === 'deny' || decision === 'interrupt' ? 'error' : 'ok',
-      error: decision === 'deny' || decision === 'interrupt' ? message : null,
+      status: enforced ? 'error' : 'ok',
+      error: enforced ? message : null,
       duration_ms: decidedInMs ?? null,
       input: {
         source_event_id: sourceEvent?.id || null,
@@ -40,6 +49,7 @@ export class DecisionLogger {
         rule_id: ruleId,
         rule_name: ruleName,
         message,
+        mode: effectiveMode,
       },
     });
   }

package/src/shield/policy.js

@@ -33,11 +33,23 @@ export async function loadPolicies(path) {
   }
   // Pre-compile regex for performance + early failure on bad patterns.
   const VALID_ACTIONS = ['allow', 'deny', 'interrupt'];
+  // v1.1.3 Phase 1.D — policy mode: 'enforce' (default) actually enforces
+  // the decision via the Anthropic API; 'shadow' computes the decision
+  // and logs it but skips enforcement. Shadow is the calibration bench
+  // for Guardian Core scoring (Platt scaling, diff-in-diff efficacy)
+  // and a safe staging step for new policies before promoting to enforce.
+  const VALID_MODES = ['enforce', 'shadow'];
   for (const p of data.policies) {
     compileMatchRegexes(p.match || {});
     if (!VALID_ACTIONS.includes(p.action)) {
       throw new Error(`policy ${p.id || p.name}: unsupported action "${p.action}"`);
     }
+    // Default to 'enforce' if mode is omitted → preserves v1.0.x / v1.1.x
+    // behavior for policies authored before shadow mode existed.
+    if (p.mode == null) p.mode = 'enforce';
+    if (!VALID_MODES.includes(p.mode)) {
+      throw new Error(`policy ${p.id || p.name}: unsupported mode "${p.mode}" (must be one of: ${VALID_MODES.join(', ')})`);
+    }
   }
   // v1.1.2 F-14 (P2 Codex audit): validate the ruleset's default.action
   // against the SAME canonical set as per-policy actions. Before this fix
@@ -157,6 +169,10 @@ export function evaluate(event, ruleset) {
         rule_id: policy.id || null,
         rule_name: policy.name || null,
         message: policy.message || null,
+        // v1.1.3 Phase 1.D — `mode` propagated so the Shield runtime can
+        // decide whether to actually call the Anthropic enforcement API
+        // (mode=enforce) or just log the would-be decision (mode=shadow).
+        mode: policy.mode || 'enforce',
       };
     }
   }
@@ -165,5 +181,8 @@ export function evaluate(event, ruleset) {
     rule_id: null,
     rule_name: '(default)',
     message: null,
+    // The ruleset-level default has no shadow concept — defaults always
+    // enforce (or, when the default is 'allow', do nothing of consequence).
+    mode: 'enforce',
   };
 }

package/src/shield/sources/fortress.js

@@ -233,6 +233,9 @@ export class FortressPolicySource {
 // Convert a Fortress DB policy row to the local Shield format.
 // Throws on anything invalid so _refresh can skip it (policies from the cloud
 // are NOT fully trusted — apply the same hardening as the local JSON loader).
+// v1.1.3 Phase 1.D — same modes as the local JSON loader.
+const VALID_MODES = new Set(['enforce', 'shadow']);
+
 function compilePolicyFromFortress(p) {
   if (!p || typeof p !== 'object') throw new Error('policy is not an object');
   if (!VALID_ACTIONS.has(p.action)) {
@@ -244,6 +247,14 @@ function compilePolicyFromFortress(p) {
   if (p.priority != null && (typeof p.priority !== 'number' || !Number.isFinite(p.priority))) {
     throw new Error(`priority must be a finite number (got ${p.priority})`);
   }
+  // v1.1.3 Phase 1.D — accept `mode` from Fortress rows (added by Lovable
+  // when the companion prompt deploys the schema column). Default to
+  // 'enforce' for backwards compat: existing Fortress instances without
+  // the `mode` column yield policies that enforce, as they always have.
+  const mode = p.mode ?? 'enforce';
+  if (!VALID_MODES.has(mode)) {
+    throw new Error(`unsupported mode "${mode}" (expected enforce|shadow)`);
+  }
   const out = {
     id: p.rule_id,
     name: p.name,
@@ -252,6 +263,7 @@ function compilePolicyFromFortress(p) {
     action: p.action,
     message: p.message,
     priority: p.priority ?? 100,
+    mode,
   };
   // Reuse the SAME ReDoS-safe compiler as the local JSON loader (rejects
   // catastrophic-backtracking patterns + over-long regexes). Previously this

package/src/sources/anthropic-managed.js

@@ -17,7 +17,7 @@
 
 import { request } from 'node:https';
 import { URLSearchParams } from 'node:url';
-import { Source, PROVIDERS, ENFORCEMENT_MODES, ACTION_TYPES } from './contract.js';
+import { Source, PROVIDERS, ENFORCEMENT_MODES, ACTION_TYPES, COMPOSITION_PATTERNS } from './contract.js';
 import {
   getAgentConfig, detectAlwaysAsk,
   confirmAllow, confirmDeny, interruptSession,
@@ -183,11 +183,54 @@ const RELEVANT_TYPES = [
 
 const tsMs = ev => Date.parse(ev.processed_at || ev.created_at || '') || null;
 
+// v1.1.3 Phase 1.B — `fetchSessionEntries` is now a 3-line wrapper around
+// the pure async transformer below. The HTTP layer (fetchRawEvents) is
+// the only thing that needs the network — the per-event normalization
+// logic is a pure async generator that any test can drive with synthetic
+// event arrays. Same external contract; new internal seam for testing.
 export async function* fetchSessionEntries({ apiKey, agentId, sessionId, model }) {
+  yield* transformRawEventsToWMAActions(
+    fetchRawEvents(apiKey, sessionId),
+    { agentId, sessionId, model },
+  );
+}
+
+/**
+ * Pure async transformer: raw Anthropic events → WMAAction objects.
+ *
+ * Takes any async iterable of raw Anthropic events (live HTTP stream OR
+ * synthetic test fixture array) plus the routing metadata, yields one
+ * WMAAction per relevant event. Maintains all the cross-event state
+ * (pendingModelReq / pendingToolUse pairs, subThreadIds tracking, F-6a
+ * discriminators, F-8 end-of-session flush of unresolved tool calls).
+ *
+ * Why a separate function: keeps `fetchSessionEntries` HTTP-only and
+ * makes integration tests trivial — no network mocking required.
+ */
+export async function* transformRawEventsToWMAActions(rawEventsAsyncIterable, { agentId, sessionId, model }) {
   // Pair-tracking maps: event_id of the "start" → its timestamp + metadata
   const pendingModelReq = new Map();    // span.model_request_start.id → ts
   const pendingToolUse = new Map();     // agent.tool_use.id → { ts, name, isMcp, input }
 
+  // v1.1.3 Phase 1.C — Anthropic sub-agent detection.
+  // Anthropic Task tool: when a parent agent delegates, a NEW thread is
+  // spawned within the parent's session (`session.thread_created` event).
+  // Subsequent events with that session_thread_id belong to the sub-agent.
+  // We track the set of "spawned" thread ids and, for each event, set
+  // composition_pattern='hierarchy' if it happened inside a sub-thread.
+  //
+  // Important Anthropic-specific design note: the sub-agent does NOT have
+  // a separate agent_id at the Anthropic API level — it runs inside the
+  // parent's session and its actions are attributed to the parent's
+  // agent_id. So `parent_agent_id` STAYS NULL for all events of this
+  // session (the sub-agent shares identity with the parent). Operators
+  // who want per-sub-agent visibility use the local NDJSON's
+  // `session_thread_id` + `agent_name` discriminators (captured since
+  // v1.0.2 F-6a) to differentiate. Other adapters (OpenAI handoffs,
+  // CrewAI manager, Hermes spawn_subagent) where sub-agents DO have
+  // distinct API-level IDs will populate parent_agent_id natively.
+  const subThreadIds = new Set();
+
   // `provider` is the canonical field per src/sources/contract.js (no
   // other consumer ever read the previous `framework` field, so it was
   // dropped in PR-B with zero downstream impact).
@@ -201,7 +244,7 @@ export async function* fetchSessionEntries({ apiKey, agentId, sessionId, model }
   // exact filterable set is undocumented & evolves. We pull everything and
   // filter here, ensuring future event types are surfaced rather than dropped.
   const RELEVANT = new Set(RELEVANT_TYPES);
-  for await (const ev of fetchRawEvents(apiKey, sessionId)) {
+  for await (const ev of rawEventsAsyncIterable) {
     if (!RELEVANT.has(ev.type)) continue;
     const type = ev.type;
     const ts = ev.processed_at || ev.created_at || new Date().toISOString();
@@ -211,7 +254,21 @@ export async function* fetchSessionEntries({ apiKey, agentId, sessionId, model }
     // Preserved LOCALLY (NDJSON) only — never sent raw to Fortress.
     const session_thread_id = ev.session_thread_id ?? null;
     const agent_name = ev.agent_name ?? null;
-    const subAgentMeta = { session_thread_id, agent_name };
+    // v1.1.3 Phase 1.C: derive composition_pattern at event level.
+    // Sub-thread events (session_thread_id registered in subThreadIds via
+    // a prior session.thread_created) → hierarchy. Root-thread events
+    // OR events without thread_id → solo. The aggregator in uploadSignals
+    // upgrades the AGENT-level composition_pattern to "hierarchy" when
+    // any event in the window is non-solo, so even pre-spawn root events
+    // contribute correctly to the agent's overall classification.
+    const inSubThread = session_thread_id != null && subThreadIds.has(session_thread_id);
+    const composition_pattern = inSubThread ? COMPOSITION_PATTERNS.HIERARCHY : COMPOSITION_PATTERNS.SOLO;
+    // parent_agent_id: see the design note at the top of fetchSessionEntries.
+    // Anthropic Task tool sub-agents share the parent's agent_id at the API
+    // level, so the field is null for ALL Anthropic events. Explicitly
+    // null (not undefined) so consumers see a documented value per WMAAction
+    // schema and downstream tests can assert it cleanly.
+    const subAgentMeta = { session_thread_id, agent_name, composition_pattern, parent_agent_id: null };
     const tsMillis = tsMs(ev);
 
     if (type === 'span.model_request_start') {
@@ -358,9 +415,24 @@ export async function* fetchSessionEntries({ apiKey, agentId, sessionId, model }
       const start = pendingToolUse.get(ev.tool_use_id);
       pendingToolUse.delete(ev.tool_use_id);
       const isError = ev.is_error === true;
+      // v1.1.3 Phase 1.B fix: the yielded action represents the TOOL CALL
+      // as a whole (input from start, output from result). Its discriminators
+      // (session_thread_id, agent_name, composition_pattern) should reflect
+      // the START's context — where the tool was INVOKED — not the result
+      // event's, which may or may not carry these fields depending on
+      // provider event-shape quirks. Falls back to the current event's
+      // subAgentMeta if the start somehow didn't capture them (defensive).
+      const pairedMeta = start ? {
+        session_thread_id: start.session_thread_id ?? subAgentMeta.session_thread_id,
+        agent_name: start.agent_name ?? subAgentMeta.agent_name,
+        composition_pattern: (start.session_thread_id != null && subThreadIds.has(start.session_thread_id))
+          ? COMPOSITION_PATTERNS.HIERARCHY
+          : COMPOSITION_PATTERNS.SOLO,
+        parent_agent_id: null,  // see subAgentMeta — Anthropic shares parent's agent_id
+      } : subAgentMeta;
       yield {
         ...base,
-        ...subAgentMeta,
+        ...pairedMeta,
         id: ev.id,
         action_type: start?.isMcp ? 'mcp_tool_use' : 'tool_use',
         tool_name: start?.name || 'unknown',
@@ -447,6 +519,14 @@ export async function* fetchSessionEntries({ apiKey, agentId, sessionId, model }
     }
 
     if (type === 'session.thread_created') {
+      // v1.1.3 Phase 1.C: register the newly-spawned thread as a sub-thread
+      // BEFORE yielding so subsequent events with this session_thread_id are
+      // correctly marked composition_pattern='hierarchy'. The thread_created
+      // event itself is yielded with the pattern computed before this line —
+      // it's the PARENT's act of spawning, so 'solo' is correct here (the
+      // parent did this act in its own context); only the events that
+      // FOLLOW inside the new thread get 'hierarchy'.
+      if (ev.session_thread_id) subThreadIds.add(ev.session_thread_id);
       yield {
         ...base,
         ...subAgentMeta,
@@ -587,7 +667,12 @@ function extractText(content) {
 
 export class AnthropicManagedSource extends Source {
   static providerName = PROVIDERS.ANTHROPIC_MANAGED;
-  static enforcementMode = ENFORCEMENT_MODES.SYNC_CONFIRM;
+  // v1.1.3: renamed from `enforcementMode` — the static field is the MAX
+  // capability the provider exposes; the EFFECTIVE per-agent mode is
+  // resolved at runtime via effectiveEnforcementMode() since v1.0.1 F-2.
+  // The `enforcementMode` getter inherited from Source.enforcementMode
+  // returns this value, so callers reading either name still work.
+  static enforcementCapability = ENFORCEMENT_MODES.SYNC_CONFIRM;
 
   constructor({ apiKey } = {}) {
     super({ apiKey });

package/src/sources/contract.js

@@ -29,26 +29,76 @@
 // Every WMAAction.action_type MUST be one of these. New adapters that
 // emit a novel kind of action should propose adding a new constant here
 // (and document it) rather than inventing one inline.
+//
+// Audit note (Phase 1.A, v1.1.3): the vocabulary is grouped into two
+// tiers to make the contract honest about which types are framework-
+// agnostic vs which originated from one specific framework (Anthropic
+// Managed Agents was the seed adapter). New adapters can:
+//   1. Use UNIVERSAL types directly — they're always meaningful.
+//   2. Use FRAMEWORK-SPECIFIC types ONLY if the new framework has a
+//      genuinely equivalent concept. Otherwise emit a UNIVERSAL type
+//      (e.g., OpenAI handoffs → HANDOFF, NOT THREAD_MESSAGE_SENT).
+//   3. Propose a new constant via a PR when their framework exposes a
+//      genuinely new category of event.
 export const ACTION_TYPES = Object.freeze({
+  // ── UNIVERSAL (every adapter should be able to emit these) ─────────────
+  /** Model inference call (with token usage + duration). */
   LLM_CALL: 'llm_call',
+  /** Provider-built-in tool invocation (web_search, web_fetch, bash, code_exec, …). */
   TOOL_USE: 'tool_use',
+  /** MCP server tool invocation. */
   MCP_TOOL_USE: 'mcp_tool_use',
+  /** Customer-defined tool invocation (the agent calls a tool the user wired). */
   CUSTOM_TOOL_USE: 'custom_tool_use',
+  /** Customer returned the result of a custom tool. */
   CUSTOM_TOOL_RESULT: 'custom_tool_result',
+  /** Human (or orchestrator) approved/denied a pending tool call. */
   TOOL_CONFIRMATION: 'tool_confirmation',
+  /** User sent input to the agent (prompt, follow-up question, …). */
   USER_MESSAGE: 'user_message',
+  /** User cancelled execution mid-flight. */
   USER_INTERRUPT: 'user_interrupt',
+  /** Agent emitted an output message (final reply or intermediate). */
   MESSAGE: 'message',
+  /** Agent emitted internal reasoning (extended thinking / scratchpad). */
   THINKING: 'thinking',
+  /** Session-level error from the provider runtime. */
+  SESSION_ERROR: 'session_error',
+  /** Agent A passes control to agent B (OpenAI Agents handoffs, AgentCore
+   *  multi-agent, CrewAI manager delegation, Hermes spawn_subagent, LangGraph
+   *  subgraph spawn). For Anthropic Task tool, this is typically emitted as
+   *  THREAD_MESSAGE_SENT — both are valid for that framework. */
+  HANDOFF: 'handoff',
+  /** Graph-flavored frameworks (LangGraph, AutoGen state machine,
+   *  conditional workflow engines) emit this when execution moves from one
+   *  node/state to another. Carries `from_node`/`to_node` in `output`. */
+  GRAPH_NODE_TRANSITION: 'graph_node_transition',
+  /** Shield-internal — emitted when WMA itself blocks/allows/interrupts
+   *  an action. Always carries the decision in `output`. */
+  SHIELD_DECISION: 'shield_decision',
+
+  // ── FRAMEWORK-SPECIFIC (Anthropic Managed Agents-origin, may map cleanly to
+  //    other frameworks but were named after the Anthropic event vocabulary) ──
+  /** Anthropic-specific: emitted when the context window saturates and the
+   *  thread is compacted (some history lost). OpenAI/CrewAI/LangGraph
+   *  generally roll the window silently without an explicit event. */
   CONTEXT_COMPACTED: 'context_compacted',
+  /** Anthropic-specific: a sub-thread was spawned within a session (Task
+   *  tool delegation). Other frameworks model this as HANDOFF + a new
+   *  agent identity. */
   THREAD_CREATED: 'thread_created',
+  /** Anthropic-specific: inter-agent message in a thread (parent → sub-agent). */
   THREAD_MESSAGE_SENT: 'thread_message_sent',
+  /** Anthropic-specific: reply from a sub-agent in a thread (sub → parent). */
   THREAD_MESSAGE_RECEIVED: 'thread_message_received',
+  /** Anthropic-specific: session configuration changed mid-flight
+   *  (`session.updated` event with a diff). Other frameworks generally
+   *  don't expose live config edits as events. */
   CONFIG_CHANGE: 'config_change',
+  /** Anthropic-specific: session/thread lifecycle state change (running/
+   *  idle/rescheduled/terminated). Other frameworks have different state
+   *  machines; map cautiously. */
   STATE_TRANSITION: 'state_transition',
-  SESSION_ERROR: 'session_error',
-  // Shield-only — emitted when WMA itself blocks an action:
-  SHIELD_DECISION: 'shield_decision',
 });
 
 export const STATUS_VALUES = Object.freeze({
@@ -185,19 +235,35 @@ export function validateWMAAction(obj) {
  * provider-agnostic.
  *
  * Static contract:
- *   providerName        — value from PROVIDERS
- *   enforcementMode     — value from ENFORCEMENT_MODES
+ *   providerName            — value from PROVIDERS
+ *   enforcementCapability   — value from ENFORCEMENT_MODES; the MAX the
+ *                             provider can do. The EFFECTIVE per-agent
+ *                             mode may be weaker (resolved at runtime
+ *                             via the provider's effectiveEnforcementMode
+ *                             helper; see AnthropicManagedSource for the
+ *                             reference impl).
+ *
+ *   ⚠️  Renamed from `enforcementMode` in v1.1.3 because the previous
+ *       name was misleading (a static field is the capability ceiling,
+ *       not the runtime mode). `enforcementMode` is kept as a backward-
+ *       compat alias for v1.x consumers; it returns the same value.
  *
  * Instance contract:
- *   listAgents()        — return all agents accessible with the client creds
- *   streamEvents(id)    — async generator yielding WMAAction objects
- *   enforce(action, d)  — only required if enforcementMode != detect_only
+ *   listAgents()       — return all agents accessible with the client creds
+ *   streamEvents(id)   — async generator yielding WMAAction objects
+ *   enforce(action, d) — only required if enforcementCapability != detect_only
  *
  * See `docs/SOURCE-ADAPTER-CONTRACT.md` for the full author guide.
  */
 export class Source {
   static providerName = null;
-  static enforcementMode = null;
+  static enforcementCapability = null;
+  // v1.1.3 backwards-compat alias for the renamed static field. Subclasses
+  // that set `enforcementMode` directly still work; new subclasses should
+  // set `enforcementCapability` instead. Resolved as a getter at read
+  // time so the rename can land without breaking consumers like
+  // assertImplementsSource() that read it from the class.
+  static get enforcementMode() { return this.enforcementCapability; }
 
   constructor(config = {}) {
     if (new.target === Source) {
@@ -237,7 +303,7 @@ export class Source {
    * @returns {Promise<{enforced: boolean, native_response?: object}>}
    */
   async enforce(action, decision) { // eslint-disable-line no-unused-vars
-    if (this.constructor.enforcementMode === ENFORCEMENT_MODES.DETECT_ONLY) {
+    if (this.constructor.enforcementCapability === ENFORCEMENT_MODES.DETECT_ONLY) {
       throw new Error(`${this.constructor.name} is detect_only — enforce() must not be called`);
     }
     throw new Error(`${this.constructor.name}.enforce() not implemented`);
@@ -256,8 +322,11 @@ export function assertImplementsSource(SourceClass) {
   if (!Object.values(PROVIDERS).includes(SourceClass.providerName)) {
     throw new Error(`${SourceClass.name}.providerName="${SourceClass.providerName}" not in PROVIDERS`);
   }
-  if (!Object.values(ENFORCEMENT_MODES).includes(SourceClass.enforcementMode)) {
-    throw new Error(`${SourceClass.name}.enforcementMode="${SourceClass.enforcementMode}" not in ENFORCEMENT_MODES`);
+  // v1.1.3: read enforcementCapability (the new canonical name) but fall
+  // back to enforcementMode for legacy subclasses that haven't migrated.
+  const capability = SourceClass.enforcementCapability ?? SourceClass.enforcementMode;
+  if (!Object.values(ENFORCEMENT_MODES).includes(capability)) {
+    throw new Error(`${SourceClass.name}.enforcementCapability="${capability}" not in ENFORCEMENT_MODES`);
   }
   // The base class throws "not implemented" — a real subclass must override.
   for (const m of ['listAgents', 'streamEvents']) {
@@ -265,8 +334,8 @@ export function assertImplementsSource(SourceClass) {
       throw new Error(`${SourceClass.name}.${m}() must be overridden`);
     }
   }
-  if (SourceClass.enforcementMode !== ENFORCEMENT_MODES.DETECT_ONLY
+  if (capability !== ENFORCEMENT_MODES.DETECT_ONLY
       && SourceClass.prototype.enforce === Source.prototype.enforce) {
-    throw new Error(`${SourceClass.name}.enforce() must be overridden (enforcementMode=${SourceClass.enforcementMode})`);
+    throw new Error(`${SourceClass.name}.enforce() must be overridden (enforcementCapability=${capability})`);
   }
 }