dsh-dlp 0.1.0

package/lib/guard.js

@@ -0,0 +1,133 @@
+/**
+ * The guard floor: the one part of this plugin that holds under attack.
+ *
+ * It tests the path-typed arguments of a call — never file content — against
+ * the credential table, resolving symlinks first, and the whole argument set
+ * against the tier-1 detectors when the tool can move data off the machine.
+ * The `command` arm inside that is advisory pattern-matching: tokenising a
+ * shell command line catches `cat ~/.ssh/id_rsa` and loses to one glob
+ * character. README.md says so plainly and so does this comment.
+ *
+ * `ctx.tools.guard()` takes a synchronous `(exec) => string | undefined`. It
+ * has no allow arm, so no registration order can turn a denial back into
+ * permission, and the first denial wins. It runs after the whole
+ * `tools/pre-execute` waterfall and after `ctx.approval`, which is why the
+ * floor lives here rather than in a listener: `exec.arguments` is deep-frozen
+ * but `exec` itself is not frozen until after execution, so a pre-execute
+ * listener can reassign `exec.arguments` or `exec.name` and succeed. The guard
+ * reads what every listener finally left behind.
+ *
+ * Registered on a plain context, never through `agent.ctx`: a global guard
+ * covers every agent, every `run_code` inner sub-call, and every subagent
+ * child, while an agent-scoped listener never sees a subagent child's calls
+ * because a child agent is a sibling, not a descendant.
+ *
+ * The floor is not configurable. Per CONVENTIONS, security invariants stay
+ * fixed; the repo-local policy tier may only add to its tables.
+ * @module dsh-dlp/guard
+ */
+import { DENY_SEVERITY, scanSync, severityRank } from "./detectors.js";
+import { isEgressCapable, matchPathArgument, pathArguments, pathCandidates } from "./paths.js";
+import { nestedStrings } from "./redaction.js";
+/**
+ * Denial text for a credential-path match.
+ *
+ * The matched path is named by rule id and keyed hash, never quoted. A path is
+ * itself sensitive — a tenant name, a customer directory, a shell command that
+ * happens to end in `.pem` — and this string is both model-visible and written
+ * to the audit sink.
+ */
+function credentialPathReason(toolName, ruleId, hash) {
+    return `dsh-dlp denied ${JSON.stringify(toolName)}: one of its path arguments is credential material `
+        + `(rule ${ruleId}, keyed hash ${hash}). Reading or passing credential files through a tool is blocked by `
+        + 'policy and cannot be overridden. Ask the user to supply the value you need, or use a path that is not a '
+        + 'credential store.';
+}
+/** Denial text for secrets found in arguments heading to an egress-capable tool. */
+function secretArgumentReason(toolName, ruleIds, hashes) {
+    return `dsh-dlp denied ${JSON.stringify(toolName)}: its arguments contain credential material matching `
+        + `${ruleIds.join(', ')} (${hashes.length} finding(s), keyed hash ${hashes.join(', ')}). `
+        + `${JSON.stringify(toolName)} can send data off this machine, so secrets in its arguments are blocked by policy `
+        + 'and cannot be overridden. Remove the credential from the call — reference an environment variable the tool '
+        + 'already has, or ask the user to run the command themselves.';
+}
+/**
+ * Decide whether the floor denies one call.
+ *
+ * Credential paths are denied for every tool, not only readers: a shell that
+ * can `cat` a key can also copy it. Only path-typed arguments are tested —
+ * running the table over every string matches file content and denies writing
+ * a `.gitignore` that mentions `.env`. Argument secrets are denied only for
+ * egress-capable tools, because denying a local editor for holding the text it
+ * was asked to write would break ordinary work without closing an exfiltration
+ * path.
+ * @param exec - the pending call as the guard stage sees it.
+ * @param policy - the effective policy after the tighten-only merge.
+ * @param hasher - mints the keyed hashes quoted in a denial reason.
+ * @returns the denial, or `undefined` to abstain.
+ */
+export function evaluateGuard(exec, policy, hasher) {
+    for (const argument of pathArguments(exec.arguments)) {
+        const candidates = argument.shell ? pathCandidates(argument.text) : [argument.text];
+        for (const candidate of candidates) {
+            const rule = matchPathArgument(candidate, policy.credentialPathRules);
+            if (rule === undefined)
+                continue;
+            const hash = hasher.hash(candidate);
+            return {
+                kind: 'credential-path',
+                reason: credentialPathReason(exec.name, rule.id, hash),
+                spans: [{
+                        ruleId: rule.id,
+                        ruleVersion: rule.version,
+                        severity: 'critical',
+                        start: 0,
+                        end: candidate.length,
+                        hash,
+                    }],
+            };
+        }
+    }
+    if (!isEgressCapable(exec.name, policy.extraEgressTools))
+        return undefined;
+    const spans = [];
+    for (const text of nestedStrings(exec.arguments)) {
+        for (const detection of scanSync(text, policy.syncRules).detections) {
+            if (severityRank(detection.severity) < severityRank(DENY_SEVERITY))
+                continue;
+            spans.push({ ...detection, hash: hasher.hash(text.slice(detection.start, detection.end)) });
+        }
+    }
+    if (spans.length === 0)
+        return undefined;
+    const ruleIds = [...new Set(spans.map(span => span.ruleId))];
+    return {
+        kind: 'secret-argument',
+        reason: secretArgumentReason(exec.name, ruleIds, spans.map(span => span.hash)),
+        spans,
+    };
+}
+/**
+ * Wrap {@link evaluateGuard} so an internal fault becomes a denial.
+ *
+ * A guard that throws fails the call closed *and* skips `tools/post-execute`,
+ * which would silently disable result redaction for that call. Converting the
+ * fault into a denial string keeps the post-execute stage running.
+ * @param exec - the pending call.
+ * @param policy - the effective policy.
+ * @param hasher - mints the keyed hashes quoted in a denial reason.
+ * @returns the denial, or `undefined` to abstain.
+ */
+export function safeEvaluateGuard(exec, policy, hasher) {
+    try {
+        return evaluateGuard(exec, policy, hasher);
+    }
+    catch (error) {
+        return {
+            kind: 'internal-fault',
+            reason: `dsh-dlp denied ${JSON.stringify(exec.name)}: the data-loss-prevention floor failed to evaluate `
+                + `this call (${String(error)}) and denies by default. Report this to the deployment operator.`,
+            spans: [],
+        };
+    }
+}

