@gethelio/proxy 0.3.0 → 0.4.0

package/dist/cli.js

@@ -171,6 +171,19 @@ var policiesSchema = z.object({
   flag_destructive: z.enum(["log", "require_approval"]).optional(),
   dry_run: z.boolean().default(false),
   rules: z.array(policyRuleSchema).default([]),
+  /**
+   * How to treat calls to a tool whose definition (annotations, schemas,
+   * description) has drifted from the baseline Helio captured on first
+   * sight.
+   * - "block": deny the call until the proxy is restarted (re-baselines)
+   *   or the upstream reverts. Conservative default when omitted.
+   * - "require_approval": escalate the call through the approval channel.
+   * - "log": audit the drift; rules evaluate against both baseline and
+   *   current annotations and the stricter decision wins.
+   * Kept optional (like hot_reload) so PoliciesConfig literal fixtures
+   * don't need the field; undefined is treated as "block".
+   */
+  on_tool_drift: z.enum(["block", "require_approval", "log"]).optional(),
   /**
    * Whether `helio start` should watch the config file for changes and
    * reconcile policy state on every save. Defaults to `true` when omitted.
@@ -233,14 +246,14 @@ var helioConfigBaseSchema = z.object({
 });
 var helioConfigSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
   const hasConfiguredEnvironment = typeof cfg.environment === "string" && cfg.environment.trim().length > 0;
-  const requiresSecret = cfg.policies.flag_destructive === "require_approval" || cfg.policies.rules.some((rule) => rule.action === "require_approval");
+  const requiresSecret = cfg.policies.flag_destructive === "require_approval" || cfg.policies.on_tool_drift === "require_approval" || cfg.policies.rules.some((rule) => rule.action === "require_approval");
   const hasSecret = hasDashboardApiSecret(cfg.dashboard.api_secret);
   if (requiresSecret) {
     if (!hasSecret) {
       ctx.addIssue({
         code: "custom",
         path: ["dashboard", "api_secret"],
-        message: 'dashboard.api_secret is required when any rule uses require_approval or policies.flag_destructive is "require_approval". Generate one with: `openssl rand -hex 32` and set it under `dashboard.api_secret` in your helio.yaml. (See docs/approvals.md.)'
+        message: 'dashboard.api_secret is required when any rule uses require_approval or policies.flag_destructive or policies.on_tool_drift is "require_approval". Generate one with: `openssl rand -hex 32` and set it under `dashboard.api_secret` in your helio.yaml. (See docs/approvals.md.)'
       });
     }
   }
@@ -459,6 +472,7 @@ function compilePolicies(config) {
     defaultAction: config.default,
     flagDestructive: config.flag_destructive,
     ...config.dry_run && { dryRun: true },
+    ...config.on_tool_drift && { onToolDrift: config.on_tool_drift },
     rules
   };
   return { policy, warnings };
@@ -2306,49 +2320,161 @@ function evaluatePolicy(policy, ctx) {
 }
 
 // src/policy/annotation-cache.ts
+var ASPECT_FIELDS = [
+  "annotations",
+  "inputSchema",
+  "description",
+  "outputSchema",
+  "title"
+];
 var ToolAnnotationCache = class {
-  cache = /* @__PURE__ */ new Map();
-  /** Number of tools currently cached. */
+  baselines = /* @__PURE__ */ new Map();
+  present = /* @__PURE__ */ new Set();
+  currentAnnotations = /* @__PURE__ */ new Map();
+  driftedTools = /* @__PURE__ */ new Map();
+  /** Number of tools present in the most recent tools/list. */
   get size() {
-    return this.cache.size;
+    return this.present.size;
   }
-  /**
-   * Update the cache from a tools/list JSON-RPC response body.
-   *
-   * Performs a full replacement — tools that existed in the previous cache
-   * but are absent from the new response are removed. This correctly handles
-   * tool list changes (additions, removals, annotation updates).
-   *
-   * @returns `true` if the response body was a valid tools/list response and
-   *   the cache was updated, `false` if the body shape was unexpected.
-   */
+  /** Diff a tools/list JSON-RPC response body against the baselines. */
   update(responseBody) {
     const tools = extractTools(responseBody);
-    if (!tools) return false;
-    this.cache.clear();
+    if (!tools) return { updated: false, baselined: [], drifted: [], reverted: [] };
+    const baselined = [];
+    const drifted = [];
+    const reverted = [];
+    const present = /* @__PURE__ */ new Set();
+    const currentAnnotations = /* @__PURE__ */ new Map();
+    const entries = [];
+    const nameCounts = /* @__PURE__ */ new Map();
     for (const tool of tools) {
       if (typeof tool !== "object" || tool === null) continue;
       const t = tool;
       const name = t["name"];
       if (typeof name !== "string") continue;
-      const annotations = t["annotations"];
-      if (annotations && typeof annotations === "object") {
-        this.cache.set(name, annotations);
-      } else {
-        this.cache.set(name, void 0);
+      entries.push({ name, definition: t });
+      nameCounts.set(name, (nameCounts.get(name) ?? 0) + 1);
+    }
+    const duplicateNames = /* @__PURE__ */ new Set();
+    for (const { name, definition: t } of entries) {
+      const isDuplicate = (nameCounts.get(name) ?? 0) > 1;
+      if (isDuplicate) {
+        present.add(name);
+        currentAnnotations.set(name, void 0);
+        if (duplicateNames.has(name)) continue;
+        duplicateNames.add(name);
+        const baseline2 = this.baselines.get(name);
+        const allDefinitions = entries.filter((e) => e.name === name).map((e) => e.definition);
+        const changes2 = [
+          {
+            aspect: "duplicate",
+            baseline: baseline2?.definition,
+            current: allDefinitions
+          }
+        ];
+        const event2 = { toolName: name, changes: changes2 };
+        const existing2 = this.driftedTools.get(name);
+        const isNewDrift2 = !existing2 || canonicalize(existing2.changes) !== canonicalize(changes2);
+        this.driftedTools.set(name, event2);
+        if (isNewDrift2) drifted.push(event2);
+        continue;
+      }
+      present.add(name);
+      const annotations = extractAnnotations(t);
+      currentAnnotations.set(name, annotations);
+      const definitionKey = canonicalize(t);
+      const baseline = this.baselines.get(name);
+      if (!baseline) {
+        this.baselines.set(name, { definition: t, definitionKey, annotations });
+        baselined.push(name);
+        if (this.driftedTools.has(name)) {
+          this.driftedTools.delete(name);
+          reverted.push(name);
+        }
+        continue;
+      }
+      if (definitionKey === baseline.definitionKey) {
+        if (this.driftedTools.has(name)) {
+          this.driftedTools.delete(name);
+          reverted.push(name);
+        }
+        continue;
+      }
+      const changes = [];
+      for (const field of ASPECT_FIELDS) {
+        const baselineValue = baseline.definition[field];
+        const currentValue = t[field];
+        if (canonicalize(baselineValue) !== canonicalize(currentValue)) {
+          changes.push({ aspect: field, baseline: baselineValue, current: currentValue });
+        }
       }
+      if (changes.length === 0) {
+        changes.push({ aspect: "other", baseline: baseline.definition, current: t });
+      }
+      const event = { toolName: name, changes };
+      const existing = this.driftedTools.get(name);
+      const isNewDrift = !existing || canonicalize(existing.changes) !== canonicalize(changes);
+      this.driftedTools.set(name, event);
+      if (isNewDrift) drifted.push(event);
     }
-    return true;
+    this.present = present;
+    this.currentAnnotations = currentAnnotations;
+    return { updated: true, baselined, drifted, reverted };
   }
-  /** Get cached annotations for a tool. Returns `undefined` if the tool is not in the cache. */
+  /**
+   * Get the **baseline** annotations for a tool — the definition first seen,
+   * not the latest upstream claim. Returns `undefined` if the tool has no
+   * annotations or was never seen.
+   */
   get(toolName) {
-    return this.cache.get(toolName);
+    return this.baselines.get(toolName)?.annotations;
+  }
+  /**
+   * Get the annotations from the most recent tools/list. Used for the
+   * stricter-of-both evaluation of drifted tools in on_tool_drift: log mode.
+   * Returns `undefined` for tools absent from the latest list.
+   */
+  getCurrent(toolName) {
+    return this.currentAnnotations.get(toolName);
   }
-  /** Check whether a tool exists in the cache (regardless of whether it has annotations). */
+  /** Whether the tool was present in the most recent tools/list. */
   has(toolName) {
-    return this.cache.has(toolName);
+    return this.present.has(toolName);
+  }
+  /** Whether the tool's current definition differs from its baseline. */
+  isDrifted(toolName) {
+    return this.driftedTools.has(toolName);
+  }
+  /** The active drift event for a tool, if any. */
+  getDrift(toolName) {
+    return this.driftedTools.get(toolName);
   }
 };
+function extractAnnotations(tool) {
+  const annotations = tool["annotations"];
+  return annotations && typeof annotations === "object" ? annotations : void 0;
+}
+function canonicalize(value) {
+  const encoded = JSON.stringify(sortKeysDeep(value));
+  return encoded ?? "";
+}
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value !== null && typeof value === "object") {
+    const source = value;
+    const out = {};
+    for (const key of Object.keys(source).sort()) {
+      Object.defineProperty(out, key, {
+        value: sortKeysDeep(source[key]),
+        enumerable: true,
+        writable: true,
+        configurable: true
+      });
+    }
+    return out;
+  }
+  return value;
+}
 function extractTools(body) {
   if (typeof body !== "object" || body === null) return null;
   const b = body;
@@ -2550,6 +2676,19 @@ function buildRateLimitedFeedback(decision, result) {
     retry_allowed: true
   };
 }
