@codebam/dsh-thinking-auditor 0.1.0

package/src/ledger.mjs

@@ -0,0 +1,398 @@
+/**
+ * Evidence ledger: a bounded, per-session index of what the monitored model
+ * actually saw.
+ *
+ * The session log is the harness's model-visible source of truth. This module
+ * subscribes to committed `session/event`s incrementally (never rewrites or
+ * blocks them) and keeps the small slice an auditor needs: tool calls with
+ * their raw arguments, paired results/outcomes, and user messages. On resume,
+ * sessions seeded before the plugin mounted are backfilled from
+ * `session.deriveMessages()`, which is the current supported full-history read.
+ *
+ * Pure module: no dsh imports, so claim verification is testable without the
+ * harness closure.
+ *
+ * @module @codebam/dsh-thinking-auditor/ledger
+ */
+
+/** Recursively flatten model content blocks to their text. */
+export function flattenContentText(content) {
+  if (content === undefined || content === null) return ''
+  if (typeof content === 'string') return content
+  if (!Array.isArray(content)) return ''
+  const parts = []
+  for (const block of content) {
+    if (typeof block === 'string') {
+      parts.push(block)
+      continue
+    }
+    if (block === null || typeof block !== 'object') continue
+    switch (block.type) {
+      case 'text':
+        if (typeof block.text === 'string') parts.push(block.text)
+        break
+      case 'reasoning':
+        // Reasoning is never evidence for a factual claim.
+        break
+      case 'tool-result':
+        parts.push(flattenContentText(block.content))
+        break
+      default:
+        if (typeof block.text === 'string') parts.push(block.text)
+        break
+    }
+  }
+  return parts.filter((part) => part.length > 0).join('\n')
+}
+
+/** Normalize text for case/whitespace-insensitive evidence search. */
+export function normalizeEvidenceText(text) {
+  return String(text ?? '').toLowerCase().replace(/\s+/g, ' ').trim()
+}
+
+/** Extract a non-zero exit code from rendered command output, when present. */
+export function parseExitCode(text) {
+  const match = /\[exit code:\s*(-?\d+|null)\]/i.exec(String(text ?? ''))
+  if (match === null || match[1] === 'null') return undefined
+  const parsed = Number(match[1])
+  return Number.isSafeInteger(parsed) ? parsed : undefined
+}
+
+/** True when a rendered result carries a failure marker independent of `isError`. */
+export function hasFailureMarker(text) {
+  const value = String(text ?? '')
+  if (/\[(?:timed out after|killed by signal|sandbox: file access denied)[^\]]*\]/i.test(value)) return true
+  if (/\b(?:ERROR|FAIL(?:ED)?|Traceback|command not found|no such file or directory)\b/.test(value)) return true
+  const exitCode = parseExitCode(value)
+  return exitCode !== undefined && exitCode !== 0
+}
+
+/** Cap one string at `max` characters with a deterministic suffix. */
+function capText(value, max) {
+  const text = String(value ?? '')
+  if (text.length <= max) return text
+  const suffix = `…[truncated ${text.length - max} chars]`
+  if (suffix.length >= max) return text.slice(0, max)
+  return `${text.slice(0, max - suffix.length)}${suffix}`
+}
+
+/** Plain deep copy of a ledger record safe to expose in a view. */
+function detach(record) {
+  return { ...record }
+}
+
+/** One session's bounded ledger. */
+class SessionLedger {
+  constructor({ maxToolCalls, maxResultChars, maxUserMessages, maxUserChars }) {
+    this.maxToolCalls = maxToolCalls
+    this.maxResultChars = maxResultChars
+    this.maxUserMessages = maxUserMessages
+    this.maxUserChars = maxUserChars
+    /** @type {Map<string, object>} */
+    this.toolCalls = new Map()
+    /** @type {string[]} insertion order for eviction. */
+    this.order = []
+    /** @type {object[]} */
+    this.users = []
+    this.currentTurn = 0
+    this.currentStep = 0
+    this.lastSeq = -1
+  }
+
+  /** Evict the oldest tool call when the bounded window is full. */
+  #trimToolCalls() {
+    while (this.order.length > this.maxToolCalls) {
+      const oldest = this.order.shift()
+      this.toolCalls.delete(oldest)
+    }
+  }
+
+  /** Record (or extend) one tool call. */
+  setToolCall(input) {
+    const callId = String(input.callId)
+    let record = this.toolCalls.get(callId)
+    if (record === undefined) {
+      record = {
+        callId,
+        turn: input.turn ?? this.currentTurn,
+        step: input.step ?? this.currentStep,
+        seq: input.seq ?? this.lastSeq,
+        name: String(input.name ?? 'unknown'),
+        argsRaw: capText(input.arguments ?? '', 4000),
+        resultText: '',
+        failed: false,
+        isError: false,
+        error: undefined,
+      }
+      this.toolCalls.set(callId, record)
+      this.order.push(callId)
+      this.#trimToolCalls()
+    } else {
+      if (input.name !== undefined) record.name = String(input.name)
+      if (input.arguments !== undefined) record.argsRaw = capText(input.arguments, 4000)
+      if (input.turn !== undefined) record.turn = input.turn
+      if (input.step !== undefined) record.step = input.step
+      if (input.seq !== undefined) record.seq = input.seq
+    }
+    return record
+  }
+
+  /** Record one tool result against its call id. */
+  setToolResult(input) {
+    const callId = String(input.callId)
+    const record = this.setToolCall({
+      callId,
+      name: input.name ?? this.toolCalls.get(callId)?.name ?? 'unknown',
+      turn: input.turn,
+      step: input.step,
+      seq: input.seq,
+    })
+    record.resultText = capText(input.text ?? '', this.maxResultChars)
+    record.isError = input.isError === true
+    record.failed = input.isError === true || hasFailureMarker(record.resultText)
+    record.error = input.error
+    return record
+  }
+
+  /** Record one user-role message on the model-visible surface. */
+  addUser(input) {
+    this.users.push({
+      seq: input.seq ?? this.lastSeq,
+      turn: input.turn ?? this.currentTurn,
+      step: input.step ?? this.currentStep,
+      sourceKind: input.sourceKind ?? 'unknown',
+      text: capText(input.text ?? '', this.maxUserChars),
+    })
+    while (this.users.length > this.maxUserMessages) this.users.shift()
+  }
+}
+
+/**
+ * Bounded evidence index over every session the process observes.
+ *
+ * The class is deliberately passive: it records events and answers questions;
+ * it never mutates a session and never appends to a log.
+ */
+export class EvidenceLedger {
+  constructor(options = {}) {
+    this.config = {
+      maxToolCalls: options.maxToolCalls ?? 120,
+      maxResultChars: options.maxResultChars ?? 6000,
+      maxUserMessages: options.maxUserMessages ?? 12,
+      maxUserChars: options.maxUserChars ?? 4000,
+    }
+    /** @type {Map<string, SessionLedger>} */
+    this.sessions = new Map()
+  }
+
+  /** Get or lazily create one session ledger. */
+  #session(sessionId, create = true) {
+    const key = String(sessionId)
+    let ledger = this.sessions.get(key)
+    if (ledger === undefined && create) {
+      ledger = new SessionLedger(this.config)
+      this.sessions.set(key, ledger)
+    }
+    return ledger
+  }
+
+  /**
+   * Record one committed session event.
+   * @param {string} sessionId - owning session.
+   * @param {{type: string, seq: number, data: object}} event - committed event envelope.
+   */
+  onSessionEvent(sessionId, event) {
+    const ledger = this.#session(sessionId)
+    ledger.lastSeq = event.seq
+    const data = event.data ?? {}
+    switch (event.type) {
+      case 'turn/start':
+        ledger.currentTurn = data.turn ?? ledger.currentTurn + 1
+        ledger.currentStep = 0
+        break
+      case 'step/start':
+        ledger.currentTurn = data.turn ?? ledger.currentTurn
+        ledger.currentStep = data.step ?? ledger.currentStep
+        break
+      case 'tool/call':
+        ledger.setToolCall({
+          callId: data.callId,
+          name: data.name,
+          arguments: data.arguments,
+          turn: data.turn,
+          step: data.step,
+          seq: event.seq,
+        })
+        break
+      case 'tool/result':
+        ledger.setToolResult({
+          callId: data.message?.content?.[0]?.toolCallId,
+          text: flattenContentText(data.message?.content),
+          isError: data.message?.content?.[0]?.isError === true || data.error !== undefined,
+          error: data.error,
+          turn: data.turn,
+          step: data.step,
+          seq: event.seq,
+        })
+        break
+      case 'user/message':
+        ledger.addUser({
+          text: flattenContentText(data.content),
+          sourceKind: data.source?.kind ?? 'unknown',
+          seq: event.seq,
+        })
+        break
+      default:
+        break
+    }
+  }
+
+  /**
+   * Backfill a session that was seeded from persistence before this plugin
+   * mounted. Uses `session.deriveMessages()` (current supported full read)
+   * rather than the deprecated synchronous event-range reads.
+   * @param {string} sessionId - owning session.
+   * @param {Array<object>} messages - derived, model-visible history.
+   */
+  seedFromMessages(sessionId, messages) {
+    const ledger = this.#session(sessionId)
+    for (const message of messages ?? []) {
+      if (message?.role === 'assistant') {
+        for (const block of message.content ?? []) {
+          if (block?.type === 'tool-call') {
+            ledger.setToolCall({
+              callId: block.id,
+              name: block.name,
+              arguments: block.arguments,
+            })
+          }
+        }
+        continue
+      }
+      if (message?.role !== 'user') continue
+      if (message.source?.kind === 'tool') {
+        const block = message.content?.[0]
+        ledger.setToolResult({
+          callId: block?.toolCallId ?? message.source.callId,
+          text: flattenContentText(block?.content ?? message.content),
+          isError: block?.isError === true,
+        })
+        continue
+      }
+      ledger.addUser({
+        text: flattenContentText(message.content),
+        sourceKind: message.source?.kind ?? 'unknown',
+      })
+    }
+  }
+
+  /** Drop one session's ledger. */
+  dropSession(sessionId) {
+    this.sessions.delete(String(sessionId))
+  }
+
+  /**
+   * Build a detached, read-only evidence view for one session.
+   *
+   * The view is what deterministic claim verification and prompt assembly
+   * consume: plain data plus `has`/`hasUser` search helpers. It never exposes
+   * the live ledger object.
+   *
+   * @param {string} sessionId - session to view.
+   * @returns {object} evidence view.
+   */
+  view(sessionId) {
+    const ledger = this.#session(sessionId, false)
+    if (ledger === undefined) {
+      return {
+        calls: [],
+        users: [],
+        currentTurn: 0,
+        currentStep: 0,
+        has: () => false,
+        hasUser: () => false,
+        callById: () => undefined,
+      }
+    }
+    const calls = ledger.order
+      .map((callId) => ledger.toolCalls.get(callId))
+      .filter((record) => record !== undefined)
+      .map((record) => ({
+        ...detach(record),
+        searchText: normalizeEvidenceText(`${record.name} ${record.argsRaw} ${record.resultText}`),
+      }))
+    const users = ledger.users.map((record) => ({
+      ...detach(record),
+      searchText: normalizeEvidenceText(record.text),
+    }))
+    const has = (needle) => {
+      const query = normalizeEvidenceText(needle)
+      if (query.length < 2) return false
+      return calls.some((call) => call.searchText.includes(query))
+    }
+    const hasUser = (needle) => {
+      const query = normalizeEvidenceText(needle)
+      if (query.length < 2) return false
+      return users.some((user) => user.searchText.includes(query))
+    }
+    return {
+      calls,
+      users,
+      currentTurn: ledger.currentTurn,
+      currentStep: ledger.currentStep,
+      has,
+      hasUser,
+      callById: (callId) => calls.find((call) => call.callId === String(callId)),
+    }
+  }
+
+  /**
+   * Build the bounded evidence digest sent to the auditor. Recent calls and
+   * calls that share a focus term with the current claims are preferred; the
+   * result is chronological and hard-capped.
+   * @param {string} sessionId - session to summarize.
+   * @param {object} [options] - `focus` terms and `maxChars`.
+   * @returns {string} digest text.
+   */
+  digest(sessionId, options = {}) {
+    const view = this.view(sessionId)
+    const maxChars = options.maxChars ?? 16000
+    const focus = (options.focus ?? [])
+      .map((term) => normalizeEvidenceText(term))
+      .filter((term) => term.length >= 3)
+    const selected = new Map()
+    for (let index = view.calls.length - 1; index >= 0 && selected.size < 40; index -= 1) {
+      selected.set(view.calls[index].callId, view.calls[index])
+    }
+    if (focus.length > 0) {
+      for (const call of view.calls) {
+        if (selected.has(call.callId)) continue
+        if (focus.some((term) => call.searchText.includes(term))) selected.set(call.callId, call)
+      }
+    }
+    const ordered = [...selected.values()].sort((left, right) => left.seq - right.seq)
+    const lines = []
+    for (const call of ordered) {
+      lines.push(`[call ${call.callId}] ${call.name} args=${JSON.stringify(call.argsRaw)}`)
+      if (call.resultText.length > 0 || call.isError) {
+        const outcome = call.failed ? 'FAILED' : 'ok'
+        lines.push(`[result ${call.callId}] ${outcome}${call.error?.code ? ` code=${call.error.code}` : ''} output=${JSON.stringify(call.resultText)}`)
+      }
+    }
+    for (const user of view.users.slice(-4)) {
+      lines.push(`[user seq=${user.seq} source=${user.sourceKind}] ${JSON.stringify(user.text)}`)
+    }
+    if (lines.length === 0) return '(evidence ledger empty)'
+    let digest = ''
+    let truncated = false
+    for (const line of lines) {
+      if (digest.length + line.length + 1 > maxChars) {
+        truncated = true
+        break
+      }
+      digest += `${line}\n`
+    }
+    if (truncated) digest += '[evidence digest truncated]\n'
+    return digest.trimEnd()
+  }
+}

