@sanqianx/claude-ai-workbench 0.13.2 → 0.13.4

package/src/backend/lib/native-task-trace.js

@@ -1,440 +1,440 @@
-'use strict';
-
-// Native task trace collection from Claude Agent SDK in-process hooks.
-//
-// Real hook payloads (verified on SDK 0.2.141 + global CLI 2.1.143) carry
-// session_id, agent_id, tool_use_id and real tool content, and they keep
-// firing for background subagents after the main reply ends. Every emitted
-// field is an observed raw fact: no owner, no parent relation and no id is
-// ever inferred or fabricated here. Traces that cannot be correlated stay
-// association "unassigned" for a later, separately reviewed resolver.
-
-const crypto = require('crypto');
-
-const TOOL_HOOKS = new Set(['PreToolUse', 'PostToolUse', 'PostToolUseFailure']);
-const LIFECYCLE_HOOKS = new Set(['SubagentStart', 'SubagentStop']);
-// Root-level dispatch tools: their receipts tie a real returned agentId to
-// a root tool_use_id, so they are traced even though agent_id is empty.
-const ROOT_TASK_TOOLS = new Set(['Agent', 'Task']);
-
-// Only the values of these explicit credential env names are read from the
-// session env; the env object itself never reaches an emitted event.
-const CREDENTIAL_ENV_KEYS = [
-  'ANTHROPIC_AUTH_TOKEN',
-  'ANTHROPIC_API_KEY',
-  'ANTHROPIC_DYNAMIC_API_KEY',
-  'OPENAI_API_KEY',
-];
-
-// Keys whose value is a credential by name, in any spelling. Usage counters
-// such as total_tokens are deliberately not part of this set.
-const SENSITIVE_KEYS = new Set([
-  'authorization', 'proxyauthorization', 'apikey', 'authtoken', 'accesstoken',
-  'refreshtoken', 'password', 'secret', 'clientsecret', 'credential',
-  'credentials', 'privatekey',
-]);
-
-const BEARER_RE = /Bearer\s+[A-Za-z0-9._~+/=-]{4,}/g;
-const KEY_PATTERN_RE = /\bsk-(?:ant|cp|proj|test|live|svcacct|admin)-[A-Za-z0-9_-]{8,}\b/g;
-const REDACTED_SECRET = '[REDACTED:secret]';
-const REDACTED_KEY = '[REDACTED:key]';
-const MAX_DEPTH = 8;
-const MAX_NODES = 4000;
-const MAX_STRING = 8000;
-const MAX_CHARS = 65536;
-const SECRET_MAX = 4096;
-const PATTERN_LOOKAHEAD = 512;
-const MAX_MATCHES = 512;
-const REDACTED_BEARER = 'Bearer [REDACTED:bearer]';
-
-function idString(value) {
-  return typeof value === 'string' ? value : null;
-}
-
-function isSensitiveKey(key) {
-  return SENSITIVE_KEYS.has(String(key).toLowerCase().replace(/[^a-z0-9]/g, ''));
-}
-
-// Any non-empty configured credential value is protected, however short;
-// only the empty string is excluded because it cannot be searched.
-function collectSecretValues(env) {
-  const values = [];
-  if (!env || typeof env !== 'object') return values;
-  for (const key of CREDENTIAL_ENV_KEYS) {
-    const value = env[key];
-    if (typeof value === 'string' && value.length > 0) values.push(value);
-  }
-  return values;
-}
-
-function newBudget() {
-  return {
-    chars: 0, nodes: 0, truncated: false, reason: null,
-    mark(reason) { if (!this.truncated) { this.truncated = true; this.reason = reason; } },
-  };
-}
-
-// Bounded masking. All sensitive intervals - configured credentials plus
-// generic Bearer and sk- key patterns - are collected once on a bounded
-// window (the first MAX_STRING raw characters plus a lookahead only wide
-// enough for the longest configured credential or prefix recognition) and
-// merged before any output is built, so a match straddling a boundary can
-// never survive as a fragment. The lookahead region is never published and
-// no per-chunk re-scanning exists.
-function collectCredentialIntervals(scan, secrets, intervals, state) {
-  for (const secret of secrets) {
-    let from = 0;
-    while (state.matches <= MAX_MATCHES) {
-      const at = scan.indexOf(secret, from);
-      if (at === -1) break;
-      intervals.push({ start: at, end: at + secret.length, kind: 'secret' });
-      state.matches += 1;
-      from = at + 1;
-    }
-  }
-}
-
-function collectPatternIntervals(scan, regex, kind, intervals, state) {
-  regex.lastIndex = 0;
-  while (state.matches <= MAX_MATCHES) {
-    const hit = regex.exec(scan);
-    if (!hit) break;
-    intervals.push({ start: hit.index, end: hit.index + hit[0].length, kind });
-    state.matches += 1;
-  }
-  regex.lastIndex = 0;
-}
-
-// Overlapping and adjacent intervals collapse into one; secret outranks
-// bearer which outranks key, so a configured secret found inside a Bearer
-// token masks the whole token.
-function mergeIntervals(intervals) {
-  const rank = { key: 0, bearer: 1, secret: 2 };
-  const ordered = intervals.slice().sort((a, b) => (a.start - b.start) || (rank[b.kind] - rank[a.kind]));
-  const merged = [];
-  for (const iv of ordered) {
-    const last = merged[merged.length - 1];
-    if (last && iv.start <= last.end) {
-      if (iv.end > last.end) last.end = iv.end;
-      if (rank[iv.kind] > rank[last.kind]) last.kind = iv.kind;
-    } else merged.push({ start: iv.start, end: iv.end, kind: iv.kind });
-  }
-  return merged;
-}
-
-function maskBounded(text, secrets) {
-  const longest = secrets.reduce((acc, secret) => (secret.length > acc ? secret.length : acc), 0);
-  const lookahead = Math.min(SECRET_MAX, Math.max(longest, PATTERN_LOOKAHEAD));
-  const scan = text.slice(0, MAX_STRING + lookahead);
-  const state = { matches: 0 };
-  const intervals = [];
-  collectCredentialIntervals(scan, secrets, intervals, state);
-  if (state.matches <= MAX_MATCHES) collectPatternIntervals(scan, BEARER_RE, 'bearer', intervals, state);
-  if (state.matches <= MAX_MATCHES) collectPatternIntervals(scan, KEY_PATTERN_RE, 'key', intervals, state);
-  if (state.matches > MAX_MATCHES) {
-    // The full sensitive set is unknowable within the match cap, so no
-    // output is built from partial interval knowledge.
-    return { value: '[TRUNCATED:matches]', truncated: true, reason: 'matches' };
-  }
-  let out = '';
-  let covered = 0;
-  let truncated = text.length > MAX_STRING;
-  const pushRaw = end => {
-    const stop = Math.min(end, MAX_STRING, covered + (MAX_STRING - out.length));
-    if (stop > covered) out += scan.slice(covered, stop);
-    if (stop < Math.min(end, MAX_STRING)) truncated = true;
-    covered = Math.max(covered, stop);
-  };
-  for (const iv of mergeIntervals(intervals)) {
-    if (iv.start >= MAX_STRING) break;
-    if (iv.start > covered) pushRaw(iv.start);
-    if (covered < iv.start) break;
-    const marker = iv.kind === 'secret' ? REDACTED_SECRET : iv.kind === 'bearer' ? REDACTED_BEARER : REDACTED_KEY;
-    if (out.length + marker.length > MAX_STRING) {
-      // No room for a whole marker: publishing stops here. Later intervals
-      // were never traversed, so the final raw push would leak their
-      // content; return the withheld output directly instead.
-      return { value: out, truncated: true, reason: 'string' };
-    }
-    out += marker;
-    covered = Math.max(covered, iv.end);
-  }
-  if (covered < MAX_STRING) pushRaw(MAX_STRING);
-  return { value: out, truncated, reason: truncated ? 'string' : null };
-}
-
-// Full-text masking for the transcript read path. Unlike the bounded hook
-// preview above, the whole input is scanned and the whole input is
-// returned: the scan covers the entire string, so a configured credential
-// of any length and a match straddling any position can never survive as a
-// fragment. The only refusal is the match cap - the full sensitive set is
-// unknowable within MAX_MATCHES, and no output is built from partial
-// interval knowledge.
-function maskFullText(text, secrets) {
-  const state = { matches: 0 };
-  const intervals = [];
-  collectCredentialIntervals(text, secrets, intervals, state);
-  if (state.matches <= MAX_MATCHES) collectPatternIntervals(text, BEARER_RE, 'bearer', intervals, state);
-  if (state.matches <= MAX_MATCHES) collectPatternIntervals(text, KEY_PATTERN_RE, 'key', intervals, state);
-  if (state.matches > MAX_MATCHES) return { value: '', truncated: true, reason: 'matches' };
-  let out = '';
-  let covered = 0;
-  for (const iv of mergeIntervals(intervals)) {
-    if (iv.start > covered) out += text.slice(covered, iv.start);
-    out += iv.kind === 'secret' ? REDACTED_SECRET : iv.kind === 'bearer' ? REDACTED_BEARER : REDACTED_KEY;
-    covered = Math.max(covered, iv.end);
-  }
-  if (covered < text.length) out += text.slice(covered);
-  return { value: out, truncated: false, reason: null };
-}
-function numberCost(value) {
-  return Number.isFinite(value) ? String(value).length : 4;
-}
-function redact(value, secrets, budget, depth, seen) {
-  const kind = typeof value;
-  if (kind === 'string') {
-    if (budget.chars >= MAX_CHARS) { budget.mark('size'); return '[TRUNCATED:size]'; }
-    const masked = maskBounded(value, secrets);
-    budget.chars += 2 + masked.value.length;
-    if (masked.truncated) budget.mark(masked.reason === 'matches' ? 'matches' : 'string');
-    return masked.value;
-  }
-  if (value === null || value === undefined) { budget.chars += 4; return null; }
-  if (kind === 'boolean') { budget.chars += value ? 4 : 5; return value; }
-  if (kind === 'number') { budget.chars += numberCost(value); return value; }
-  if (kind === 'bigint') { budget.chars += value.toString().length + 2; return value.toString(); }
-  if (kind !== 'object') return null;
-  if (depth >= MAX_DEPTH) { budget.mark('depth'); return '[TRUNCATED:depth]'; }
-  if (budget.nodes >= MAX_NODES || budget.chars >= MAX_CHARS) { budget.mark('size'); return '[TRUNCATED:size]'; }
-  if (seen.has(value)) { budget.mark('cycle'); return '[TRUNCATED:cycle]'; }
-  seen.add(value);
-  budget.nodes += 1;
-  budget.chars += 1;
-  if (Array.isArray(value)) {
-    const out = [];
-    for (const item of value) {
-      // Every element consumes budget (separator + its own cost inside the
-      // recursion) and the check happens before the element is constructed.
-      budget.chars += out.length ? 1 : 0;
-      if (budget.chars >= MAX_CHARS) { budget.mark('size'); return out; }
-      out.push(redact(item, secrets, budget, depth + 1, seen));
-    }
-    budget.chars += 1;
-    return out;
-  }
-  // Own-property construction only: a JSON-supplied "__proto__" or
-  // "constructor" key must survive as own data and must never retarget the
-  // output prototype or create inherited properties.
-  const out = {};
-  const usedKeys = new Set();
-  const keys = Object.keys(value);
-  for (let i = 0; i < keys.length; i += 1) {
-    const key = keys[i];
-    // Classification stays on the ORIGINAL key: renaming must never spare a
-    // credential-shaped value from whole-value masking.
-    const sensitiveName = isSensitiveKey(key);
-    // Keys are payload strings too and run through the same bounded masking
-    // engine as values, so a secret or Bearer/sk- pattern inside a field
-    // name can no more survive than inside a value.
-    const maskedKey = maskBounded(key, secrets);
-    if (maskedKey.truncated) budget.mark(maskedKey.reason === 'matches' ? 'matches' : 'string');
-    let outKey = maskedKey.value;
-    if (usedKeys.has(outKey)) {
-      // Deterministic, content-free disambiguation: two originals masking to
-      // one marker keep both values; the suffix never encodes key text and
-      // nothing is silently overwritten.
-      let n = 2;
-      while (usedKeys.has(outKey + '@' + n)) n += 1;
-      outKey = outKey + '@' + n;
-    }
-    usedKeys.add(outKey);
-    // Emitted keys, quotes, separators and brackets are all charged, so the
-    // serialized payload stays near MAX_CHARS (single strings add bounded
-    // overshoot).
-    budget.chars += outKey.length + 3 + (i ? 1 : 0);
-    if (budget.chars >= MAX_CHARS) { budget.mark('size'); return out; }
-    if (sensitiveName) {
-      budget.chars += REDACTED_KEY.length + 2;
-      Object.defineProperty(out, outKey, {
-        value: REDACTED_KEY,
-        enumerable: true, writable: true, configurable: true,
-      });
-      continue;
-    }
-    Object.defineProperty(out, outKey, {
-      value: redact(value[key], secrets, budget, depth + 1, seen),
-      enumerable: true, writable: true, configurable: true,
-    });
-  }
-  budget.chars += 1;
-  return out;
-}
-
-function redactPayload(value, secrets) {
-  const budget = newBudget();
-  const safe = redact(value === undefined ? null : value, secrets, budget, 0, new Set());
-  return budget.truncated ? { value: safe, truncated: true, truncationReason: budget.reason } : { value: safe };
-}
-function stableTraceId(tuple) {
-  const json = JSON.stringify(['native-trace', 1].concat(tuple));
-  return 'nt1-' + crypto.createHash('sha256').update(json).digest('hex').slice(0, 32);
-}
-
-// Text-level redaction boundary for the native transcript path: the same
-// credential set and interval machinery the hook traces use, applied to the
-// WHOLE text. The hook preview (maskBounded) may stop at its bounded window
-// and say so; this boundary may not: a message body must survive whole, so
-// any masking that cannot be proven complete throws and the normalizer
-// fails closed instead of publishing partial text as a complete message.
-function createSecretRedactor(getSecrets) {
-  return text => {
-    const secrets = collectSecretValues(typeof getSecrets === 'function' ? getSecrets() : null);
-    if (typeof text !== 'string') throw new Error('redactor requires a string');
-    const masked = maskFullText(text, secrets);
-    if (masked.truncated) {
-      const error = new Error('native task transcript redaction could not complete: ' + masked.reason);
-      error.code = 'NATIVE_TASK_TRANSCRIPT_REDACT_INCOMPLETE';
-      throw error;
-    }
-    return masked.value;
-  };
-}
-
-function createNativeTaskHooks({ parentSessionId, emit, isCurrent, getSecrets } = {}) {
-  const safeParent = typeof parentSessionId === 'string' ? parentSessionId : null;
-
-  // Diagnostics carry a fixed literal only: no raw exception, payload or
-  // credential can leak through a collection bug.
-  const emitDiagnostic = (hookEvent, diagnostic) => {
-    try {
-      emit({
-        type: 'claude/native-trace', source: 'sdk-hook', hookEvent,
-        parentSessionId: safeParent, sdkSessionId: null, nativeAgentId: null,
-        rawToolUseId: null, callbackToolUseId: null, rawParentToolUseId: null,
-        toolName: null, diagnostic, error: 'native trace hook collection failed',
-        traceId: null, correlationIncomplete: true, association: 'unassigned',
-        ownerRunId: null,
-      });
-    } catch { /* one bounded retry only; never break the tool flow */ }
-  };
-
-  // Publish verdict of one trace: true only when the emit path confirms the
-  // fact reached its audience. The runner's gate returns false when the
-  // durable receipt was refused; a throw also means unpublished.
-  const emitTrace = event => {
-    try {
-      return emit(event) !== false;
-    } catch {
-      emitDiagnostic(event.hookEvent, 'emit-failed');
-      return false;
-    }
-  };
-
-  const attachPayload = (event, field, value, secrets) => {
-    const result = redactPayload(value, secrets);
-    event[field] = result.value;
-    if (result.truncated) {
-      event[field + 'Truncated'] = true;
-      event[field + 'TruncationReason'] = result.truncationReason;
-    }
-  };
-
-  const collect = async (hookEvent, input, callbackToolUseId) => {
-    try {
-      let current = true;
-      try { current = typeof isCurrent === 'function' ? isCurrent() : true; }
-      catch {
-        // Unknown query state: a payload-free fixed diagnostic instead of
-        // either silently dropping the fact or emitting untrusted content.
-        emitDiagnostic(hookEvent, 'guard-error');
-        return {};
-      }
-      if (!current) return {};
-      const h = input && typeof input === 'object' ? input : {};
-      const nativeAgentId = idString(h.agent_id);
-      const toolName = idString(h.tool_name);
-      const childAgent = nativeAgentId !== null && nativeAgentId !== '';
-      const rootTaskTool = !childAgent && TOOL_HOOKS.has(hookEvent) && ROOT_TASK_TOOLS.has(toolName || '');
-      const lifecycle = LIFECYCLE_HOOKS.has(hookEvent);
-      // Ordinary root tools (Read/Bash/...) already stream through the main
-      // message path; collecting them again here would duplicate facts.
-      if (!((TOOL_HOOKS.has(hookEvent) && (childAgent || rootTaskTool)) || lifecycle)) return {};
-
-      let secrets = null;
-      try { secrets = collectSecretValues(typeof getSecrets === 'function' ? getSecrets() : null); }
-      catch {
-        // Redaction inputs failed, so the payload can never be published
-        // safely; report that fact without any original content.
-        emitDiagnostic(hookEvent, 'secrets-unavailable');
-        return {};
-      }
-      if (secrets.some(secret => secret.length > SECRET_MAX)) {
-        // A credential longer than the bounded scan window cannot be
-        // matched reliably; publish a fixed diagnostic, never a payload.
-        emitDiagnostic(hookEvent, 'credential-oversize');
-        return {};
-      }
-
-      const sdkSessionId = idString(h.session_id);
-      const rawToolUseId = idString(h.tool_use_id);
-      const rawParentToolUseId = idString(h.parent_tool_use_id);
-      const correlationId = TOOL_HOOKS.has(hookEvent)
-        ? (rawToolUseId || callbackToolUseId || null)
-        : (childAgent ? nativeAgentId : null);
-      const traceId = sdkSessionId && correlationId
-        ? stableTraceId(['sdk-hook', sdkSessionId, nativeAgentId, hookEvent, correlationId])
-        : null;
-
-      const event = {
-        type: 'claude/native-trace',
-        source: 'sdk-hook',
-        hookEvent,
-        parentSessionId: safeParent,
-        sdkSessionId,
-        nativeAgentId,
-        agentType: idString(h.agent_type),
-        rawToolUseId,
-        callbackToolUseId,
-        rawParentToolUseId,
-        toolName,
-        traceId,
-        association: 'unassigned',
-        ownerRunId: null,
-      };
-      if (!traceId) event.correlationIncomplete = true;
-      if (lifecycle && !childAgent) event.diagnostic = 'missing-agent-id';
-      if (hookEvent === 'PreToolUse' && h.tool_input !== undefined) attachPayload(event, 'toolInput', h.tool_input, secrets);
-      if (hookEvent === 'PostToolUse' && h.tool_response !== undefined) attachPayload(event, 'toolResponse', h.tool_response, secrets);
-      if (hookEvent === 'PostToolUseFailure' && h.error !== undefined) attachPayload(event, 'error', h.error, secrets);
-      if (hookEvent === 'SubagentStop' && h.last_assistant_message !== undefined) attachPayload(event, 'lastAssistantMessage', h.last_assistant_message, secrets);
-      const published = emitTrace(event);
-      // A PreToolUse fact that could not be proven on disk blocks the tool
-      // call: the SDK's documented control-response shape (PreToolUseHookSpecificOutput,
-      // permissionDecision 'deny') replaces the empty-object default-allow,
-      // so an unauditable tool use never silently proceeds.
-      if (!published && hookEvent === 'PreToolUse') {
-        return {
-          hookSpecificOutput: {
-            hookEventName: 'PreToolUse',
-            permissionDecision: 'deny',
-            permissionDecisionReason: 'native task history unavailable: the tool trace could not be persisted, so the call is blocked',
-          },
-        };
-      }
-    } catch {
-      emitDiagnostic(hookEvent, 'collect-error');
-    }
-    return {};
-  };
-  const forEvent = name => async (input, toolUseID) => collect(name, input, idString(toolUseID));
-
-  return {
-    PreToolUse: [{ hooks: [forEvent('PreToolUse')] }],
-    PostToolUse: [{ hooks: [forEvent('PostToolUse')] }],
-    PostToolUseFailure: [{ hooks: [forEvent('PostToolUseFailure')] }],
-    SubagentStart: [{ hooks: [forEvent('SubagentStart')] }],
-    SubagentStop: [{ hooks: [forEvent('SubagentStop')] }],
-  };
-}
-
-module.exports = { createNativeTaskHooks, createSecretRedactor };
+'use strict';
+
+// Native task trace collection from Claude Agent SDK in-process hooks.
+//
+// Real hook payloads (verified on SDK 0.2.141 + global CLI 2.1.143) carry
+// session_id, agent_id, tool_use_id and real tool content, and they keep
+// firing for background subagents after the main reply ends. Every emitted
+// field is an observed raw fact: no owner, no parent relation and no id is
+// ever inferred or fabricated here. Traces that cannot be correlated stay
+// association "unassigned" for a later, separately reviewed resolver.
+
+const crypto = require('crypto');
+
+const TOOL_HOOKS = new Set(['PreToolUse', 'PostToolUse', 'PostToolUseFailure']);
+const LIFECYCLE_HOOKS = new Set(['SubagentStart', 'SubagentStop']);
+// Root-level dispatch tools: their receipts tie a real returned agentId to
+// a root tool_use_id, so they are traced even though agent_id is empty.
+const ROOT_TASK_TOOLS = new Set(['Agent', 'Task']);
+
+// Only the values of these explicit credential env names are read from the
+// session env; the env object itself never reaches an emitted event.
+const CREDENTIAL_ENV_KEYS = [
+  'ANTHROPIC_AUTH_TOKEN',
+  'ANTHROPIC_API_KEY',
+  'ANTHROPIC_DYNAMIC_API_KEY',
+  'OPENAI_API_KEY',
+];
+
+// Keys whose value is a credential by name, in any spelling. Usage counters
+// such as total_tokens are deliberately not part of this set.
+const SENSITIVE_KEYS = new Set([
+  'authorization', 'proxyauthorization', 'apikey', 'authtoken', 'accesstoken',
+  'refreshtoken', 'password', 'secret', 'clientsecret', 'credential',
+  'credentials', 'privatekey',
+]);
+
+const BEARER_RE = /Bearer\s+[A-Za-z0-9._~+/=-]{4,}/g;
+const KEY_PATTERN_RE = /\bsk-(?:ant|cp|proj|test|live|svcacct|admin)-[A-Za-z0-9_-]{8,}\b/g;
+const REDACTED_SECRET = '[REDACTED:secret]';
+const REDACTED_KEY = '[REDACTED:key]';
+const MAX_DEPTH = 8;
+const MAX_NODES = 4000;
+const MAX_STRING = 8000;
+const MAX_CHARS = 65536;
+const SECRET_MAX = 4096;
+const PATTERN_LOOKAHEAD = 512;
+const MAX_MATCHES = 512;
+const REDACTED_BEARER = 'Bearer [REDACTED:bearer]';
+
+function idString(value) {
+  return typeof value === 'string' ? value : null;
+}
+
+function isSensitiveKey(key) {
+  return SENSITIVE_KEYS.has(String(key).toLowerCase().replace(/[^a-z0-9]/g, ''));
+}
+
+// Any non-empty configured credential value is protected, however short;
+// only the empty string is excluded because it cannot be searched.
+function collectSecretValues(env) {
+  const values = [];
+  if (!env || typeof env !== 'object') return values;
+  for (const key of CREDENTIAL_ENV_KEYS) {
+    const value = env[key];
+    if (typeof value === 'string' && value.length > 0) values.push(value);
+  }
+  return values;
+}
+
+function newBudget() {
+  return {
+    chars: 0, nodes: 0, truncated: false, reason: null,
+    mark(reason) { if (!this.truncated) { this.truncated = true; this.reason = reason; } },
+  };
+}
+
+// Bounded masking. All sensitive intervals - configured credentials plus
+// generic Bearer and sk- key patterns - are collected once on a bounded
+// window (the first MAX_STRING raw characters plus a lookahead only wide
+// enough for the longest configured credential or prefix recognition) and
+// merged before any output is built, so a match straddling a boundary can
+// never survive as a fragment. The lookahead region is never published and
+// no per-chunk re-scanning exists.
+function collectCredentialIntervals(scan, secrets, intervals, state) {
+  for (const secret of secrets) {
+    let from = 0;
+    while (state.matches <= MAX_MATCHES) {
+      const at = scan.indexOf(secret, from);
+      if (at === -1) break;
+      intervals.push({ start: at, end: at + secret.length, kind: 'secret' });
+      state.matches += 1;
+      from = at + 1;
+    }
+  }
+}
+
+function collectPatternIntervals(scan, regex, kind, intervals, state) {
+  regex.lastIndex = 0;
+  while (state.matches <= MAX_MATCHES) {
+    const hit = regex.exec(scan);
+    if (!hit) break;
+    intervals.push({ start: hit.index, end: hit.index + hit[0].length, kind });
+    state.matches += 1;
+  }
+  regex.lastIndex = 0;
+}
+
+// Overlapping and adjacent intervals collapse into one; secret outranks
+// bearer which outranks key, so a configured secret found inside a Bearer
+// token masks the whole token.
+function mergeIntervals(intervals) {
+  const rank = { key: 0, bearer: 1, secret: 2 };
+  const ordered = intervals.slice().sort((a, b) => (a.start - b.start) || (rank[b.kind] - rank[a.kind]));
+  const merged = [];
+  for (const iv of ordered) {
+    const last = merged[merged.length - 1];
+    if (last && iv.start <= last.end) {
+      if (iv.end > last.end) last.end = iv.end;
+      if (rank[iv.kind] > rank[last.kind]) last.kind = iv.kind;
+    } else merged.push({ start: iv.start, end: iv.end, kind: iv.kind });
+  }
+  return merged;
+}
+
+function maskBounded(text, secrets) {
+  const longest = secrets.reduce((acc, secret) => (secret.length > acc ? secret.length : acc), 0);
+  const lookahead = Math.min(SECRET_MAX, Math.max(longest, PATTERN_LOOKAHEAD));
+  const scan = text.slice(0, MAX_STRING + lookahead);
+  const state = { matches: 0 };
+  const intervals = [];
+  collectCredentialIntervals(scan, secrets, intervals, state);
+  if (state.matches <= MAX_MATCHES) collectPatternIntervals(scan, BEARER_RE, 'bearer', intervals, state);
+  if (state.matches <= MAX_MATCHES) collectPatternIntervals(scan, KEY_PATTERN_RE, 'key', intervals, state);
+  if (state.matches > MAX_MATCHES) {
+    // The full sensitive set is unknowable within the match cap, so no
+    // output is built from partial interval knowledge.
+    return { value: '[TRUNCATED:matches]', truncated: true, reason: 'matches' };
+  }
+  let out = '';
+  let covered = 0;
+  let truncated = text.length > MAX_STRING;
+  const pushRaw = end => {
+    const stop = Math.min(end, MAX_STRING, covered + (MAX_STRING - out.length));
+    if (stop > covered) out += scan.slice(covered, stop);
+    if (stop < Math.min(end, MAX_STRING)) truncated = true;
+    covered = Math.max(covered, stop);
+  };
+  for (const iv of mergeIntervals(intervals)) {
+    if (iv.start >= MAX_STRING) break;
+    if (iv.start > covered) pushRaw(iv.start);
+    if (covered < iv.start) break;
+    const marker = iv.kind === 'secret' ? REDACTED_SECRET : iv.kind === 'bearer' ? REDACTED_BEARER : REDACTED_KEY;
+    if (out.length + marker.length > MAX_STRING) {
+      // No room for a whole marker: publishing stops here. Later intervals
+      // were never traversed, so the final raw push would leak their
+      // content; return the withheld output directly instead.
+      return { value: out, truncated: true, reason: 'string' };
+    }
+    out += marker;
+    covered = Math.max(covered, iv.end);
+  }
+  if (covered < MAX_STRING) pushRaw(MAX_STRING);
+  return { value: out, truncated, reason: truncated ? 'string' : null };
+}
+
+// Full-text masking for the transcript read path. Unlike the bounded hook
+// preview above, the whole input is scanned and the whole input is
+// returned: the scan covers the entire string, so a configured credential
+// of any length and a match straddling any position can never survive as a
+// fragment. The only refusal is the match cap - the full sensitive set is
+// unknowable within MAX_MATCHES, and no output is built from partial
+// interval knowledge.
+function maskFullText(text, secrets) {
+  const state = { matches: 0 };
+  const intervals = [];
+  collectCredentialIntervals(text, secrets, intervals, state);
+  if (state.matches <= MAX_MATCHES) collectPatternIntervals(text, BEARER_RE, 'bearer', intervals, state);
+  if (state.matches <= MAX_MATCHES) collectPatternIntervals(text, KEY_PATTERN_RE, 'key', intervals, state);
+  if (state.matches > MAX_MATCHES) return { value: '', truncated: true, reason: 'matches' };
+  let out = '';
+  let covered = 0;
+  for (const iv of mergeIntervals(intervals)) {
+    if (iv.start > covered) out += text.slice(covered, iv.start);
+    out += iv.kind === 'secret' ? REDACTED_SECRET : iv.kind === 'bearer' ? REDACTED_BEARER : REDACTED_KEY;
+    covered = Math.max(covered, iv.end);
+  }
+  if (covered < text.length) out += text.slice(covered);
+  return { value: out, truncated: false, reason: null };
+}
+function numberCost(value) {
+  return Number.isFinite(value) ? String(value).length : 4;
+}
+function redact(value, secrets, budget, depth, seen) {
+  const kind = typeof value;
+  if (kind === 'string') {
+    if (budget.chars >= MAX_CHARS) { budget.mark('size'); return '[TRUNCATED:size]'; }
+    const masked = maskBounded(value, secrets);
+    budget.chars += 2 + masked.value.length;
+    if (masked.truncated) budget.mark(masked.reason === 'matches' ? 'matches' : 'string');
+    return masked.value;
+  }
+  if (value === null || value === undefined) { budget.chars += 4; return null; }
+  if (kind === 'boolean') { budget.chars += value ? 4 : 5; return value; }
+  if (kind === 'number') { budget.chars += numberCost(value); return value; }
+  if (kind === 'bigint') { budget.chars += value.toString().length + 2; return value.toString(); }
+  if (kind !== 'object') return null;
+  if (depth >= MAX_DEPTH) { budget.mark('depth'); return '[TRUNCATED:depth]'; }
+  if (budget.nodes >= MAX_NODES || budget.chars >= MAX_CHARS) { budget.mark('size'); return '[TRUNCATED:size]'; }
+  if (seen.has(value)) { budget.mark('cycle'); return '[TRUNCATED:cycle]'; }
+  seen.add(value);
+  budget.nodes += 1;
+  budget.chars += 1;
+  if (Array.isArray(value)) {
+    const out = [];
+    for (const item of value) {
+      // Every element consumes budget (separator + its own cost inside the
+      // recursion) and the check happens before the element is constructed.
+      budget.chars += out.length ? 1 : 0;
+      if (budget.chars >= MAX_CHARS) { budget.mark('size'); return out; }
+      out.push(redact(item, secrets, budget, depth + 1, seen));
+    }
+    budget.chars += 1;
+    return out;
+  }
+  // Own-property construction only: a JSON-supplied "__proto__" or
+  // "constructor" key must survive as own data and must never retarget the
+  // output prototype or create inherited properties.
+  const out = {};
+  const usedKeys = new Set();
+  const keys = Object.keys(value);
+  for (let i = 0; i < keys.length; i += 1) {
+    const key = keys[i];
+    // Classification stays on the ORIGINAL key: renaming must never spare a
+    // credential-shaped value from whole-value masking.
+    const sensitiveName = isSensitiveKey(key);
+    // Keys are payload strings too and run through the same bounded masking
+    // engine as values, so a secret or Bearer/sk- pattern inside a field
+    // name can no more survive than inside a value.
+    const maskedKey = maskBounded(key, secrets);
+    if (maskedKey.truncated) budget.mark(maskedKey.reason === 'matches' ? 'matches' : 'string');
+    let outKey = maskedKey.value;
+    if (usedKeys.has(outKey)) {
+      // Deterministic, content-free disambiguation: two originals masking to
+      // one marker keep both values; the suffix never encodes key text and
+      // nothing is silently overwritten.
+      let n = 2;
+      while (usedKeys.has(outKey + '@' + n)) n += 1;
+      outKey = outKey + '@' + n;
+    }
+    usedKeys.add(outKey);
+    // Emitted keys, quotes, separators and brackets are all charged, so the
+    // serialized payload stays near MAX_CHARS (single strings add bounded
+    // overshoot).
+    budget.chars += outKey.length + 3 + (i ? 1 : 0);
+    if (budget.chars >= MAX_CHARS) { budget.mark('size'); return out; }
+    if (sensitiveName) {
+      budget.chars += REDACTED_KEY.length + 2;
+      Object.defineProperty(out, outKey, {
+        value: REDACTED_KEY,
+        enumerable: true, writable: true, configurable: true,
+      });
+      continue;
+    }
+    Object.defineProperty(out, outKey, {
+      value: redact(value[key], secrets, budget, depth + 1, seen),
+      enumerable: true, writable: true, configurable: true,
+    });
+  }
+  budget.chars += 1;
+  return out;
+}
+
+function redactPayload(value, secrets) {
+  const budget = newBudget();
+  const safe = redact(value === undefined ? null : value, secrets, budget, 0, new Set());
+  return budget.truncated ? { value: safe, truncated: true, truncationReason: budget.reason } : { value: safe };
+}
+function stableTraceId(tuple) {
+  const json = JSON.stringify(['native-trace', 1].concat(tuple));
+  return 'nt1-' + crypto.createHash('sha256').update(json).digest('hex').slice(0, 32);
+}
+
+// Text-level redaction boundary for the native transcript path: the same
+// credential set and interval machinery the hook traces use, applied to the
+// WHOLE text. The hook preview (maskBounded) may stop at its bounded window
+// and say so; this boundary may not: a message body must survive whole, so
+// any masking that cannot be proven complete throws and the normalizer
+// fails closed instead of publishing partial text as a complete message.
+function createSecretRedactor(getSecrets) {
+  return text => {
+    const secrets = collectSecretValues(typeof getSecrets === 'function' ? getSecrets() : null);
+    if (typeof text !== 'string') throw new Error('redactor requires a string');
+    const masked = maskFullText(text, secrets);
+    if (masked.truncated) {
+      const error = new Error('native task transcript redaction could not complete: ' + masked.reason);
+      error.code = 'NATIVE_TASK_TRANSCRIPT_REDACT_INCOMPLETE';
+      throw error;
+    }
+    return masked.value;
+  };
+}
+
+function createNativeTaskHooks({ parentSessionId, emit, isCurrent, getSecrets } = {}) {
+  const safeParent = typeof parentSessionId === 'string' ? parentSessionId : null;
+
+  // Diagnostics carry a fixed literal only: no raw exception, payload or
+  // credential can leak through a collection bug.
+  const emitDiagnostic = (hookEvent, diagnostic) => {
+    try {
+      emit({
+        type: 'claude/native-trace', source: 'sdk-hook', hookEvent,
+        parentSessionId: safeParent, sdkSessionId: null, nativeAgentId: null,
+        rawToolUseId: null, callbackToolUseId: null, rawParentToolUseId: null,
+        toolName: null, diagnostic, error: 'native trace hook collection failed',
+        traceId: null, correlationIncomplete: true, association: 'unassigned',
+        ownerRunId: null,
+      });
+    } catch { /* one bounded retry only; never break the tool flow */ }
+  };
+
+  // Publish verdict of one trace: true only when the emit path confirms the
+  // fact reached its audience. The runner's gate returns false when the
+  // durable receipt was refused; a throw also means unpublished.
+  const emitTrace = event => {
+    try {
+      return emit(event) !== false;
+    } catch {
+      emitDiagnostic(event.hookEvent, 'emit-failed');
+      return false;
+    }
+  };
+
+  const attachPayload = (event, field, value, secrets) => {
+    const result = redactPayload(value, secrets);
+    event[field] = result.value;
+    if (result.truncated) {
+      event[field + 'Truncated'] = true;
+      event[field + 'TruncationReason'] = result.truncationReason;
+    }
+  };
+
+  const collect = async (hookEvent, input, callbackToolUseId) => {
+    try {
+      let current = true;
+      try { current = typeof isCurrent === 'function' ? isCurrent() : true; }
+      catch {
+        // Unknown query state: a payload-free fixed diagnostic instead of
+        // either silently dropping the fact or emitting untrusted content.
+        emitDiagnostic(hookEvent, 'guard-error');
+        return {};
+      }
+      if (!current) return {};
+      const h = input && typeof input === 'object' ? input : {};
+      const nativeAgentId = idString(h.agent_id);
+      const toolName = idString(h.tool_name);
+      const childAgent = nativeAgentId !== null && nativeAgentId !== '';
+      const rootTaskTool = !childAgent && TOOL_HOOKS.has(hookEvent) && ROOT_TASK_TOOLS.has(toolName || '');
+      const lifecycle = LIFECYCLE_HOOKS.has(hookEvent);
+      // Ordinary root tools (Read/Bash/...) already stream through the main
+      // message path; collecting them again here would duplicate facts.
+      if (!((TOOL_HOOKS.has(hookEvent) && (childAgent || rootTaskTool)) || lifecycle)) return {};
+
+      let secrets = null;
+      try { secrets = collectSecretValues(typeof getSecrets === 'function' ? getSecrets() : null); }
+      catch {
+        // Redaction inputs failed, so the payload can never be published
+        // safely; report that fact without any original content.
+        emitDiagnostic(hookEvent, 'secrets-unavailable');
+        return {};
+      }
+      if (secrets.some(secret => secret.length > SECRET_MAX)) {
+        // A credential longer than the bounded scan window cannot be
+        // matched reliably; publish a fixed diagnostic, never a payload.
+        emitDiagnostic(hookEvent, 'credential-oversize');
+        return {};
+      }
+
+      const sdkSessionId = idString(h.session_id);
+      const rawToolUseId = idString(h.tool_use_id);
+      const rawParentToolUseId = idString(h.parent_tool_use_id);
+      const correlationId = TOOL_HOOKS.has(hookEvent)
+        ? (rawToolUseId || callbackToolUseId || null)
+        : (childAgent ? nativeAgentId : null);
+      const traceId = sdkSessionId && correlationId
+        ? stableTraceId(['sdk-hook', sdkSessionId, nativeAgentId, hookEvent, correlationId])
+        : null;
+
+      const event = {
+        type: 'claude/native-trace',
+        source: 'sdk-hook',
+        hookEvent,
+        parentSessionId: safeParent,
+        sdkSessionId,
+        nativeAgentId,
+        agentType: idString(h.agent_type),
+        rawToolUseId,
+        callbackToolUseId,
+        rawParentToolUseId,
+        toolName,
+        traceId,
+        association: 'unassigned',
+        ownerRunId: null,
+      };
+      if (!traceId) event.correlationIncomplete = true;
+      if (lifecycle && !childAgent) event.diagnostic = 'missing-agent-id';
+      if (hookEvent === 'PreToolUse' && h.tool_input !== undefined) attachPayload(event, 'toolInput', h.tool_input, secrets);
+      if (hookEvent === 'PostToolUse' && h.tool_response !== undefined) attachPayload(event, 'toolResponse', h.tool_response, secrets);
+      if (hookEvent === 'PostToolUseFailure' && h.error !== undefined) attachPayload(event, 'error', h.error, secrets);
+      if (hookEvent === 'SubagentStop' && h.last_assistant_message !== undefined) attachPayload(event, 'lastAssistantMessage', h.last_assistant_message, secrets);
+      const published = emitTrace(event);
+      // A PreToolUse fact that could not be proven on disk blocks the tool
+      // call: the SDK's documented control-response shape (PreToolUseHookSpecificOutput,
+      // permissionDecision 'deny') replaces the empty-object default-allow,
+      // so an unauditable tool use never silently proceeds.
+      if (!published && hookEvent === 'PreToolUse') {
+        return {
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: 'native task history unavailable: the tool trace could not be persisted, so the call is blocked',
+          },
+        };
+      }
+    } catch {
+      emitDiagnostic(hookEvent, 'collect-error');
+    }
+    return {};
+  };
+  const forEvent = name => async (input, toolUseID) => collect(name, input, idString(toolUseID));
+
+  return {
+    PreToolUse: [{ hooks: [forEvent('PreToolUse')] }],
+    PostToolUse: [{ hooks: [forEvent('PostToolUse')] }],
+    PostToolUseFailure: [{ hooks: [forEvent('PostToolUseFailure')] }],
+    SubagentStart: [{ hooks: [forEvent('SubagentStart')] }],
+    SubagentStop: [{ hooks: [forEvent('SubagentStop')] }],
+  };
+}
+
+module.exports = { createNativeTaskHooks, createSecretRedactor };