+function buildToolDriftFeedback(drift, action) {
+  const aspects = drift.changes.map((change) => change.aspect);
+  return {
+    blocked: true,
+    reason: "tool_definition_drift",
+    rule: null,
+    ruleIndex: null,
+    action,
+    drifted_aspects: aspects,
+    suggestion: `The definition of "${drift.toolName}" changed upstream (${aspects.join(", ")}) after Helio baselined it. An operator must review the change; restarting the proxy re-baselines, or the upstream can revert the change.`,
+    retry_allowed: false
+  };
+}
 function buildSpendLimitedFeedback(decision, result, currency) {
   const { rule, ruleIndex } = ruleInfo(decision.matchedRule);
   const windowSeconds = Math.round(result.windowMs / 1e3);
@@ -2686,8 +2825,8 @@ var GovernedForwarder = class {
           reason: classifyPrimeFailure(result.response)
         };
       }
-      const updated = this.annotationCache.update(result.response.body);
-      if (!updated) {
+      const update = this.applyToolDefinitionUpdate(result.response.body, void 0);
+      if (!update.updated) {
         return {
           success: false,
           toolsCached: this.annotationCache.size,
@@ -2709,10 +2848,62 @@ var GovernedForwarder = class {
     }
     const result = await this.inner.forward(request);
     if (request.method === "tools/list") {
-      this.annotationCache.update(result.response.body);
+      this.applyToolDefinitionUpdate(result.response.body, request.sessionId);
     }
     return result;
   }
+  /**
+   * Apply a tools/list response to the definition cache and surface any
+   * drift: console warning + immediate audit record per event. Single entry
+   * point for both runtime tools/list responses and startup priming, so the
+   * cache is updated exactly once per response.
+   */
+  applyToolDefinitionUpdate(responseBody, sessionId) {
+    const update = this.annotationCache.update(responseBody);
+    if (!update.updated) return update;
+    for (const drift of update.drifted) {
+      const aspects = drift.changes.map((change) => change.aspect).join(", ");
+      console.error(
+        `[helio] Tool definition drift detected: "${drift.toolName}" changed (${aspects}) after baseline \u2014 calls governed by policies.on_tool_drift (${this.policy.onToolDrift ?? "block"})`
+      );
+      this.writeDriftAuditRecord(drift, sessionId, "tool_drift");
+    }
+    for (const toolName of update.reverted) {
+      console.error(
+        `[helio] Tool definition drift cleared: "${toolName}" returned to its baseline definition`
+      );
+      this.writeDriftAuditRecord({ toolName, changes: [] }, sessionId, "tool_drift_reverted");
+    }
+    return update;
+  }
+  /** Write an immediate audit record for a drift event (not a tool call). */
+  writeDriftAuditRecord(drift, sessionId, decision) {
+    if (!this.auditWriter) return;
+    this.auditWriter.pushImmediate({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      session_id: sessionId ?? null,
+      agent_id: null,
+      environment: this.environment ?? null,
+      tool_name: drift.toolName,
+      tool_input: {},
+      policy_decision: decision,
+      block_reason: null,
+      matched_rule: null,
+      matched_rule_index: null,
+      evidence_chain: decision === "tool_drift" ? { tool_drift: { changes: drift.changes } } : null,
+      approval_status: null,
+      approved_by: null,
+      upstream_response: null,
+      upstream_error: null,
+      upstream_http_status: null,
+      upstream_latency_ms: null,
+      total_duration_ms: 0,
+      approval_wait_ms: 0,
+      proxy_compute_ms: 0,
+      flagged_destructive: false,
+      dry_run: false
+    });
+  }
   async handleToolsCall(request) {
     const startTime = performance.now();
     const timestamp = (/* @__PURE__ */ new Date()).toISOString();
@@ -2723,13 +2914,26 @@ var GovernedForwarder = class {
     }
     const toolArguments = params?.["arguments"] && typeof params["arguments"] === "object" ? params["arguments"] : void 0;
     const annotations = this.annotationCache.get(toolName);
+    const driftEvent = this.annotationCache.getDrift(toolName);
+    const driftMode = this.policy.onToolDrift ?? "block";
     let decision = evaluatePolicy(this.policy, {
       toolName,
       annotations,
       toolArguments,
       environment: this.environment
     });
-    const isDestructive = annotations?.destructiveHint ?? true;
+    if (driftEvent && driftMode === "log") {
+      const currentDecision = evaluatePolicy(this.policy, {
+        toolName,
+        annotations: this.annotationCache.getCurrent(toolName),
+        toolArguments,
+        environment: this.environment
+      });
+      decision = stricterDecision(decision, currentDecision);
+    }
+    const baselineDestructive = annotations?.destructiveHint ?? true;
+    const currentDestructive = driftEvent && driftMode === "log" ? this.annotationCache.getCurrent(toolName)?.destructiveHint ?? true : false;
+    const isDestructive = baselineDestructive || currentDestructive;
     let flaggedDestructive = false;
     if (isDestructive && !decision.matchedRule && this.policy.flagDestructive) {
       flaggedDestructive = true;
@@ -2743,6 +2947,15 @@ var GovernedForwarder = class {
         };
       }
     }
+    let driftBlocked = false;
+    if (driftEvent && driftMode !== "log") {
+      driftBlocked = driftMode === "block";
+      decision = {
+        action: driftMode === "block" ? "deny" : "require_approval",
+        matchedRule: void 0,
+        reason: `Tool "${toolName}" definition drifted from baseline (${driftEvent.changes.map((change) => change.aspect).join(", ")})`
+      };
+    }
     const originalAction = decision.action;
     let evidenceResult;
     let dependencyResult;
@@ -2806,6 +3019,8 @@ var GovernedForwarder = class {
         result = this.makeSessionRequiredBlockResult(request, decision);
       } else if (evidenceBlocked) {
         result = this.makeEvidenceBlockResult(request, decision, evidenceResult, dependencyResult);
+      } else if (driftBlocked && driftEvent) {
+        result = this.makeDriftBlockResult(request, driftEvent);
       } else if (decision.action === "allow") {
         result = await this.inner.forward(request);
       } else if (decision.action === "deny") {
@@ -2878,7 +3093,8 @@ var GovernedForwarder = class {
       rateLimitResult,
       spendLimitResult,
       isDryRun,
-      forwardingError
+      forwardingError,
+      driftEvent ? { event: driftEvent, mode: driftMode } : void 0
     );
     return result;
   }
@@ -3095,7 +3311,7 @@ var GovernedForwarder = class {
   wasForwardedUpstream(decision, approvalOutcome, rateLimitResult, spendLimitResult) {
     return decision.action === "allow" || approvalOutcome?.status === "approved" || approvalOutcome?.status === "break_glass" || approvalOutcome?.status === "timeout" && this.approvalRouter?.defaultOnTimeout === "allow" || rateLimitResult?.allowed === true || spendLimitResult?.allowed === true;
   }
-  writeAuditRecord(request, timestamp, toolName, toolArguments, decision, result, totalDurationMs, approvalWaitMs, flaggedDestructive, evidenceResult, dependencyResult, evidenceBlocked, approvalOutcome, rateLimitResult, spendLimitResult, isDryRun, forwardingError) {
+  writeAuditRecord(request, timestamp, toolName, toolArguments, decision, result, totalDurationMs, approvalWaitMs, flaggedDestructive, evidenceResult, dependencyResult, evidenceBlocked, approvalOutcome, rateLimitResult, spendLimitResult, isDryRun, forwardingError, drift) {
     if (!this.auditWriter) return;
     const wasForwarded = this.wasForwardedUpstream(
       decision,
@@ -3155,6 +3371,15 @@ var GovernedForwarder = class {
         }
       };
     }
+    if (drift) {
+      evidenceChain = {
+        ...evidenceChain ?? {},
+        tool_drift: {
+          mode: drift.mode,
+          changes: drift.event.changes
+        }
+      };
+    }
     const blockReason = extractBlockReason(result);
     const record = {
       timestamp,
@@ -3187,6 +3412,15 @@ var GovernedForwarder = class {
       this.auditWriter.push(record);
     }
   }
+  makeDriftBlockResult(request, drift) {
+    const feedback = buildToolDriftFeedback(drift, "deny");
+    return makeErrorResult(
+      request,
+      POLICY_DENIED,
+      `Tool definition drift: "${drift.toolName}" changed after baseline`,
+      { ...feedback }
+    );
+  }
   makeDenyResult(request, decision) {
     const feedback = buildPolicyDeniedFeedback(decision);
     const message = decision.matchedRule?.feedback?.message ?? `Policy denied: ${decision.reason}`;
@@ -3275,6 +3509,17 @@ function collectAllowedEvidenceKeys(policy) {
   }
   return [...keys];
 }
+var ACTION_SEVERITY = {
+  deny: 5,
+  require_approval: 4,
+  dry_run: 3,
+  spend_limit: 2,
+  rate_limit: 1,
+  allow: 0
+};
+function stricterDecision(a, b) {
+  return ACTION_SEVERITY[b.action] > ACTION_SEVERITY[a.action] ? b : a;
+}
 function makeErrorResult(request, code, message, data) {
   const body = {
     jsonrpc: "2.0",
@@ -3840,6 +4085,7 @@ function clampInt(value, fallback, min, max) {
 }
 
 // src/audit/store.ts
+var DRIFT_EVENT_DECISIONS_SQL = "('tool_drift', 'tool_drift_reverted')";
 var CREATE_TABLE_DDL = `
 CREATE TABLE IF NOT EXISTS audit_records (
   id                TEXT PRIMARY KEY,
@@ -4143,7 +4389,7 @@ var AuditStore = class {
     const totals = this.db.prepare(
       `SELECT
            COUNT(*) as total,
-           COALESCE(SUM(CASE WHEN block_reason IS NULL THEN 1 ELSE 0 END), 0) as allowed_total,
+           COALESCE(SUM(CASE WHEN block_reason IS NULL AND policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL} THEN 1 ELSE 0 END), 0) as allowed_total,
            COALESCE(SUM(CASE WHEN block_reason IS NOT NULL THEN 1 ELSE 0 END), 0) as blocked_total,
            COALESCE(SUM(CASE WHEN dry_run = 1 THEN 1 ELSE 0 END), 0) as dry_run_total,
            COALESCE(SUM(CASE WHEN dry_run = 0 THEN 1 ELSE 0 END), 0) as applied_total
@@ -4162,9 +4408,10 @@ var AuditStore = class {
          GROUP BY block_reason
          ORDER BY count DESC`
     ).all(...params);
+    const toolsClause = clause ? `${clause} AND policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL}` : `WHERE policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL}`;
     const top_tools = this.db.prepare(
       `SELECT tool_name, COUNT(*) as count
-         FROM audit_records ${clause}
+         FROM audit_records ${toolsClause}
          GROUP BY tool_name
          ORDER BY count DESC
          LIMIT 10`
@@ -6435,7 +6682,9 @@ async function startAnnotationPrimeLoop(governedForwarder) {
       primed = true;
       clearRetryTimer();
       const prefix = phase === "initial" ? "[helio] Annotation cache primed" : `[helio] Annotation cache primed after retry ${String(retryAttempt)}`;
-      console.error(`${prefix}: ${String(result.toolsCached)} tools cached`);
+      console.error(
+        `${prefix}: ${String(result.toolsCached)} tool definitions baselined for drift detection (baselines are per-process; a restart re-baselines \u2014 review tool_drift audit records before restarting)`
+      );
       return;
     }
     const reason = result.reason ?? "unknown reason";

package/dist/index.d.ts

@@ -81,6 +81,11 @@ declare const policiesSchema: z.ZodObject<{
             suggestion: z.ZodOptional<z.ZodString>;
         }, z.core.$strict>>;
     }, z.core.$strict>>>;
+    on_tool_drift: z.ZodOptional<z.ZodEnum<{
+        require_approval: "require_approval";
+        log: "log";
+        block: "block";
+    }>>;
     hot_reload: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 declare const approvalChannelSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -204,6 +209,11 @@ declare const helioConfigSchema: z.ZodObject<{
                 suggestion: z.ZodOptional<z.ZodString>;
             }, z.core.$strict>>;
         }, z.core.$strict>>>;
+        on_tool_drift: z.ZodOptional<z.ZodEnum<{
+            require_approval: "require_approval";
+            log: "log";
+            block: "block";
+        }>>;
         hot_reload: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>;
     approval: z.ZodPrefault<z.ZodObject<{
@@ -366,6 +376,11 @@ interface CompiledPolicy {
     readonly defaultAction: 'allow' | 'deny';
     readonly flagDestructive?: 'log' | 'require_approval';
     readonly dryRun?: boolean;
+    /**
+     * Response to tool definition drift (issue #25). Undefined means "block"
+     * at the use site — conservative by default.
+     */
+    readonly onToolDrift?: 'block' | 'require_approval' | 'log';
     readonly rules: readonly CompiledPolicyRule[];
 }
 /** A non-fatal warning produced during policy compilation. */
@@ -1617,6 +1632,15 @@ declare class GovernedForwarder implements McpForwarder {
      */
     primeAnnotationCache(): Promise<AnnotationCachePrimeResult>;
     forward(request: McpRequest): Promise<ForwardResult>;
+    /**
+     * Apply a tools/list response to the definition cache and surface any
+     * drift: console warning + immediate audit record per event. Single entry
+     * point for both runtime tools/list responses and startup priming, so the
+     * cache is updated exactly once per response.
+     */
+    private applyToolDefinitionUpdate;
+    /** Write an immediate audit record for a drift event (not a tool call). */
+    private writeDriftAuditRecord;
     private handleToolsCall;
     private handleApproval;
     private handleRateLimit;
@@ -1631,6 +1655,7 @@ declare class GovernedForwarder implements McpForwarder {
     /** Determine if the request was actually forwarded to the upstream MCP server. */
     private wasForwardedUpstream;
     private writeAuditRecord;
+    private makeDriftBlockResult;
     private makeDenyResult;
     private makePolicyMisconfiguredResult;
     private makeUnsupportedResult;

package/dist/index.js

@@ -161,6 +161,19 @@ var policiesSchema = z.object({
   flag_destructive: z.enum(["log", "require_approval"]).optional(),
   dry_run: z.boolean().default(false),
   rules: z.array(policyRuleSchema).default([]),
+  /**
+   * How to treat calls to a tool whose definition (annotations, schemas,
+   * description) has drifted from the baseline Helio captured on first
+   * sight.
+   * - "block": deny the call until the proxy is restarted (re-baselines)
+   *   or the upstream reverts. Conservative default when omitted.
+   * - "require_approval": escalate the call through the approval channel.
+   * - "log": audit the drift; rules evaluate against both baseline and
+   *   current annotations and the stricter decision wins.
+   * Kept optional (like hot_reload) so PoliciesConfig literal fixtures
+   * don't need the field; undefined is treated as "block".
+   */
+  on_tool_drift: z.enum(["block", "require_approval", "log"]).optional(),
   /**
    * Whether `helio start` should watch the config file for changes and
    * reconcile policy state on every save. Defaults to `true` when omitted.
@@ -223,14 +236,14 @@ var helioConfigBaseSchema = z.object({
 });
 var helioConfigSchema = helioConfigBaseSchema.superRefine((cfg, ctx) => {
   const hasConfiguredEnvironment = typeof cfg.environment === "string" && cfg.environment.trim().length > 0;
-  const requiresSecret = cfg.policies.flag_destructive === "require_approval" || cfg.policies.rules.some((rule) => rule.action === "require_approval");
+  const requiresSecret = cfg.policies.flag_destructive === "require_approval" || cfg.policies.on_tool_drift === "require_approval" || cfg.policies.rules.some((rule) => rule.action === "require_approval");
   const hasSecret = hasDashboardApiSecret(cfg.dashboard.api_secret);
   if (requiresSecret) {
     if (!hasSecret) {
       ctx.addIssue({
         code: "custom",
         path: ["dashboard", "api_secret"],
-        message: 'dashboard.api_secret is required when any rule uses require_approval or policies.flag_destructive is "require_approval". Generate one with: `openssl rand -hex 32` and set it under `dashboard.api_secret` in your helio.yaml. (See docs/approvals.md.)'
+        message: 'dashboard.api_secret is required when any rule uses require_approval or policies.flag_destructive or policies.on_tool_drift is "require_approval". Generate one with: `openssl rand -hex 32` and set it under `dashboard.api_secret` in your helio.yaml. (See docs/approvals.md.)'
       });
     }
   }
@@ -419,6 +432,7 @@ function compilePolicies(config) {
     defaultAction: config.default,
     flagDestructive: config.flag_destructive,
     ...config.dry_run && { dryRun: true },
+    ...config.on_tool_drift && { onToolDrift: config.on_tool_drift },
     rules
   };
   return { policy, warnings };
@@ -2170,49 +2184,161 @@ function evaluatePolicy(policy, ctx) {
 }
 
 // src/policy/annotation-cache.ts
+var ASPECT_FIELDS = [
+  "annotations",
+  "inputSchema",
+  "description",
+  "outputSchema",
+  "title"
+];
 var ToolAnnotationCache = class {
-  cache = /* @__PURE__ */ new Map();
-  /** Number of tools currently cached. */
+  baselines = /* @__PURE__ */ new Map();
+  present = /* @__PURE__ */ new Set();
+  currentAnnotations = /* @__PURE__ */ new Map();
+  driftedTools = /* @__PURE__ */ new Map();
+  /** Number of tools present in the most recent tools/list. */
   get size() {
-    return this.cache.size;
+    return this.present.size;
   }
-  /**
-   * Update the cache from a tools/list JSON-RPC response body.
-   *
-   * Performs a full replacement — tools that existed in the previous cache
-   * but are absent from the new response are removed. This correctly handles
-   * tool list changes (additions, removals, annotation updates).
-   *
-   * @returns `true` if the response body was a valid tools/list response and
-   *   the cache was updated, `false` if the body shape was unexpected.
-   */
+  /** Diff a tools/list JSON-RPC response body against the baselines. */
   update(responseBody) {
     const tools = extractTools(responseBody);
-    if (!tools) return false;
-    this.cache.clear();
+    if (!tools) return { updated: false, baselined: [], drifted: [], reverted: [] };
+    const baselined = [];
+    const drifted = [];
+    const reverted = [];
+    const present = /* @__PURE__ */ new Set();
+    const currentAnnotations = /* @__PURE__ */ new Map();
+    const entries = [];
+    const nameCounts = /* @__PURE__ */ new Map();
     for (const tool of tools) {
       if (typeof tool !== "object" || tool === null) continue;
       const t = tool;
       const name = t["name"];
       if (typeof name !== "string") continue;
-      const annotations = t["annotations"];
-      if (annotations && typeof annotations === "object") {
-        this.cache.set(name, annotations);
-      } else {
-        this.cache.set(name, void 0);
+      entries.push({ name, definition: t });
+      nameCounts.set(name, (nameCounts.get(name) ?? 0) + 1);
+    }
+    const duplicateNames = /* @__PURE__ */ new Set();
+    for (const { name, definition: t } of entries) {
+      const isDuplicate = (nameCounts.get(name) ?? 0) > 1;
+      if (isDuplicate) {
+        present.add(name);
+        currentAnnotations.set(name, void 0);
+        if (duplicateNames.has(name)) continue;
+        duplicateNames.add(name);
+        const baseline2 = this.baselines.get(name);
+        const allDefinitions = entries.filter((e) => e.name === name).map((e) => e.definition);
+        const changes2 = [
+          {
+            aspect: "duplicate",
+            baseline: baseline2?.definition,
+            current: allDefinitions
+          }
+        ];
+        const event2 = { toolName: name, changes: changes2 };
+        const existing2 = this.driftedTools.get(name);
+        const isNewDrift2 = !existing2 || canonicalize(existing2.changes) !== canonicalize(changes2);
+        this.driftedTools.set(name, event2);
+        if (isNewDrift2) drifted.push(event2);
+        continue;
+      }
+      present.add(name);
+      const annotations = extractAnnotations(t);
+      currentAnnotations.set(name, annotations);
+      const definitionKey = canonicalize(t);
+      const baseline = this.baselines.get(name);
+      if (!baseline) {
+        this.baselines.set(name, { definition: t, definitionKey, annotations });
+        baselined.push(name);
+        if (this.driftedTools.has(name)) {
+          this.driftedTools.delete(name);
+          reverted.push(name);
+        }
+        continue;
+      }
+      if (definitionKey === baseline.definitionKey) {
+        if (this.driftedTools.has(name)) {
+          this.driftedTools.delete(name);
+          reverted.push(name);
+        }
+        continue;
+      }
+      const changes = [];
+      for (const field of ASPECT_FIELDS) {
+        const baselineValue = baseline.definition[field];
+        const currentValue = t[field];
+        if (canonicalize(baselineValue) !== canonicalize(currentValue)) {
+          changes.push({ aspect: field, baseline: baselineValue, current: currentValue });
+        }
       }
+      if (changes.length === 0) {
+        changes.push({ aspect: "other", baseline: baseline.definition, current: t });
+      }
+      const event = { toolName: name, changes };
+      const existing = this.driftedTools.get(name);
+      const isNewDrift = !existing || canonicalize(existing.changes) !== canonicalize(changes);
+      this.driftedTools.set(name, event);
+      if (isNewDrift) drifted.push(event);
     }
-    return true;
+    this.present = present;
+    this.currentAnnotations = currentAnnotations;
+    return { updated: true, baselined, drifted, reverted };
   }
-  /** Get cached annotations for a tool. Returns `undefined` if the tool is not in the cache. */
+  /**
+   * Get the **baseline** annotations for a tool — the definition first seen,
+   * not the latest upstream claim. Returns `undefined` if the tool has no
+   * annotations or was never seen.
+   */
   get(toolName) {
-    return this.cache.get(toolName);
+    return this.baselines.get(toolName)?.annotations;
   }
-  /** Check whether a tool exists in the cache (regardless of whether it has annotations). */
+  /**
+   * Get the annotations from the most recent tools/list. Used for the
+   * stricter-of-both evaluation of drifted tools in on_tool_drift: log mode.
+   * Returns `undefined` for tools absent from the latest list.
+   */
+  getCurrent(toolName) {
+    return this.currentAnnotations.get(toolName);
+  }
+  /** Whether the tool was present in the most recent tools/list. */
   has(toolName) {
-    return this.cache.has(toolName);
+    return this.present.has(toolName);
+  }
+  /** Whether the tool's current definition differs from its baseline. */
+  isDrifted(toolName) {
+    return this.driftedTools.has(toolName);
+  }
+  /** The active drift event for a tool, if any. */
+  getDrift(toolName) {
+    return this.driftedTools.get(toolName);
   }
 };
+function extractAnnotations(tool) {
+  const annotations = tool["annotations"];
+  return annotations && typeof annotations === "object" ? annotations : void 0;
+}
+function canonicalize(value) {
+  const encoded = JSON.stringify(sortKeysDeep(value));
+  return encoded ?? "";
+}
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) return value.map(sortKeysDeep);
+  if (value !== null && typeof value === "object") {
+    const source = value;
+    const out = {};
+    for (const key of Object.keys(source).sort()) {
+      Object.defineProperty(out, key, {
+        value: sortKeysDeep(source[key]),
+        enumerable: true,
+        writable: true,
+        configurable: true
+      });
+    }
+    return out;
+  }
+  return value;
+}
 function extractTools(body) {
   if (typeof body !== "object" || body === null) return null;
   const b = body;
@@ -2414,6 +2540,19 @@ function buildRateLimitedFeedback(decision, result) {
     retry_allowed: true
   };
 }
+function buildToolDriftFeedback(drift, action) {
+  const aspects = drift.changes.map((change) => change.aspect);
+  return {
+    blocked: true,
+    reason: "tool_definition_drift",
+    rule: null,
+    ruleIndex: null,
+    action,
+    drifted_aspects: aspects,
+    suggestion: `The definition of "${drift.toolName}" changed upstream (${aspects.join(", ")}) after Helio baselined it. An operator must review the change; restarting the proxy re-baselines, or the upstream can revert the change.`,
+    retry_allowed: false
+  };
+}
 function buildSpendLimitedFeedback(decision, result, currency) {
   const { rule, ruleIndex } = ruleInfo(decision.matchedRule);
   const windowSeconds = Math.round(result.windowMs / 1e3);
@@ -2550,8 +2689,8 @@ var GovernedForwarder = class {
           reason: classifyPrimeFailure(result.response)
         };
       }
-      const updated = this.annotationCache.update(result.response.body);
-      if (!updated) {
+      const update = this.applyToolDefinitionUpdate(result.response.body, void 0);
+      if (!update.updated) {
         return {
           success: false,
           toolsCached: this.annotationCache.size,
@@ -2573,10 +2712,62 @@ var GovernedForwarder = class {
     }
     const result = await this.inner.forward(request);
     if (request.method === "tools/list") {
-      this.annotationCache.update(result.response.body);
+      this.applyToolDefinitionUpdate(result.response.body, request.sessionId);
     }
     return result;
   }
+  /**
+   * Apply a tools/list response to the definition cache and surface any
+   * drift: console warning + immediate audit record per event. Single entry
+   * point for both runtime tools/list responses and startup priming, so the
+   * cache is updated exactly once per response.
+   */
+  applyToolDefinitionUpdate(responseBody, sessionId) {
+    const update = this.annotationCache.update(responseBody);
+    if (!update.updated) return update;
+    for (const drift of update.drifted) {
+      const aspects = drift.changes.map((change) => change.aspect).join(", ");
+      console.error(
+        `[helio] Tool definition drift detected: "${drift.toolName}" changed (${aspects}) after baseline \u2014 calls governed by policies.on_tool_drift (${this.policy.onToolDrift ?? "block"})`
+      );
+      this.writeDriftAuditRecord(drift, sessionId, "tool_drift");
+    }
+    for (const toolName of update.reverted) {
+      console.error(
+        `[helio] Tool definition drift cleared: "${toolName}" returned to its baseline definition`
+      );
+      this.writeDriftAuditRecord({ toolName, changes: [] }, sessionId, "tool_drift_reverted");
+    }
+    return update;
+  }
+  /** Write an immediate audit record for a drift event (not a tool call). */
+  writeDriftAuditRecord(drift, sessionId, decision) {
+    if (!this.auditWriter) return;
+    this.auditWriter.pushImmediate({
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      session_id: sessionId ?? null,
+      agent_id: null,
+      environment: this.environment ?? null,
+      tool_name: drift.toolName,
+      tool_input: {},
+      policy_decision: decision,
+      block_reason: null,
+      matched_rule: null,
+      matched_rule_index: null,
+      evidence_chain: decision === "tool_drift" ? { tool_drift: { changes: drift.changes } } : null,
+      approval_status: null,
+      approved_by: null,
+      upstream_response: null,
+      upstream_error: null,
+      upstream_http_status: null,
+      upstream_latency_ms: null,
+      total_duration_ms: 0,
+      approval_wait_ms: 0,
+      proxy_compute_ms: 0,
+      flagged_destructive: false,
+      dry_run: false
+    });
+  }
   async handleToolsCall(request) {
     const startTime = performance.now();
     const timestamp = (/* @__PURE__ */ new Date()).toISOString();
@@ -2587,13 +2778,26 @@ var GovernedForwarder = class {
     }
     const toolArguments = params?.["arguments"] && typeof params["arguments"] === "object" ? params["arguments"] : void 0;
     const annotations = this.annotationCache.get(toolName);
+    const driftEvent = this.annotationCache.getDrift(toolName);
+    const driftMode = this.policy.onToolDrift ?? "block";
     let decision = evaluatePolicy(this.policy, {
       toolName,
       annotations,
       toolArguments,
       environment: this.environment
     });
-    const isDestructive = annotations?.destructiveHint ?? true;
+    if (driftEvent && driftMode === "log") {
+      const currentDecision = evaluatePolicy(this.policy, {
+        toolName,
+        annotations: this.annotationCache.getCurrent(toolName),
+        toolArguments,
+        environment: this.environment
+      });
+      decision = stricterDecision(decision, currentDecision);
+    }
+    const baselineDestructive = annotations?.destructiveHint ?? true;
+    const currentDestructive = driftEvent && driftMode === "log" ? this.annotationCache.getCurrent(toolName)?.destructiveHint ?? true : false;
+    const isDestructive = baselineDestructive || currentDestructive;
     let flaggedDestructive = false;
     if (isDestructive && !decision.matchedRule && this.policy.flagDestructive) {
       flaggedDestructive = true;
@@ -2607,6 +2811,15 @@ var GovernedForwarder = class {
         };
       }
     }
+    let driftBlocked = false;
+    if (driftEvent && driftMode !== "log") {
+      driftBlocked = driftMode === "block";
+      decision = {
+        action: driftMode === "block" ? "deny" : "require_approval",
+        matchedRule: void 0,
+        reason: `Tool "${toolName}" definition drifted from baseline (${driftEvent.changes.map((change) => change.aspect).join(", ")})`
+      };
+    }
     const originalAction = decision.action;
     let evidenceResult;
     let dependencyResult;
@@ -2670,6 +2883,8 @@ var GovernedForwarder = class {
         result = this.makeSessionRequiredBlockResult(request, decision);
       } else if (evidenceBlocked) {
         result = this.makeEvidenceBlockResult(request, decision, evidenceResult, dependencyResult);
+      } else if (driftBlocked && driftEvent) {
+        result = this.makeDriftBlockResult(request, driftEvent);
       } else if (decision.action === "allow") {
         result = await this.inner.forward(request);
       } else if (decision.action === "deny") {
@@ -2742,7 +2957,8 @@ var GovernedForwarder = class {
       rateLimitResult,
       spendLimitResult,
       isDryRun,
-      forwardingError
+      forwardingError,
+      driftEvent ? { event: driftEvent, mode: driftMode } : void 0
     );
     return result;
   }
@@ -2959,7 +3175,7 @@ var GovernedForwarder = class {
   wasForwardedUpstream(decision, approvalOutcome, rateLimitResult, spendLimitResult) {
     return decision.action === "allow" || approvalOutcome?.status === "approved" || approvalOutcome?.status === "break_glass" || approvalOutcome?.status === "timeout" && this.approvalRouter?.defaultOnTimeout === "allow" || rateLimitResult?.allowed === true || spendLimitResult?.allowed === true;
   }
-  writeAuditRecord(request, timestamp, toolName, toolArguments, decision, result, totalDurationMs, approvalWaitMs, flaggedDestructive, evidenceResult, dependencyResult, evidenceBlocked, approvalOutcome, rateLimitResult, spendLimitResult, isDryRun, forwardingError) {
+  writeAuditRecord(request, timestamp, toolName, toolArguments, decision, result, totalDurationMs, approvalWaitMs, flaggedDestructive, evidenceResult, dependencyResult, evidenceBlocked, approvalOutcome, rateLimitResult, spendLimitResult, isDryRun, forwardingError, drift) {
     if (!this.auditWriter) return;
     const wasForwarded = this.wasForwardedUpstream(
       decision,
@@ -3019,6 +3235,15 @@ var GovernedForwarder = class {
         }
       };
     }
+    if (drift) {
+      evidenceChain = {
+        ...evidenceChain ?? {},
+        tool_drift: {
+          mode: drift.mode,
+          changes: drift.event.changes
+        }
+      };
+    }
     const blockReason = extractBlockReason(result);
     const record = {
       timestamp,
@@ -3051,6 +3276,15 @@ var GovernedForwarder = class {
       this.auditWriter.push(record);
     }
   }
+  makeDriftBlockResult(request, drift) {
+    const feedback = buildToolDriftFeedback(drift, "deny");
+    return makeErrorResult(
+      request,
+      POLICY_DENIED,
+      `Tool definition drift: "${drift.toolName}" changed after baseline`,
+      { ...feedback }
+    );
+  }
   makeDenyResult(request, decision) {
     const feedback = buildPolicyDeniedFeedback(decision);
     const message = decision.matchedRule?.feedback?.message ?? `Policy denied: ${decision.reason}`;
@@ -3139,6 +3373,17 @@ function collectAllowedEvidenceKeys(policy) {
   }
   return [...keys];
 }
+var ACTION_SEVERITY = {
+  deny: 5,
+  require_approval: 4,
+  dry_run: 3,
+  spend_limit: 2,
+  rate_limit: 1,
+  allow: 0
+};
+function stricterDecision(a, b) {
+  return ACTION_SEVERITY[b.action] > ACTION_SEVERITY[a.action] ? b : a;
+}
 function makeErrorResult(request, code, message, data) {
   const body = {
     jsonrpc: "2.0",
@@ -4110,6 +4355,7 @@ function clampInt(value, fallback, min, max) {
 }
 
 // src/audit/store.ts
+var DRIFT_EVENT_DECISIONS_SQL = "('tool_drift', 'tool_drift_reverted')";
 var CREATE_TABLE_DDL = `
 CREATE TABLE IF NOT EXISTS audit_records (
   id                TEXT PRIMARY KEY,
@@ -4413,7 +4659,7 @@ var AuditStore = class {
     const totals = this.db.prepare(
       `SELECT
            COUNT(*) as total,
-           COALESCE(SUM(CASE WHEN block_reason IS NULL THEN 1 ELSE 0 END), 0) as allowed_total,
+           COALESCE(SUM(CASE WHEN block_reason IS NULL AND policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL} THEN 1 ELSE 0 END), 0) as allowed_total,
            COALESCE(SUM(CASE WHEN block_reason IS NOT NULL THEN 1 ELSE 0 END), 0) as blocked_total,
            COALESCE(SUM(CASE WHEN dry_run = 1 THEN 1 ELSE 0 END), 0) as dry_run_total,
            COALESCE(SUM(CASE WHEN dry_run = 0 THEN 1 ELSE 0 END), 0) as applied_total
@@ -4432,9 +4678,10 @@ var AuditStore = class {
          GROUP BY block_reason
          ORDER BY count DESC`
     ).all(...params);
+    const toolsClause = clause ? `${clause} AND policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL}` : `WHERE policy_decision NOT IN ${DRIFT_EVENT_DECISIONS_SQL}`;
     const top_tools = this.db.prepare(
       `SELECT tool_name, COUNT(*) as count
-         FROM audit_records ${clause}
+         FROM audit_records ${toolsClause}
          GROUP BY tool_name
          ORDER BY count DESC
          LIMIT 10`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gethelio/proxy",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Open-source MCP governance proxy for AI agents",
   "license": "Apache-2.0",