vellum 0.2.12 → 0.2.14

package/src/runtime/routes/events-routes.ts

@@ -8,64 +8,133 @@
  */
 
 import { getOrCreateConversation } from '../../memory/conversation-key-store.js';
-import { assistantEventHub } from '../assistant-event-hub.js';
-import { formatSseFrame } from '../assistant-event.js';
+import { assistantEventHub, AssistantEventHub } from '../assistant-event-hub.js';
+import { formatSseFrame, formatSseHeartbeat } from '../assistant-event.js';
 import type { AssistantEventSubscription } from '../assistant-event-hub.js';
 
+/** Keep-alive comment sent to idle clients every 30 s by default. */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+
 /**
  * Stream assistant events as Server-Sent Events for a specific conversation.
  *
  * Query params:
  *   conversationKey — required; scopes the stream to one conversation.
+ *
+ * Options (for testing):
+ *   hub               — override the event hub (defaults to process singleton).
+ *   heartbeatIntervalMs — how often to emit keep-alive comments (default 30 s).
  */
 export function handleSubscribeAssistantEvents(
   req: Request,
   url: URL,
+  options?: {
+    hub?: AssistantEventHub;
+    heartbeatIntervalMs?: number;
+  },
 ): Response {
   const conversationKey = url.searchParams.get('conversationKey');
   if (!conversationKey) {
     return Response.json({ error: 'conversationKey is required' }, { status: 400 });
   }
 
+  const hub = options?.hub ?? assistantEventHub;
+  const heartbeatIntervalMs = options?.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+
   const mapping = getOrCreateConversation(conversationKey);
   const encoder = new TextEncoder();
-  let sub: AssistantEventSubscription | null = null;
+
+  // ── Eager subscribe ──────────────────────────────────────────────────────
+  // Subscribe before creating the ReadableStream so the callback and onEvict
+  // closures are in place before events can arrive.  `controllerRef` is set
+  // synchronously inside ReadableStream's start(), so it is non-null by the
+  // time any event or eviction fires.
+  // 'self' is the assistantId that RunOrchestrator assigns to all HTTP-run
+  // events (see buildAssistantEvent('self', ...) in run-orchestrator.ts).
+  let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null;
+  let heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  let sub!: AssistantEventSubscription;
+
+  function cleanup() {
+    if (heartbeatTimer) { clearInterval(heartbeatTimer); heartbeatTimer = null; }
+    try { controllerRef?.close(); } catch { /* already closed */ }
+  }
+
+  try {
+    sub = hub.subscribe(
+      { assistantId: 'self', sessionId: mapping.conversationId },
+      (event) => {
+        const controller = controllerRef;
+        if (!controller) return;
+        try {
+          // Shed stalled consumers: desiredSize <= 0 means the 16-event buffer
+          // is full and the client isn't draining it.
+          if (controller.desiredSize !== null && controller.desiredSize <= 0) {
+            sub.dispose();
+            cleanup();
+            return;
+          }
+          controller.enqueue(encoder.encode(formatSseFrame(event)));
+        } catch {
+          sub.dispose();
+          cleanup();
+        }
+      },
+      {
+        // Called by the hub when a newer connection evicts this one (capacity
+        // management: oldest subscriber out, newest in).
+        onEvict: cleanup,
+      },
+    );
+  } catch (err) {
+    if (err instanceof RangeError) {
+      return Response.json({ error: 'Too many concurrent connections' }, { status: 503 });
+    }
+    throw err;
+  }
 
   // Allow up to 16 queued frames before treating the consumer as stalled.
   // This absorbs normal token-stream bursts without prematurely closing the
   // connection, while still shedding genuinely slow clients.
-  const stream = new ReadableStream({
+  const stream = new ReadableStream<Uint8Array>({
     start(controller) {
-      // 'self' is the assistantId that RunOrchestrator assigns to all HTTP-run events
-      // (see buildAssistantEvent('self', ...) in run-orchestrator.ts). This endpoint
-      // is part of the HTTP runtime API, so only HTTP-run events are relevant here.
-      // IPC/daemon events use a different assistantId ('default') and reach desktop
-      // clients through a separate channel — they are intentionally excluded.
-      sub = assistantEventHub.subscribe(
-        { assistantId: 'self', sessionId: mapping.conversationId },
-        (event) => {
-          try {
-            // Shed stalled consumers: desiredSize <= 0 means the 16-event buffer
-            // is full and the client isn't draining it.
-            if (controller.desiredSize !== null && controller.desiredSize <= 0) {
-              sub?.dispose();
-              try { controller.close(); } catch { /* already closed */ }
-              return;
-            }
-            controller.enqueue(encoder.encode(formatSseFrame(event)));
-          } catch {
-            sub?.dispose();
+      controllerRef = controller;
+
+      // If the client already disconnected before start() ran, clean up
+      // immediately — the abort event fires once and won't be re-dispatched.
+      if (req.signal.aborted) {
+        sub.dispose();
+        cleanup();
+        return;
+      }
+
+      // Send a keep-alive comment on each interval to prevent proxies and
+      // load-balancers from treating idle connections as timed out.
+      heartbeatTimer = setInterval(() => {
+        try {
+          // Apply the same slow-consumer guard as the event path: stop
+          // feeding heartbeats into a queue the client is not draining.
+          if (controller.desiredSize !== null && controller.desiredSize <= 0) {
+            sub.dispose();
+            cleanup();
+            return;
           }
-        },
-      );
+          controller.enqueue(encoder.encode(formatSseHeartbeat()));
+        } catch {
+          // Controller already closed (e.g. client disconnected).
+          sub.dispose();
+          cleanup();
+        }
+      }, heartbeatIntervalMs);
 
       req.signal.addEventListener('abort', () => {
-        sub?.dispose();
-        try { controller.close(); } catch { /* already closed */ }
+        sub.dispose();
+        cleanup();
       }, { once: true });
     },
     cancel() {
-      sub?.dispose();
+      sub.dispose();
+      cleanup();
     },
   }, new CountQueuingStrategy({ highWaterMark: 16 }));
 

package/src/runtime/routes/run-routes.ts

@@ -200,13 +200,8 @@ export async function handleAddTrustRule(
   }
 
   try {
-    // Intentionally omit executionTarget: core tools (bash, file_*, etc.)
-    // have no executionTarget in their PolicyContext, so a rule with one
-    // would never match and users would keep getting re-prompted.
-    addRule(confirmation.toolName, pattern, scope, decision, 100, {
-      principalKind: confirmation.principalKind,
-      principalId: confirmation.principalId,
-      principalVersion: confirmation.principalVersion,
+    addRule(confirmation.toolName, pattern, scope, decision, undefined, {
+      executionTarget: confirmation.executionTarget,
     });
     log.info(
       { tool: confirmation.toolName, pattern, scope, decision, runId },

package/src/runtime/run-orchestrator.ts

@@ -131,9 +131,6 @@ export class RunOrchestrator {
           executionTarget: msg.executionTarget,
           allowlistOptions: msg.allowlistOptions,
           scopeOptions: msg.scopeOptions,
-          principalKind: msg.principalKind,
-          principalId: msg.principalId,
-          principalVersion: msg.principalVersion,
           persistentDecisionsAllowed: msg.persistentDecisionsAllowed,
         });
         this.pending.set(run.id, {

package/src/schedule/recurrence-engine.ts

@@ -11,8 +11,24 @@ export interface ScheduleSpec {
 const SUPPORTED_RRULE_PREFIXES = ['DTSTART', 'RRULE:', 'RDATE', 'EXDATE', 'EXRULE'];
 
 function normalizeRruleExpression(expression: string): string {
-  // Handle escaped newlines from JSON transport
-  return expression.replace(/\\n/g, '\n').trim();
+  // Handle escaped newlines from JSON transport, then uppercase property name
+  // prefixes (before the first ';' or ':') on each line so rrulestr() receives
+  // the canonical uppercase form regardless of what the caller provided. We
+  // stop at the earliest delimiter to preserve case-sensitive parameter values
+  // such as timezone names in DTSTART;TZID=America/New_York:...
+  return expression
+    .replace(/\\n/g, '\n')
+    .trim()
+    .split(/\r?\n/)
+    .map(line => {
+      const colonIdx = line.indexOf(':');
+      const semiIdx = line.indexOf(';');
+      if (colonIdx === -1 && semiIdx === -1) return line;
+      // Uppercase only the property name (before the first ';' or ':')
+      const nameEnd = semiIdx !== -1 && (colonIdx === -1 || semiIdx < colonIdx) ? semiIdx : colonIdx;
+      return line.slice(0, nameEnd).toUpperCase() + line.slice(nameEnd);
+    })
+    .join('\n');
 }
 
 function parseRruleLines(expression: string): string[] {
@@ -129,6 +145,14 @@ export function computeNextRunAt(spec: ScheduleSpec, nowMs?: number): number {
       : rrulestr(normalized, { tzid });
     const next = parsed.after(new Date(now));
     if (!next) {
+      // When after() (exclusive) returns null the rule may still have a
+      // terminal occurrence that lands exactly on `now` — e.g. COUNT=1 or the
+      // final UNTIL instance.  Treat that as "due right now" so claimDueSchedules
+      // doesn't silently skip the last run.
+      const exactMatch = parsed.before(new Date(now), true);
+      if (exactMatch && exactMatch.getTime() === now) {
+        return now;
+      }
       throw new Error(`RRULE expression has no upcoming runs after ${new Date(now).toISOString()}`);
     }
     return next.getTime();

package/src/schedule/recurrence-types.ts

@@ -60,7 +60,7 @@ export function normalizeScheduleSyntax(input: {
 
   // Legacy cron_expression fallback
   if (input.legacyCronExpression) {
-    return { syntax: 'cron', expression: input.legacyCronExpression };
+    return { syntax: input.syntax ?? 'cron', expression: input.legacyCronExpression };
   }
 
   return null;

package/src/schedule/schedule-store.ts

@@ -4,8 +4,11 @@ import { Cron } from 'croner';
 import { getDb } from '../memory/db.js';
 import { scheduleJobs, scheduleRuns } from '../memory/schema.js';
 import { computeNextRunAt as computeNextRunAtEngine, isValidScheduleExpression } from './recurrence-engine.js';
+import { getLogger } from '../util/logger.js';
 import type { ScheduleSyntax } from './recurrence-types.js';
 
+const logger = getLogger('schedule-store');
+
 export interface ScheduleJob {
   id: string;
   name: string;
@@ -216,9 +219,15 @@ export function claimDueSchedules(now: number): ScheduleJob[] {
         expression: row.cronExpression,
         timezone: row.timezone,
       });
-    } catch {
-      // Finite schedule with no future runs — still claim the current due
-      // run but disable the schedule so it doesn't fire again.
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (!msg.includes('no upcoming runs')) {
+        // Log but don't abort — one bad schedule shouldn't block everything
+        logger.warn({ err, scheduleId: row.id }, 'Failed to compute next run for schedule');
+        continue;
+      }
+      // Expired schedules fire their final pending due run then auto-disable,
+      // ensuring no due run is silently dropped.
       newNextRunAt = null;
       exhausted = true;
     }

package/src/security/secret-scanner.ts

@@ -81,6 +81,13 @@ const PATTERNS: SecretPattern[] = [
     regex: /(https:\/\/hooks\.slack\.com\/services\/T[A-Z0-9]+\/B[A-Z0-9]+\/[A-Za-z0-9]+)/g,
   },
 
+  // -- Telegram --
+  {
+    type: 'Telegram Bot Token',
+    // Format: <bot_id>:<secret> where bot_id is 8-10 digits and secret is 35 alphanumeric/dash/underscore chars
+    regex: /\b([0-9]{8,10}:[A-Za-z0-9_-]{35})(?=[^A-Za-z0-9_-]|$)/g,
+  },
+
   // -- Anthropic --
   {
     type: 'Anthropic API Key',

package/src/tasks/ephemeral-permissions.ts

@@ -44,7 +44,5 @@ export function buildTaskRules(taskRunId: string, requiredTools: string[], _work
     allowHighRisk: true,
     priority: 75,
     createdAt: Date.now(),
-    principalKind: 'task',
-    principalId: taskRunId,
   }));
 }

package/src/tasks/task-scheduler.ts

@@ -1,7 +1,8 @@
 import { createSchedule } from '../schedule/schedule-store.js';
 
 /**
- * Create a recurrence schedule that runs a task on a cron or RRULE expression.
+ * Create a cron schedule that runs a task on a recurring cron expression.
+ * RRULE syntax is supported at the store layer but this helper currently defaults to cron.
  * The scheduler detects the `run_task:<taskId>` message format
  * and delegates to runTask() instead of processMessage().
  */

package/src/tools/calls/call-start.ts

@@ -24,6 +24,11 @@ const definition: ToolDefinition = {
         type: 'string',
         description: 'Additional context for the conversation',
       },
+      caller_identity_mode: {
+        type: 'string',
+        enum: ['assistant_number', 'user_number'],
+        description: 'Which phone number to use as the caller ID. assistant_number uses the AI assistant\'s Twilio number; user_number uses the user\'s verified personal number.',
+      },
     },
     required: ['phone_number', 'task'],
   },
@@ -49,6 +54,7 @@ class CallStartTool implements Tool {
       task: input.task as string,
       context: input.context as string | undefined,
       conversationId: context.conversationId,
+      callerIdentityMode: input.caller_identity_mode as 'assistant_number' | 'user_number' | undefined,
     });
 
     if (!result.ok) {
@@ -61,6 +67,8 @@ class CallStartTool implements Tool {
         `  Call Session ID: ${result.session.id}`,
         `  Call SID: ${result.callSid}`,
         `  To: ${result.session.toNumber}`,
+        `  From: ${result.session.fromNumber}`,
+        `  Caller Identity Mode: ${result.callerIdentityMode}`,
         `  Status: initiated`,
         '',
         'The AI voice assistant is now placing the call. Use call_status to check progress.',

package/src/tools/execution-target.ts

@@ -0,0 +1,21 @@
+import type { ExecutionTarget } from './types.js';
+import { getTool } from './registry.js';
+
+export function resolveExecutionTarget(toolName: string): ExecutionTarget {
+  const tool = getTool(toolName);
+  // Manifest-declared execution target is authoritative — check it first so
+  // skill tools with host_/computer_use_ prefixes aren't mis-classified.
+  if (tool?.executionTarget) {
+    return tool.executionTarget;
+  }
+  // Check the tool's executionMode metadata — proxy tools run on the connected
+  // client (host), not inside the sandbox.
+  if (tool?.executionMode === 'proxy') {
+    return 'host';
+  }
+  // Prefix heuristics for core tools that don't declare an explicit target.
+  if (toolName.startsWith('host_') || toolName.startsWith('computer_use_')) {
+    return 'host';
+  }
+  return 'sandbox';
+}

package/src/tools/execution-timeout.ts

@@ -0,0 +1,49 @@
+import type { ToolExecutionResult } from './types.js';
+
+const TIMEOUT_SENTINEL = Symbol('tool-timeout');
+
+export const DEFAULT_TOOL_TIMEOUT_SEC = 120;
+
+/**
+ * Convert a config-provided seconds value to a safe milliseconds value,
+ * falling back to the default if the input is NaN, non-finite, zero, or negative.
+ */
+export function safeTimeoutMs(sec: unknown): number {
+  const n = Number(sec);
+  if (!Number.isFinite(n) || n <= 0) {
+    return DEFAULT_TOOL_TIMEOUT_SEC * 1000;
+  }
+  return n * 1000;
+}
+
+/**
+ * Race a tool execution promise against a timeout. Returns a timeout error
+ * result instead of throwing so the agent loop can continue gracefully.
+ */
+export async function executeWithTimeout(
+  promise: Promise<ToolExecutionResult>,
+  timeoutMs: number,
+  toolName: string,
+): Promise<ToolExecutionResult> {
+  // Guard against NaN/invalid values that would cause setTimeout to fire immediately
+  const safeMs = Number.isFinite(timeoutMs) && timeoutMs > 0
+    ? timeoutMs
+    : DEFAULT_TOOL_TIMEOUT_SEC * 1000;
+  let timeoutHandle: ReturnType<typeof setTimeout>;
+  const timeoutPromise = new Promise<typeof TIMEOUT_SENTINEL>((resolve) => {
+    timeoutHandle = setTimeout(() => resolve(TIMEOUT_SENTINEL), safeMs);
+  });
+  try {
+    const result = await Promise.race([promise, timeoutPromise]);
+    if (result === TIMEOUT_SENTINEL) {
+      const sec = Math.round(safeMs / 1000);
+      return {
+        content: `Tool "${toolName}" timed out after ${sec}s. The operation may still be running in the background. Consider increasing timeouts.toolExecutionTimeoutSec in the config.`,
+        isError: true,
+      };
+    }
+    return result;
+  } finally {
+    clearTimeout(timeoutHandle!);
+  }
+}

package/src/tools/executor.ts

@@ -1,8 +1,7 @@
 import { readFileSync, existsSync, statSync } from 'node:fs';
 import { getTool, getAllTools } from './registry.js';
-import type { ExecutionTarget, Tool, ToolContext, ToolExecutionResult, ToolLifecycleEvent } from './types.js';
+import type { ToolContext, ToolExecutionResult, ToolLifecycleEvent } from './types.js';
 import { RiskLevel } from '../permissions/types.js';
-import type { PolicyContext } from '../permissions/types.js';
 import { check, classifyRisk, generateAllowlistOptions, generateScopeOptions } from '../permissions/checker.js';
 import { addRule } from '../permissions/trust-store.js';
 import { PermissionPrompter } from '../permissions/prompter.js';
@@ -18,6 +17,9 @@ import { scanText, redactSecrets } from '../security/secret-scanner.js';
 import { redactSensitiveFields } from '../security/redaction.js';
 import { getHookManager } from '../hooks/manager.js';
 import { getTaskRunRules } from '../tasks/ephemeral-permissions.js';
+import { safeTimeoutMs, executeWithTimeout } from './execution-timeout.js';
+import { buildPolicyContext } from './policy-context.js';
+import { resolveExecutionTarget } from './execution-target.js';
 
 const log = getLogger('tool-executor');
 
@@ -196,7 +198,7 @@ export class ToolExecutor {
         }
 
         // Need user approval
-        const allowlistOptions = generateAllowlistOptions(name, input);
+        const allowlistOptions = await generateAllowlistOptions(name, input);
         const scopeOptions = generateScopeOptions(context.workingDir, name);
 
         // Compute preview diff for file tools so the user sees what will change
@@ -253,11 +255,6 @@ export class ToolExecutor {
           sandboxed,
           context.conversationId,
           executionTarget,
-          policyContext?.principal ? {
-            kind: policyContext.principal.kind,
-            id: policyContext.principal.id,
-            version: policyContext.principal.version,
-          } : undefined,
           persistentDecisionsAllowed,
         );
 
@@ -325,9 +322,6 @@ export class ToolExecutor {
         ) {
           const ruleOptions: {
             allowHighRisk?: boolean;
-            principalKind?: string;
-            principalId?: string;
-            principalVersion?: string;
             executionTarget?: string;
           } = {};
 
@@ -335,19 +329,6 @@ export class ToolExecutor {
             ruleOptions.allowHighRisk = true;
           }
 
-          // Capture the principal context from the tool so the saved rule
-          // is scoped to the specific skill/version that was approved.
-          if (policyContext?.principal) {
-            if (policyContext.principal.kind != null) {
-              ruleOptions.principalKind = policyContext.principal.kind;
-            }
-            if (policyContext.principal.id != null) {
-              ruleOptions.principalId = policyContext.principal.id;
-            }
-            if (policyContext.principal.version != null) {
-              ruleOptions.principalVersion = policyContext.principal.version;
-            }
-          }
           if (policyContext?.executionTarget != null) {
             ruleOptions.executionTarget = policyContext.executionTarget;
           }
@@ -393,11 +374,7 @@ export class ToolExecutor {
       const rawTimeoutSec = getConfig().timeouts.toolExecutionTimeoutSec;
       const toolTimeoutMs = safeTimeoutMs(rawTimeoutSec);
 
-      // Enrich context with principal so tools (e.g. claude_code) can
-      // forward it through sub-tool confirmation requests.
-      const execContext = policyContext?.principal
-        ? { ...context, principal: policyContext.principal }
-        : context;
+      const execContext = context;
 
       if (tool.executionMode === 'proxy') {
         if (!context.proxyToolResolver) {
@@ -589,7 +566,6 @@ export class ToolExecutor {
               undefined, // not sandboxed
               context.conversationId,
               executionTarget,
-              undefined, // no principal
               false, // no persistent decisions
             );
 
@@ -756,111 +732,6 @@ export function isSideEffectTool(toolName: string, input?: Record<string, unknow
   return false;
 }
 
-const TIMEOUT_SENTINEL = Symbol('tool-timeout');
-
-const DEFAULT_TOOL_TIMEOUT_SEC = 120;
-
-/**
- * Convert a config-provided seconds value to a safe milliseconds value,
- * falling back to the default if the input is NaN, non-finite, zero, or negative.
- */
-function safeTimeoutMs(sec: unknown): number {
-  const n = Number(sec);
-  if (!Number.isFinite(n) || n <= 0) {
-    return DEFAULT_TOOL_TIMEOUT_SEC * 1000;
-  }
-  return n * 1000;
-}
-
-/**
- * Race a tool execution promise against a timeout. Returns a timeout error
- * result instead of throwing so the agent loop can continue gracefully.
- */
-async function executeWithTimeout(
-  promise: Promise<ToolExecutionResult>,
-  timeoutMs: number,
-  toolName: string,
-): Promise<ToolExecutionResult> {
-  // Guard against NaN/invalid values that would cause setTimeout to fire immediately
-  const safeMs = Number.isFinite(timeoutMs) && timeoutMs > 0
-    ? timeoutMs
-    : DEFAULT_TOOL_TIMEOUT_SEC * 1000;
-  let timeoutHandle: ReturnType<typeof setTimeout>;
-  const timeoutPromise = new Promise<typeof TIMEOUT_SENTINEL>((resolve) => {
-    timeoutHandle = setTimeout(() => resolve(TIMEOUT_SENTINEL), safeMs);
-  });
-  try {
-    const result = await Promise.race([promise, timeoutPromise]);
-    if (result === TIMEOUT_SENTINEL) {
-      const sec = Math.round(safeMs / 1000);
-      return {
-        content: `Tool "${toolName}" timed out after ${sec}s. The operation may still be running in the background. Consider increasing timeouts.toolExecutionTimeoutSec in the config.`,
-        isError: true,
-      };
-    }
-    return result;
-  } finally {
-    clearTimeout(timeoutHandle!);
-  }
-}
-
-/**
- * Build a PolicyContext from tool metadata and execution context. Skill-origin
- * tools carry a principal identifying the owning skill. When executing within
- * a task run, ephemeral permission rules are included so pre-approved tools
- * are auto-allowed without prompting.
- */
-function buildPolicyContext(tool: Tool, context?: ToolContext): PolicyContext | undefined {
-  const ephemeralRules = context?.taskRunId
-    ? getTaskRunRules(context.taskRunId)
-    : undefined;
-
-  if (tool.origin === 'skill') {
-    return {
-      principal: {
-        kind: 'skill',
-        id: tool.ownerSkillId,
-        version: tool.ownerSkillVersionHash,
-      },
-      executionTarget: tool.executionTarget,
-      ephemeralRules: ephemeralRules?.length ? ephemeralRules : undefined,
-    };
-  }
-
-  // For non-skill tools in a task run, create a context with task principal
-  // and ephemeral rules so pre-approved tools are honored.
-  if (context?.taskRunId && ephemeralRules?.length) {
-    return {
-      principal: {
-        kind: 'task',
-        id: context.taskRunId,
-      },
-      ephemeralRules,
-    };
-  }
-
-  return undefined;
-}
-
-function resolveExecutionTarget(toolName: string): ExecutionTarget {
-  const tool = getTool(toolName);
-  // Manifest-declared execution target is authoritative — check it first so
-  // skill tools with host_/computer_use_ prefixes aren't mis-classified.
-  if (tool?.executionTarget) {
-    return tool.executionTarget;
-  }
-  // Check the tool's executionMode metadata — proxy tools run on the connected
-  // client (host), not inside the sandbox.
-  if (tool?.executionMode === 'proxy') {
-    return 'host';
-  }
-  // Prefix heuristics for core tools that don't declare an explicit target.
-  if (toolName.startsWith('host_') || toolName.startsWith('computer_use_')) {
-    return 'host';
-  }
-  return 'sandbox';
-}
-
 /**
  * Sanitize tool inputs before they are emitted in lifecycle events and hooks.
  * Applies recursive field-level redaction for known-sensitive keys.