package/lib/index.js

@@ -0,0 +1,212 @@
+/**
+ * `dsh-dlp` — data-loss prevention for DeepSeek Harness.
+ *
+ * Four registrations, in descending order of how much they can be trusted:
+ *
+ * 1. `ctx.tools.guard()` — an unconditional, non-configurable deny floor for
+ *    credential paths named in a path-typed argument and for secrets heading
+ *    into an egress-capable tool. Order-independent, because the guard seam
+ *    has no allow arm.
+ * 2. `tools/pre-execute` — the async breadth tier, which can await
+ *    `@secretlint/core`. Neutralizable by any listener registered ahead of it.
+ * 3. `tools/post-execute` — result redaction, applied before the `tool/result`
+ *    session event is appended, so the durable log records the redacted copy;
+ *    a result that cannot be cleaned is withheld rather than accepted.
+ * 4. `session-telemetry/record` — fail-closed redaction of exported telemetry,
+ *    reaching tier 1 only because the waterfall is synchronous.
+ *
+ * This plugin is not a containment boundary. It runs in-process at the agent's
+ * own uid; anything the agent can execute can read the same files the guard
+ * denies. See README.md.
+ * @module dsh-dlp
+ */
+import { randomBytes } from 'node:crypto';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { loadRepoPolicy, resolvePolicy } from "./policy.js";
+import { SpanHasher } from "./redaction.js";
+import { safeEvaluateGuard } from "./guard.js";
+import { breadthTierDenial, evaluateBreadthTier, redactDecision } from "./results.js";
+import { redactRecord } from "./telemetry.js";
+import { AuditSink, CallCorrelator, newDecisionId, RECORD_VERSION } from "./sink.js";
+export { Config } from "./policy.js";
+/** Display metadata; labels the plugin in Cordis diagnostics. */
+export const name = 'dsh-dlp';
+/** Services required before `apply` runs. */
+export const inject = ['tools'];
+/** Bytes generated for a new installation redaction key. */
+const KEY_BYTES = 32;
+/**
+ * Read the installation's redaction key, creating it on first mount.
+ *
+ * The key makes every placeholder a keyed hash rather than a bare digest:
+ * without it, anyone holding a candidate secret could confirm it against the
+ * audit log.
+ * @param path - the key file named by `redactionKeyFile`.
+ * @returns the key bytes.
+ * @throws when an existing key file is too short to be a key.
+ */
+export function loadOrCreateKey(path) {
+    let existing;
+    try {
+        existing = readFileSync(path);
+    }
+    catch (error) {
+        // Only absence means "first mount". A permission or I/O failure on an
+        // existing key must not mint a new one: every placeholder and every audit
+        // hash would change, silently breaking correlation with the whole history.
+        if (error.code !== 'ENOENT') {
+            throw new Error(`dsh-dlp: cannot read the redaction key at ${path}: ${String(error)}`);
+        }
+        existing = undefined;
+    }
+    if (existing !== undefined) {
+        if (existing.length < 16) {
+            throw new Error(`dsh-dlp: redaction key at ${path} is ${existing.length} bytes; at least 16 are required`);
+        }
+        return existing;
+    }
+    const created = randomBytes(KEY_BYTES);
+    writeFileSync(path, created, { mode: 0o600 });
+    return created;
+}
+/**
+ * Load the repo-local policy tier, if the deployment named one.
+ *
+ * A missing file is no policy at all, and a malformed one is reported and
+ * ignored. The floor never depends on a workspace file being present or
+ * well-formed: the recommended `policyFile` is workspace-relative, so failing
+ * the mount would refuse to start `dsh` in every repository without one, and
+ * would let a hostile repository disable the plugin by shipping a broken file.
+ * @param ctx - the plugin's context, used only for its logger.
+ * @param policyFile - the configured path, or `undefined` when the deployment named none.
+ * @returns the validated policy, or `undefined` when there is none to apply.
+ */
+function loadConfiguredPolicy(ctx, policyFile) {
+    if (policyFile === undefined)
+        return undefined;
+    const load = loadRepoPolicy(policyFile);
+    switch (load.kind) {
+        case 'absent':
+            return undefined;
+        case 'loaded':
+            return load.policy;
+        case 'invalid':
+            ctx.logger.error(`dsh-dlp: ignoring the repo-local policy at ${policyFile}: ${load.problem}`);
+            return undefined;
+        /* v8 ignore next 4 -- unreachable while `RepoPolicyLoad` stays closed; the arm exists so adding a variant fails the build. */
+        default: {
+            const unhandled = load;
+            throw new TypeError(`dsh-dlp: unhandled repo policy load ${JSON.stringify(unhandled)}`);
+        }
+    }
+}
+/**
+ * Mount the plugin.
+ * @param ctx - the plugin's context; every registration is undone on unload.
+ * @param config - validated `cordis.yml` configuration.
+ */
+export function apply(ctx, config) {
+    const policy = resolvePolicy(config, loadConfiguredPolicy(ctx, config.policyFile));
+    const hasher = new SpanHasher(loadOrCreateKey(config.redactionKeyFile));
+    const correlator = new CallCorrelator();
+    const sink = new AuditSink(config.auditLog, (error) => {
+        ctx.logger.error(`dsh-dlp: audit sink write failed: ${String(error)}`);
+    });
+    /** Identity every audit record carries; the session-log envelope carries none of it. */
+    const identity = (exec) => {
+        const position = correlator.lookup(exec.callId);
+        return {
+            tool: exec.name,
+            callId: exec.callId,
+            rootCallId: exec.rootCallId,
+            ...exec.agent === undefined ? {} : { sessionId: String(exec.agent.session.id) },
+            ...position === undefined ? {} : { turn: position.turn, step: position.step },
+        };
+    };
+    ctx.on('session/event', (_session, event) => {
+        if (event.type === 'tool/call') {
+            correlator.note(event.data.callId, { turn: event.data.turn, step: event.data.step });
+            return;
+        }
+        if (event.type === 'tool/result') {
+            correlator.forget(event.data.message.source.callId);
+        }
+    });
+    // The floor. Registered on a plain context so it applies globally: to every
+    // agent, every `run_code` inner sub-call, and every subagent child.
+    ctx.effect(() => ctx.tools.guard((exec) => {
+        const verdict = safeEvaluateGuard(exec, policy, hasher);
+        if (verdict === undefined)
+            return undefined;
+        sink.write({
+            v: RECORD_VERSION,
+            time: new Date().toISOString(),
+            kind: 'guard-deny',
+            decisionId: newDecisionId(),
+            ...identity(exec),
+            spans: verdict.spans,
+        });
+        return verdict.reason;
+    }), 'dsh-dlp guard floor');
+    if (policy.breadthTier) {
+        ctx.on('tools/pre-execute', async (exec, next) => {
+            const decision = await next();
+            if (decision.kind !== 'allow')
+                return decision;
+            const finding = await evaluateBreadthTier(exec, policy, hasher);
+            if (finding === undefined)
+                return decision;
+            sink.write({
+                v: RECORD_VERSION,
+                time: new Date().toISOString(),
+                kind: 'pre-execute-deny',
+                decisionId: newDecisionId(),
+                ...identity(exec),
+                spans: finding.spans,
+            });
+            return breadthTierDenial(finding.reason);
+        });
+    }
+    if (policy.resultRedaction) {
+        ctx.on('tools/post-execute', async (exec, result, next) => {
+            const redacted = await redactDecision(await next(), result, policy, hasher);
+            // A truncated scan is recorded even with nothing found: without a record
+            // an operator cannot tell "this result was clean" from "this result was
+            // only partly examined".
+            if (redacted.spans.length > 0 || redacted.truncatedScan) {
+                sink.write({
+                    v: RECORD_VERSION,
+                    time: new Date().toISOString(),
+                    kind: 'result-redaction',
+                    decisionId: newDecisionId(),
+                    ...identity(exec),
+                    spans: redacted.spans,
+                    ...redacted.truncatedScan ? { truncatedScan: true } : {},
+                });
+            }
+            return redacted.decision;
+        });
+    }
+    if (policy.telemetryRedaction) {
+        ctx.on('session-telemetry/record', (_record, next) => {
+            // Throwing here withholds this one record; the coordinator contains it
+            // and the agent loop never sees the failure. That is the fail-closed
+            // behavior this listener wants.
+            const redacted = redactRecord(next(), policy, hasher);
+            if (redacted.spans.length > 0) {
+                sink.write({
+                    v: RECORD_VERSION,
+                    time: new Date().toISOString(),
+                    kind: 'telemetry-redaction',
+                    decisionId: newDecisionId(),
+                    channel: redacted.record.channel,
+                    ...typeof redacted.record.attributes['session.id'] === 'string'
+                        ? { sessionId: redacted.record.attributes['session.id'] }
+                        : {},
+                    spans: redacted.spans,
+                });
+            }
+            return redacted.record;
+        });
+    }
+}

