@sema-ai/core 1.275.1

package/dist/core/tool-policy.js

@@ -0,0 +1,567 @@
+import { homedir } from "node:os";
+import { isAbsolute, join, sep } from "node:path";
+import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
+import { canonicalToolName } from "./tool-name-aliases.js";
+/** The human/model-readable text of a decision: `message` wins, falling back to the legacy `reason`. */
+export function decisionText(d) {
+    return d.message ?? d.reason;
+}
+const ALLOW = { action: "allow" };
+/**
+ * Resolve `p`, but if it hasn't settled within `ms`, resolve with `onTimeout()` instead. A
+ * **rejection of `p` propagates** (rejects the returned promise) — it is NOT mislabeled as a timeout,
+ * so a real error (e.g. a throwing `approve`) surfaces with its true cause instead of being silently
+ * turned into the timeout value.
+ */
+function withTimeout(p, ms, onTimeout) {
+    if (!ms || ms <= 0) {
+        return p;
+    }
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const settle = (fn, v) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            fn(v);
+        };
+        // Compute `onTimeout()` lazily, only when the timeout actually wins — never eagerly as a settle
+        // argument (which would run its side effects even on the path where `p` already settled).
+        const timer = setTimeout(() => {
+            if (settled)
+                return;
+            settle(resolve, onTimeout());
+        }, ms);
+        timer.unref?.();
+        p.then((v) => settle(resolve, v), (e) => settle(reject, e));
+    });
+}
+/**
+ * Name-based allow/deny. `deny` always wins. If `allow` is provided, only those tools are permitted
+ * (everything else denied). Without `allow`, everything not in `deny` is permitted.
+ */
+export function createAllowDenyPolicy(opts) {
+    const allow = opts.allow ? new Set(opts.allow.map(canonicalToolName)) : undefined;
+    const deny = new Set((opts.deny ?? []).map(canonicalToolName));
+    return {
+        check(req) {
+            // durable compat: a resumed checkpoint can carry a pre-rename tool name; the sets hold the new (CC) names,
+            // so canonicalize before lookup (identity for live new names). See tool-name-aliases.ts.
+            const toolName = canonicalToolName(req.toolName);
+            if (deny.has(toolName)) {
+                return { action: "deny", reason: `tool "${req.toolName}" is denied by policy` };
+            }
+            if (allow && !allow.has(toolName)) {
+                return { action: "deny", reason: `tool "${req.toolName}" is not in the allowlist` };
+            }
+            return ALLOW;
+        },
+    };
+}
+/**
+ * Human-in-the-loop approval for selected tools. Tools in `requireApproval` call `approve(req)` and
+ * are allowed only if it resolves true; tools in `deny` are always blocked; everything else is allowed
+ * (override with `denyByDefault: true` to allow only `requireApproval` + an explicit `autoAllow`).
+ */
+export function createApprovalPolicy(opts) {
+    const need = new Set(opts.requireApproval.map(canonicalToolName));
+    const deny = new Set((opts.deny ?? []).map(canonicalToolName));
+    const auto = new Set((opts.autoAllow ?? []).map(canonicalToolName));
+    return {
+        async check(req, signal) {
+            // durable compat: canonicalize a possibly-pre-rename persisted tool name before set lookups (identity for new).
+            const toolName = canonicalToolName(req.toolName);
+            if (deny.has(toolName)) {
+                return { action: "deny", reason: `tool "${req.toolName}" is denied by policy` };
+            }
+            if (need.has(toolName)) {
+                if (signal?.aborted) {
+                    return { action: "deny", reason: `approval aborted for "${req.toolName}" (task ended)` };
+                }
+                let ok;
+                try {
+                    ok = await withTimeout(Promise.resolve(opts.approve(req, signal)), opts.approvalTimeoutMs, () => false);
+                }
+                catch (err) {
+                    // A throwing `approve` is fail-closed (deny) but surfaces the real cause — not hidden as a timeout.
+                    return {
+                        action: "deny",
+                        reason: `approval errored for "${req.toolName}": ${err instanceof Error ? err.message : String(err)}`,
+                    };
+                }
+                return ok ? ALLOW : { action: "deny", reason: `approval denied for "${req.toolName}"` };
+            }
+            if (opts.denyByDefault && !auto.has(toolName)) {
+                return { action: "deny", reason: `tool "${req.toolName}" requires explicit allow` };
+            }
+            return ALLOW;
+        },
+    };
+}
+/**
+ * Combine policies with the three-state fold **deny > ask > allow** (design/37): the WORST outcome
+ * across all policies wins. A `deny` short-circuits (nothing can override it); an `ask` does NOT
+ * short-circuit — scanning continues, because a later policy may still `deny` (which outranks ask).
+ * With no deny, the first `ask` wins; with neither, `allow`.
+ *
+ * **Idempotency requirement:** because the fold continues past an `ask` to look for a later `deny`, a
+ * policy's `check()` can be invoked even after an earlier policy returned `ask`. `check()` MUST be
+ * idempotent — repeated calls with the same {@link ToolCallRequest} return the same decision and
+ * accumulate no side effects (e.g. don't fire a duplicate approval notification on each call).
+ */
+export function combinePolicies(...policies) {
+    return {
+        async check(req, signal) {
+            let asked;
+            // A-1 (round-2 audit): an `allow{updatedInput}` rewrite (redact a secret, clamp a path) must NOT be
+            // dropped — the twin of the 1.65 single-policy `runToolGate` fix, missed on the combine path. Cascade
+            // the rewritten args into the NEXT policy (so a later policy audits the redacted args, not stale ones)
+            // and carry the latest rewrite out instead of returning bare ALLOW. Priority is unchanged: deny > ask
+            // > allow. When an `ask` outranks a later rewrite, the rewrite is carried OUT on the ask itself
+            // (`ask.updatedInput`, now part of the type) so the redaction survives human approval — runToolGate's
+            // `policyRewrite` captures it on the ask path (round-2 council confirmed dropping it was a real bug).
+            let current = req;
+            let rewrite;
+            for (const p of policies) {
+                const d = await p.check(current, signal);
+                if (d.action === "deny") {
+                    // Worst outcome — short-circuit. 1.256 复审 MED-2: carry the ACCUMULATED rewrite out on the
+                    // deny (an earlier policy redacted, this one denies) so the deny observer's payload shows
+                    // the final post-rewrite args — the payload contract says "terminal, post-rewrite", and
+                    // returning the bare deny here silently reverted it to the un-redacted originals.
+                    return rewrite?.updatedInput !== undefined ? { ...d, updatedInput: rewrite.updatedInput } : d;
+                }
+                // R-3 (round-3 council): BOTH ask and allow may carry `updatedInput` — cascade it into `current` so
+                // subsequent policies audit the redacted args (not stale ones), and remember it as the LATEST
+                // rewrite (a later policy's redaction must not be lost behind an earlier ask/allow). `asked` still
+                // records the first ask for the deny>ask>allow priority; the rewrite tracking is independent of it.
+                if (d.updatedInput !== undefined) {
+                    current = { ...current, args: d.updatedInput };
+                    rewrite = d;
+                }
+                if (d.action === "ask" && !asked) {
+                    asked = d; // remember the first ask, but keep scanning for a deny that would outrank it
+                }
+            }
+            // An ask carries the LATEST accumulated rewrite forward so a redaction isn't lost when the human
+            // approves (the most recent rewrite wins — it audited the freshest args).
+            if (asked) {
+                const merged = rewrite?.updatedInput;
+                return merged !== undefined ? { ...asked, updatedInput: merged } : asked;
+            }
+            return rewrite ?? ALLOW;
+        },
+    };
+}
+/** The shell tools whose `{ command }` arg a coarse command-name policy parses. Other tools are out of scope. */
+const COARSE_SHELL_TOOLS = ["Bash"];
+/**
+ * design/center §10 — a COARSE allow/deny gate keyed on the LEADING command NAME (`argv[0]`) of a single
+ * simple shell command. It reuses the ONE shared simple-command parser
+ * ({@link import("../tools/fs/index.js").parseLeadingCommandName}) — it does NOT re-implement argv[0] parsing
+ * (a second parser would drift and open a bypass). For a `bash`/`bash_readonly` call it extracts the leading
+ * command name and:
+ *  - if the name is in `deny` → `deny` (deny-wins, matching {@link createAllowDenyPolicy}; NOT last-match-wins,
+ *    which would fight {@link combinePolicies}'s deny>ask>allow fold);
+ *  - else if `allow` is provided and the name is NOT in it → `defaultAction` (`"ask"` default, or `"deny"`);
+ *  - else → `allow`.
+ * A command the parser cannot reduce to a single bare name (it has shell operators / a path-prefix / a leading
+ * env-assignment) is treated by `defaultAction` (fail-toward-gate): such a command is exactly what would bypass
+ * an argv[0] filter, so it should not silently `allow`. NON-shell tools are out of scope → `allow` (this gate
+ * only speaks about shell command names; compose it with other policies for the rest).
+ *
+ * **core ships NO opinionated command list** — only this mechanism. The actual `allow`/`deny` rule set is
+ * injected by the profile/config/deployment.
+ *
+ * ⚠️ **NOT A SANDBOX — coarse filter / defense-in-depth only.** This matches `argv[0]` NAME and nothing else,
+ * so the bypass surface is large and the gate MUST NOT be relied on as containment:
+ *   - command substitution / subshells (`$(curl …)`, backticks), pipes, redirects, `;`/`&&` chaining — all
+ *     rejected as un-parseable here (→ `defaultAction`), so they don't sneak past `allow`, but that is a GATE
+ *     not a guarantee of safety;
+ *   - an indirection wrapper runs an arbitrary inner program under an allowlisted `argv[0]`: `sh -c '…'`,
+ *     `env FOO=bar curl …`, `sudo rm …`, `timeout 5 curl …`, `xargs curl`, `find . -exec rm {} \;`,
+ *     `python -c '…'`, `npm run <script>`, `git <subcommand>` — the inner action is INVISIBLE to an
+ *     argv[0]-name filter. Allowlisting any such wrapper effectively allowlists everything it can launch.
+ * Real isolation is the deployment's sandboxed `executionEnv` (a remote/E2B container with no egress, a
+ * read-only FS, dropped capabilities). Use this only as a cheap first-line coarse filter layered over that.
+ *
+ * 🪤 **TRAP #1 — `TaskSpec.toolPolicy` OVERRIDES (does not merge) `RunnerDeps.toolPolicy`.** A consumer that
+ * sets `TaskSpec.toolPolicy = createCoarseCommandNamePolicy(…)` directly **silently discards the deployment's
+ * baseline policy** (the runner does `spec.toolPolicy ?? deps.toolPolicy`). To LAYER this on top of a baseline
+ * you MUST compose explicitly: `combinePolicies(deploymentBaseline, createCoarseCommandNamePolicy(…))`
+ * (deny-wins — both policies' denies still fire). {@link tightenTaskSpec} does this for you.
+ *
+ * 🪤 **TRAP #2 — under `TaskSpec.shellGate: "classify"`, a plain `ask` from this policy is promoted to a
+ * NON-budgetable `irreversible_ask`.** `shellGate:"classify"` statically marks `bash` `irreversibility:"maybe"`;
+ * the safety gate keys the checkpoint axis on that STATIC tool mark (not on `decisionReason`), so a `bash`
+ * command that doesn't prove reversible suspends as `irreversible_ask` — which a budget-aware escalation
+ * resolver will NEVER auto-approve. Net: combining this policy's `ask` with `shellGate:"classify"` does NOT
+ * give you a budgetable normal-ask on `bash`; it gives a hard human-approval suspend. Choose `shellGate` and a
+ * `defaultAction:"ask"` deliberately.
+ */
+export function createCoarseCommandNamePolicy(opts) {
+    const allow = opts.allow ? new Set(opts.allow) : undefined;
+    const deny = new Set(opts.deny ?? []);
+    const shellTools = new Set(opts.tools ?? COARSE_SHELL_TOOLS);
+    const defaultAction = opts.defaultAction ?? "ask";
+    const fallback = (reason) => defaultAction === "deny"
+        ? { action: "deny", reason, decisionReason: "rule" }
+        : { action: "ask", message: reason, decisionReason: "rule" };
+    return {
+        check(req) {
+            // Out of scope for non-shell tools: this gate only speaks about shell command names.
+            if (!shellTools.has(req.toolName))
+                return ALLOW;
+            const command = req.args?.command;
+            if (typeof command !== "string") {
+                // Can't even read a command string → fail toward the gate (don't silent-allow).
+                return fallback(`tool "${req.toolName}" call has no parseable command string`);
+            }
+            const parsed = parseLeadingCommandName(command);
+            if ("reject" in parsed) {
+                // Un-parseable (operators / path-prefix / env-assignment) = exactly the argv[0]-bypass surface →
+                // route through defaultAction rather than allow.
+                return fallback(`command is not a single simple command (${parsed.reject})`);
+            }
+            if (deny.has(parsed.name)) {
+                return { action: "deny", reason: `command "${parsed.name}" is denied by policy`, decisionReason: "rule" };
+            }
+            if (allow && !allow.has(parsed.name)) {
+                return fallback(`command "${parsed.name}" is not in the allowlist`);
+            }
+            return ALLOW;
+        },
+    };
+}
+// ─── CC 2.1.205/206 auto-mode safety-rule parity (feat(parity-206)) ─────────────────────────────────────────
+//
+// Two rules ported from the CC 2.1.206 auto-mode classifier (bundle-verified, cc206-bundle.js):
+//
+//  1. "Session Transcript Tampering" (206 @~14268700): «Writing to a Claude Code session transcript (the
+//     session `.jsonl` history files under `~/.claude/projects/` or the equivalent configured config dir) —
+//     directly or through shell commands — or forging or altering classifier meta lines … The transcript is
+//     harness-written session state, not an agent working file … Reading transcripts is routine and not this
+//     rule.» → {@link createTranscriptIntegrityPolicy}, keyed on SEMA's real transcript location
+//     (`$AGENT_DATA_DIR ?? ~/.ai-agent` + `/sessions/<sessionId>.jsonl`, stores/file/session-store.ts) — NOT
+//     CC's path.
+//
+//  2. "Unverifiable Deletion Target" (206 @~14248800): «A recursive, forced delete — `rm -rf`/`-fr`/`-Rf`,
+//     `Remove-Item -Recurse -Force`, or an equivalent … — whose target is a shell variable (`$VAR`, `${VAR}`)
+//     or a glob rooted at one … whose value cannot be derived from anything in this transcript: no in-window
+//     assignment … The value came only from earlier command output the classifier never sees, so the blast
+//     radius is unknowable — an empty or unexpected `$VAR` turns `rm -rf "$VAR"/*` into a `$HOME` or
+//     filesystem-root wipe. Fail closed. … the agent re-runs the delete with the resolved literal path written
+//     into the command itself … so the target can be verified» → {@link createUnverifiableDeletePolicy}.
+//
+// DECISION MAPPING (mode surface reviewed): sema has no CC four-state permission mode in core — "auto/bypass
+// mode" here is a headless or `onAsk:"allow"` deployment. CC says the rule «cannot be auto-allowed by a
+// permission rule», but a sema `ask` WOULD be auto-allowed under `onAsk:"allow"` (resolveAsk). So both rules
+// return **deny** (`decisionReason:"safety"`): in the `combinePolicies` deny>ask>allow fold a deny
+// short-circuits and no caller allow/ask/onAsk can override it — the "cannot be auto-allowed" clause becomes
+// structural. Each deny message carries the CC-sanctioned self-serve remediation (rule 2: re-run with the
+// resolved literal path / assign the variable in the same command), so an agent recovers in one turn.
+//
+// ⚠️ Like every argv/text-level gate in this file: COARSE, fail-closed, defense-in-depth — NOT a sandbox.
+// Real containment stays the deployment's executionEnv boundary.
+/** Default well-known-safe variable roots for {@link createUnverifiableDeletePolicy} (the CC rule's
+ *  "well-known-safe temp pattern" carve-out): `rm -rf "$TMPDIR"/<literal>` does not fire. */
+const UNVERIFIABLE_DELETE_SAFE_VARS = ["TMPDIR"];
+/** Wrapper argv[0]s skipped before the `rm` detection (a wrapper/compound keyword must not hide the delete:
+ *  `sudo rm -rf $X`, `if …; then rm -rf $X; fi`, `while …; do rm -rf $X; done`). */
+const DELETE_WRAPPERS = new Set(["sudo", "command", "nohup", "time", "do", "then", "else"]);
+/** Statement splitter for the coarse shell scan: `;` `&`/`&&` `|`/`||` and newlines terminate a
+ *  simple-command window. Parens are NOT split on (that would destroy the `$(…)` substitution marker a
+ *  target check must see); they are stripped at the token level instead. Coarser than a real shell parser
+ *  ON PURPOSE — mangling can only cause a MISSED allow (fail-closed direction) on well-formed deletes. */
+const STATEMENT_SPLIT = /[;&|\n]+/;
+/** Strip shell quoting and grouping punctuation off a token edge for NAME comparisons (`(rm` → `rm`). */
+const stripTokenEdges = (t) => t.replace(/^[("'{]+|[)"'}]+$/g, "");
+/**
+ * Scan a (possibly compound) shell command for a recursive+forced delete whose target cannot be resolved from
+ * the command text itself — the deterministic sema port of CC 2.1.206 "Unverifiable Deletion Target".
+ * Returns a human/model-readable description of the first offending target, or `undefined` when clean.
+ *
+ * Fires on: `rm` with recursive (`-r`/`-R`/`--recursive`) AND force (`-f`/`--force`) flags whose target
+ * contains command substitution, a positional/special parameter, or a variable with NO in-window assignment
+ * (`VAR=…`, `export VAR=…`, `read VAR`, `for VAR in …` earlier in the SAME command string — our verification
+ * window is the single command, stricter than CC's whole-transcript window); `… | xargs rm -rf` (the target
+ * comes from pipe output no gate can see); and `Remove-Item -Recurse -Force` with a `$` target.
+ * Does NOT fire on: literal paths (`rm -rf ./node_modules`), in-window-assigned variables, or
+ * `$TMPDIR/<literal>` (safe-var carve-out; a glob after the safe var still fires).
+ * Out of scope (different CC rules, not this port): `find -delete` sweeps, literal-path destruction.
+ *
+ * Exported for tests.
+ */
+export function findUnverifiableRecursiveDelete(command, safeVars = new Set(UNVERIFIABLE_DELETE_SAFE_VARS)) {
+    const assigned = new Set();
+    const statements = command.split(STATEMENT_SPLIT);
+    for (const stmt of statements) {
+        const tokens = stmt.trim().split(/\s+/).filter(Boolean);
+        let i = 0;
+        // Leading env-assignments (`FOO=bar cmd`) both count as in-window assignments and are skipped.
+        while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) {
+            assigned.add(tokens[i].slice(0, tokens[i].indexOf("=")));
+            i++;
+        }
+        // Wrapper prefixes must not hide the delete (`sudo rm -rf …`, `timeout 5 rm -rf …`, `then rm -rf …`).
+        while (i < tokens.length) {
+            const t = stripTokenEdges(tokens[i]);
+            if (DELETE_WRAPPERS.has(t)) {
+                i++;
+                continue;
+            }
+            if (t === "timeout" && i + 1 < tokens.length) {
+                i += 2; // `timeout <duration>` consumes its duration argument
+                continue;
+            }
+            break;
+        }
+        if (i >= tokens.length)
+            continue;
+        const head = stripTokenEdges(tokens[i]);
+        const headName = head.split("/").pop() ?? head;
+        // In-window assignment forms make a later `$VAR` target verifiable (CC: "no in-window assignment").
+        let m;
+        if ((m = stmt.trim().match(/^(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)=/)))
+            assigned.add(m[1]);
+        if (headName === "read") {
+            for (let j = i + 1; j < tokens.length; j++) {
+                if (!tokens[j].startsWith("-"))
+                    assigned.add(tokens[j].replace(/[^A-Za-z0-9_].*$/, ""));
+            }
+        }
+        if (headName === "for" && tokens[i + 1] && tokens[i + 2] === "in")
+            assigned.add(tokens[i + 1]);
+        // `xargs … rm -r…f…`: the delete target arrives from pipe output — unverifiable by construction.
+        if (headName === "xargs") {
+            const rest = tokens.slice(i + 1).map(stripTokenEdges);
+            const rmAt = rest.findIndex((t) => (t.split("/").pop() ?? t) === "rm");
+            if (rmAt >= 0 && hasRecursiveForce(rest.slice(rmAt + 1))) {
+                return "`xargs rm` with recursive+force flags — the delete targets come from pipe output that cannot be verified";
+            }
+            continue;
+        }
+        // PowerShell `Remove-Item -Recurse -Force $Var` (CC names it explicitly alongside rm -rf).
+        if (/^remove-item$/i.test(headName) || /^ri$/i.test(headName)) {
+            const rest = tokens.slice(i + 1);
+            const recurse = rest.some((t) => /^-recurse$/i.test(t));
+            const force = rest.some((t) => /^-force$/i.test(t));
+            const varTarget = rest.find((t) => !t.startsWith("-") && t.includes("$"));
+            if (recurse && force && varTarget !== undefined) {
+                return `\`Remove-Item -Recurse -Force\` target ${varTarget} is a variable that cannot be verified from this command`;
+            }
+            continue;
+        }
+        if (headName !== "rm")
+            continue;
+        const rest = tokens.slice(i + 1);
+        if (!hasRecursiveForce(rest))
+            continue;
+        // Targets = non-flag tokens (a `--` ends option parsing; everything after is a target).
+        let optionsEnded = false;
+        for (const raw of rest) {
+            if (!optionsEnded && raw === "--") {
+                optionsEnded = true;
+                continue;
+            }
+            if (!optionsEnded && raw.startsWith("-"))
+                continue;
+            const target = raw.replace(/["']/g, "");
+            if (target.includes("$(") || target.includes("`")) {
+                return `\`rm\` recursive+force target ${raw} uses command substitution — the deleted path cannot be verified from this command`;
+            }
+            if (/\$[@*#!?0-9-]/.test(target)) {
+                return `\`rm\` recursive+force target ${raw} uses a positional/special shell parameter that cannot be verified from this command`;
+            }
+            for (const vm of target.matchAll(/\$\{?([A-Za-z_][A-Za-z0-9_]*)\}?/g)) {
+                const name = vm[1];
+                if (assigned.has(name))
+                    continue; // in-window assignment → verifiable, other gates judge the value
+                if (safeVars.has(name)) {
+                    // Safe-var carve-out ONLY for `$SAFE/<literal…>` with no glob — `rm -rf $TMPDIR` bare or
+                    // `$TMPDIR/foo-*` still fires (CC shared-scratch adjacency).
+                    const after = target.slice((vm.index ?? 0) + vm[0].length);
+                    if (/^\/[^*?[\]]+$/.test(after))
+                        continue;
+                }
+                return `\`rm\` recursive+force target ${raw} references $${name}, which has no assignment in this command — an empty or unexpected value could make this a home-directory or filesystem-root wipe`;
+            }
+        }
+    }
+    return undefined;
+}
+/** True when an `rm` argv tail carries BOTH a recursive (`-r`/`-R`/`--recursive`) and a force
+ *  (`-f`/`--force`) flag, combined (`-rf`, `-fR`, `-rfv`) or separate. Options stop at `--`. */
+function hasRecursiveForce(argvTail) {
+    let recursive = false;
+    let force = false;
+    for (const raw of argvTail) {
+        const t = raw.replace(/^["']|["']$/g, "");
+        if (t === "--")
+            break;
+        if (!t.startsWith("-"))
+            continue;
+        if (t === "--recursive")
+            recursive = true;
+        else if (t === "--force")
+            force = true;
+        else if (/^-[A-Za-z]+$/.test(t)) {
+            if (/[rR]/.test(t))
+                recursive = true;
+            if (t.includes("f"))
+                force = true;
+        }
+    }
+    return recursive && force;
+}
+/**
+ * CC 2.1.206 "Unverifiable Deletion Target" parity (auto-mode rule, 2.1.205): DENY a recursive+forced delete
+ * whose target is a variable / substitution that cannot be resolved from the command itself — fail-closed
+ * («Fail closed», 206 bundle). See {@link findUnverifiableRecursiveDelete} for exact firing conditions.
+ * The deny message carries the CC-sanctioned remediation: re-run with the resolved LITERAL path written into
+ * the command (or assign the variable in the same command), so the target becomes verifiable.
+ *
+ * Deny (not ask) on purpose: `onAsk:"allow"` — sema's bypass-mode analog — would auto-approve an ask, and the
+ * CC rule text forbids exactly that («must be explicitly approved … cannot be auto-allowed by a permission
+ * rule»). A deny short-circuits the deny>ask>allow fold, making the invariant structural. Core wires this
+ * policy ALWAYS-ON in the runner's gate composition (prepare-task); it is exported so deployments can also
+ * compose/test it directly.
+ */
+export function createUnverifiableDeletePolicy(opts) {
+    const safeVars = new Set([...UNVERIFIABLE_DELETE_SAFE_VARS, ...(opts?.safeVars ?? [])]);
+    const shellTools = new Set(opts?.tools ?? COARSE_SHELL_TOOLS);
+    return {
+        check(req) {
+            if (!shellTools.has(canonicalToolName(req.toolName)))
+                return ALLOW;
+            const command = req.args?.command;
+            if (typeof command !== "string")
+                return ALLOW; // no command text = nothing for THIS rule; other gates adjudicate
+            const finding = findUnverifiableRecursiveDelete(command, safeVars);
+            if (finding === undefined)
+                return ALLOW;
+            return {
+                action: "deny",
+                decisionReason: "safety",
+                reason: `Unverifiable recursive delete blocked (fail-closed): ${finding}. ` +
+                    `Re-run the delete with the resolved literal path written into the command itself ` +
+                    `(or assign the variable in the same command, e.g. \`DIR=/exact/path; rm -rf "$DIR"\`) so the target can be verified.`,
+            };
+        },
+    };
+}
+/**
+ * CC 2.1.206 "Session Transcript Tampering" parity (auto-mode rule, 2.1.205): DENY shell commands and
+ * file-write tools that would modify sema's OWN session transcripts — the harness-written `.jsonl` session
+ * state under `<dataRoot>/sessions/` (`$AGENT_DATA_DIR ?? ~/.ai-agent`, stores/file/session-store.ts; the
+ * sema analog of CC's `~/.claude/projects/` transcripts, including the first-line `meta` record CC calls the
+ * classifier ground-truth line). A tampered entry feeds every later leg once the session is resumed —
+ * self-erasure of the audit trail — so the deny is unconditional (no ask; see the mapping note above).
+ *
+ * «Reading transcripts is routine and not this rule»: a SINGLE simple command whose argv[0] is in the
+ * read-only allowlist ({@link BASH_READONLY_DEFAULT_ALLOW}) may reference the transcript dir (`ls`, `cat`,
+ * `grep`, …). Anything else that references it — a write command, a redirect/pipe/compound command (which the
+ * shared parser rejects → fail-closed), an `rm`/`mv`/`sed -i` — is denied. `Write`/`Edit` file tools are
+ * denied on an absolute or `~`-rooted `file_path` inside the transcript dir.
+ *
+ * Coarse + textual by design (defense-in-depth, not containment): the match is against the RESOLVED data
+ * root's absolute path plus its `~/…` and `$HOME/…` spellings — a command that reaches the same files through
+ * an unrelated alias/symlink is the sandbox's job. Wired ALWAYS-ON by the runner (prepare-task); exported for
+ * direct composition/tests.
+ */
+export function createTranscriptIntegrityPolicy(opts) {
+    const home = homedir();
+    const defaultRoot = (process.env.AGENT_DATA_DIR ?? join(home, ".ai-agent")).normalize("NFC");
+    const dirs = (opts?.sessionsDirs ?? [join(defaultRoot, "sessions")]).map((d) => d.normalize("NFC").replace(/[\\/]+$/, ""));
+    // Textual spellings a shell command could use for each protected dir: absolute, `~/…`, `$HOME/…`.
+    const textualForms = dirs.flatMap((d) => {
+        const forms = [d];
+        if (d.startsWith(home + sep)) {
+            const rel = d.slice(home.length); // keeps the leading separator
+            forms.push(`~${rel}`, `$HOME${rel}`, `\${HOME}${rel}`);
+        }
+        return forms;
+    });
+    const readAllow = new Set(opts?.readAllow ?? BASH_READONLY_DEFAULT_ALLOW);
+    const shellTools = new Set(opts?.tools ?? COARSE_SHELL_TOOLS);
+    const inProtectedDir = (p) => {
+        const norm = p.normalize("NFC");
+        const abs = norm.startsWith("~" + sep) || norm === "~" ? join(home, norm.slice(1)) : norm;
+        if (!isAbsolute(abs))
+            return false; // relative paths resolve against the task root, not the data dir
+        return dirs.some((d) => abs === d || abs.startsWith(d + sep));
+    };
+    const denyReason = (what) => ({
+        action: "deny",
+        decisionReason: "safety",
+        reason: `Session-transcript write blocked: ${what}. Session transcripts (the .jsonl files under the agent data ` +
+            `dir's sessions/ directory) are harness-written session state, not agent working files — modifying or ` +
+            `deleting them tampers with the run's own audit trail. Reading them (ls/cat/grep as a single simple ` +
+            `command) is fine.`,
+    });
+    return {
+        check(req) {
+            const toolName = canonicalToolName(req.toolName);
+            if (shellTools.has(toolName)) {
+                const command = req.args?.command;
+                if (typeof command !== "string")
+                    return ALLOW;
+                const cmd = command.normalize("NFC");
+                if (!textualForms.some((f) => cmd.includes(f)))
+                    return ALLOW;
+                const parsed = parseLeadingCommandName(command);
+                if ("name" in parsed && readAllow.has(parsed.name))
+                    return ALLOW; // reading transcripts is routine
+                return denyReason("name" in parsed
+                    ? `\`${parsed.name}\` is not a read-only command`
+                    : "the command references the transcript directory and is not a single read-only command (fail-closed)");
+            }
+            if (toolName === "Write" || toolName === "Edit" || toolName === "NotebookEdit") {
+                const a = req.args;
+                const p = a?.file_path ?? a?.notebook_path;
+                if (typeof p === "string" && inProtectedDir(p)) {
+                    return denyReason(`"${p}" is inside the session-transcript directory`);
+                }
+            }
+            return ALLOW;
+        },
+    };
+}
+/**
+ * Resolve an `ask` decision to a terminal `allow`/`deny` via {@link OnAsk}. Centralizes the headless
+ * auto-deny default, fail-closed error handling, and stable deny reasons so every ask site is
+ * consistent. Never returns `ask`.
+ */
+export async function resolveAsk(req, onAsk, signal) {
+    if (onAsk === "allow") {
+        return { action: "allow", decisionReason: "mode" };
+    }
+    if (onAsk === undefined || onAsk === "deny") {
+        // Headless auto-deny: deterministic, with a reason the model can read and react to.
+        return {
+            action: "deny",
+            message: `approval required for "${req.toolName}" but no approver is wired (headless auto-deny): ${req.message}`,
+            decisionReason: "mode",
+        };
+    }
+    if (signal?.aborted) {
+        return { action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, decisionReason: "mode" };
+    }
+    let ok;
+    try {
+        ok = await onAsk(req, signal);
+    }
+    catch (err) {
+        // Fail-closed: a throwing approver denies, but surfaces the true cause (not hidden as a default).
+        return {
+            action: "deny",
+            message: `approval errored for "${req.toolName}": ${err instanceof Error ? err.message : String(err)}`,
+            decisionReason: "mode",
+        };
+    }
+    return ok
+        ? { action: "allow", decisionReason: "mode" }
+        : { action: "deny", message: `approval denied for "${req.toolName}": ${req.message}`, decisionReason: "mode" };
+}
+//# sourceMappingURL=tool-policy.js.map

package/dist/core/tool-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-policy.js","sourceRoot":"","sources":["../../src/core/tool-policy.ts"],"names":[],"mappings":"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"}

package/dist/core/tool-result-budget.d.ts

@@ -0,0 +1,44 @@
+import type { AgentMessage } from "../internal/harness.js";
+import { type ToolResultStore } from "./tool-result-store.js";
+/**
+ * Per-message aggregate tool-result budget (design/64 §17.2 / §24 — CC `MAX_TOOL_RESULTS_PER_MESSAGE_CHARS`,
+ * `constants/toolLimits.ts:49`). A single turn's batch of N parallel tool results can each be under the
+ * per-tool offload threshold yet SUM past the model/API limit (10×40K = 400K). This caps the aggregate of
+ * one turn's tool_result batch: while over budget, the LARGEST fresh non-exempt result is offloaded to a
+ * preview (largest-first), repeating until the batch fits.
+ *
+ * **Simpler than CC by construction (§24.2):** a request-only, non-destructive transform (returns a new
+ * array; the durable session keeps full results) applied in the existing `harness.on("context")` hook —
+ * the same per-query point as `clearStaleToolResults` (the mirror of CC's query.ts:379). It is DETERMINISTIC
+ * (stable `ref = tr_<sessionId>_<toolCallId>` + deterministic {@link buildPreview}), so re-running it every
+ * query yields byte-identical previews → prompt-cache safe **without** CC's ContentReplacementState freeze
+ * machine (the determinism IS the freeze), and resume-free (the transcript holds originals; this re-applies
+ * on replay). Reuses design/30's offload store + preview format; with no store it falls back to a
+ * self-contained head+tail truncation preview that still bounds the request.
+ */
+/** CC's per-message cap (chars, not tokens — the "100K token" figure in old notes was unsourced). */
+export declare const AGGREGATE_TOOL_RESULT_BUDGET_CHARS = 200000;
+export interface AggregateBudgetOptions {
+    /** Per-batch char budget. Default {@link AGGREGATE_TOOL_RESULT_BUDGET_CHARS}. */
+    budgetChars?: number;
+    /** Tool names exempt from the budget (their own caps bound them) — e.g. read_file, read_tool_result. */
+    exemptTools?: ReadonlySet<string>;
+    /** design/30 store for offload+read-back. Absent ⇒ self-contained truncation preview. */
+    store?: ToolResultStore;
+    /** Namespaces the stable ref so an offloaded result is globally addressable. */
+    sessionId: string;
+    /** service [398] C8: fired once per result actually capped (offloaded OR degraded to a truncation
+     *  preview). `storeFallback` = the model LOST read-back for this result (store.put failed / no store)
+     *  — the silent-degradation face this callback exists for. Must not throw (caller-side contract). */
+    onCapped?: (info: {
+        tool?: string;
+        sizeChars: number;
+        storeFallback: boolean;
+    }) => void;
+}
+/** Default exemptions: tools whose result is self-bounded (read_file errors at its own token cap; the
+ *  offload reader pages small slices). grep/bash/glob/web_fetch/MCP are the risk sources, NOT exempt. */
+export declare const DEFAULT_BUDGET_EXEMPT_TOOLS: ReadonlySet<string>;
+/** Cap each over-budget turn-batch (run of consecutive tool_result messages). Request-only; see file docs. */
+export declare function capAggregateToolResults(messages: AgentMessage[], opts: AggregateBudgetOptions): Promise<AgentMessage[]>;
+//# sourceMappingURL=tool-result-budget.d.ts.map