package/src/policy.mjs

@@ -0,0 +1,189 @@
+/**
+ * Deterministic gate policy.
+ *
+ * The LLM auditor supplies one more opinion; this module owns escalation. It
+ * converts mechanical findings plus the auditor's structured response into one
+ * frozen `record.level`, then decides actuator actions from that level,
+ * trailing-window hysteresis, configured maximum tier, and the reversibility of
+ * the next action.
+ *
+ * Tiers:
+ * - T0 observe: always on; verdicts are stored, never acted on.
+ * - T1 verify: at `agent/turn-stopping`, steer one neutral re-verification step.
+ * - T2 block: at `tools/pre-execute`, ask/deny an irreversible next action.
+ * - T3 cancel: only when explicitly configured; cancel the active turn.
+ *
+ * Pure module: no dsh imports.
+ *
+ * @module @codebam/dsh-thinking-auditor/policy
+ */
+
+/** Threat-level order used by escalation math. */
+export const LEVEL_RANK = Object.freeze({ none: 0, watch: 1, verify: 2, block: 3 })
+
+/** Status order used by deterministic merge. */
+export const STATUS_RANK = Object.freeze({ supported: 0, speculative: 1, unsupported: 2, contradicted: 3 })
+
+/** Highest threat level. */
+export function maxLevel(left, right) {
+  return (LEVEL_RANK[left] ?? 0) >= (LEVEL_RANK[right] ?? 0) ? left : right
+}
+
+/** Number of trailing history entries at or above one level. */
+export function trailingCount(history, level) {
+  let count = 0
+  for (let index = (history?.length ?? 0) - 1; index >= 0; index -= 1) {
+    if ((LEVEL_RANK[history[index]?.level] ?? 0) < (LEVEL_RANK[level] ?? 0)) break
+    count += 1
+  }
+  return count
+}
+
+/** Normalize an auditor response into a level, treating bad data as no signal. */
+export function auditorLevel(llm) {
+  return LEVEL_RANK[llm?.level] === undefined ? 'none' : llm.level
+}
+
+/** True when the auditor itself reports a high-confidence contradiction. */
+export function auditorConfirmedFabrication(llm) {
+  const claims = Array.isArray(llm?.claims) ? llm.claims : []
+  const contradiction = claims.some((claim) => claim?.status === 'contradicted' && (claim.severity === 'high' || claim.severity === 'medium'))
+  const fabrication = typeof llm?.signals?.fabrication === 'number' ? llm.signals.fabrication : 0
+  return contradiction && fabrication >= 0.5
+}
+
+/**
+ * Merge the mechanical summary and the auditor response into one verdict.
+ *
+ * Mechanical findings are authoritative: the auditor may add claims and raise
+ * concern, but it cannot clear a deterministic contradiction or a missing
+ * tool-call antecedent.
+ *
+ * @param {object} mechanical - output of `summarizeFindings`.
+ * @param {object} llm - normalized auditor response.
+ * @returns {{ level: string, confirmedFabrication: boolean, auditorConfirmed: boolean, reasons: string[] }}
+ */
+export function mergeVerdict(mechanical, llm) {
+  const mechanicalLevel = mechanical?.level ?? 'none'
+  const llmLevel = auditorLevel(llm)
+  const confirmed = mechanical?.confirmedFabrication === true || auditorConfirmedFabrication(llm)
+  const reasons = [...(mechanical?.reasons ?? [])]
+  if (llmLevel !== 'none') reasons.push(`auditor reported ${llmLevel}${llm?.summary ? `: ${llm.summary}` : ''}`)
+  return {
+    level: maxLevel(mechanicalLevel, llmLevel),
+    confirmedFabrication: confirmed,
+    auditorConfirmed: auditorConfirmedFabrication(llm),
+    reasons,
+  }
+}
+
+/**
+ * Decide the turn-boundary action (T1/T3).
+ *
+ * Verify needs `max(1, consecutive - 1)` trailing windows at verify+; block
+ * and cancel need `consecutive`; cancel additionally requires a confirmed
+ * fabrication and an explicit `maxTier: cancel` + `cancelOn: confirmed`.
+ *
+ * @param {object} input - record, history, resolved config, and per-turn flags.
+ * @returns {{ action: 'observe'|'verify'|'cancel', reason: string, tier: number }}
+ */
+export function decideTurnAction({ record, history = [], config, alreadyVerified = false, alreadyCancelled = false }) {
+  const gates = config?.gates ?? {}
+  if (!record) return { action: 'observe', reason: 'no verdict', tier: 0 }
+  const consecutive = Math.max(1, gates.consecutive ?? 1)
+  const verifyRequired = Math.max(1, consecutive - 1)
+  const blockRequired = Math.max(1, consecutive)
+  const cancelRequired = Math.max(blockRequired, 2)
+
+  if (
+    gates.maxTier === 'cancel'
+    && gates.cancelOn === 'confirmed'
+    && record.confirmedFabrication === true
+    && trailingCount(history, 'block') >= cancelRequired
+    && !alreadyCancelled
+  ) {
+    return {
+      action: 'cancel',
+      tier: 3,
+      reason: 'confirmed fabrication survived verification and the turn is about to close',
+    }
+  }
+
+  const verifyEnabled = gates.maxTier === 'verify' || gates.maxTier === 'block' || gates.maxTier === 'cancel'
+  if (
+    verifyEnabled
+    && (LEVEL_RANK[record.level] ?? 0) >= LEVEL_RANK.verify
+    && trailingCount(history, 'verify') >= verifyRequired
+    && !alreadyVerified
+  ) {
+    return {
+      action: 'verify',
+      tier: 1,
+      reason: record.confirmedFabrication
+        ? 'confirmed fabrication is about to close the turn'
+        : 'unsupported claims need a verification step before the turn closes',
+    }
+  }
+  return { action: 'observe', reason: `verdict ${record.level} below the active gate`, tier: 0 }
+}
+
+/**
+ * Decide the pre-execute action (T2) for the next tool call.
+ *
+ * T2 requires `maxTier: block|cancel`, an irreversible next action, a block
+ * verdict, and hysteresis: a confirmed fabrication needs one fewer window than
+ * an unconfirmed block. An in-flight audit at an irreversible boundary can be
+ * gated fail-closed when `askOnTimeoutForIrreversible` is on and no verdict has
+ * arrived.
+ *
+ * @param {object} input - record, history, config, stakes, and audit-pending flag.
+ * @returns {{ action: 'allow'|'ask'|'deny', reason: string, tier: number }}
+ */
+export function decideToolAction({ record, history = [], config, stakes, auditPending = false }) {
+  const gates = config?.gates ?? {}
+  if (gates.blockOn === 'never') {
+    return { action: 'allow', reason: 'T2 disabled by blockOn', tier: 0 }
+  }
+  if (gates.maxTier !== 'block' && gates.maxTier !== 'cancel') {
+    return { action: 'allow', reason: 'T2 disabled by maxTier', tier: 0 }
+  }
+  if (!stakes || stakes.kind !== 'irreversible') {
+    return { action: 'allow', reason: `stakes are ${stakes?.kind ?? 'unknown'}; T2 targets irreversible actions only`, tier: 0 }
+  }
+  if (!record) {
+    if (auditPending && gates.askOnTimeoutForIrreversible === true) {
+      return { action: 'ask', tier: 2, reason: 'no verdict yet for an irreversible action while an audit is in flight' }
+    }
+    return { action: 'allow', reason: 'no verdict yet', tier: 0 }
+  }
+  if ((LEVEL_RANK[record.level] ?? 0) < LEVEL_RANK.block) {
+    // A fresh window is still being audited; an irreversible action should not
+    // race the verdict when the deployment opted into fail-closed handles.
+    if (auditPending && gates.askOnTimeoutForIrreversible === true) {
+      return { action: 'ask', tier: 2, reason: `verdict ${record.level} but a fresh audit is still in flight for an irreversible action` }
+    }
+    return { action: 'allow', reason: `verdict ${record.level} below block`, tier: 0 }
+  }
+  const consecutive = Math.max(1, gates.consecutive ?? 1)
+  const required = record.confirmedFabrication === true ? Math.max(1, consecutive - 1) : consecutive
+  if (trailingCount(history, 'block') < required) {
+    return { action: 'allow', reason: `only ${trailingCount(history, 'block')}/${required} block windows`, tier: 0 }
+  }
+  if (gates.t2Mode === 'deny') {
+    return { action: 'deny', tier: 2, reason: 'blocked by a confirmed untrusted-claims gate' }
+  }
+  return { action: 'ask', tier: 2, reason: 'irreversible action needs approval while claims are unresolved' }
+}
+
+/**
+ * Append one verdict record to a bounded trailing history used for hysteresis.
+ * @param {object[]} history - mutable trailing history.
+ * @param {object} record - the verdict just committed.
+ * @param {number} [cap] - maximum trailing entries.
+ * @returns {object[]} the same array.
+ */
+export function pushHistory(history, record, cap = 12) {
+  history.push({ level: record.level, at: record.at, confirmedFabrication: record.confirmedFabrication, id: record.id })
+  while (history.length > cap) history.shift()
+  return history
+}

