@huaqiu/dsh-log 0.0.0-stage → 1.1.2

package/audit-core.ts

@@ -0,0 +1,1149 @@
+/**
+ * Pure business logic for the dsh-log plugin (v1.1).
+ *
+ * Zero DSH/SDK imports so every rule — masking, truncation, whitelisting,
+ * path-traversal protection, timeout and process-group kill — is unit-testable
+ * on its own. The DSH adapter (`index.ts`) only wires this core to the tool
+ * registry and the audit sinks.
+ *
+ * @module dsh-log/audit-core
+ */
+
+import { execFile, spawn, type ChildProcess } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { readdirSync, statSync } from 'node:fs'
+import path from 'node:path'
+
+/** Sensitive keywords for recursive log masking (spec §3). */
+export const SENSITIVE_KEYWORDS = ['token', 'secret', 'password', 'ak', 'sk', 'accessKey', 'apiKey'] as const
+
+/**
+ * Fold a key/parameter name to its comparison form: lowercased with separators
+ * removed. Exists because a separator must not be able to HIDE a credential —
+ * `api_key`, `api-key`, `x-api-key` and `apiKey` are the same parameter, but a
+ * raw `includes()` on the lowercase name misses three of those four.
+ */
+function foldKeyName(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9]/g, '')
+}
+
+/**
+ * True when a key or query-parameter NAME names a credential (spec §3).
+ * Matches case-insensitively and across separators (`_`, `-`, `.`).
+ * @param keyName - object key or URL query parameter name.
+ * @returns whether the value under this name must be masked.
+ */
+export function isSensitiveName(keyName: string): boolean {
+  const folded = foldKeyName(keyName)
+  return SENSITIVE_KEYWORDS.some(keyword => folded.includes(foldKeyName(keyword)))
+}
+
+/** Unified error classification (spec §6). */
+export const ERROR_TYPES = {
+  TIMEOUT: 'TIMEOUT',
+  NETWORK_ERROR: 'NETWORK_ERROR',
+  PERMISSION_DENIED: 'PERMISSION_DENIED',
+  SCRIPT_EXIT_ERROR: 'SCRIPT_EXIT_ERROR',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+} as const
+
+/** One member of the unified errorType enum. */
+export type ErrorType = (typeof ERROR_TYPES)[keyof typeof ERROR_TYPES]
+
+/** Log level of one audit record (spec §3: INFO / ERROR). */
+export type AuditLevel = 'INFO' | 'ERROR'
+
+/**
+ * Lifecycle phase an audit record reports (spec §4's start / finished / error
+ * event types). Carried explicitly so a log reader never has to infer the phase
+ * from which fields happen to be present — the trajectory channel only ever
+ * holds the terminal record, this channel is the only place the full lifecycle
+ * is observable.
+ */
+export type AuditPhase = 'start' | 'finished' | 'error'
+
+/**
+ * A losslessly JSON-serializable log segment. Structurally identical to DSH's
+ * `JsonValue` (kept local so this core module stays SDK-free); the adapter
+ * relies on that compatibility when embedding records in tool results.
+ */
+export type AuditJsonValue = null | boolean | number | string | AuditJsonValue[] | { [key: string]: AuditJsonValue }
+
+/** Audit record schema version — lets log consumers handle plugin upgrades compatibly. */
+export const SCHEMA_VERSION = '1.0'
+
+/**
+ * Unified audit log record (spec §3 data model, v1.0 mandatory fields).
+ * `level` is carried explicitly so every sink can route without re-deriving it.
+ * Declared as a TYPE ALIAS (not an interface) so it carries the implicit
+ * index signature required by DSH's JSON-value output schemas.
+ */
+export type AuditRecord = {
+  /** DSH session id — top-level correlation key ('standalone' when no agent session owns the call). */
+  sessionId: string
+  /** Unique id of this tool invocation — a generated UUID v4 per spec §3. */
+  callId: string
+  /** The platform's own call identifier (DSH exec.callId) when one exists, for joining with tool/call|tool/result events. */
+  dshCallId?: string
+  /** Schema version of this record shape (log consumers use it for compatibility). */
+  schemaVersion: string
+  /** Tool name: `call_external_api` | `run_external_script`. */
+  tool: string
+  level: AuditLevel
+  /**
+   * 1-based index of this record within the invocation (1 = start, 2 = terminal).
+   * Makes a LOST record detectable: a call whose records are not `1, 2` lost one,
+   * which is exactly the failure mode a single-record channel (the trajectory)
+   * cannot observe. Absent on records written by plugin versions < 1.0.1.
+   */
+  seq?: number
+  /**
+   * Which lifecycle phase this record reports. Absent on records written by
+   * plugin versions < 1.0.1 (readers fall back to field-presence inference).
+   */
+  phase?: AuditPhase
+  /** Masked + truncated request parameters (JSON-serializable by construction); absent on records written before the request is known. */
+  request?: AuditJsonValue
+  /** Truncated response summary (JSON-serializable by construction); may be omitted on ERROR records. */
+  response?: AuditJsonValue
+  /** Execution cost in milliseconds. */
+  costMs: number
+  /** API: HTTP status code. Script: process exit code. Absent when no process/HTTP exchange completed. */
+  code?: number
+  /** Error classification; present only on ERROR records. */
+  errorType?: ErrorType
+  /** Exception detail; present only on ERROR records. */
+  error?: string
+}
+
+/** Plain-object guard for recursive masking (arrays handled separately). */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false
+  const proto = Object.getPrototypeOf(value)
+  return proto === Object.prototype || proto === null
+}
+
+/**
+ * Recursively replace values whose KEY contains any sensitive keyword with `***`
+ * (case-insensitive substring match, spec §3). Traverses plain objects and
+ * arrays at any depth. Returns a NEW structure — the input is never mutated,
+ * so masking only ever touches log copies, never the live request parameters.
+ *
+ * STRING values containing a URL additionally go through `maskUrlsInText`, so a
+ * credential is caught wherever it hides: a secret carried in `?token=…`, in
+ * userinfo, or echoed back inside a response body ("your request to
+ * `https://x/y?token=…` failed") is masked even though no KEY names it.
+ *
+ * Cyclic references are replaced by the `'[Circular]'` marker instead of
+ * overflowing the stack (defensive: DSH arguments normally cross a lossless-
+ * JSON boundary first, but the log pipeline must never crash on odd input).
+ * Keys whose value is `undefined` are dropped entirely — undefined is not
+ * JSON-serializable and would fail DSH's lossless-JSON result validation.
+ * @param obj - value to mask; may be any JSON-compatible value.
+ * @returns masked copy (primitives pass through unchanged).
+ */
+export function maskSensitive(obj: unknown, seen = new WeakSet<object>()): unknown {
+  if (Array.isArray(obj)) {
+    if (seen.has(obj)) return '[Circular]'
+    seen.add(obj)
+    const out = obj.map(item => maskSensitive(item, seen))
+    seen.delete(obj)
+    return out
+  }
+  if (isPlainObject(obj)) {
+    if (seen.has(obj)) return '[Circular]'
+    seen.add(obj)
+    const out: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(obj)) {
+      if (value === undefined) continue // not JSON-serializable: drop the key (lossless-JSON boundary)
+      const sensitive = isSensitiveName(key)
+      out[key] = sensitive ? '***' : maskSensitive(value, seen)
+    }
+    seen.delete(obj)
+    return out
+  }
+  if (typeof obj === 'string' && (obj.includes('?') || obj.includes('://'))) return maskUrlsInText(obj)
+  return obj
+}
+
+/**
+ * UUID v4 call id (spec §3: callId is a per-invocation UUID). Prefers the
+ * platform generator; falls back to a manual v4 over crypto bytes.
+ * @returns a uuid v4 string.
+ */
+export function generateCallId(): string {
+  try {
+    return randomUUID()
+  } catch {
+    const bytes = new Uint8Array(16)
+    for (let i = 0; i < 16; i += 1) bytes[i] = Math.floor(Math.random() * 256)
+    bytes[6] = (bytes[6] & 0x0f) | 0x40
+    bytes[8] = (bytes[8] & 0x3f) | 0x80
+    const hex = [...bytes].map(b => b.toString(16).padStart(2, '0')).join('')
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`
+  }
+}
+
+/**
+ * Byte-bounded string truncation (spec §3: limits are BYTES). Cuts on a UTF-8
+ * character boundary and appends the `[TRUNCATED]` marker when the input
+ * exceeds `maxBytes`.
+ * @param str - original string.
+ * @param maxBytes - maximum allowed byte length of the kept prefix.
+ * @returns the original string, or `<prefix>[TRUNCATED]`.
+ */
+export function truncateString(str: string, maxBytes: number): string {
+  if (maxBytes <= 0) return ''
+  const buf = Buffer.from(str, 'utf8')
+  if (buf.byteLength <= maxBytes) return str
+  let end = maxBytes
+  // Back off over UTF-8 continuation bytes so we never split a code point.
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end -= 1
+  return `${buf.subarray(0, end).toString('utf8')}[TRUNCATED]`
+}
+
+/**
+ * Truncate one log segment of arbitrary JSON value to a byte budget: values
+ * that already fit are returned untouched (still structured); oversized values
+ * become the truncated serialized string with the `[TRUNCATED]` marker.
+ * @param value - the segment to bound (request, response, script output).
+ * @param maxBytes - byte budget from plugin config.
+ * @returns the original value or a truncated string.
+ */
+export function truncateJson(value: unknown, maxBytes: number): unknown {
+  if (value === undefined) return undefined
+  let text: string
+  try {
+    text = JSON.stringify(value)
+  } catch {
+    text = String(value)
+  }
+  if (text === undefined) text = 'undefined'
+  if (Buffer.byteLength(text, 'utf8') <= maxBytes) return value
+  return truncateString(text, maxBytes)
+}
+
+/** Default ceiling for a per-call timeout override: 2 minutes. */
+export const DEFAULT_MAX_TIMEOUT_MS = 120_000
+
+/**
+ * Resolve the timeout budget of ONE invocation: prefer the caller's per-call
+ * `timeoutMs`, otherwise the configured `defaultTimeoutMs`, and never exceed
+ * `maxTimeoutMs`.
+ *
+ * Clamping (rather than refusing) is deliberate: a model that asks for an
+ * hour-long call still gets a bounded, useful call, and the audit record's
+ * `request.timeoutMs` shows the value that was actually applied — so nothing
+ * is hidden, but the plugin can never be parked forever (spec §5.4).
+ * @param requested - caller-supplied override; anything that is not a positive finite number is ignored.
+ * @param defaultMs - configured `defaultTimeoutMs`.
+ * @param maxMs - configured `maxTimeoutMs` ceiling.
+ * @returns the effective budget in whole milliseconds, always >= 1.
+ */
+export function resolveTimeoutMs(requested: unknown, defaultMs: number, maxMs: number = DEFAULT_MAX_TIMEOUT_MS): number {
+  const ceiling = Number.isFinite(maxMs) && maxMs >= 1 ? Math.floor(maxMs) : DEFAULT_MAX_TIMEOUT_MS
+  const configured = Number.isFinite(defaultMs) && defaultMs >= 1 ? Math.floor(defaultMs) : 30_000
+  const fallback = Math.min(configured, ceiling)
+  if (typeof requested !== 'number' || !Number.isFinite(requested) || requested <= 0) return fallback
+  return Math.max(1, Math.min(Math.floor(requested), ceiling))
+}
+
+/** Dummy base used to parse a RELATIVE reference (`/p?token=…`) so it can be masked too. */
+const RELATIVE_BASE = 'http://relative.invalid'
+
+/**
+ * Replace credential-bearing parts of an already-parsed URL in place.
+ * @param parsed - the parsed URL to redact.
+ * @returns whether anything was replaced.
+ */
+function redactParsedUrl(parsed: URL): boolean {
+  let touched = false
+  for (const key of [...parsed.searchParams.keys()]) {
+    if (isSensitiveName(key)) {
+      parsed.searchParams.set(key, '***')
+      touched = true
+    }
+  }
+  if (parsed.username !== '' || parsed.password !== '') {
+    parsed.username = '***'
+    parsed.password = '***'
+    touched = true
+  }
+  return touched
+}
+
+/**
+ * Mask credentials that hide inside a URL *string*. `maskSensitive` matches on
+ * object KEYS, so a secret smuggled in `?token=…` or in the userinfo part of a
+ * URL would otherwise sail straight into the log (spec §5.3: logs must never
+ * store credentials in plaintext). Query names are matched with the same
+ * keyword list as object keys, case-insensitively.
+ *
+ * Handles BOTH absolute URLs and bare relative references, because an API
+ * commonly echoes the failing request back as a path (`/v1/x?token=…`).
+ *
+ * Best effort: a string that is neither is returned unchanged (the whitelist
+ * gate rejects unparsable absolute URLs before any I/O anyway).
+ * @param url - the URL exactly as the caller supplied it, absolutely or relatively.
+ * @returns the URL with sensitive query values and any userinfo replaced by `***`,
+ *          or the input unchanged when nothing sensitive was found.
+ */
+export function maskUrlQuery(url: string): string {
+  if (typeof url !== 'string' || url === '') return url
+  try {
+    const parsed = new URL(url)
+    return redactParsedUrl(parsed) ? parsed.toString() : url
+  } catch {
+    // Not an absolute URL. Only a PATH-relative reference (`/p?token=…`) is worth
+    // re-parsing: prose that merely CONTAINS a URL is handled by `maskUrlsInText`,
+    // and re-parsing prose as a relative path would percent-encode and mangle it.
+    if (!url.includes('?') || !/^[./]/.test(url)) return url
+    try {
+      const parsed = new URL(url, RELATIVE_BASE)
+      if (!redactParsedUrl(parsed)) return url
+      return `${parsed.pathname}${parsed.search}${parsed.hash}`
+    } catch {
+      return url
+    }
+  }
+}
+
+/**
+ * A URL embedded in free text — either an absolute `http(s)://…` (with or
+ * without a query string) or a `/path?query` reference. Stops at whitespace,
+ * quotes, brackets and CSV punctuation so surrounding prose is left alone.
+ */
+const URL_IN_TEXT = /(?:https?:\/\/|\/)[^\s"'`<>()[\]{},;]*\?[^\s"'`<>()[\]{},;]*|https?:\/\/[^\s"'`<>()[\]{},;]+/g
+
+/**
+ * Mask credentials in a string that CONTAINS a URL (possibly inside prose), not
+ * just a bare URL. This is the everyday case on the response side: an API that
+ * reports failure usually quotes the offending request back —
+ * `request to https://api.example.com/v1?token=… failed`, or a bare
+ * `/v1/resource?token=…` — which carries no sensitive KEY at all, so key-based
+ * masking cannot see it (spec §5.3).
+ * @param text - arbitrary log-bound string.
+ * @returns the string with every embedded URL's credentials masked.
+ */
+export function maskUrlsInText(text: string): string {
+  if (typeof text !== 'string' || text === '' || (!text.includes('?') && !text.includes('://'))) return text
+  const whole = maskUrlQuery(text)
+  if (whole !== text) return whole // the entire string was a URL/reference and something got masked
+  return text.replace(URL_IN_TEXT, match => maskUrlQuery(match))
+}
+
+/**
+ * Mask credentials in a free-text log FIELD (an error message, a stderr line).
+ * This is the safety net for text the plugin does NOT author: `fetch` failure
+ * messages and internal-exception messages routinely quote the offending URL —
+ * `request to https://api.example.com/v1?token=… failed` — and key-based masking
+ * is blind to them because there is no key to match (spec §5.3).
+ * Total function: accepts anything, always yields a string, never throws, so it
+ * can wrap every value on its way into an audit record.
+ * @param text - value bound for a log field; coerced to string when not one.
+ * @returns the masked string.
+ */
+export function maskTextForLog(text: unknown): string {
+  const value = typeof text === 'string' ? text : String(text)
+  try {
+    return maskUrlsInText(value)
+  } catch {
+    // Unreachable in practice (maskUrlsInText swallows its own parse failures).
+    // Defence in depth: strip anything query- or userinfo-shaped rather than
+    // ever letting a raw credential reach the log.
+    return value.replace(/\?[^\s]*/g, '?***').replace(/\/\/[^/@\s]*@/g, '//***@')
+  }
+}
+
+/**
+ * Merge caller-supplied query parameters into the request URL using the URL
+ * parser's own encoder — never string concatenation — so a value containing
+ * `&`, `=`, `#` or spaces cannot corrupt the request or smuggle extra
+ * parameters. Existing parameters are preserved; a name present in both the
+ * URL and `query` is overridden by `query`.
+ * @param url - base URL (callers gate this with `checkApiUrl` first, so it parses).
+ * @param query - normalized string map of extra parameters.
+ * @returns the effective request URL.
+ * @throws when `url` does not parse — unreachable for the gated call path.
+ */
+export function buildRequestUrl(url: string, query?: Record<string, string>): string {
+  if (query === undefined) return url
+  const entries = Object.entries(query).filter(([, value]) => value !== undefined && value !== null)
+  if (entries.length === 0) return url
+  const parsed = new URL(url)
+  for (const [key, value] of entries) parsed.searchParams.set(key, value)
+  return parsed.toString()
+}
+
+/** Result of the API host-whitelist gate (spec §4.1/§5.1 — SSRF protection). */
+export type UrlGate = { ok: true; host: string } | { ok: false; reason: string }
+
+/**
+ * Validate a request URL against the configured host whitelist: only http/https
+ * schemes are accepted and the host must EXACTLY match (case-insensitive) one
+ * of `allowHosts`. Anything else is refused before any network I/O happens.
+ * @param url - candidate request URL.
+ * @param allowHosts - configured `api_allow_hosts` entries.
+ * @returns gate verdict with a human-readable refusal reason.
+ */
+export function checkApiUrl(url: string, allowHosts: readonly string[]): UrlGate {
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch {
+    return { ok: false, reason: `invalid url: ${JSON.stringify(url)}` }
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return { ok: false, reason: `scheme "${parsed.protocol}" not allowed (only http/https)` }
+  }
+  const host = parsed.hostname.toLowerCase()
+  const allowed = allowHosts.map(entry => entry.trim().toLowerCase()).filter(entry => entry !== '')
+  if (!allowed.includes(host)) {
+    return { ok: false, reason: `host "${host}" not in api_allow_hosts whitelist (${allowed.join(', ') || 'empty'})` }
+  }
+  return { ok: true, host }
+}
+
+/**
+ * Why an `api_allow_hosts` entry deserves a second look before it is ever used.
+ * `loopback` is the ordinary local-verification case; the rest are the ones that
+ * turn "call an API" into "reach the intranet or the cloud metadata service".
+ */
+export type HostRiskTier = 'metadata' | 'link-local' | 'private' | 'loopback'
+
+/** One flagged whitelist entry. */
+export interface HostRisk {
+  /** Normalised host exactly as it appears in `api_allow_hosts`. */
+  host: string
+  tier: HostRiskTier
+  /** Why this address space is a risk, in one line. */
+  reason: string
+}
+
+/**
+ * Severity per tier. Link-local/metadata (cloud instance credentials) and
+ * RFC1918/ULA/private-name targets (intranet services) are worth a warning;
+ * loopback is expected during local verification and gets an informational note.
+ */
+export const HOST_RISK_SEVERITY: Record<HostRiskTier, 'WARN' | 'INFO'> = {
+  metadata: 'WARN',
+  'link-local': 'WARN',
+  private: 'WARN',
+  loopback: 'INFO',
+}
+
+/**
+ * Cloud metadata endpoints reachable by NAME. Azure/AWS/OCI answer on the IP literal
+ * handled above; these are the aliases images and SDKs resolve for you.
+ */
+const METADATA_HOSTS = new Set([
+  'metadata',
+  'metadata.google.internal',
+  'metadata.goog',
+  'instance-data',
+  'instance-data.ec2.internal',
+])
+
+/** Suffixes reserved for private use (RFC 6761 `.local`, RFC 8375 `.home.arpa`, ICANN `.internal`). */
+const PRIVATE_NAME_SUFFIXES = ['.internal', '.local', '.home.arpa', '.lan', '.corp', '.intranet']
+
+/**
+ * Parse a dotted-quad IPv4 literal. Returns null for anything that is not exactly
+ * four 0-255 octets, so `999.1.1.1` and `1.2.3` stay "names" rather than becoming
+ * half-classified addresses.
+ */
+function parseIpv4(host: string): number[] | null {
+  const parts = host.split('.')
+  if (parts.length !== 4) return null
+  const octets: number[] = []
+  for (const part of parts) {
+    if (!/^\d{1,3}$/.test(part)) return null
+    const value = Number(part)
+    if (value > 255) return null
+    octets.push(value)
+  }
+  return octets
+}
+
+/**
+ * Classify an IPv4 literal against the special-purpose registries. Matching is done
+ * on OCTETS, never on the host string, so an IPv4-mapped IPv6 form
+ * (`::ffff:169.254.169.254`) is recognised as the same target.
+ * @param octets - four 0-255 values.
+ * @param host - the whitelist entry this address came from (label only).
+ */
+function classifyIpv4(octets: number[], host: string): HostRisk | null {
+  const [a, b, c, d] = octets
+  if (a === 169 && b === 254) {
+    if ((c === 169 && d === 254) || (c === 170 && d === 2)) {
+      return { host, tier: 'metadata', reason: 'cloud instance metadata endpoint (IMDS) — reachable instance credentials' }
+    }
+    return { host, tier: 'link-local', reason: 'link-local address (169.254.0.0/16)' }
+  }
+  if (a === 0 && b === 0 && c === 0 && d === 0) {
+    return { host, tier: 'loopback', reason: 'wildcard address (0.0.0.0) — names every local interface' }
+  }
+  if (a === 127) return { host, tier: 'loopback', reason: 'loopback address (127.0.0.0/8)' }
+  if (a === 10) return { host, tier: 'private', reason: 'private range (10.0.0.0/8)' }
+  if (a === 172 && b >= 16 && b <= 31) return { host, tier: 'private', reason: 'private range (172.16.0.0/12)' }
+  if (a === 192 && b === 168) return { host, tier: 'private', reason: 'private range (192.168.0.0/16)' }
+  if (a === 100 && b >= 64 && b <= 127) return { host, tier: 'private', reason: 'carrier-grade NAT range (100.64.0.0/10)' }
+  return null
+}
+
+/** Classify an IPv6 literal (zone id and IPv4-mapped forms included). */
+function classifyIpv6(address: string, host: string): HostRisk | null {
+  const addr = address.split('%')[0]
+  if (addr === '::' || addr === '::1') return { host, tier: 'loopback', reason: 'IPv6 unspecified/loopback address' }
+  if (addr.startsWith('::ffff:')) {
+    // IPv4-mapped (::ffff:10.0.0.1) reaches the same place as the v4 address it wraps.
+    const mapped = parseIpv4(addr.slice('::ffff:'.length))
+    return mapped === null ? null : classifyIpv4(mapped, host)
+  }
+  if (addr.startsWith('fd00:ec2::')) return { host, tier: 'metadata', reason: 'cloud instance metadata endpoint (IPv6 IMDS)' }
+  if (/^fe[89ab]/.test(addr)) return { host, tier: 'link-local', reason: 'IPv6 link-local address (fe80::/10)' }
+  if (addr.startsWith('fc') || addr.startsWith('fd')) return { host, tier: 'private', reason: 'IPv6 unique-local address (fc00::/7)' }
+  return null
+}
+
+/**
+ * Static classification of a whitelist entry (spec §5.1 hardening).
+ *
+ * Answering "is this host safe to whitelist?" needs no DNS: the dangerous targets
+ * are recognisable *lexically* — special-purpose IP literals and private-use name
+ * suffixes. A public-looking name that RESOLVES to a private address cannot be
+ * caught here (that would need a lookup at gate time), which is exactly why the
+ * gate itself stays a pure string comparison and this is a boot-time advisory.
+ *
+ * @param hostInput - one `api_allow_hosts` entry, with or without IPv6 brackets.
+ * @returns the risk finding, or null when the entry looks ordinary.
+ */
+export function classifyHost(hostInput: string): HostRisk | null {
+  // `label` is what the finding reports back (the entry as configured, so the operator
+  // can grep their own yml); `host` is the matching form with IPv6 brackets removed.
+  const label = hostInput.trim().toLowerCase()
+  const host = label.replace(/^\[/, '').replace(/\]$/, '')
+  if (host === '') return null
+  const ipv4 = parseIpv4(host)
+  if (ipv4 !== null) return classifyIpv4(ipv4, label)
+  if (host.includes(':')) {
+    const ipv6 = classifyIpv6(host, label)
+    if (ipv6 !== null) return ipv6
+  }
+  if (METADATA_HOSTS.has(host)) {
+    return { host: label, tier: 'metadata', reason: 'well-known cloud instance metadata hostname' }
+  }
+  if (host === 'localhost' || host.endsWith('.localhost')) {
+    return { host: label, tier: 'loopback', reason: 'loopback hostname' }
+  }
+  if (PRIVATE_NAME_SUFFIXES.some(suffix => host.endsWith(suffix))) {
+    return { host: label, tier: 'private', reason: 'private-use name suffix — resolves inside the local network' }
+  }
+  // No public DNS name is dotless, so a single label necessarily resolves through the
+  // local search domain or hosts file. The `:` guard keeps address literals out of this
+  // rule: a global IPv6 literal has no dot either and is emphatically not "local".
+  if (!host.includes('.') && !host.includes(':')) {
+    return { host: label, tier: 'private', reason: 'single-label hostname — resolves locally, never on the public internet' }
+  }
+  return null
+}
+
+/**
+ * Classify every whitelist entry, preserving config order and collapsing duplicates.
+ * @param allowHosts - configured `api_allow_hosts` entries.
+ * @returns findings for the entries that are not ordinary public hostnames.
+ */
+export function inspectAllowHosts(allowHosts: readonly string[]): HostRisk[] {
+  const seen = new Set<string>()
+  const risks: HostRisk[] = []
+  for (const entry of allowHosts) {
+    const risk = classifyHost(entry)
+    if (risk === null || seen.has(risk.host)) continue
+    seen.add(risk.host)
+    risks.push(risk)
+  }
+  return risks
+}
+
+/** Hostname of a URL, or null when it does not parse. Used for per-call risk tagging. */
+export function hostOfUrl(url: string): string | null {
+  try {
+    return new URL(url).hostname.toLowerCase()
+  } catch {
+    return null
+  }
+}
+
+/** HTTP methods the tool accepts (spec §4.1's four plus PATCH/HEAD). */
+export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD'] as const
+
+/** One accepted HTTP method. */
+export type HttpMethod = (typeof HTTP_METHODS)[number]
+
+/** Methods that can carry a request body. */
+const METHODS_WITH_BODY: ReadonlySet<string> = new Set(['POST', 'PUT', 'PATCH', 'DELETE'])
+
+/** Parameters for one whitelisted HTTP call (spec §4.1). */
+export interface ApiCallParams {
+  url: string
+  method?: HttpMethod
+  headers?: Record<string, string>
+  /** Extra query parameters merged into the URL with proper percent-encoding. */
+  query?: Record<string, string>
+  /**
+   * Request body. An object/array is serialized as JSON; a STRING is sent
+   * verbatim (so `application/x-www-form-urlencoded` and plain-text payloads
+   * work without double-encoding). Omitted entirely when undefined.
+   */
+  body?: unknown
+  /** Per-call timeout override; clamped to [1, maxTimeoutMs] by `resolveTimeoutMs`. */
+  timeoutMs?: number
+}
+
+/** Plugin config slice consumed by the API tool. */
+export interface ApiConfig {
+  apiAllowHosts: readonly string[]
+  defaultTimeoutMs: number
+  /** Upper bound for a per-call `timeoutMs` override; undefined → DEFAULT_MAX_TIMEOUT_MS. */
+  maxTimeoutMs?: number
+  /** Max response BODY bytes to buffer (memory protection); undefined → DEFAULT_MAX_RESPONSE_BYTES. */
+  maxResponseBytes?: number
+  /** Max request BODY bytes to serialize and send; undefined → DEFAULT_MAX_REQUEST_BYTES. */
+  maxRequestBytes?: number
+}
+
+/** Default response-body memory cap: 10 MiB (spec §5 hardening, P0). */
+export const DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024
+
+/**
+ * Default request-body cap: 1 MiB. The counterpart of `maxResponseBytes` — the
+ * response side is bounded because a hostile endpoint controls it, the request
+ * side because the MODEL controls it. Without a bound, an oversized body is
+ * fully serialized in memory and then pushed onto the wire before anything can
+ * object. Checked before any I/O, so an oversized request costs nothing.
+ */
+export const DEFAULT_MAX_REQUEST_BYTES = 1024 * 1024
+
+/** Byte budget for the response-header summary returned to the caller: 8 KiB. */
+export const MAX_RESPONSE_HEADER_BYTES = 8 * 1024
+
+/**
+ * Response headers whose VALUE is always replaced by `[REDACTED]` before the
+ * header map is logged or handed back. `set-cookie` carries a live session
+ * credential that outlives this single call — unlike the request headers (which
+ * the caller supplied and already knows), it is pure leak with no upside: this
+ * tool has no cookie jar, so the caller cannot use it anyway.
+ */
+const REDACTED_RESPONSE_HEADERS: ReadonlySet<string> = new Set(['set-cookie', 'set-cookie2'])
+
+/** Placeholder written in place of a redacted response-header value. */
+export const REDACTED_HEADER_VALUE = '[REDACTED]'
+
+/** Outcome of one API call — transport-level; non-2xx responses are still `ok` (spec §6 has no HTTP_ERROR class). */
+export interface ApiCallResult {
+  ok: boolean
+  status?: number
+  /** Response headers summary (byte-bounded); present when an HTTP response was received at all. */
+  headers?: Record<string, string>
+  /** Parsed response body (JSON when possible, raw text otherwise) — JSON-serializable by construction. */
+  data?: AuditJsonValue
+  errorType?: ErrorType
+  error?: string
+}
+
+/**
+ * Collect response headers under a byte budget, so an endpoint that answers
+ * with an enormous header set cannot inflate the tool result (and therefore
+ * the session stream) without limit. The last header that would overflow is
+ * truncated rather than dropped, so its name is still visible.
+ *
+ * Values of `set-cookie`/`set-cookie2` are replaced by `[REDACTED]` here, at the
+ * source — so the credential never reaches EITHER consumer (the audit log AND
+ * the result handed to the model). Doing it here rather than at each sink keeps
+ * the two from drifting apart (spec §5.3).
+ * @param resp - the received response.
+ * @returns a plain string map, at most MAX_RESPONSE_HEADER_BYTES of values.
+ */
+function collectResponseHeaders(resp: Response): Record<string, string> {
+  const out: Record<string, string> = {}
+  let budget = MAX_RESPONSE_HEADER_BYTES
+  resp.headers.forEach((value, key) => {
+    if (budget <= 0) return
+    // Redact BEFORE measuring, so the budget reflects what actually ships.
+    const safeValue = REDACTED_RESPONSE_HEADERS.has(key.toLowerCase()) ? REDACTED_HEADER_VALUE : value
+    const cost = Buffer.byteLength(key, 'utf8') + Buffer.byteLength(safeValue, 'utf8')
+    if (cost > budget) {
+      out[key] = truncateString(safeValue, budget)
+      budget = 0
+      return
+    }
+    budget -= cost
+    out[key] = safeValue
+  })
+  return out
+}
+
+/**
+ * Perform the whitelisted HTTP request with AbortController timeout control
+ * (spec §4.1). Never throws: every failure path resolves to a classified
+ * result so the adapter can always emit an audit record.
+ * @param params - url/method/headers/body of the call.
+ * @param cfg - whitelist + timeout budget from plugin config.
+ * @param externalSignal - optional caller cancellation (DSH exec.signal).
+ * @returns classified outcome with status/data or errorType/error.
+ */
+export async function callExternalApi(
+  params: ApiCallParams,
+  cfg: ApiConfig,
+  externalSignal?: AbortSignal,
+): Promise<ApiCallResult> {
+  const gate = checkApiUrl(params.url, cfg.apiAllowHosts)
+  if (!gate.ok) return { ok: false, errorType: ERROR_TYPES.PERMISSION_DENIED, error: gate.reason }
+
+  const method = (params.method ?? 'GET').toUpperCase()
+  const timeoutMs = resolveTimeoutMs(params.timeoutMs, cfg.defaultTimeoutMs, cfg.maxTimeoutMs)
+  // Query params are merged with the URL parser's encoder, AFTER the whitelist gate
+  // (which only looks at the origin, so merging first would be harmless too — but
+  // gating first keeps "refused before any I/O" literally true).
+  let target: string
+  try {
+    target = buildRequestUrl(params.url, params.query)
+  } catch (err) {
+    return { ok: false, errorType: ERROR_TYPES.PERMISSION_DENIED, error: `invalid url: ${err instanceof Error ? err.message : String(err)}` }
+  }
+
+  const controller = new AbortController()
+  let timedOut = false
+  const timer = setTimeout(() => {
+    timedOut = true
+    controller.abort(new Error(`request timed out after ${timeoutMs}ms`))
+  }, timeoutMs)
+  if (externalSignal !== undefined) {
+    if (externalSignal.aborted) controller.abort(new Error('aborted by caller'))
+    else externalSignal.addEventListener('abort', () => controller.abort(new Error('aborted by caller')), { once: true })
+  }
+
+  // A string body is sent verbatim (form-urlencoded / plain text); anything else is
+  // JSON-serialized. No body at all for GET/HEAD, or when the caller passed none.
+  const hasBody = METHODS_WITH_BODY.has(method) && params.body !== undefined
+
+  // Inside the try so the finally clause still clears the timeout timer on the
+  // early return below (an already-armed timer must never outlive the call).
+  try {
+    // Serialize ONCE so the size gate and the actual send can never disagree
+    // about what the body is.
+    let bodyText: string | undefined
+    if (hasBody) {
+      bodyText = typeof params.body === 'string' ? params.body : JSON.stringify(params.body)
+      if (bodyText !== undefined) {
+        // Symmetric to the response cap: bounded BEFORE any I/O, so an oversized
+        // body is never serialized onto the wire (memory + egress protection).
+        const limit = cfg.maxRequestBytes ?? DEFAULT_MAX_REQUEST_BYTES
+        const size = Buffer.byteLength(bodyText, 'utf8')
+        if (size > limit) {
+          return { ok: false, errorType: ERROR_TYPES.PERMISSION_DENIED, error: `request body is ${size} bytes, over maxRequestBytes (${limit}) — refused before any I/O` }
+        }
+      }
+    }
+
+    const resp = await fetch(target, {
+      method,
+      headers: params.headers,
+      ...(bodyText !== undefined ? { body: bodyText } : {}),
+      signal: controller.signal,
+      // P0 hardening: NEVER follow redirects. fetch's default redirect-following would let a
+      // whitelisted host 302-jump to an internal address and bypass the SSRF gate (only the
+      // INITIAL url is validated). A 3xx response is reported as-is (like any non-2xx) and
+      // its body is cancelled so no second request can happen.
+      redirect: 'manual',
+    })
+    const headers = collectResponseHeaders(resp)
+    if (resp.status >= 300 && resp.status < 400) {
+      void resp.body?.cancel().catch(() => {})
+      // Headers are kept: `location` is how a caller sees WHERE it was asked to go
+      // (without the plugin ever following it).
+      return { ok: true, status: resp.status, headers }
+    }
+    // P0 hardening: stream the body with a byte cap instead of buffering it whole —
+    // a malicious/faulty endpoint returning a huge body must not be able to OOM us.
+    const limit = cfg.maxResponseBytes ?? DEFAULT_MAX_RESPONSE_BYTES
+    let text = ''
+    let bytes = 0
+    if (resp.body) {
+      const reader = resp.body.getReader()
+      const decoder = new TextDecoder('utf-8')
+      for (;;) {
+        const { done, value } = await reader.read()
+        if (done) break
+        bytes += value.byteLength
+        if (bytes > limit) {
+          await reader.cancel().catch(() => {})
+          return { ok: false, errorType: ERROR_TYPES.NETWORK_ERROR, error: `response body exceeded ${limit} bytes and was aborted (memory protection)` }
+        }
+        text += decoder.decode(value, { stream: true })
+      }
+      text += decoder.decode()
+    }
+    let data: AuditJsonValue = text
+    try {
+      data = JSON.parse(text) as AuditJsonValue
+    } catch {
+      // Non-JSON payload: keep the raw text as the response summary.
+    }
+    return { ok: true, status: resp.status, headers, data }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err)
+    if (timedOut) return { ok: false, errorType: ERROR_TYPES.TIMEOUT, error: `request timed out after ${timeoutMs}ms` }
+    if (externalSignal?.aborted === true) {
+      return { ok: false, errorType: ERROR_TYPES.INTERNAL_ERROR, error: 'call aborted by caller (USER_CANCEL tracking lands in v1.3)' }
+    }
+    return { ok: false, errorType: ERROR_TYPES.NETWORK_ERROR, error: `network failure: ${message}` }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** Result of the script path-traversal gate (spec §4.2/§5.2). */
+export type ScriptPathGate = { ok: true; fullPath: string } | { ok: false; reason: string }
+
+/**
+ * Resolve a bare script file name inside the whitelisted directory, refusing
+ * absolute paths, separators, and `..` components outright (spec: scriptName is
+ * FILE NAME ONLY), then re-checking the resolved path stays under the base.
+ * Also requires the target to exist as a regular file — a missing script is
+ * reported as PERMISSION_DENIED at the audit level.
+ * @param allowDir - configured `script_allow_dir`.
+ * @param scriptName - bare file name supplied by the model.
+ * @returns resolved full path or a refusal reason.
+ */
+export function resolveScriptPath(allowDir: string, scriptName: string): ScriptPathGate {
+  if (typeof scriptName !== 'string' || scriptName.trim() === '') {
+    return { ok: false, reason: 'scriptName is required and must be a bare file name' }
+  }
+  if (path.isAbsolute(scriptName)) return { ok: false, reason: `absolute path not allowed: ${scriptName}` }
+  if (scriptName.includes('/') || scriptName.includes('\\') || scriptName.split(/[\\/]+/).includes('..')) {
+    return { ok: false, reason: `path traversal blocked: "${scriptName}" must be a bare file name inside script_allow_dir` }
+  }
+  const base = path.resolve(allowDir)
+  const full = path.resolve(base, scriptName)
+  if (full !== base && !full.startsWith(base + path.sep)) {
+    return { ok: false, reason: `resolved path escapes script_allow_dir: ${scriptName}` }
+  }
+  try {
+    if (!statSync(full).isFile()) return { ok: false, reason: `script not found in allow dir: ${scriptName}` }
+  } catch {
+    return { ok: false, reason: `script not found in allow dir: ${scriptName}` }
+  }
+  return { ok: true, fullPath: full }
+}
+
+/**
+ * Ordered interpreter candidates per script extension. The first candidate that
+ * actually spawns wins, so the same whitelisted directory works on machines
+ * where only one of `python`/`python3`/`py` exists — and, crucially, on Windows
+ * where a `.py`/`.js`/`.sh` file is NOT directly executable by CreateProcess
+ * (Node's `spawn` would fail outright: Windows resolves interpreters through
+ * file associations only when a shell is involved, which spec §5.5 forbids).
+ *
+ * Names are looked up on PATH; the values come from THIS table, never from the
+ * model, so no caller-supplied string can ever become an interpreter.
+ * `.bat`/`.cmd` are handled separately (cmd.exe), `.ps1` needs `-File`.
+ */
+export const SCRIPT_INTERPRETERS: Record<string, readonly string[]> = {
+  '.py': ['python', 'python3', 'py'],
+  '.js': ['node'],
+  '.mjs': ['node'],
+  '.cjs': ['node'],
+  '.sh': ['bash', 'sh'],
+  '.bash': ['bash'],
+  '.ps1': ['pwsh', 'powershell'],
+}
+
+/** How one resolved script file will be launched. */
+export interface ScriptLaunchPlan {
+  /** Display name of the interpreter that will run the file (or the file itself when directly executable). */
+  interpreter: string
+  /** Ordered argv prefixes; every candidate ends with the gated script path. Args are appended after it. */
+  candidates: readonly (readonly string[])[]
+}
+
+/**
+ * Decide HOW a gated script file is launched, without spawning anything.
+ * Pure and inspectable so the decision is unit-testable and so a caller can
+ * audit what would run before it runs.
+ * @param fullPath - the gated absolute path inside the allow dir.
+ * @returns the interpreter label plus ordered argv-prefix candidates.
+ */
+export function planScriptLaunch(fullPath: string): ScriptLaunchPlan {
+  const ext = path.extname(fullPath).toLowerCase()
+  if (process.platform === 'win32' && (ext === '.bat' || ext === '.cmd')) {
+    // Windows cannot CreateProcess a batch file (spawn EINVAL) — go through cmd.exe.
+    // Still a pure argv array, never a shell string (spec §5.5).
+    return { interpreter: 'cmd.exe', candidates: [['cmd.exe', '/d', '/s', '/c', fullPath]] }
+  }
+  const names = SCRIPT_INTERPRETERS[ext]
+  if (names !== undefined && names.length > 0) {
+    const candidates = names.map(name => (ext === '.ps1'
+      ? [name, '-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', fullPath]
+      : [name, fullPath]))
+    return { interpreter: names[0], candidates }
+  }
+  // No known extension → the file must be a real executable (.exe/.com on Windows,
+  // anything with the executable bit on POSIX, or a shebang'd file).
+  return { interpreter: path.basename(fullPath), candidates: [[fullPath]] }
+}
+
+/**
+ * List the regular files available in the script allow dir (sorted, capped).
+ * Used to make a refusal actionable: without it, a model that guesses a wrong
+ * file name gets only "not found" and has no way to discover what IS runnable.
+ * @param allowDir - configured `script_allow_dir`.
+ * @param limit - maximum entries returned (default 50).
+ * @returns file names, or an empty array when the directory is unreadable.
+ */
+export function listAvailableScripts(allowDir: string, limit = 50): string[] {
+  try {
+    return readdirSync(allowDir, { withFileTypes: true })
+      .filter(entry => entry.isFile())
+      .map(entry => entry.name)
+      .sort()
+      .slice(0, limit)
+  } catch {
+    return []
+  }
+}
+
+/** Build the `(available in script_allow_dir: …)` suffix for a refusal message. */
+function availableScriptsHint(allowDir: string): string {
+  const names = listAvailableScripts(allowDir)
+  return names.length === 0 ? '' : ` (available in script_allow_dir: ${names.join(', ')})`
+}
+
+/** Parameters for one whitelisted script execution (spec §4.2). */
+export interface ScriptRunParams {
+  scriptName: string
+  args?: string[]
+  /** Per-call timeout override; clamped to [1, maxTimeoutMs] by `resolveTimeoutMs`. */
+  timeoutMs?: number
+  /** Text piped to the child's stdin, then EOF. Logged as a byte count only (it may hold a credential). */
+  stdin?: string
+}
+
+/** Plugin config slice consumed by the script tool. */
+export interface ScriptConfig {
+  scriptAllowDir: string
+  defaultTimeoutMs: number
+  /** Byte budget for captured stdout/stderr (capture is capped at the same size as the log). */
+  maxOutputLogBytes: number
+  /** Upper bound for a per-call `timeoutMs` override; undefined → DEFAULT_MAX_TIMEOUT_MS. */
+  maxTimeoutMs?: number
+  /** Working directory for the child; defaults to `scriptAllowDir` when empty. */
+  scriptWorkingDir?: string
+}
+
+/** Outcome of one script execution — args pass through verbatim, outputs are byte-capped. */
+export interface ScriptRunResult {
+  ok: boolean
+  exitCode?: number
+  stdout?: string
+  stderr?: string
+  /** Interpreter that actually ran the file (make the launch decision auditable). */
+  interpreter?: string
+  errorType?: ErrorType
+  error?: string
+}
+
+/** Append a chunk to a byte-capped buffer; returns the capped text plus an overflow flag. */
+function appendCapped(current: string, chunk: string, maxBytes: number): { text: string; truncated: boolean } {
+  const combined = current + chunk
+  if (Buffer.byteLength(combined, 'utf8') <= maxBytes) return { text: combined, truncated: false }
+  const buf = Buffer.from(combined, 'utf8')
+  let end = maxBytes
+  while (end > 0 && (buf[end] & 0xc0) === 0x80) end -= 1
+  return { text: buf.subarray(0, end).toString('utf8'), truncated: true }
+}
+
+/**
+ * Kill the whole process group of a spawned script so no zombie children
+ * survive a timeout (spec §4.2/§5.4). POSIX: SIGKILL to `-pid`. Windows has
+ * no process groups: kill the tree with `taskkill /t` (array arguments — never
+ * a shell string, per spec §5.5).
+ * @param proc - the spawned child to tear down.
+ */
+export function killProcessGroup(proc: ChildProcess): void {
+  if (proc.pid === undefined) return
+  try {
+    if (process.platform !== 'win32') {
+      process.kill(-proc.pid, 'SIGKILL')
+    } else {
+      // /t kills the entire process tree; arguments are passed as an array — no shell interpolation.
+      execFile('taskkill', ['/pid', String(proc.pid), '/t', '/f'], () => {})
+      try { proc.kill() } catch { /* already gone */ }
+    }
+  } catch {
+    // The process may have exited between the timer firing and the kill — fine.
+  }
+}
+
+/**
+ * Execute a whitelisted script with process-group spawn, timeout kill, and
+ * byte-capped stdout/stderr capture (spec §4.2). Never rejects: every failure
+ * path resolves to a classified result so the adapter can always emit an audit
+ * record. Args are passed verbatim as argv — no shell string is ever built.
+ *
+ * Launch decision comes from `planScriptLaunch`, so a `.py`/`.js`/`.sh`/`.ps1`
+ * file runs under its interpreter instead of failing to spawn (the whole point
+ * on Windows, where such files are not directly executable). Interpreter
+ * candidates are tried in order until one starts.
+ * @param params - bare scriptName + args/stdin/timeout override from the model.
+ * @param cfg - allow dir, timeout budget, output byte cap, working dir from plugin config.
+ * @param externalSignal - optional caller cancellation (DSH exec.signal).
+ * @returns classified outcome with exitCode/stdout/stderr or errorType/error.
+ */
+export function runExternalScript(
+  params: ScriptRunParams,
+  cfg: ScriptConfig,
+  externalSignal?: AbortSignal,
+): Promise<ScriptRunResult> {
+  const gate = resolveScriptPath(cfg.scriptAllowDir, params.scriptName)
+  if (!gate.ok) {
+    // Make the refusal actionable: say what IS runnable instead of just "not found".
+    return Promise.resolve({ ok: false, errorType: ERROR_TYPES.PERMISSION_DENIED, error: `${gate.reason}${availableScriptsHint(cfg.scriptAllowDir)}` })
+  }
+
+  const plan = planScriptLaunch(gate.fullPath)
+  const timeoutMs = resolveTimeoutMs(params.timeoutMs, cfg.defaultTimeoutMs, cfg.maxTimeoutMs)
+  const cwd = typeof cfg.scriptWorkingDir === 'string' && cfg.scriptWorkingDir.trim() !== ''
+    ? cfg.scriptWorkingDir.trim()
+    : cfg.scriptAllowDir
+  const stdinText = typeof params.stdin === 'string' ? params.stdin : undefined
+  const scriptArgs = params.args ?? []
+
+  // Fail fast on a bad working directory: spawn reports a missing cwd as ENOENT too,
+  // which would otherwise be mistaken for a missing interpreter and burn every candidate.
+  try {
+    if (!statSync(cwd).isDirectory()) {
+      return Promise.resolve({ ok: false, errorType: ERROR_TYPES.PERMISSION_DENIED, error: `working directory is not a directory: ${cwd}` })
+    }
+  } catch {
+    return Promise.resolve({ ok: false, errorType: ERROR_TYPES.PERMISSION_DENIED, error: `working directory does not exist: ${cwd}` })
+  }
+
+  return new Promise(resolvePromise => {
+    let settled = false
+    let attempt = 0
+    let proc: ChildProcess | undefined
+    let stdout = ''
+    let stderr = ''
+    let stdoutTruncated = false
+    let stderrTruncated = false
+
+    const finish = (result: ScriptRunResult): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      externalSignal?.removeEventListener('abort', onExternalAbort)
+      resolvePromise(result)
+    }
+
+    // One timer for the WHOLE invocation (not per interpreter attempt), so trying
+    // several candidates cannot silently extend the budget past the configured ceiling.
+    const timer = setTimeout(() => {
+      if (proc !== undefined) killProcessGroup(proc)
+      finish({ ok: false, errorType: ERROR_TYPES.TIMEOUT, error: `script exceeded ${timeoutMs}ms and was killed` })
+    }, timeoutMs)
+    const onExternalAbort = (): void => {
+      if (proc !== undefined) killProcessGroup(proc)
+      finish({ ok: false, errorType: ERROR_TYPES.INTERNAL_ERROR, error: 'call aborted by caller (USER_CANCEL tracking lands in v1.3)' })
+    }
+    externalSignal?.addEventListener('abort', onExternalAbort, { once: true })
+
+    /**
+     * Classify a failed spawn attempt. An ENOENT (candidate not on PATH) moves on to
+     * the next candidate; anything else is terminal. Reached from BOTH the `error`
+     * event and the synchronous throw below — Windows reports some targets
+     * synchronously (EFTYPE for a non-executable file) instead of emitting `error`.
+     */
+    const onSpawnFailure = (err: Error & { code?: string }, argv: readonly string[]): void => {
+      if (err.code === 'ENOENT' && attempt + 1 < plan.candidates.length) {
+        attempt += 1
+        startAttempt() // this interpreter is not installed — try the next candidate
+        return
+      }
+      // Terminal spawn failure (interpreter missing, file vanished between stat and
+      // spawn, not an executable): refuse, don't crash.
+      const label = plan.candidates.length > 1 ? plan.candidates.map(candidate => candidate[0]).join('/') : argv[0]
+      finish({
+        ok: false,
+        errorType: ERROR_TYPES.PERMISSION_DENIED,
+        error: `failed to start script via "${label}": ${err.message}${err.code === 'ENOENT' ? ' (interpreter not found on PATH)' : ''}`,
+      })
+    }
+
+    /**
+     * Spawn interpreter candidate #attempt and wire its streams.
+     * Everything stays an ARGV array — no shell string is ever built or concatenated
+     * (spec §5.5); the script path was already gated to a bare file name inside the
+     * allow dir, and args pass through verbatim.
+     */
+    const startAttempt = (): void => {
+      const argv = plan.candidates[attempt]
+      let child: ChildProcess
+      try {
+        child = spawn(argv[0], [...argv.slice(1), ...scriptArgs], {
+          cwd,
+          // Own process group on POSIX so a timeout kills every descendant;
+          // Windows trees are covered by taskkill /t in killProcessGroup.
+          detached: process.platform !== 'win32',
+        })
+      } catch (err) {
+        // Synchronous spawn rejection (observed on Windows: EFTYPE / EINVAL for a file
+        // CreateProcess cannot start). MUST be handled here — letting it escape would
+        // reject the returned promise and break the "never rejects" contract the
+        // adapter relies on to always emit an audit record.
+        onSpawnFailure(err as Error & { code?: string }, argv)
+        return
+      }
+      proc = child
+
+      if (stdinText !== undefined && child.stdin !== null && child.stdin !== undefined) {
+        // The child may never read stdin → EPIPE is expected, not an error worth reporting.
+        child.stdin.on('error', () => {})
+        child.stdin.end(stdinText)
+      }
+
+      child.stdout?.on('data', (chunk: Buffer) => {
+        const capped = appendCapped(stdout, chunk.toString('utf8'), cfg.maxOutputLogBytes)
+        stdout = capped.text
+        stdoutTruncated = capped.truncated || stdoutTruncated
+      })
+      child.stderr?.on('data', (chunk: Buffer) => {
+        const capped = appendCapped(stderr, chunk.toString('utf8'), cfg.maxOutputLogBytes)
+        stderr = capped.text
+        stderrTruncated = capped.truncated || stderrTruncated
+      })
+
+      child.on('error', (err: Error & { code?: string }) => { onSpawnFailure(err, argv) })
+
+      child.on('close', (exitCode: number | null) => {
+        const out = stdoutTruncated ? `${stdout}[TRUNCATED]` : stdout
+        const errText = stderrTruncated ? `${stderr}[TRUNCATED]` : stderr
+        if (exitCode === 0) {
+          finish({ ok: true, exitCode: 0, stdout: out, stderr: errText, interpreter: plan.interpreter })
+        } else {
+          finish({
+            ok: false,
+            exitCode: exitCode ?? undefined,
+            stdout: out,
+            stderr: errText,
+            interpreter: plan.interpreter,
+            errorType: ERROR_TYPES.SCRIPT_EXIT_ERROR,
+            error: `script exited with code ${String(exitCode)}`,
+          })
+        }
+      })
+    }
+
+    startAttempt()
+  })
+}