@sema-agent/core 7.10.0 → 7.11.0

package/dist/core/gate-lanes.js

@@ -5,6 +5,9 @@ import { inlineUntrusted } from "./untrusted-text.js";
 import { isRuleBehavior } from "./permission-rule-model.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 import { applyPersistedTightening, disclosedRuleSet } from "./persisted-rule-arms.js";
+import { readOnlyShellVerdict } from "./read-only-shell.js";
+import { COMMAND_RULE_TOOL } from "./permission-rule-model.js";
+import { catalogRuleFaceOf } from "./tool-registry.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, settleOrgVerdictWithin } from "./permission-rule-org.js";
 import { exitGate, traceHookCrash } from "./runner/gate-exit.js";
 function isPlainOwnRecord(x) {
@@ -144,15 +147,17 @@ export function normalizePersistedRuleHit(hit) {
 export function persistedRuleMandateOf(marks) {
     return marks.probeMandated === true
         ? "probe_mandate"
-        : marks.egress === true
-            ? "tool_marks"
-            : marks.shellGated === true
-                ? marks.irreversibility === "always"
-                    ? "operator_always"
-                    : undefined
-                : marks.irreversibility === "always" || marks.irreversibility === "maybe"
-                    ? "tool_marks"
-                    : undefined;
+        : marks.probeUnanswered === true
+            ? "probe_unanswered"
+            : marks.egress === true
+                ? "tool_marks"
+                : marks.shellGated === true
+                    ? marks.irreversibility === "always"
+                        ? "operator_always"
+                        : undefined
+                    : marks.irreversibility === "always" || marks.irreversibility === "maybe"
+                        ? "tool_marks"
+                        : undefined;
 }
 function parkWith(suspendAsk, parkArgs, carry) {
     return suspendAsk(...parkArgs, carry);
@@ -160,9 +165,11 @@ function parkWith(suspendAsk, parkArgs, carry) {
 export async function runGateLanes(pass) {
     const { input, toolName, toolCallId, callSignal, ledger, notifier, screening, adjudicate, resolveAsk, suspendAsk } = pass;
     let orgRealApprovalRequired = false;
+    let markedThisRound;
+    const markedUnresolvable = () => (markedThisRound ??= input.isMarkedUnresolvable?.(input.event.toolCallId) === true);
     const askOriginFacts = (org, ruleStore) => ({
         contentQuestion: toolName === ASK_USER_QUESTION_TOOL_NAME,
-        markedUnresolvable: input.isMarkedUnresolvable?.(input.event.toolCallId) === true,
+        markedUnresolvable: markedUnresolvable(),
         org,
         ...(ruleStore !== undefined ? { ruleStore } : {}),
         tightened: pass.tightenedBy,
@@ -269,6 +276,7 @@ export async function runGateLanes(pass) {
             pass.deniedBy = "persisted_rule";
     }
     if (pass.decision.action === "ask") {
+        pass.decision = { ...pass.decision };
         if (pass.policyRewrite !== undefined) {
             pass.currentInput = pass.policyRewrite;
             pass.req.args = pass.policyRewrite;
@@ -278,18 +286,19 @@ export async function runGateLanes(pass) {
             shellGated: input.shellGated,
             irreversibility: input.irreversibility,
             probeMandated: pass.decision.action === "ask" && pass.decision.probeMandated === true,
+            probeUnanswered: pass.probeUnanswered === true,
         });
         let personalEvidence = { dotsAbsent: input.persistedRules === undefined ? "not_wired" : "not_adjudicated" };
         if (laneAnswer?.unreadable === true)
             personalEvidence = { dotsAbsent: "unavailable" };
         let laneCoverage;
-        if (input.persistedRules &&
-            !orgRealApprovalRequired &&
+        const allowLayerMayClear = () => !orgRealApprovalRequired &&
             pass.decision.action === "ask" &&
             pass.decision.requiresRealApproval !== true &&
             pass.decision.decisionReason !== "hook" &&
             pass.req.toolName !== ASK_USER_QUESTION_TOOL_NAME &&
-            input.isMarkedUnresolvable?.(input.event.toolCallId) !== true) {
+            !markedUnresolvable();
+        if (input.persistedRules && allowLayerMayClear()) {
             const answer = laneAnswer ?? {};
             const hitRules = answer.hit?.behavior === "allow" ? answer.hit.rules : undefined;
             laneCoverage = answer.coverage;
@@ -328,11 +337,13 @@ export async function runGateLanes(pass) {
                 const shownRule = disclosedRuleSet(hitRules);
                 const mandateNoun = persistedRuleMandate === "probe_mandate"
                     ? "the reversibility check declared this call structurally gated (the built-in shell check raises this for a read outside the directories allowed for this session) — it is cleared by confirming this call, never by a standing allow rule"
-                    : persistedRuleMandate === "operator_always"
-                        ? "this deployment mandates per-call confirmation for shell commands (shellGate: always)"
-                        : persistedRuleMandate !== undefined
-                            ? "this tool carries egress/irreversibility marks (a mandated confirmation a rule cannot clear)"
-                            : "an explicit ask rule matched this call (a person's ask-me-each-time outranks a standing allow rule)";
+                    : persistedRuleMandate === "probe_unanswered"
+                        ? "the reversibility check did not answer for this call (it timed out or failed), so whether the call reads outside the directories allowed for this session is unknown — it is cleared by confirming this call, never by a standing allow rule"
+                        : persistedRuleMandate === "operator_always"
+                            ? "this deployment mandates per-call confirmation for shell commands (shellGate: always)"
+                            : persistedRuleMandate !== undefined
+                                ? "this tool carries egress/irreversibility marks (a mandated confirmation a rule cannot clear)"
+                                : "an explicit ask rule matched this call (a person's ask-me-each-time outranks a standing allow rule)";
                 pass.decision = {
                     ...pass.decision,
                     persistedRuleShadowed: shownRule,
@@ -347,6 +358,21 @@ export async function runGateLanes(pass) {
             const stamped = { ...pass.decision, ruleEvidence: mintRuleEvidence(personalEvidence), ...(laneCoverage !== undefined ? { segmentCoverage: laneCoverage } : {}) };
             pass.decision = { ...stamped, origin: askOriginOf(stamped, originFacts) };
         }
+        if (allowLayerMayClear() && pass.decision.action === "ask" && persistedRuleMandate === undefined && pass.decision.matchedAskRule === undefined && pass.req.toolName === COMMAND_RULE_TOOL) {
+            const commandParam = catalogRuleFaceOf(COMMAND_RULE_TOOL)?.primaryParams[0] ?? "command";
+            const args = pass.req.args;
+            const command = typeof args === "object" && args !== null && !Array.isArray(args) ? args[commandParam] : undefined;
+            const backgrounded = typeof args === "object" && args !== null && args.run_in_background === true;
+            if (typeof command === "string" && !backgrounded && readOnlyShellVerdict(command).readOnly) {
+                pass.decision = {
+                    action: "allow",
+                    message: "the command is read-only (upstream's read-only command tables) — allowed without asking",
+                    decisionReason: "read_only",
+                    ...(pass.policyRewrite !== undefined ? { updatedInput: pass.policyRewrite } : {}),
+                };
+                await notifier.notifyAsync(() => input.onReadOnlyAllowed?.({ toolName: pass.req.toolName, toolCallId, command }), "toolGate.readOnlyAllowed");
+            }
+        }
         if (pass.decision.action === "ask")
             ledger.supersede();
         if (input.autoMode && pass.decision.action === "ask" && pass.decision.origin !== undefined && classifierMayAnswer(pass.decision.origin)) {
@@ -634,6 +660,7 @@ export async function runGateLanes(pass) {
                         editRewrittenSinceHuman = true;
                     }
                     const editAskSnapshot = { ...recheck, ruleEvidence: mintRuleEvidence({ dotsAbsent: "not_adjudicated" }) };
+                    markedThisRound = undefined;
                     const editAskDecision = { ...editAskSnapshot, origin: askOriginOf(editAskSnapshot, askOriginFacts(editOrg.org, editRuleStore)) };
                     const editAskReq = { toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) };
                     const rr = await (callSignal !== undefined ? resolveAsk(editAskDecision, editAskReq, callSignal) : resolveAsk(editAskDecision, editAskReq));

package/dist/core/hooks.d.ts

@@ -1511,6 +1511,19 @@ export interface ToolGateInput {
             rules: readonly string[];
         }) => void;
     };
+    /**
+     * #619 — observation sink for a shell call the READ-ONLY reader cleared (`readOnlyShellVerdict`, the
+     * allow layer's second member beside the persisted allow rule: consulted for the shell tool only, after
+     * the person's allow rules, under the SAME consumption predicate — never over a mandated ask, a hook's
+     * ask, an explicit ask rule, governance or a marked call). The allow-side disclosure of "why did this run
+     * without asking me?" for that arm; `command` is the FINAL command the gate judged (a policy rewrite
+     * included). Never affects the outcome. Absent ⇒ the arm still runs, silently.
+     */
+    onReadOnlyAllowed?: (info: {
+        toolName: string;
+        toolCallId: string;
+        command: string;
+    }) => void;
     /**
      * design/182 §7 — the ORG layer. Present ONLY when the deployment DECLARED org governance (the
      * overlay constructor is the boot gate: a governed declaration with no snapshot provider refuses to

package/dist/core/permission-rule-model.d.ts

@@ -499,7 +499,7 @@ export declare function formatRuleText(command: string, match: PersistedRuleMatc
 /**
  * The closed set of BASES a path-form pattern resolves against — facts of the CALL (its execution
  * environment and its task), never of the rule:
- *  - `cwd`  — a relative pattern (`dist/**`, `./x`): the live tracked working directory; when no tracker
+ *  - `cwd`  — a relative pattern (`dist/**`, `./x`, a bare `x` read at any depth): the live tracked working directory; when no tracker
  *             moved (or the caller keeps none) the task root stands in for it — that stand-in is the WORD's
  *             own meaning (the same reading `TOOL_PATH_BASES.cwd` gives a tool's relative slot), not a
  *             fallback to a different base;
@@ -544,7 +544,9 @@ export declare function isUsablePathBase(base: string | undefined): boolean;
  * does this deny/ask rule reach the call's target path? The target is the caller's ALREADY-RESOLVED
  * lexical-normal absolute path (the same identity the read/write fences judge with). A `subpath` rule
  * reaches the directory and everything under it ({@link directoryRuleAdmits}); a `path` rule resolves its
- * spelling against the call's bases and matches segment-wise (`*` within a segment, `**` across
+ * spelling against the call's bases ({@link resolvePathPattern} — a cwd-relative bare name reads at any
+ * depth, a trailing `/**` peeled first and, for that peeled form alone, by the rule's BEHAVIOR:
+ * `path_rule.bare_name`) and matches segment-wise (`*` within a segment, `**` across
  * segments), reaching the path it names and everything under a directory it names. A command-family rule
  * reaches no path. `unreadable` (#644): the pattern needs a base the call did not supply (or supplied as
  * a non-absolute spelling) — the rule CANNOT be judged, and the answer says which base; a lane that must
@@ -553,7 +555,7 @@ export declare function isUsablePathBase(base: string | undefined): boolean;
  * defect (a `~/` deny falling back to the engine host's home guarded the wrong directory; a `/…` deny with
  * no root reached nothing at all).
  */
-export declare function pathRuleReachOf(rule: Pick<PersistedRule, "match" | "command">, target: string, bases: PathRuleBases): ProgramRunReachOutcome;
+export declare function pathRuleReachOf(rule: Pick<PersistedRule, "match" | "command" | "behavior">, target: string, bases: PathRuleBases): ProgramRunReachOutcome;
 /**
  * Does this rule's command pattern admit `command`?
  *

package/dist/core/permission-rule-model.js

@@ -363,7 +363,7 @@ function baseValueOf(base, bases) {
         }
     }
 }
-function resolvePathPattern(pattern, bases) {
+function resolvePathPattern(pattern, bases, behavior) {
     if (pattern.startsWith("//"))
         return { resolved: "/" + pattern.slice(2) };
     const needed = ruleBasesNeeded({ match: "path", command: pattern })[0];
@@ -371,7 +371,11 @@ function resolvePathPattern(pattern, bases) {
     if (normal === undefined)
         return { missingBase: needed };
     const rest = pattern.startsWith("~/") ? pattern.slice(2) : pattern.startsWith("/") ? pattern.slice(1) : pattern.startsWith("./") ? pattern.slice(2) : pattern;
-    return { resolved: (normal === "/" ? "" : normal) + "/" + rest };
+    const peeled = rest.endsWith("/**") ? rest.slice(0, -3) : rest;
+    const bare = needed === "cwd" && peeled !== "" && !peeled.includes("/");
+    const anyDepth = bare && (peeled === rest || behavior !== "allow");
+    const body = anyDepth ? "**/" + peeled : rest;
+    return { resolved: (normal === "/" ? "" : normal) + "/" + body };
 }
 export function isUsablePathBase(base) {
     return base !== undefined && lexicalNormalAbsolutePathOf(base) !== undefined;
@@ -423,7 +427,7 @@ export function pathRuleReachOf(rule, target, bases) {
         return NOT_REACHED;
     if (!isLexicalNormalAbsoluteDir(target) && target !== "/")
         return NOT_REACHED;
-    const r = resolvePathPattern(rule.command, bases);
+    const r = resolvePathPattern(rule.command, bases, rule.behavior);
     if ("missingBase" in r) {
         return { reach: "unreadable", reason: `the rule is relative to ${PATH_RULE_BASE_LABEL[r.missingBase]} and this call supplies no absolute \`${r.missingBase}\` base to resolve it against` };
     }

package/dist/core/persisted-rule-arms.js

@@ -39,11 +39,12 @@ export function applyPersistedTightening(decision, read) {
             tightened: "ask",
         };
     }
+    const asked = { ...decision };
     return {
         decision: {
-            ...decision,
-            ...(decision.matchedAskRule === undefined ? { matchedAskRule: shown } : {}),
-            message: `${decision.message !== undefined ? `${decision.message} ` : ""}(a persisted ask rule (${shown}) also requires approval for this call)`,
+            ...asked,
+            ...(asked.matchedAskRule === undefined ? { matchedAskRule: shown } : {}),
+            message: `${asked.message !== undefined ? `${asked.message} ` : ""}(a persisted ask rule (${shown}) also requires approval for this call)`,
         },
         tightened: "ask",
     };

package/dist/core/read-only-shell-table.d.ts

@@ -0,0 +1,87 @@
+/**
+ * The READ-ONLY shell tables — the closed data the read-only reader (`read-only-shell.ts`) judges a
+ * command against, transcribed from upstream's own tables (CC 2.1.250) and kept as DATA so the parity
+ * question is answered by diffing two tables, never by reading two programs:
+ *  - {@link READ_ONLY_COMMAND_TABLE} — the flag-vetted commands: a command (one or more leading words,
+ *    `git status`, `gh pr view`, `grep`) with the closed set of flags it may carry, each flag's value
+ *    ARITY, and where upstream carries one, its extra danger predicate over the remaining words
+ *    (upstream `w3t` + `tqe` + `nqe` + `XGn` + `JGn` + `dmt`);
+ *  - {@link READ_ONLY_BARE_PROGRAMS} — programs read-only under ANY literal arguments (upstream `jpe`);
+ *  - {@link READ_ONLY_GLOB_PROGRAMS} — the programs a segment carrying a GLOB may still be read-only
+ *    under (upstream `B3t`; a glob may expand to any name, so only a program that cannot write however
+ *    it is named is admitted);
+ *  - {@link READ_ONLY_EXACT_FORMS} / {@link READ_ONLY_BARE_ONLY} — whole-command forms (`node -v`) and
+ *    programs admitted only bare (`pwd`) (upstream `N3t` / `D3t`);
+ *  - {@link FIND_ACTION_PRIMARIES} / {@link FIND_VALUE_PRIMARIES} / {@link FIND_NEWER_PRIMARY} — the
+ *    `find` primaries that ACT (write, execute) and the ones that take a value (upstream `I3t`/`smt`/`amt`);
+ *  - {@link READ_ONLY_ENV_NAMES} — the environment variables a read-only command may be prefixed with
+ *    (upstream `nH`: a variable that cannot change what a program DOES);
+ *  - {@link XARGS_READ_ONLY_TARGETS} — the programs `xargs` may hand its input to (upstream `v3t`).
+ *
+ * NOT transcribed, each a stated gap rather than a silent one: `sed` (upstream vets the sed SCRIPT with a
+ * dedicated analyzer; without it a `sed` is not read-only here — fail-closed), the Windows PowerShell table
+ * and every Windows-only arm (UNC paths), and the two filesystem probes upstream runs beside the tables (a
+ * bare-repository indicator check and a `.git` redirection check — a shell tool here has no filesystem seat).
+ *
+ * Every predicate over the remaining words receives the words AFTER the command's own (upstream's `t`),
+ * dequoted. Upstream's substitution placeholders never appear here: a word carrying an expansion has
+ * already taken the whole command out of the read-only reading before a table is consulted.
+ */
+import type { AssertAllKeysHandled } from "./ask-origin.js";
+/** How many words a flag's VALUE takes, and what the value must look like (upstream `ni`): `none` — the flag
+ *  takes no value (`--flag=x` is refused); `number` — one word of digits; `string` — one word, any text
+ *  (a value that starts with `-` is refused: it is another flag); `char` — one word of length 1; `{}` and
+ *  `EOF` — one word spelled exactly so (`xargs -I {}`, `xargs -E EOF`). Registered in docs/CLOSED-SETS.md. */
+export declare const READ_ONLY_FLAG_ARITIES: readonly ["none", "number", "string", "char", "{}", "EOF"];
+export type ReadOnlyFlagArity = (typeof READ_ONLY_FLAG_ARITIES)[number];
+/** The disposition table over the arity set: does `value` satisfy the arity? (`none` accepts NO value.) */
+export declare const FLAG_VALUE_ACCEPTS: {
+    readonly none: () => boolean;
+    readonly number: (value: string) => boolean;
+    readonly string: () => boolean;
+    readonly char: (value: string) => boolean;
+    readonly "{}": (value: string) => boolean;
+    readonly EOF: (value: string) => boolean;
+};
+/** Compile-time fence: `never` while every arity has a row. */
+export type FlagArityTableCoversEveryArity = AssertAllKeysHandled<Exclude<ReadOnlyFlagArity, keyof typeof FLAG_VALUE_ACCEPTS>>;
+/** One row of {@link READ_ONLY_COMMAND_TABLE}. */
+export interface ReadOnlyCommandRow {
+    /** Flag → the arity of its value. A flag not in the table refuses the command (a short cluster `-abc`
+     *  is admitted only when every letter is a `none` flag). */
+    readonly safeFlags: Readonly<Record<string, ReadOnlyFlagArity>>;
+    /** `false`: a `--` word is skipped like any other rather than ending the flag walk (the words after it
+     *  keep being vetted). Default: `--` ends the walk and the rest are operands. */
+    readonly respectsDoubleDash?: false;
+    /** Upstream carries a whole-text regex for this row; expressed here over the remaining words. */
+    readonly wordsShape?: (args: readonly string[]) => boolean;
+    /** Upstream's `additionalCommandIsDangerousCallback` over the remaining words: `true` refuses. */
+    readonly dangerous?: (args: readonly string[]) => boolean;
+}
+export declare const dockerRetargetDanger: (args: readonly string[]) => boolean;
+/**
+ * The flag-vetted command table (upstream `w3t` and everything it spreads; `sed` withheld — see the module
+ * note). Keys with a space are multi-word commands and are matched on the leading words.
+ */
+export declare const READ_ONLY_COMMAND_TABLE: Readonly<Record<string, ReadOnlyCommandRow>>;
+/** Programs read-only under any LITERAL arguments (upstream `jpe`): `cat x`, `wc -l x`, `diff a b`, `sleep 3`…
+ *  The two-word `docker ps` / `docker images` are matched on both words. */
+export declare const READ_ONLY_BARE_PROGRAMS: readonly ["docker ps", "docker images", "cal", "uptime", "cat", "head", "tail", "wc", "stat", "strings", "hexdump", "od", "nl", "id", "uname", "free", "df", "du", "locale", "groups", "nproc", "basename", "dirname", "realpath", "cut", "paste", "tr", "column", "tac", "rev", "fold", "expand", "unexpand", "fmt", "comm", "cmp", "numfmt", "readlink", "diff", "true", "false", "sleep", "which", "type", "expr", "seq", "tsort", "pr"];
+/** Programs a segment carrying a GLOB may still be read-only under (upstream `B3t`): the glob may name
+ *  anything, so only a program that writes nothing whatever it is handed. */
+export declare const READ_ONLY_GLOB_PROGRAMS: readonly ["ls", "cat", "head", "tail", "wc", "stat", "grep", "egrep", "fgrep", "diff", "du", "df", "echo", "strings", "hexdump", "od", "nl", "cut", "column", "tr", "tac", "rev", "cmp", "basename", "dirname", "realpath", "readlink", "sha256sum", "sha1sum", "md5sum", "cd"];
+/** Whole-command forms admitted exactly as spelled (upstream `N3t`). */
+export declare const READ_ONLY_EXACT_FORMS: readonly (readonly string[])[];
+/** Programs admitted only BARE (upstream `D3t`: `pwd`, `whoami`, `alias` — with an operand `alias` DEFINES one). */
+export declare const READ_ONLY_BARE_ONLY: readonly ["pwd", "whoami", "alias"];
+/** `find` primaries that ACT — delete, execute, write a file (upstream `I3t`). */
+export declare const FIND_ACTION_PRIMARIES: readonly ["-delete", "-exec", "-execdir", "-ok", "-okdir", "-fprint", "-fprint0", "-fls", "-fprintf", "-files0-from"];
+/** `find` primaries that take ONE value word (the value is skipped, not vetted) (upstream `smt`). */
+export declare const FIND_VALUE_PRIMARIES: readonly ["-name", "-iname", "-path", "-ipath", "-lname", "-ilname", "-regex", "-iregex", "-wholename", "-iwholename", "-samefile", "-newer", "-anewer", "-cnewer", "-mnewer", "-perm", "-user", "-group", "-uid", "-gid", "-size", "-type", "-xtype", "-fstype", "-inum", "-links", "-used", "-context", "-amin", "-cmin", "-mmin", "-atime", "-ctime", "-mtime", "-mindepth", "-maxdepth", "-printf", "-regextype", "-D", "-f", "-flags", "-Bnewer", "-Btime", "-Bmin", "-files0-from", "-xattrname"];
+/** The `-newerXY` family, a value primary spelled by pattern (upstream `amt`). */
+export declare const FIND_NEWER_PRIMARY: RegExp;
+/** Environment variables a read-only command may be prefixed with (upstream `nH`): locale, colour, terminal
+ *  and toolchain switches that change how output LOOKS, never what a program does to the filesystem. */
+export declare const READ_ONLY_ENV_NAMES: readonly ["GOEXPERIMENT", "GOOS", "GOARCH", "CGO_ENABLED", "GO111MODULE", "RUST_BACKTRACE", "RUST_LOG", "NODE_ENV", "PYTHONUNBUFFERED", "PYTHONDONTWRITEBYTECODE", "PYTEST_DISABLE_PLUGIN_AUTOLOAD", "PYTEST_DEBUG", "ANTHROPIC_API_KEY", "LANG", "LANGUAGE", "LC_ALL", "LC_CTYPE", "LC_TIME", "CHARSET", "TERM", "COLORTERM", "NO_COLOR", "FORCE_COLOR", "TZ", "LS_COLORS", "LSCOLORS", "GREP_COLOR", "GREP_COLORS", "GCC_COLORS", "TIME_STYLE", "BLOCK_SIZE", "BLOCKSIZE", "COLUMNS", "LINES", "CLICOLOR", "CLICOLOR_FORCE", "CI", "DEBIAN_FRONTEND", "GIT_TERMINAL_PROMPT"];
+/** The programs `xargs` may hand its input to and stay read-only (upstream `v3t`). */
+export declare const XARGS_READ_ONLY_TARGETS: readonly ["echo", "printf", "wc", "grep", "egrep", "fgrep", "head", "tail"];