package/src/stakes.mjs

@@ -0,0 +1,104 @@
+/**
+ * Reversibility classification for the next tool action.
+ *
+ * T2's whole point is that the right response depends on the next action, not
+ * on certainty about intent: an irreversible action gets gated, a reversible
+ * one continues. This module classifies only the action; it never decides.
+ *
+ * Pure module: no dsh imports.
+ *
+ * @module @codebam/dsh-thinking-auditor/stakes
+ */
+
+const IRREVERSIBLE_COMMAND_PATTERNS = Object.freeze([
+  { re: /\brm\s+-(?:[a-zA-Z]*[rR][a-zA-Z]*[fF]|[a-zA-Z]*[fF][a-zA-Z]*[rR])/, why: 'recursive/forced removal' },
+  { re: /\bgit\s+push\b/, why: 'push to a remote' },
+  { re: /\b(?:npm|pnpm|yarn|bun)\s+(?:publish|unpublish|deprecate)\b/, why: 'package publication' },
+  { re: /\bgh\s+(?:api|pr|release|repo|workflow|gist)\b/, why: 'GitHub mutation' },
+  { re: /\bcurl\b[\s\S]*?(?:-X\s*(?:POST|PUT|PATCH|DELETE)|--request\s+(?:POST|PUT|PATCH|DELETE)|--data(?:-raw|-binary)?\b|-d\s|--upload-file\b|-T\s)/i, why: 'network write' },
+  { re: /\bwget\b[\s\S]*?(?:--post-data|--post-file|--method=POST)/i, why: 'network write' },
+  { re: /\b(?:scp|sftp|rsync)\b/, why: 'remote file transfer' },
+  { re: /\bnixos-rebuild\s+(?:switch|boot|test)\b/, why: 'system generation activation' },
+  { re: /\bhome-manager\s+switch\b/, why: 'user generation activation' },
+  { re: /\bnix\s+profile\s+install\b|\bnix-env\s+-i\b/, why: 'imperative profile write' },
+  { re: /\bsystemctl\s+(?:start|stop|restart|enable|disable|daemon-reload|mask)\b/, why: 'service mutation' },
+  { re: /\b(?:kill|pkill|killall)\b/, why: 'process termination' },
+  { re: /\bmkfs(?:\.\w+)?\b|\bdd\s+(?:if|of)=|\btruncate\b/, why: 'destructive disk operation' },
+  { re: /\bsudo\b|\bdoas\b/, why: 'privilege escalation' },
+  { re: /\bchmod\s+-R\b|\bchown\s+-R\b/, why: 'recursive ownership/permission change' },
+  { re: /(?:^|[^|])(?:>>?|(?:^|\s)tee\s+(?:-a\s+)?)\s*[^\s|>]/, why: 'shell output redirection/write' },
+  { re: /\bgit\s+(?:reset\s+--hard|clean\s+-[a-zA-Z]*f|checkout\s+--\s+\.)\b/, why: 'destructive git operation' },
+  { re: /\b(?:shutdown|reboot|poweroff)\b/, why: 'machine power state' },
+  { re: /\b(?:crontab\s+-r|at\s+now)\b/, why: 'scheduled job mutation' },
+  { re: /\bpython[0-9.]*\s+-(?:c|-e)\b[\s\S]*?(?:requests\.(?:post|put|delete|patch)|urlopen|socket\.)/i, why: 'scripted network write' },
+  { re: /\bnode\s+-(?:e|p)\b[\s\S]*?(?:fetch\(|https?\.request|axios\.(?:post|put|delete))/i, why: 'scripted network write' },
+])
+
+const REVERSIBLE_MUTATION_TOOL_RE = /\b(?:write|write_file|edit|edit_file|str_replace|replace|apply_patch|create|mkdir|touch|save|move|copy|rename|bash|nu|pwsh|shell|exec|run|terminal)\b/i
+
+const READ_ONLY_COMMAND_RE = /^\s*(?:ls|pwd|cat|head|tail|wc|file|stat|find|rg|grep|sed\s+-n|awk|view|open|show|read|git\s+(?:status|log|diff|show|branch|remote\s+-v)|nix\s+(?:eval|build|flake\s+show|path-info|why-depends)|npm\s+(?:ls|view)|node\s+--version|which|type|env|printenv|date|echo)\b/
+
+/** Recursively collect short string arguments from parsed tool arguments. */
+export function collectArgumentStrings(value, depth = 0, out = []) {
+  if (depth > 4 || out.length > 40) return out
+  if (typeof value === 'string') {
+    if (value.length > 0 && value.length <= 8000) out.push(value)
+    return out
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) collectArgumentStrings(item, depth + 1, out)
+    return out
+  }
+  if (value !== null && typeof value === 'object') {
+    for (const [key, nested] of Object.entries(value)) {
+      if (key === 'description' || key === 'justification') continue
+      collectArgumentStrings(nested, depth + 1, out)
+    }
+  }
+  return out
+}
+
+/** True when a string is plausibly a command or shell snippet worth classifying. */
+function looksLikeCommand(value) {
+  const text = String(value ?? '')
+  if (text.trim().length === 0) return false
+  if (/[\s|;&$(){}[\]<>]/.test(text)) return true
+  if (READ_ONLY_COMMAND_RE.test(text)) return true
+  return /^(?:git|npm|pnpm|yarn|nix|docker|podman|curl|wget|ssh|scp|rsync|rm|mv|cp|sed|awk|python|node|bash|sh|nu|pwsh|powershell)\b/.test(text)
+}
+
+/**
+ * Classify one pending tool call.
+ * @param {string} toolName - registry tool name.
+ * @param {unknown} args - parsed arguments (the loop's JSON value).
+ * @returns {{ kind: 'read-only'|'mutating'|'irreversible'|'unknown', reason: string, command?: string }}
+ */
+export function classifyAction(toolName, args) {
+  const name = String(toolName ?? '').toLowerCase()
+  const strings = collectArgumentStrings(args)
+
+  for (const value of strings) {
+    for (const pattern of IRREVERSIBLE_COMMAND_PATTERNS) {
+      if (pattern.re.test(value)) {
+        return { kind: 'irreversible', reason: pattern.why, command: value.slice(0, 800) }
+      }
+    }
+  }
+
+  const commandCandidates = strings.filter(looksLikeCommand)
+  const firstCandidate = commandCandidates[0] ?? strings[0] ?? ''
+  const allReadOnly = commandCandidates.length > 0 && commandCandidates.every((value) => READ_ONLY_COMMAND_RE.test(value))
+
+  // A write/edit tool is mutating even when the payload has no command string;
+  // its explicit view/read mode is the one read-only exception.
+  if (REVERSIBLE_MUTATION_TOOL_RE.test(name)) {
+    if (allReadOnly) return { kind: 'read-only', reason: 'read-only invocation of a mutating tool', command: firstCandidate.slice(0, 800) }
+    return { kind: 'mutating', reason: 'file/system mutation that can be reviewed or reverted', command: firstCandidate.slice(0, 800) }
+  }
+
+  const executor = /^(?:bash|nu|pwsh|powershell|shell|exec|run|process|subprocess|terminal|command|run_code)$/.test(name)
+  if (commandCandidates.length === 0) return { kind: 'unknown', reason: 'no command-like arguments to classify' }
+  if (allReadOnly) return { kind: 'read-only', reason: 'read-only command string', command: firstCandidate.slice(0, 800) }
+  if (executor) return { kind: 'mutating', reason: 'executor command with no irreversible pattern and no read-only proof', command: firstCandidate.slice(0, 800) }
+  return { kind: 'unknown', reason: 'no irreversible pattern matched', command: firstCandidate.slice(0, 800) }
+}