@sema-agent/core 7.41.0 → 7.42.0

package/dist/core/synthetic-read-verdict.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The synthetic-Read DENY judge — "would a `Read` of this file be refused outright?", asked without a call,
+ * without an approver and without a hook. One judge, one set of layers, for every consumer that needs the
+ * answer for a file the model did not itself ask to read (the changed-file notice today; a user's
+ * attachment next). It answers in THREE states and never picks a direction:
+ *
+ *   deny          — some layer refuses it;
+ *   no_objection  — every layer it consulted answered and none refused (an `ask` is not a refusal);
+ *   unanswerable  — no layer refused, and at least one could not answer (see the table below).
+ *
+ * The CONSUMER decides where `unanswerable` goes: a notice that merely tells the model a file changed
+ * reads it as no objection (the worst case is a notice about a file it then cannot re-read); a face that
+ * would put a file's contents in front of the model reads it as a refusal.
+ *
+ * THE LAYERS (every one that can refuse a model's own `Read`): the run's skill deny rows; the
+ * deny-narrowing fold (session rules, inherited ancestor rules, frozen constraint projections); the
+ * deployment's caller policy; each live inherited parent policy; the person's persisted-rule lane; the org
+ * lane. Not consulted, by design: PreToolUse hooks (the deployment's screening of a model's CALL), the
+ * permission mode's write gate and the integrity guards (neither refuses a read), and the read-deny table
+ * and containment roots (the path's own resolution judges those before this judge is asked). A deny
+ * anywhere wins over an unanswerable layer elsewhere.
+ *
+ * FAULT → STATE (the live gate's own readings, through the same functions — never a second copy):
+ *   | layer                       | fault                                                | state                         |
+ *   | skill rows                  | throws                                               | unanswerable `threw`          |
+ *   | narrowing fold              | throws / exceeds the judgment's budget               | unanswerable `threw`/`timed_out` |
+ *   | caller / inherited policy   | throws / times out                                   | unanswerable `threw`/`timed_out` |
+ *   | caller / inherited policy   | its deny carries an engine settlement (an approval   | unanswerable `approval_seat`  |
+ *   |                             | seat that ended unanswered; in a combinePolicies     |                               |
+ *   |                             | composition a rule deny anywhere is returned instead)|                               |
+ *   | persisted lane              | store unreadable, throws, times out (readPersistedRuleLane ⇒ `{unreadable}`) | its rows take no part |
+ *   | persisted lane              | the call cannot be read against the rows (`reason`) — applyPersistedTightening ⇒ `unreadable` | unanswerable `call_unreadable` |
+ *   | org lane                    | unavailable: throws, garbage (readOrgRuleLane)       | unanswerable `org_unavailable` |
+ *   | any layer                   | the judgment's budget (one dependency timeout, or a  | unanswerable `timed_out`      |
+ *   |                             | batch's shared deadline) is spent                    | (persisted: rows take no part)|
+ *
+ * NEVER AN APPROVER. A deployment policy (the caller's, an inherited parent's) is consulted with an
+ * ALREADY-ABORTED signal and no approver seat: the `ToolPolicy.check` contract is that an aborted signal
+ * releases a pending approval, and every engine policy factory checks it before reaching a seat (the
+ * approval factory answers a deny attested `task_aborted`, read here as `approval_seat`; the inherited
+ * PreToolUse constraint does the same before invoking its hook). A deny that carries no engine settlement
+ * is a rule's deny and stands. RESIDUALS (stated, not closed): a deployment closure that reaches an
+ * approver before it reads its signal can still be asked; a deployment wrapper that answers an aborted
+ * signal with a deny of its own (no settlement) is read as a deny — the attachment face then withholds,
+ * the notice face stays silent. The engine's own layers (narrowing, skill rows, the two lanes) get the
+ * run's real signal: they are pure matchers and store reads.
+ *
+ * THE PROBE'S IDENTITY. Every layer sees `toolName: "Read"`, the probed arguments, and the stable synthetic
+ * call id `<face>-visibility-probe` ({@link syntheticReadProbeId}), so a deployment's audit can tell a
+ * visibility probe from a model's call.
+ */
+import type { ToolCallRequest, ToolCallFace, ToolPolicy } from "./tool-policy.js";
+import { type SkillGrantLane } from "./skill-grant.js";
+import type { OrgGateVerdict, PersistedRuleAnswer } from "./hooks.js";
+/** The layers the judge consults, as named in its verdicts. */
+export declare const SYNTHETIC_READ_LAYERS: readonly ["skill_rows", "narrowing", "caller_policy", "inherited_constraint", "persisted_rules", "org_rules"];
+export type SyntheticReadLayer = (typeof SYNTHETIC_READ_LAYERS)[number];
+/** Why a layer could not answer — the consumer's disclosure word. */
+export declare const SYNTHETIC_READ_UNANSWERABLE_CAUSES: readonly ["threw", "timed_out", "approval_seat", "call_unreadable", "org_unavailable"];
+export type SyntheticReadUnanswerableCause = (typeof SYNTHETIC_READ_UNANSWERABLE_CAUSES)[number];
+export type SyntheticReadVerdict = {
+    verdict: "deny";
+    layer: SyntheticReadLayer;
+    message?: string;
+} | {
+    verdict: "no_objection";
+} | {
+    verdict: "unanswerable";
+    layer: SyntheticReadLayer;
+    cause: SyntheticReadUnanswerableCause;
+    reason: string;
+};
+export interface SyntheticReadLayers {
+    skillGrants?: Pick<SkillGrantLane, "denying">;
+    denyNarrowingPolicy?: ToolPolicy;
+    callerPolicy?: ToolPolicy;
+    inheritedPolicies?: readonly ToolPolicy[];
+    persistedRuleLane?: {
+        adjudicate: (req: ToolCallRequest) => PersistedRuleAnswer | Promise<PersistedRuleAnswer>;
+    };
+    orgRuleLane?: {
+        adjudicate: (req: ToolCallRequest) => Promise<OrgGateVerdict>;
+    };
+    /** The run's signal, for the engine's own layers. */
+    signal?: AbortSignal;
+}
+/** The arguments a synthetic `Read` carries, and the facts a request stamps. */
+export interface SyntheticReadCall {
+    file_path: string;
+    offset?: number;
+    limit?: number;
+    /** The tracked working directory a relative `file_path` resolves against. */
+    cwd?: string;
+    /** The live roster's face for `Read`, when the consumer has one. */
+    face?: ToolCallFace;
+}
+/** The stable synthetic call id a probe carries: `<face>-visibility-probe`, `face` a lowercase word
+ *  (letters and hyphens) naming the consumer. */
+export declare function syntheticReadProbeId(face: string): string;
+/** One judgment's wait budget. `deadlineAt` (epoch ms) bounds the WHOLE judgment — every layer waits at most
+ *  what is left of it, and a layer reached after it has passed is not consulted (`timed_out`). Absent ⇒ the
+ *  dependency timeout from the start of this judgment. A consumer judging a batch passes one shared deadline,
+ *  so a hung layer costs the batch one bound, not one per file per layer. */
+export interface SyntheticReadBudget {
+    deadlineAt?: number;
+}
+export type SyntheticReadJudge = (call: SyntheticReadCall, face: string, budget?: SyntheticReadBudget) => Promise<SyntheticReadVerdict>;
+export declare function createSyntheticReadJudge(layers: SyntheticReadLayers): SyntheticReadJudge;

package/dist/core/synthetic-read-verdict.js

@@ -0,0 +1,111 @@
+import { describeThrown, engineSettlementOf, refuseOutOfContractDecision } from "./tool-policy.js";
+import { skillRowRefusal } from "./skill-grant.js";
+import { applyPersistedTightening } from "./persisted-rule-arms.js";
+import { readOrgRuleLane, readPersistedRuleLane } from "./rule-lane-reads.js";
+import { ORG_ADJUDICATION_TIMEOUT_MS, settleOrgVerdictWithin } from "./permission-rule-org.js";
+export const SYNTHETIC_READ_LAYERS = Object.freeze(["skill_rows", "narrowing", "caller_policy", "inherited_constraint", "persisted_rules", "org_rules"]);
+export const SYNTHETIC_READ_UNANSWERABLE_CAUSES = Object.freeze(["threw", "timed_out", "approval_seat", "call_unreadable", "org_unavailable"]);
+export function syntheticReadProbeId(face) {
+    if (!/^[a-z][a-z-]*$/.test(face))
+        throw new Error(`syntheticReadProbeId: the probe face must be a lowercase word (letters and hyphens), got ${JSON.stringify(face)}`);
+    return `${face}-visibility-probe`;
+}
+const ABORTED = AbortSignal.abort();
+export function createSyntheticReadJudge(layers) {
+    return async (call, face, budget) => {
+        const deadlineAt = budget?.deadlineAt ?? Date.now() + ORG_ADJUDICATION_TIMEOUT_MS;
+        const left = () => Math.max(0, Math.min(ORG_ADJUDICATION_TIMEOUT_MS, deadlineAt - Date.now()));
+        const req = {
+            toolName: "Read",
+            args: { file_path: call.file_path, ...(call.offset !== undefined ? { offset: call.offset } : {}), ...(call.limit !== undefined ? { limit: call.limit } : {}) },
+            toolCallId: syntheticReadProbeId(face),
+            ...(call.cwd !== undefined ? { cwd: call.cwd } : {}),
+            ...(call.face !== undefined ? { face: call.face } : {}),
+        };
+        let unanswered;
+        const cannot = (layer, cause, reason) => {
+            unanswered ??= { verdict: "unanswerable", layer, cause, reason };
+        };
+        const spent = (layer) => {
+            if (left() > 0)
+                return false;
+            cannot(layer, "timed_out", "the judgment's wait budget was spent before this layer was asked");
+            return true;
+        };
+        const policyLayer = async (layer, policy, signal) => {
+            if (spent(layer))
+                return undefined;
+            const waitMs = left();
+            let timedOut = false;
+            const TIMEOUT = Symbol("timeout");
+            let d;
+            try {
+                d = await settleOrgVerdictWithin(Promise.resolve().then(() => policy.check(req, signal)), TIMEOUT, { ...(layers.signal !== undefined ? { signal: layers.signal } : {}), timeoutMs: waitMs, onFallback: () => void (timedOut = true) });
+            }
+            catch (err) {
+                cannot(layer, "threw", describeThrown(err));
+                return undefined;
+            }
+            if (d === TIMEOUT || timedOut) {
+                cannot(layer, "timed_out", `no answer within ${waitMs}ms (or the run ended first)`);
+                return undefined;
+            }
+            let read;
+            try {
+                read = refuseOutOfContractDecision(d);
+            }
+            catch (err) {
+                cannot(layer, "threw", describeThrown(err));
+                return undefined;
+            }
+            if (read.action !== "deny")
+                return undefined;
+            if (engineSettlementOf(d, req) !== undefined) {
+                cannot(layer, "approval_seat", "the policy would ask an approver, who is never consulted for a visibility probe");
+                return undefined;
+            }
+            return { verdict: "deny", layer, ...(read.message !== undefined ? { message: read.message } : {}) };
+        };
+        try {
+            const refusal = skillRowRefusal(layers.skillGrants, req);
+            if (refusal !== undefined)
+                return { verdict: "deny", layer: "skill_rows", ...(refusal.message !== undefined ? { message: refusal.message } : {}) };
+        }
+        catch (err) {
+            cannot("skill_rows", "threw", describeThrown(err));
+        }
+        if (layers.denyNarrowingPolicy !== undefined) {
+            const v = await policyLayer("narrowing", layers.denyNarrowingPolicy, layers.signal);
+            if (v !== undefined)
+                return v;
+        }
+        if (layers.callerPolicy !== undefined) {
+            const v = await policyLayer("caller_policy", layers.callerPolicy, ABORTED);
+            if (v !== undefined)
+                return v;
+        }
+        for (const parent of layers.inheritedPolicies ?? []) {
+            if (parent === layers.callerPolicy)
+                continue;
+            const v = await policyLayer("inherited_constraint", parent, ABORTED);
+            if (v !== undefined)
+                return v;
+        }
+        if (layers.persistedRuleLane !== undefined && !spent("persisted_rules")) {
+            const read = await readPersistedRuleLane(layers.persistedRuleLane, req, layers.signal, left());
+            const tightened = applyPersistedTightening({ action: "allow" }, read).tightened;
+            if (tightened === "deny")
+                return { verdict: "deny", layer: "persisted_rules" };
+            if (tightened === "unreadable")
+                cannot("persisted_rules", "call_unreadable", read.reason ?? "the call could not be read against the rules");
+        }
+        if (layers.orgRuleLane !== undefined && !spent("org_rules")) {
+            const org = await readOrgRuleLane(layers.orgRuleLane, req, layers.signal, left());
+            if (org.status === "unavailable")
+                cannot("org_rules", left() > 0 ? "org_unavailable" : "timed_out", org.disclosures.join("; ") || "organization governance could not be read");
+            else if (org.verdict?.behavior === "deny")
+                return { verdict: "deny", layer: "org_rules", message: `an organization policy rule (${org.verdict.rule}) denies it` };
+        }
+        return unanswered ?? { verdict: "no_objection" };
+    };
+}

package/dist/core/task-spec.d.ts

@@ -975,6 +975,24 @@ export interface TaskSpec {
      * when the person actually invoked one; a mid-turn invocation (one riding a steer) grants nothing.
      */
     userInvokedSkills?: string[];
+    /**
+     * This run's ALLOW RULES — the reference implementation's `allowedTools` (its `--allowedTools` list): each entry, in the
+     * rule grammar a skill's `allowed-tools` reads ({@link SkillSpec.allowedTools}), is a standing yes for this run. A
+     * whole tool name (`Write`, `Bash`), a protocol namespace (`mcp__srv`, `mcp__srv__*`), a shell command rule
+     * (`Bash(git:*)`, `Bash(npm test)`) or a Read directory (`Read(//srv/data/**)`) clears the question the permission
+     * layers raise for a call it covers — read in the allow layer beside a person's stored rules, a skill's list and the
+     * deployment's {@link import("./runner-deps.js").RunnerDeps.allowedTools}, under the same predicate: deny and ask rules
+     * still win, and a question no allow rule clears (a mandated, governance, hook or plan question) is still put to a person,
+     * with the entry disclosed on the card. In `auto` mode an entry that hands over arbitrary code (the whole shell, an
+     * interpreter or launcher prefix) is left to the classifier.
+     *
+     * Lives for this run — the steers it takes in included; a delegated child holds the entries until it ends; a resumed leg
+     * holds them only when its spec supplies them again (they are not written into a checkpoint). An entry this grammar
+     * reads as nothing (`*`, `mcp__*`, a write-path or domain pattern) grants nothing and is announced at the start of the
+     * run (`permission.allowed_tool_not_granted`); a list holding `*` grants nothing at all. A value that is not a list of
+     * strings refuses the run before it starts (`config.invalid_permission_rules`, with its issues).
+     */
+    allowedTools?: readonly string[];
     /**
      * Fraction of the model's context window the `<skills>` listing may spend. Absent ⇒ `0.01` (1%).
      * Domain `(0, 1]`; anything else — including `0`, a string, `NaN` — REFUSES at the door with

package/dist/core/tool-name-readings.d.ts

@@ -130,7 +130,7 @@ export declare const NAME_READINGS: {
         readonly kind: "wire";
         readonly file: string;
     };
-    readonly "skillGrant.names": {
+    readonly "allowEntry.names": {
         readonly kind: "any";
         readonly file: string;
     };

package/dist/core/tool-name-readings.js

@@ -34,7 +34,7 @@ export const NAME_READINGS = {
     "policy.projectionReplay": any(POLICY),
     "policy.sessionRules": any("src/core/runner/session-rule-policy.ts"),
     "policy.sessionRules.effect": wire("src/core/runner/session-rule-policy.ts"),
-    "skillGrant.names": any("src/core/skill-grant.ts"),
+    "allowEntry.names": any("src/core/allow-entry.ts"),
     "skillGrant.binding": wire("src/core/skill-grant.ts"),
     "gate.skillActivationSeat": wire(GATE),
     "policy.permissionRules": any("src/core/permission-rules.ts"),

package/dist/core/tool-policy.d.ts

@@ -159,6 +159,11 @@ export declare function advertisedWritableRootsSeat(seat: {
 /** Declared beside the receipt's list (decision-receipt.ts) — a new member added to either side is a compile error rather
  *  than a silent drift between the type and the screen; re-exported here, the module every consumer of the decision reads. */
 export type { DecisionReason };
+/** The `task_aborted`-attested deny an engine policy answers on an aborted signal instead of reaching a seat. */
+export declare function abortedSeatDeny(req: {
+    toolCallId: string;
+    toolName: string;
+}, message: string, origin: AskOrigin): PermissionResult;
 /** Carry every engine attestation from a decision onto a reconstruction of it — the
  *  seam for the engine's OWN clone sites outside this module (the inherited chain's final-form re-check carries the
  *  post-rewrite args on a spread of an ancestor's deny). Returns the reconstruction. Not re-exported from `src/index.ts`. */
@@ -298,19 +303,17 @@ export type PermissionResult = {
      *  same safe direction as `matchedAskRule`); it cannot state a window of its own, because the
      *  route it would be a window for has not been chosen yet. */
     denialLimitFallback?: import("./auto-mode.js").UnarmedDenialLimitFallback;
-    /** #144 disclosure (additive): a persisted allow rule MATCHED this call but could not clear the
-     *  ask, because the ask is MANDATED (operator shellGate:"always", or the tool's own
-     *  egress/irreversibility marks) rather than a classifier's hesitation — "allow rules silence
-     *  the classifier's questions, never a mandated one". Carries the matched rule text — a covering
-     *  SET (conjunction arm) joins up to five sanitized member texts with an "and N more" tail — so a
-     *  consumer (approval card, wire frame) can tell the person their rule is alive, just outranked.
-     *  Absent ⇒ no rule matched, or the ask was cleared normally. */
-    persistedRuleShadowed?: string;
+    /** The allow layer's DISCLOSURE: the members that MATCHED this call and could not clear the ask (it is a class
+     *  no allow rule clears — a mandated, governance, hook, ask-rule or mode question — or the call reached the layer
+     *  marked), one record per member ({@link AllowRuleShadow}). ENGINE-STAMPED by the allow layer, overwriting a
+     *  policy's own value; a DISPLAY member: the approval card and the park row render it, nothing reads it to
+     *  decide, and the classifier never sees it (it is not part of `message`). Absent ⇒ no member matched. */
+    allowRuleShadowed?: readonly import("./allow-rule-shadow.js").AllowRuleShadow[];
     /** backlog #239 disclosure (additive): WHY the reversibility probe did not clear this call, in the
      *  probe's own words. ENGINE-STAMPED at the irreversibility tighten (which constructs this decision
      *  wholesale), already neutralized + capped there; a `"maybe"` tier whose probe supplied no cause,
      *  and the `"always"` tier (which runs no probe), leave it absent. Same DISPLAY-ONLY posture as
-     *  {@link persistedRuleShadowed}: a policy that self-declares it can only put its own prose on its
+     *  {@link allowRuleShadowed}: a policy that self-declares it can only put its own prose on its
      *  own card — nothing reads this member to decide anything, so it is not an authority channel. */
     probeReason?: string;
     /** backlog #239 disclosure (additive): the STRUCTURED cause, for a probe whose verdict this engine
@@ -370,7 +373,7 @@ export type PermissionResult = {
      *  stamp point whenever the persisted-rule lane reported one (overwriting a policy's claim);
      *  consumed only by the offer factory, which puts on the batch offer exactly the segments this
      *  table calls uncovered. Absent ⇒ all segments read as uncovered (over-offer, the safe way).
-     *  Same display-only posture as {@link persistedRuleShadowed}: never adjudication input, and a
+     *  Same display-only posture as {@link allowRuleShadowed}: never adjudication input, and a
      *  value nobody stamps over can only shrink or annotate the card's ADVISORY offers — every
      *  offered rule still passes the validator at redemption. */
     segmentCoverage?: readonly import("./permission-rule-model.js").SegmentCoverage[];
@@ -451,7 +454,7 @@ export declare const ASK_EVIDENCE_ABSENCE_VALUES: readonly AskEvidenceAbsence[];
  * snapshot's `revision`, the personal rule's add `dot`s — onto the surface a consumer can actually
  * read. It performs no new judgment and changes no verdict; removing it would leave every decision
  * byte-identical. The prose channels ({@link PermissionResult}'s ask `message`,
- * {@link AskRequest.persistedRuleShadowed}) say the same things to a PERSON; those are sanitized,
+ * {@link AskRequest.allowRuleShadowed}) say the same things to a PERSON; those are sanitized,
  * capped, display-shaped strings, and reconciling a decision against a published policy revision by
  * regexing them is not an audit trail. This member is the machine's copy.
  *
@@ -480,7 +483,7 @@ export interface AskRuleEvidence {
      *  #144 shadowed arm) — the deduplicated UNION across the covering set when the conjunction arm
      *  matched, so the array does not belong to one rule on those asks. The dots are the rule's durable
      *  identity — unlike
-     *  {@link AskRequest.persistedRuleShadowed}, which is a sanitized, length-capped DISPLAY value and
+     *  {@link AskRequest.allowRuleShadowed}, which is a sanitized, length-capped DISPLAY value and
      *  deliberately not an identity channel. A rule is a set of adds (concurrent approvals on one text
      *  each redeem their own dot), so this is an array by construction: render/reconcile the entries as
      *  data, never re-derive one scalar id by joining them. Absent ⇒ {@link personalRuleDotsAbsent}. */
@@ -499,12 +502,12 @@ export declare function decisionText(d: PermissionResult): string | undefined;
  *
  * `check` may be async, which is also how **human-in-the-loop approval** works: a deployment can
  * hold the promise open until an operator approves/denies. `signal` fires when the task aborts
- * (timeout / max turns / cancel) and, since design/384, when the asking turn is interrupted (a bare
- * user halt / steer-now boundary cut) — honor it to release a pending approval instead of hanging (F4).
- * The Runner also races `check` against `signal` itself, so a policy that ignores it still cannot
- * hang the worker past the deadline; passing it through just lets you clean up the wait early.
+ * (timeout / max turns / cancel) or the asking turn is interrupted (design/384) — honor it to release a
+ * pending approval (F4; the Runner also races `check` against it). An already-aborted one: see `check`.
  */
 export interface ToolPolicy {
+    /** @contract policy.check.aborted_signal_reaches_nobody — handed an already-aborted signal, `check` reaches no person and
+     *  no external approval (it answers at once, or with a `task_aborted` deny); visibility probes rely on it. */
     check(req: ToolCallRequest, signal?: AbortSignal): PermissionResult | Promise<PermissionResult>;
     /**
      * The policy's CONSTRAINT PROJECTION — its deterministic DENY-verdict half expressed as pure data
@@ -1117,13 +1120,11 @@ export interface AskDelegationProvenance {
  *  (see {@link OnAsk} for the full detached-settlement contract). */
 export interface AskRequest {
     toolName: string;
-    /** A persisted allow rule MATCHED this call but could not clear the ask (mandated — see
-     *  {@link PermissionResult}'s ask arm). The matched rule text — or, when a covering SET admitted the
-     *  command segment-wise (the conjunction arm), a comma-joined display list of up to five sanitized
-     *  rule texts with an "and N more" tail — so the approval card renders "your rule is alive, just
-     *  outranked" instead of leaving the person to regex the message prose. A DISPLAY value, not an
-     *  identity channel: per-rule identity travels on {@link AskRuleEvidence.personalRuleDots}. */
-    persistedRuleShadowed?: string;
+    /** The allow-layer members that MATCHED this call and could not clear the ask (see {@link PermissionResult}'s ask arm),
+     *  one sanitized record per member — so the card renders "your rule is alive, just outranked" from data; the same
+     *  account is rendered once onto {@link message} at this request's mint. A DISPLAY value, not an identity channel:
+     *  a stored rule's identity travels on {@link AskRuleEvidence.personalRuleDots}. */
+    allowRuleShadowed?: readonly import("./allow-rule-shadow.js").AllowRuleShadow[];
     /** WHY the reversibility probe did not clear this call — the account of the tighten the
      *  card was showing WITHOUT until now (the gate knew the cause and dropped it at this seam, leaving the
      *  approver the action but not the reason it is being asked about). Present only for a `"maybe"`-tier
@@ -1213,7 +1214,7 @@ export interface AskRequest {
      * (operator shellGate:"always", the tool's own egress/irreversibility marks, a
      * `requiresRealApproval` demand, or — #502, the one PER-CALL member of that family — a demotion the
      * call's own reversibility probe declared structural, which for the built-in shell probe means a read
-     * outside the session's allowed directories) and an ask carrying {@link persistedRuleShadowed} offer
+     * outside the session's allowed directories) and an ask carrying {@link allowRuleShadowed} offer
      * none.
      *
      * CONTRACT — see {@link import("./permission-rule-model.js").RuleOffer} for the closed union, the

package/dist/core/tool-policy.js

@@ -36,6 +36,9 @@ function attestEngineSettlement(d, record, call) {
     ENGINE_SETTLEMENTS.set(d, { settlement, origin: record.origin, toolCallId: call.toolCallId, toolName: call.toolName });
     return d;
 }
+export function abortedSeatDeny(req, message, origin) {
+    return attestEngineSettlement({ action: "deny", message }, { settlement: settledByNobody("task_aborted"), origin }, req);
+}
 function transferEngineAttestations(from, to) {
     for (const seat of ENGINE_ATTESTATION_SEATS) {
         const v = seat.get(from);
@@ -256,7 +259,7 @@ const ALLOW = Object.freeze({ action: "allow" });
 const ALLOW_BY_RULE = Object.freeze({ action: "allow", decisionReason: "rule" });
 const RETIRED_TEXT_FIELD = "reason";
 export const DECISION_MEMBERS = Object.keys({
-    action: 0, updatedInput: 0, message: 0, decisionReason: 0, requiresRealApproval: 0, denialLimitFallback: 0, persistedRuleShadowed: 0, probeReason: 0,
+    action: 0, updatedInput: 0, message: 0, decisionReason: 0, requiresRealApproval: 0, denialLimitFallback: 0, allowRuleShadowed: 0, probeReason: 0,
     probeCause: 0, probeMandated: 0, mandated: 0, mandate: 0, probeReadRootCandidate: 0, matchedAskRule: 0, ruleEvidence: 0, segmentCoverage: 0,
     origin: 0, askClass: 0, classes: 0, guard: 0, ruleUnreadable: 0, authoredBy: 0, foldedAskClasses: 0,
 });
@@ -453,9 +456,8 @@ export function createApprovalPolicy(opts) {
             }
             if (nameListHolds(need, req) || namespacedCoveringHit(needCovering, req)) {
                 const attest = (d, settlement) => attestEngineSettlement(d, { settlement, origin: "policy" }, req);
-                if (signal?.aborted) {
-                    return attest({ action: "deny", message: `approval aborted for "${req.toolName}" (run or turn interrupted)` }, settledByNobody("task_aborted"));
-                }
+                if (signal?.aborted)
+                    return abortedSeatDeny(req, `approval aborted for "${req.toolName}" (run or turn interrupted)`, "policy");
                 let ok;
                 try {
                     ok = await withTimeout(Promise.resolve(opts.approve(req, signal)), opts.approvalTimeoutMs, () => DEADLINE_ELAPSED);
@@ -470,9 +472,8 @@ export function createApprovalPolicy(opts) {
                             `(${opts.approvalTimeoutMs}ms) with no answer; denied fail-closed`,
                     }, { kind: "approval_window_expired", who: { party: "engine", window: "approval_factory" }, when: Date.now() });
                 }
-                if (signal?.aborted) {
-                    return attest({ action: "deny", message: `approval aborted for "${req.toolName}" (run or turn interrupted)` }, settledByNobody("task_aborted"));
-                }
+                if (signal?.aborted)
+                    return abortedSeatDeny(req, `approval aborted for "${req.toolName}" (run or turn interrupted)`, "policy");
                 if (typeof ok === "object" && ok !== null) {
                     const reading = readApproverOutcomeObject(ok, req.toolName, "none");
                     if (reading.kind === "refused")
@@ -552,19 +553,25 @@ export function combinePolicies(...policies) {
             let fallbackSeen;
             let authoredBySeen = false;
             const contributors = [];
+            const settleDeny = (d) => {
+                const out = rewrite?.updatedInput !== undefined ? { ...d, updatedInput: rewrite.updatedInput } : d;
+                if (out !== d)
+                    transferEngineAttestations(d, out);
+                if (!anyRecord)
+                    return out;
+                const owned = out === d ? { ...d } : out;
+                transferEngineAttestations(records, owned);
+                transferEngineAttestations(d, owned);
+                return owned;
+            };
+            let seatDeny;
             for (const p of policies) {
                 const d = refuseOutOfContractDecision(await p.check(current, signal));
                 if (d.action === "deny") {
-                    const out = rewrite?.updatedInput !== undefined ? { ...d, updatedInput: rewrite.updatedInput } : d;
-                    if (out !== d) {
-                        transferEngineAttestations(d, out);
-                    }
-                    if (!anyRecord)
-                        return out;
-                    const owned = out === d ? { ...d } : out;
-                    transferEngineAttestations(records, owned);
-                    transferEngineAttestations(d, owned);
-                    return owned;
+                    if (engineSettlementOf(d, current)?.settlement.kind !== "task_aborted")
+                        return settleDeny(d);
+                    seatDeny ??= settleDeny(d);
+                    continue;
                 }
                 if (d.updatedInput !== undefined) {
                     current = { ...current, args: d.updatedInput };
@@ -595,6 +602,8 @@ export function combinePolicies(...policies) {
                 if (d.action === "ask")
                     contributors.push(d);
             }
+            if (seatDeny !== undefined)
+                return seatDeny;
             if (asked) {
                 const merged = rewrite?.updatedInput;
                 const withRuleAsk = ruleAskText !== undefined && asked.matchedAskRule === undefined ? { ...asked, matchedAskRule: ruleAskText } : asked;

package/dist/core/tool-spec.d.ts

@@ -1079,6 +1079,13 @@ export interface ToolExecuteContext {
      * tool runs outside a Runner task.
      */
     activeSkillGrants?: () => readonly import("./skill-grant.js").SkillGrantRecord[];
+    /**
+     * A read-only CAPTURE of this (parent) task's request allow entries for the run ({@link import("./task-spec.js").TaskSpec.allowedTools},
+     * its own and any it inherited), filled by the Runner beside {@link activeSkillGrants}: a delegation tool reads it AT SPAWN
+     * TIME and threads it into the child, which holds them as its own request rows until it ends. A copy; the model can
+     * neither read nor set it. Undefined when the tool runs outside a Runner task.
+     */
+    activeRequestAllowedTools?: () => readonly string[];
     /**
      * Parent effective-policy inheritance (tighten-only) — the Runner-filled chain accessor a delegation tool
      * (`createSubagentTool` / the `run_workflow` spawn legs) calls AT SPAWN TIME and threads verbatim into the

package/dist/core/trace.d.ts

@@ -456,6 +456,22 @@ export type TraceEvent = {
     skill: string;
     entries: string[];
     ts: number;
+} | {
+    /**
+     * An entry of the deployment's `RunnerDeps.allowedTools` (`source: "deployment"`) or of this run's
+     * `TaskSpec.allowedTools` (`source: "request"`) cleared the call, so no person and no classifier was asked: the
+     * allow layer's attribution channel for its two entry-list members, beside `permission.skill_allowed`. `entries` are
+     * the entries the call stands on, as the list spells them (deployment or caller text; a consumer rendering it applies
+     * its own display sanitizer).
+     */
+    kind: "permission.allowed_tools_allowed";
+    version: 1;
+    taskId: string;
+    toolName: string;
+    toolCallId: string;
+    source: "deployment" | "request";
+    entries: string[];
+    ts: number;
 } | {
     /**
      * design/179 — the person's persisted rule store could not be read (at prepare, or for one call), so

package/dist/index.d.ts

@@ -198,7 +198,11 @@ export { type AskOrigin, ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL,
 export { PERMISSION_MODES, type PermissionMode, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, type AskClass, isAskClass, MODE_ARBITRATION, type ModeArbitrationRow, RELEASABLE_ASK_CLASSES, MODE_RELEASE_REASONS, type ModeReleaseReason, isModeReleaseReason, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, type AskClassification, type AskClassFacts, type ToolMarkSource, arbitrateByMode, type Arbitration, fileCommandOptionsSentence } from "./core/ask-origin.js";
 export { modePolicyOf, type ModePolicy, PERMISSION_MODE_FOLD_REASONS, type PermissionModeFoldReason, type PermissionModeReceipt, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
 export type { PermissionSeatInputs, PermissionSeatReading } from "./core/mode-policy.js";
-export type { SkillGateSeats, SkillGrantHit, SkillGrantLane, SkillGrantRecord } from "./core/skill-grant.js";
+export type { SkillGateSeats, SkillGrantHit, SkillGrantLane, SkillGrantOrigin, SkillGrantRecord } from "./core/skill-grant.js";
+export { SKILL_GRANT_ORIGINS } from "./core/skill-grant.js";
+export { ALLOW_ENTRY_INERT_REASONS, compileAllowEntry, compileAllowList, type AllowEntryInertReason, type CompiledAllowEntry, type AllowEntryGateSeats, type AllowEntryLane, type AllowEntryHit } from "./core/allow-entry.js";
+export { ALLOW_RULE_MEMBERS, type AllowRuleMember, type AllowRuleShadow } from "./core/allow-rule-shadow.js";
+export { mintNamespacePrefix } from "./core/protocol-naming.js";
 export { readDenyClassifierRules, renderClassifierDenyRules, type DerivedDenyRule } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource, type AutoModeDenySource } from "./core/runtime-caps.js";
 export { SETTLEMENT_KINDS, type SettlementKind, isSettlementKind, type Settlement, SETTLEMENT_PARTIES, type SettlementParty, isSettlementParty, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, type DeniedBy, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, type ClassifierDenyCause, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, type GateDisposition, type GateOutcome, type ModeRelease, type ModeRefusal, screenGateOutcome } from "./core/gate-outcome.js";

package/dist/index.js

@@ -162,6 +162,10 @@ export {} from "./core/read-root-grant-screen.js";
 export { ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, isPersistedRuleMandate, screenAskClassMembers } from "./core/ask-origin.js";
 export { PERMISSION_MODES, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, isAskClass, MODE_ARBITRATION, RELEASABLE_ASK_CLASSES, MODE_RELEASE_REASONS, isModeReleaseReason, RRA_EXPLAINERS, classifyAsk, foldArbitrationRow, arbitrateByMode, fileCommandOptionsSentence } from "./core/ask-origin.js";
 export { modePolicyOf, PERMISSION_MODE_FOLD_REASONS, ACCEPT_EDITS_FILE_COMMANDS, modeAcceptsFileCommand } from "./core/mode-policy.js";
+export { SKILL_GRANT_ORIGINS } from "./core/skill-grant.js";
+export { ALLOW_ENTRY_INERT_REASONS, compileAllowEntry, compileAllowList } from "./core/allow-entry.js";
+export { ALLOW_RULE_MEMBERS } from "./core/allow-rule-shadow.js";
+export { mintNamespacePrefix } from "./core/protocol-naming.js";
 export { readDenyClassifierRules, renderClassifierDenyRules } from "./core/auto-mode-prompt.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./core/runtime-caps.js";
 export { SETTLEMENT_KINDS, isSettlementKind, SETTLEMENT_PARTIES, isSettlementParty, SETTLEMENT_IS_REFUSAL, DENIED_BY_VALUES, isDeniedBy, DENIED_BY_MAY_VETO, CLASSIFIER_DENY_CAUSES, isClassifierDenyCause, DENIED_BY_MAY_CARRY_CAUSE, screenGateOutcome } from "./core/gate-outcome.js";

package/dist/internal/harness-types.d.ts

@@ -8,7 +8,7 @@ export type { CompactionPreparation, SummarizationClampDryRun } from "../engine/
 export type { InvokedSkillRetention } from "../engine/compaction/utils.js";
 export type { AgentCoreRuntimeDeps } from "../engine/loop/runtime-deps.js";
 export type { AgentMessage, AgentTool, AgentToolResult, AgentToolUpdateCallback, ThinkingLevel, ToolExecutionMode, ToolInputValidationContext, ToolInputVerdict, } from "../engine/loop/types.js";
-export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileError, FileErrorCode, FileInfo, Result, WriteExpectation, WriteReceipt, SymlinkChain, Session, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
+export type { AgentHarnessEvent, CompactionSettings, ExecutionEnv, ExecutionErrorCode, FileError, FileKind, FileErrorCode, FileInfo, Result, WriteExpectation, WriteReceipt, SymlinkChain, Session, SessionMetadata, SessionRepo, SessionStorage, SessionTreeEntry, Skill, } from "../engine/harness/types.js";
 export type { ExecutionEnvExecOptions, ExecResult } from "../engine/harness/types.js";
 export type { SessionWriteOptions, CompactionEntry } from "../engine/harness/types.js";
 export type { ActiveWorktreeSession, WorkspaceState } from "../engine/harness/types.js";

package/dist/tools/fs/dir-entries.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Directory ENTRIES for the model, and the one per-entry read-deny judge every traversal shares.
+ *
+ * The judge ({@link createEntryDenyJudge}) is the walk's (search.ts `walk`, the throat Glob, the Grep
+ * fallback and the repo map traverse through): an entry path is judged as spelled and at its home view
+ * (read-deny-home.ts), so a traversal that enters the home through an alias of it meets the
+ * home-anchored rows where the home is. It answers; it does not count — each caller counts what its own
+ * result has to disclose.
+ *
+ * The enumerator ({@link enumerateDirectory}) lists ONE level of a directory the way the upstream
+ * at-mention lists one (a single readdir, at most {@link DIRECTORY_LISTING_MAX_ENTRIES} names, then
+ * "… and N more entries"), with three differences that are this engine's facts:
+ *  · entries are files, directories AND symbolic links (kinds from the environment's listing, which does
+ *    not follow links); a link is listed by its own name and judged at its own path — its target is never
+ *    resolved or read here;
+ *  · every entry passes the per-entry read-deny judge; a withheld entry is neither named nor counted in
+ *    the remainder, and the withheld count is EXACT (one level, so every entry is judged);
+ *  · no ignore rules apply: the user named this directory, and ignore files are a search-noise filter, not
+ *    a read boundary.
+ * Entries sort by code unit (a stable listing; the environment's own order is not one). Three counts stay
+ * apart: `omitted` (withheld by the deny judge), `more` (kept entries past the cap), `incomplete` (the
+ * judging was cut short by an abort — the listing is a prefix, not the directory).
+ */
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+import type { FileError, FileKind, Result } from "../../internal/harness.js";
+import { type HomeViewEnv, type HomeViewsCarrier } from "./read-deny-home.js";
+/** The upstream at-mention's cap on listed entries. */
+export declare const DIRECTORY_LISTING_MAX_ENTRIES = 1000;
+/** The read-deny table as the traversals hold it. */
+export type EntryDenyTable = {
+    matchPath(path: string): {
+        pattern: string;
+    } | null;
+} & HomeViewsCarrier;
+/** Judge one entry path: the row that withholds it, or null. `leaf: "file"` asks the home view for a file
+ *  leaf (a directory entry is judged as a directory). */
+export type EntryDenyJudge = (path: string, leaf?: "file") => Promise<{
+    pattern: string;
+} | null>;
+/** The per-entry judge over `deny` (literal spelling, then the home view). */
+export declare function createEntryDenyJudge(env: HomeViewEnv, deny: EntryDenyTable, signal?: AbortSignal): EntryDenyJudge;
+export interface DirectoryEntry {
+    name: string;
+    kind: FileKind;
+}
+export interface DirectoryListing {
+    /** At most {@link DIRECTORY_LISTING_MAX_ENTRIES}, sorted. */
+    entries: DirectoryEntry[];
+    /** Kept entries past the cap. */
+    more: number;
+    /** Entries withheld by the read-deny judge (exact). */
+    omitted: number;
+    /** The rows that withheld something, first-seen order. */
+    omittedPatterns: string[];
+    /** An abort cut the judging short: `entries` / `more` / `omitted` describe a prefix of the directory. */
+    incomplete: boolean;
+}
+/** List one level of `dir` (a canonical directory path). A listing the environment refuses is the error. */
+export declare function enumerateDirectory(env: ExecutionEnv, dir: string, judge: EntryDenyJudge | undefined, signal?: AbortSignal): Promise<Result<DirectoryListing, FileError>>;
+/**
+ * A data label (a path, a file name) as a JSON string literal with every C0/C1 control, format character
+ * and line / paragraph separator written as `\uXXXX` — lossless (JSON.parse gives the original back), and
+ * one line whatever the name holds. JSON's own escaping alone leaves U+2028 / U+2029 / U+0085 and the
+ * format characters raw.
+ */
+export declare function quoteDataLabel(label: string): string;
+/** The listing as text: one entry per line (a directory with a trailing "/"; a name that could break or
+ *  hide in its line is written as {@link quoteDataLabel}), then "… and N more entries" when capped. */
+export declare function renderDirectoryListing(l: DirectoryListing): string;