package/lib/paths.js

@@ -0,0 +1,227 @@
+/**
+ * The two classifications the guard floor runs on: which paths are credential
+ * material, and which tools can move data off the machine.
+ *
+ * Both tables are security invariants. Neither is settable from `cordis.yml`;
+ * the repo-local policy tier may only add to them.
+ * @module dsh-dlp/paths
+ */
+import { realpathSync } from 'node:fs';
+import { posix } from 'node:path';
+/**
+ * File extensions that name source code or documentation rather than a
+ * credential store, used by {@link CREDENTIAL_PATH_RULES}'s filename
+ * heuristic. Without them `src/auth/token.ts` would be undeniable-file
+ * material and ordinary work would stop.
+ */
+const CODE_EXTENSIONS = 'ts|tsx|js|jsx|mjs|cjs|py|go|rs|java|rb|php|c|h|hpp|cc|cpp|cs|swift|kt|md|rst|txt|html|css|scss|sh|bash|zsh|sql|lock|snap|map';
+/**
+ * Paths whose contents are credentials. Reading any of them through a tool is
+ * denied unconditionally.
+ *
+ * Order matters only for reporting: the first match wins, so the specific
+ * rules precede the filename heuristic and an operator sees the precise rule
+ * id in the audit record.
+ *
+ * `$DSH_HOME/.credentials.yaml` is here because core permits it: the harness
+ * has no file-read restriction in any mode ("Reads pass through untouched:
+ * every mode permits reading"), so the provider token the agent itself
+ * authenticates with is agent-readable. That is the gap this table closes.
+ */
+export const CREDENTIAL_PATH_RULES = [
+    { id: 'dsh-dlp/path-dotenv', version: 2, pattern: /(^|\/)\.env(\.(?!(?:example|sample|template|dist)(?:\/|$))[^/]*)?(\/|$)/i },
+    { id: 'dsh-dlp/path-ssh-dir', version: 2, pattern: /(^|\/)\.ssh[^/]*(\/|$)/i },
+    { id: 'dsh-dlp/path-ssh-key', version: 2, pattern: /(^|\/)id_(rsa|dsa|ecdsa|ed25519)([._-][^/]*)?$/i },
+    { id: 'dsh-dlp/path-aws', version: 2, pattern: /(^|\/)\.aws(\/|$)/i },
+    { id: 'dsh-dlp/path-azure', version: 1, pattern: /(^|\/)\.azure(\/|$)/i },
+    { id: 'dsh-dlp/path-dsh-credentials', version: 1, pattern: /(^|\/)\.credentials\.yaml$/i },
+    { id: 'dsh-dlp/path-netrc', version: 1, pattern: /(^|\/)\.netrc$/i },
+    { id: 'dsh-dlp/path-npmrc', version: 1, pattern: /(^|\/)\.npmrc$/i },
+    { id: 'dsh-dlp/path-pypirc', version: 1, pattern: /(^|\/)\.pypirc$/i },
+    { id: 'dsh-dlp/path-git-credentials', version: 1, pattern: /(^|\/)\.git-credentials$/i },
+    { id: 'dsh-dlp/path-gh-config', version: 1, pattern: /(^|\/)\.config\/gh(\/|$)/i },
+    { id: 'dsh-dlp/path-kubeconfig', version: 2, pattern: /(^|\/)(\.kube\/[^/]*|kubeconfig[^/]*)$/i },
+    { id: 'dsh-dlp/path-kubernetes-conf', version: 1, pattern: /(^|\/)kubernetes\/[^/]*\.conf$/i },
+    { id: 'dsh-dlp/path-docker-config', version: 2, pattern: /(^|\/)(\.docker\/config\.json|\.dockercfg)$/i },
+    { id: 'dsh-dlp/path-gcloud-credentials', version: 1, pattern: /(^|\/)\.config\/gcloud\/[^/]*credential[^/]*$/i },
+    { id: 'dsh-dlp/path-rclone-config', version: 1, pattern: /(^|\/)rclone\.conf$/i },
+    { id: 'dsh-dlp/path-pgpass', version: 1, pattern: /(^|\/)\.pgpass$/i },
+    { id: 'dsh-dlp/path-mysql-config', version: 1, pattern: /(^|\/)\.my\.cnf$/i },
+    { id: 'dsh-dlp/path-service-account', version: 1, pattern: /(^|\/)[^/]*service[._-]?account[^/]*\.json$/i },
+    { id: 'dsh-dlp/path-keystore', version: 2, pattern: /\.(pem|p12|pfx|jks|keystore|key|asc|gpg)$/i },
+    { id: 'dsh-dlp/path-credential-name', version: 1, pattern: new RegExp(String.raw `(^|\/)(?!.*\.(?:${CODE_EXTENSIONS})$)[^/]*(credentials?|secrets?|tokens?)([._-][^/]*)?$`, 'i') },
+];
+/**
+ * Normalize one candidate path for matching: Windows separators become
+ * forward slashes, surrounding quotes come off, `~` expands to a
+ * root-anchored marker, `..` segments collapse so a traversal cannot hide a
+ * credential path from the table, and a trailing slash is dropped so `.env/`
+ * matches the same rule as `.env`.
+ * @param candidate - a raw string from tool arguments.
+ * @returns the normalized form the rules are matched against.
+ */
+export function normalizeCandidatePath(candidate) {
+    const slashed = candidate.replace(/\\/g, '/');
+    const stripped = slashed.replace(/^["']|["']$/g, '');
+    const homeExpanded = stripped.startsWith('~/') ? `/~/${stripped.slice(2)}` : stripped;
+    const normalized = posix.normalize(homeExpanded);
+    return normalized.length > 1 ? normalized.replace(/\/+$/, '') : normalized;
+}
+/**
+ * Whether one string names credential material. Pure: it never touches the
+ * filesystem, so a symlink is matched by the name it was given. The guard
+ * calls {@link matchPathArgument} instead, which resolves first.
+ * @param candidate - a raw string from tool arguments.
+ * @param rules - the rule table; defaults to {@link CREDENTIAL_PATH_RULES}.
+ * @returns the first matching rule, or `undefined`.
+ */
+export function matchCredentialPath(candidate, rules = CREDENTIAL_PATH_RULES) {
+    const normalized = normalizeCandidatePath(candidate);
+    return rules.find(rule => rule.pattern.test(normalized));
+}
+/**
+ * Resolve one candidate through the filesystem so a symlink cannot rename a
+ * credential file out of the table.
+ * @param candidate - a raw string from tool arguments.
+ * @returns the canonical path, or `undefined` when it does not resolve.
+ */
+export function resolveCandidatePath(candidate) {
+    try {
+        return realpathSync(normalizeCandidatePath(candidate));
+    }
+    catch {
+        // ENOENT for a path being created, ELOOP for a broken link, EACCES for an
+        // unreadable parent: in every case the literal spelling is all we have.
+        return undefined;
+    }
+}
+/**
+ * Match one path-typed argument against the credential table, by the name the
+ * caller used and by what that name resolves to.
+ * @param candidate - a raw string from a path-typed tool argument.
+ * @param rules - the rule table; defaults to {@link CREDENTIAL_PATH_RULES}.
+ * @returns the first matching rule, or `undefined`.
+ */
+export function matchPathArgument(candidate, rules = CREDENTIAL_PATH_RULES) {
+    const literal = matchCredentialPath(candidate, rules);
+    if (literal !== undefined)
+        return literal;
+    const resolved = resolveCandidatePath(candidate);
+    return resolved === undefined ? undefined : matchCredentialPath(resolved, rules);
+}
+/**
+ * Split one shell command into the substrings worth testing as paths: the
+ * whole string, plus each shell-ish token. A `bash` command is a single string
+ * argument, so without tokenization `cat ~/.ssh/id_rsa && echo ok` would not
+ * match a rule anchored at the end of a path.
+ *
+ * This is advisory only. A shell command is a program, not a path, and any
+ * quoting, globbing, substitution or encoding defeats the split — see the
+ * "what this is not" section of README.md.
+ * @param text - one shell command line taken from tool arguments.
+ * @returns the whole string followed by its tokens.
+ */
+export function pathCandidates(text) {
+    const tokens = text.split(/[\s;|&<>()"'`,]+/).filter(token => token.length > 0);
+    return [text, ...tokens];
+}
+/**
+ * Argument keys whose values name filesystem paths.
+ *
+ * The guard tests these and nothing else. Running the credential-path table
+ * over every string argument matches file *content* — a `.gitignore` listing
+ * `.env`, an edit that mentions `id_rsa`, a grep pattern — and denies ordinary
+ * work with a message saying it cannot be overridden.
+ */
+export const PATH_ARGUMENT_KEYS = new Set([
+    // Names the shipped tools use: `file_path` (read, write, edit), `path` and
+    // `paths` (search, lsp, terminal), `cwd` and `workdir` (the shells), `root`.
+    'file_path', 'filePath', 'path', 'paths', 'file', 'files', 'filename', 'file_name',
+    'notebook_path', 'notebookPath', 'target_file', 'source_path', 'destination_path',
+    'source', 'destination', 'directory', 'dir', 'cwd', 'workdir', 'root',
+    'output_path', 'input_path',
+]);
+/**
+ * Argument keys whose values are shell command lines. Their tokens are tested
+ * as paths; see {@link pathCandidates} for why that is advisory.
+ */
+export const SHELL_ARGUMENT_KEYS = new Set(['command', 'cmd', 'script', 'shell_command']);
+/**
+ * Collect the path-typed strings inside one tool's arguments, at any depth.
+ *
+ * A key names paths for every tool that uses it: the tool registry is open, so
+ * a per-tool table would abstain on every plugin and MCP tool this build has
+ * never heard of.
+ * @param args - the pending call's parsed arguments.
+ * @returns each path-typed string, labelled with whether it is a command line.
+ */
+export function pathArguments(args) {
+    const found = [];
+    const collect = (node, shell) => {
+        if (typeof node === 'string') {
+            found.push({ text: node, shell });
+            return;
+        }
+        if (Array.isArray(node)) {
+            for (const item of node)
+                collect(item, shell);
+            return;
+        }
+        if (typeof node === 'object' && node !== null) {
+            for (const item of Object.values(node))
+                collect(item, shell);
+        }
+    };
+    const walk = (node) => {
+        if (Array.isArray(node)) {
+            for (const item of node)
+                walk(item);
+            return;
+        }
+        if (typeof node !== 'object' || node === null)
+            return;
+        for (const [key, value] of Object.entries(node)) {
+            if (PATH_ARGUMENT_KEYS.has(key)) {
+                collect(value, false);
+                continue;
+            }
+            if (SHELL_ARGUMENT_KEYS.has(key)) {
+                collect(value, true);
+                continue;
+            }
+            walk(value);
+        }
+    };
+    walk(args);
+    return found;
+}
+/**
+ * Tools that provably cannot move data off the machine: they read local
+ * state, edit local files, or talk only to the session itself.
+ *
+ * Anything absent from this set — every shell, `run_code`, the web tools,
+ * every `mcp__*` tool, and any plugin tool this build has never heard of — is
+ * treated as egress-capable. Unknown defaults to the safe side.
+ */
+export const LOCAL_TOOLS = new Set([
+    'read', 'read_image', 'glob', 'grep',
+    'write', 'edit', 'str_replace_editor',
+    'todo_write', 'ask_user_question',
+    'create_goal', 'get_goal', 'update_goal',
+    'session_search', 'session_trace',
+    'session_event_read', 'session_event_search', 'session_event_trace',
+    'list_agents', 'job_list', 'job_output',
+    'terminal_list', 'terminal_read',
+    'lsp',
+]);
+/**
+ * Whether a tool can move data off the machine.
+ * @param toolName - the executing tool's registered name.
+ * @param extraEgressTools - names the repo-local policy tier added.
+ * @returns `true` when the tool is not a known local-only tool.
+ */
+export function isEgressCapable(toolName, extraEgressTools = new Set()) {
+    if (extraEgressTools.has(toolName))
+        return true;
+    return !LOCAL_TOOLS.has(toolName);
+}