@sema-agent/core 7.9.0 → 7.9.2

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

@@ -1,4 +1,4 @@
-import { escapeForDisclosure, parseRuleText, ruleReachesProgramRun } from "./permission-rule-model.js";
+import { escapeForDisclosure, parseRuleText, programRunReachOf, ruleReachesProgramRun } from "./permission-rule-model.js";
 import { writerOf } from "./permission-rule-store.js";
 export const ORG_UNAVAILABLE_DECISION_REASON = "org_unavailable";
 export const ORG_ADJUDICATION_TIMEOUT_MS = 15_000;
@@ -244,19 +244,25 @@ function validateOrgSnapshot(s, nowMs) {
 }
 export function orgRuleVerdictFor(rules, call) {
     let ask;
+    let unreadable;
     for (const r of rules) {
         const parsed = parseRuleText(r.rule, r.behavior);
         if ("reject" in parsed)
             continue;
         if (parsed.rule.tool !== call.tool)
             continue;
-        if (!ruleReachesProgramRun(parsed.rule, call.command))
+        const outcome = programRunReachOf(parsed.rule, call.command);
+        if (outcome.reach === "not_reached")
             continue;
+        if (outcome.reach === "unreadable") {
+            unreadable ??= { behavior: "ask", rule: r.rule, unreadable: outcome.reason };
+            continue;
+        }
         if (r.behavior === "deny")
             return { behavior: "deny", rule: r.rule };
         ask ??= { behavior: "ask", rule: r.rule };
     }
-    return ask;
+    return unreadable ?? ask;
 }
 export function orgRuleShadows(orgRules, rule) {
     return compileOrgShadowPredicate(orgRules)(rule);

package/dist/core/permission-rules.d.ts

@@ -16,8 +16,9 @@
  * this compiler now compiles it AS SUCH for the two tightening behaviors: the text goes through the ONE
  * validator (`parseRuleText(text, behavior)` — the tightening floor, so `Bash(node:*)` as a deny is a
  * legitimately wide tightening) and the call is judged with the ONE tightening reach
- * (`ruleReachesProgramRun`: the whole command line or any program run in a connector chain — upstream's
- * per-subcommand deny, the same instrument the org partition and the personal store's deny/ask rows use).
+ * (`programRunReachOf`: the whole command line or any program run in a connector chain — upstream's
+ * per-subcommand deny, the same instrument the org partition and the personal store's deny/ask rows use;
+ * a call the lexer cannot read against a rule is a fail-closed ask, never silence).
  * It sits in the field-level tier of the evaluation order — right after the bare deny (resp. ask) — which
  * is upstream's placement (`bs()` whole-tool deny → `AN(…,"deny")` field-level deny → `ph()` whole-tool
  * ask → `AN(…,"ask")` field-level ask → allow). A content-form ALLOW is refused (`unsupported.bash_prefix`):

package/dist/core/permission-rules.js

@@ -1,8 +1,9 @@
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { catalogRuleFaceOf, pathTargetOf } from "./tool-registry.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
-import { isUsablePathBase, lexicalNormalAbsolutePathOf, parseRuleText, pathRuleReaches, ruleReachesProgramRun } from "./permission-rule-model.js";
-import { pathTargetValue, protectivePathTargetOf } from "./tool-registry.js";
+import { isUsablePathBase, parseRuleText, pathRuleReaches, programRunReachOf } from "./permission-rule-model.js";
+import { effectivePathTargetOf } from "./effective-path-target.js";
+import { protectivePathTargetOf } from "./tool-registry.js";
 export { parsePermissionRule };
 export const BASH_GENERIC_PARAMS = new Set(catalogRuleFaceOf("Bash")?.params ?? []);
 const DEFAULT_CAPS = {
@@ -317,18 +318,34 @@ export function createPermissionRulePolicy(rules, opts) {
     const coveringHit = (lane, toolName) => lane.length === 0 ? undefined : lane.find((r) => namespacedRuleNameCovers(r.ruleName, toolName));
     const hasCovering = namespacedCovering.deny.length > 0 || namespacedCovering.ask.length > 0 || namespacedCovering.allow.length > 0;
     const commandParam = catalogRuleFaceOf("Bash")?.primaryParams[0] ?? "command";
-    const cwdBase = (pathBases.cwd ?? pathBases.root ?? "").replace(/\/+$/, "");
     const contentHit = (lane, req) => {
         if (lane.length === 0)
             return undefined;
-        const pt = protectivePathTargetOf(req);
-        const spelled = pt !== undefined ? pathTargetValue(req.args, pt) : undefined;
-        const target = spelled === undefined ? undefined : lexicalNormalAbsolutePathOf(spelled.startsWith("/") ? spelled : `${cwdBase}/${spelled}`);
+        const target = effectivePathTargetOf(req, protectivePathTargetOf(req), pathBases);
         const command = isPlainObjectArgs(req.args) ? req.args[commandParam] : undefined;
-        return lane.find((r) => r.parsed.match === "subpath" || r.parsed.match === "path"
-            ? target !== undefined && pathRuleReaches(r.parsed, target, pathBases)
-            : typeof command === "string" && ruleReachesProgramRun(r.parsed, command));
+        let unreadable;
+        for (const r of lane) {
+            if (r.parsed.match === "subpath" || r.parsed.match === "path") {
+                if (target !== undefined && pathRuleReaches(r.parsed, target, pathBases))
+                    return { rule: r };
+                continue;
+            }
+            if (typeof command !== "string")
+                continue;
+            const outcome = programRunReachOf(r.parsed, command);
+            if (outcome.reach === "reached")
+                return { rule: r };
+            if (outcome.reach === "unreadable")
+                unreadable ??= { rule: r, unreadable: outcome.reason };
+        }
+        return unreadable;
     };
+    const unreadableAsk = (hit, req) => ({
+        action: "ask",
+        message: `tool "${req.toolName}" needs approval: the command could not be read against the permission rule ${hit.rule.ruleText} (${hit.unreadable}) — a person must decide`,
+        matchedAskRule: hit.rule.ruleText,
+        requiresRealApproval: true,
+    });
     return {
         nameSets: [nameSets],
         check(req) {
@@ -342,15 +359,19 @@ export function createPermissionRulePolicy(rules, opts) {
                 if (coveringDeny)
                     return { action: "deny", message: ruleMessage("denied", coveringDeny.ruleText, coveringDeny.source) };
             }
+            const contentDeny = entry !== undefined ? contentHit(entry.content.deny, req) : undefined;
+            if (contentDeny !== undefined && contentDeny.unreadable === undefined) {
+                return { action: "deny", message: ruleMessage("denied", contentDeny.rule.ruleText, contentDeny.rule.source) };
+            }
             if (entry) {
-                const contentDeny = contentHit(entry.content.deny, req);
-                if (contentDeny) {
-                    return { action: "deny", message: ruleMessage("denied", contentDeny.ruleText, contentDeny.source) };
-                }
                 const paramDeny = matchParamRules(entry.param.deny, req.args, caps.maxScalarValueChars);
                 if (paramDeny) {
                     return { action: "deny", message: ruleMessage("denied", paramDeny.ruleText, paramDeny.source) };
                 }
+            }
+            if (contentDeny?.unreadable !== undefined)
+                return unreadableAsk({ rule: contentDeny.rule, unreadable: contentDeny.unreadable }, req);
+            if (entry) {
                 if (entry.bare.ask) {
                     return { action: "ask", message: ruleMessage("flagged", entry.bare.ask.ruleText, entry.bare.ask.source), matchedAskRule: entry.bare.ask.ruleText };
                 }
@@ -362,8 +383,10 @@ export function createPermissionRulePolicy(rules, opts) {
             }
             if (entry) {
                 const contentAsk = contentHit(entry.content.ask, req);
-                if (contentAsk) {
-                    return { action: "ask", message: ruleMessage("flagged", contentAsk.ruleText, contentAsk.source), matchedAskRule: contentAsk.ruleText };
+                if (contentAsk !== undefined) {
+                    if (contentAsk.unreadable !== undefined)
+                        return unreadableAsk({ rule: contentAsk.rule, unreadable: contentAsk.unreadable }, req);
+                    return { action: "ask", message: ruleMessage("flagged", contentAsk.rule.ruleText, contentAsk.rule.source), matchedAskRule: contentAsk.rule.ruleText };
                 }
                 const paramAsk = matchParamRules(entry.param.ask, req.args, caps.maxScalarValueChars);
                 if (paramAsk) {

package/dist/core/persisted-rule-arms.d.ts

@@ -18,6 +18,9 @@ import type { PersistedRuleHit, PersistedRuleHitRule } from "./hooks.js";
 export interface PersistedRuleRead {
     readonly hit?: PersistedRuleHit;
     readonly unreadable?: true;
+    /** The lexer's reason when the CALL could not be read against the person's deny/ask rows (absent for
+     *  a store read failure) — the message says which it was; the decision is the same. */
+    readonly reason?: string;
 }
 /** Display form of a rule set (design/375 §5.1): every rule text is a DISPLAY value on a human trust
  *  boundary, and the set must stay readable however large a lane makes it — each member rides
@@ -42,8 +45,10 @@ export declare function disclosedRuleSet(rules: readonly PersistedRuleHitRule[])
  *    ask, the marker is stamped if absent and the message names the rule — the standing question
  *    outranks a remembered yes across lanes, exactly as the DSL's own order says within one; a deny
  *    stays a deny.
- *  · UNREADABLE — the wired store could not be read (a read failure, a timeout): the person's deny/ask
- *    rows cannot be enforced, so the call fails CLOSED the way an unreadable org snapshot does — an
+ *  · UNREADABLE — the wired store could not be read (a read failure, a timeout), or the CALL could not be
+ *    read against the person's standing deny/ask rows (`reason` carries the lexer's word: an expansion
+ *    where a rule reads a word, an unterminated quote, a syntax error): the person's deny/ask rows
+ *    cannot be enforced for this call, so it fails CLOSED the way an unreadable org snapshot does — an
  *    allow tightens to an ask carrying `requiresRealApproval` (no automatic lane clears it; the gate
  *    derives the origin `rule_store_unavailable` from its own record of the read), an ask acquires the
  *    bit, a deny stays a deny. Reading an unreadable store as "no rule" would erase every deny the

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

@@ -8,7 +8,9 @@ export function applyPersistedTightening(decision, read) {
     if (read?.unreadable === true) {
         if (decision.action === "deny")
             return { decision };
-        const message = "the persisted permission-rule store could not be read for this call — the person's own deny/ask rules cannot be enforced, so this call needs a real approval until the store is readable";
+        const message = read.reason !== undefined
+            ? `this call could not be read against the person's standing deny/ask rules (${read.reason}) — whether one of them forbids it is unknown, so it needs a real approval`
+            : "the persisted permission-rule store could not be read for this call — the person's own deny/ask rules cannot be enforced, so this call needs a real approval until the store is readable";
         return {
             decision: decision.action === "allow"
                 ? { action: "ask", message, decisionReason: "persisted_rule", requiresRealApproval: true, ...(decision.updatedInput !== undefined ? { updatedInput: decision.updatedInput } : {}) }

package/dist/core/roles.d.ts

@@ -98,6 +98,14 @@ export interface ResolvedRole {
  * Resolve the model (and default thinking) for a task. Explicit `spec.model` wins; otherwise walk the
  * `modelRole`'s fallback chain over the merged roles (task overrides runner) and use the first role
  * that supplies a model. Throws a helpful error if nothing resolves.
+ *
+ * @contract roles.side_channels_deployment_only — an engine SIDE CHANNEL (the auto-mode classifier,
+ * the compaction/summarize lane, memory consolidation, next-prompt suggestion) resolves here with a
+ * `modelRole` and NO run model: it runs on the deployment's roles alone — the boot default at the end of
+ * its chain — and never follows the model a run was switched to. Only a run's CHILDREN follow the parent:
+ * the delegation seat (`childModelSeat`) passes the parent's `Model` as `spec.model` with the role kept
+ * on `modelRole`, so the role's presets still apply. A side channel that must follow a run passes that
+ * run's model explicitly; nothing here infers it.
  */
 export declare function resolveTaskModel(spec: {
     model?: ModelRef;

package/dist/core/runner/active-skill-scope.js

@@ -1,5 +1,6 @@
 import { canonicalizeTarget } from "../../tools/fs/safety.js";
 import { pathTargetValue } from "../tool-registry.js";
+import { pathTargetBaseOf } from "../effective-path-target.js";
 import { PATH_WRITE_TOOLS, isWithin } from "./session-rule-policy.js";
 import { parseSkillToolEntry, skillSpecifierRejection } from "../skill-tool-specifier.js";
 export class ActiveSkillScope {
@@ -99,7 +100,7 @@ export function createActiveSkillScopePolicy(opts) {
                             decisionReason: "safety",
                         };
                     }
-                    const canon = await canonicalizeTarget(env, path, signal, req.cwd ?? rootPath);
+                    const canon = await canonicalizeTarget(env, path, signal, pathTargetBaseOf(declaredTarget, { root: rootPath, cwd: req.cwd }));
                     if (!canon.ok) {
                         return {
                             action: "deny",

package/dist/core/runner/contracts.d.ts

@@ -43,7 +43,7 @@ import type { SystemInjectionPriority, TaskNotificationPayload } from "../task-n
 import type { OnAsk, PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "../tool-policy.js";
 import type { RemoteExecutionEnv, SnapshotId, WorkspaceHandle } from "../remote-env.js";
 import type { ToolDisclosureManifest } from "../trace.js";
-import type { AgentDefinition, Brain, CompactOutcome, NestedUsageAccum, RunnerDeps, TaskEvent, TaskResult, TaskSpec, TaskStream, ToolActivity, ToolEffect } from "../types.js";
+import type { AgentDefinition, Brain, CompactOutcome, ModelRoles, NestedUsageAccum, RunnerDeps, TaskEvent, TaskResult, TaskSpec, TaskStream, ToolActivity, ToolEffect } from "../types.js";
 import type { WiringManifest } from "../wiring-manifest.js";
 import type { ActiveSkillFrame } from "./active-skill-scope.js";
 import type { BudgetAxis } from "./assemble-result.js";
@@ -2377,11 +2377,12 @@ export interface RunnerDepsSeat {
 export interface RunnerSelfSeat {
     /** The session store this Runner was constructed over — the delegation tools acquire / release / fork through it. */
     readonly sessions: SessionStore;
-    /** The deployment agent + model catalog, READ-ONLY (a fresh copy per read; the definitions are the shared objects). */
+    /** The deployment agent + model catalog, READ-ONLY (a fresh copy per read; the definitions are the shared objects); `roles` = `RunnerDeps.roles` (the delegation seat's `childModelSeat` reads `roles.subagent`). */
     readonly agentCatalog: {
         agents?: AgentDefinition[];
         builtinAgents?: boolean;
         models?: Record<string, Model>;
+        roles?: ModelRoles;
     };
     /** The deployment-level gating baseline (deps toolPolicy / hooks) as delegate wrappers — for assemblers that compose with it. */
     readonly gateBaseline: {

package/dist/core/runner/permission-rule-lanes.d.ts

@@ -26,7 +26,7 @@
  * silence the ungated-write warning for deployments that wired no policy at all.
  */
 import type { AskRuleEvidence, ToolCallRequest } from "../tool-policy.js";
-import { persistedRuleMandateOf, type OrgGateVerdict, type PersistedRuleAnswer, type PersistedRuleHit } from "../hooks.js";
+import { persistedRuleMandateOf, type OrgGateVerdict, type PersistedRuleAnswer, type PersistedRuleHit, type PersistedRuleUnreadable } from "../hooks.js";
 import type { PersistedRule, PersistedRuleVerdict, RuleOffer, SegmentCoverage } from "../permission-rule-model.js";
 import { type OrgRuleResolution } from "../permission-rule-org.js";
 import type { PermissionRuleStoreProvider } from "../permission-rule-provider.js";
@@ -79,11 +79,19 @@ export declare function orgRevisionEvidenceOf(resolution: OrgRuleResolution, onD
  * aliased: the evidence must not change under a store that reuses its row objects.
  */
 export declare function persistedRuleHitOf(verdict: PersistedRuleVerdict | undefined): PersistedRuleHit | undefined;
+/** The COMMAND arm's projection of a verdict: a call the lexer could not read against a standing deny/ask
+ *  row is the lane's UNREADABLE answer — the same fail-closed shape an unreadable store takes (a
+ *  real-approval ask no automatic lane clears), with the lexer's reason in place of the store's — never a
+ *  matched ask rule, which would let a blanket `onAsk: "allow"` clear a question nobody can answer. Every
+ *  other verdict is {@link persistedRuleHitOf}'s hit. */
+export declare function persistedRuleAnswerOf(verdict: PersistedRuleVerdict | undefined): PersistedRuleHit | PersistedRuleUnreadable | undefined;
 /**
  * design/382 §2.5-1, widened to every path-targeting tool — the persisted-rule lane's PATH arm: the call's
- * target path in the SAME lexical identity the rule family is defined over — absolute as spelled, relative
- * resolved against the LIVE tracked working directory (the very base the file tools themselves resolve
- * against; task root when no tracker moved), then normalized lexically, zero IO.
+ * target path in the SAME lexical identity the rule family is defined over, resolved by the ONE reader every
+ * fence and every tool goes through (`effectivePathTargetOf`), so the lane judges the path the tool will
+ * really open. The tool's own declaration decides which base a relative spelling takes and what an ABSENT
+ * slot means — the lane no longer guesses `liveCwd ?? root` for every tool, which was wrong for the two
+ * search tools in three separate shapes (see effective-path-target.ts). Still zero IO.
  *
  * TWO readings of the call's path slot, one per direction (design/388 B6/B17): the tightening arms judge
  * the PROTECTIVE target (the object face's declaration, the catalog's for the name as the floor — reading

package/dist/core/runner/permission-rule-lanes.js

@@ -1,6 +1,7 @@
 import { persistedRuleMandateOf } from "../hooks.js";
-import { adjudicatePersistedPathRules, adjudicatePersistedRules, lexicalNormalAbsolutePathOf, ruleToolGrammarOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
-import { declaredPathTargetOf, pathTargetValue, protectivePathTargetOf } from "../tool-registry.js";
+import { adjudicatePersistedPathRules, adjudicatePersistedRules, ruleToolGrammarOf, segmentCoverageOf, suggestRulesForCommand } from "../permission-rule-model.js";
+import { effectivePathTargetOf } from "../effective-path-target.js";
+import { declaredPathTargetOf, protectivePathTargetOf } from "../tool-registry.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
 export const PERSISTED_RULE_TOOL = "Bash";
 const HANDOFF_BOUND = 256;
@@ -24,21 +25,18 @@ export function persistedRuleHitOf(verdict) {
         ? undefined
         : { behavior: verdict.behavior, rules: verdict.rules.map((r) => ({ rule: r.rule, dots: r.adds.map((a) => ({ actor: a.dot.actor, counter: a.dot.counter })) })) };
 }
+export function persistedRuleAnswerOf(verdict) {
+    if (verdict?.unreadable !== undefined)
+        return { unreadable: true, reason: verdict.unreadable };
+    return persistedRuleHitOf(verdict);
+}
 export function pathRuleLaneAnswer(table, req, ctx) {
-    const base = (ctx.liveCwd ?? ctx.root ?? "").replace(/\/+$/, "");
-    const resolve = (pt) => {
-        if (pt === undefined)
-            return undefined;
-        const spelled = pathTargetValue(req.args, pt);
-        if (spelled === undefined)
-            return undefined;
-        return lexicalNormalAbsolutePathOf(spelled.startsWith("/") ? spelled : `${base}/${spelled}`);
-    };
-    const tighten = resolve(protectivePathTargetOf(req));
-    const allow = resolve(declaredPathTargetOf(req));
+    const bases = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), ...(ctx.liveCwd !== undefined ? { cwd: ctx.liveCwd } : {}) };
+    const tighten = effectivePathTargetOf(req, protectivePathTargetOf(req), bases);
+    const allow = effectivePathTargetOf(req, declaredPathTargetOf(req), bases);
     if (tighten === undefined && allow === undefined)
         return undefined;
-    return persistedRuleHitOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, { ...(ctx.root !== undefined ? { root: ctx.root } : {}), ...(ctx.liveCwd !== undefined ? { cwd: ctx.liveCwd } : {}) }));
+    return persistedRuleHitOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, bases));
 }
 export function createPermissionRuleLanes(cfg) {
     const provider = cfg.provider;
@@ -137,7 +135,7 @@ export function createPermissionRuleLanes(cfg) {
                 const execCwd = liveCwd !== undefined ? { execCwd: liveCwd } : {};
                 const verdict = adjudicatePersistedRules(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
                 if (verdict !== undefined)
-                    return persistedRuleHitOf(verdict);
+                    return persistedRuleAnswerOf(verdict);
                 const coverage = segmentCoverageOf(command, { persisted: table }, { tool: req.toolName, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
                 return coverage !== undefined ? { segmentCoverage: coverage } : undefined;
             },

package/dist/core/runner/prepare-caps-and-workflow.js

@@ -1,6 +1,6 @@
 import { isSyntheticApiErrorMessage } from "../../internal/harness.js";
 import { createHash } from "node:crypto";
-import { forkGovernanceDenial } from "../../agents/subagent.js";
+import { deploymentSubagentTierModel, forkGovernanceDenial } from "../../agents/subagent.js";
 import { CROSS_SESSION_CLASSIFIER_RULE } from "../../agents/cross-session-envelope.js";
 import { createRunWorkflowTool } from "../../orchestration/run-workflow-tool.js";
 import { isSelfOrchestrationActive } from "../../orchestration/workflow-script-runner.js";
@@ -243,7 +243,7 @@ export async function prepareCapsAndWorkflow(input) {
             taskOwner: hostTaskId,
             limits: deps.workflowLimits,
             sourceTaskId: hostTaskId,
-            parentModel: () => harnessRef.current?.getModel(),
+            parentModel: () => deploymentSubagentTierModel(runnerSelf.agentCatalog) ?? harnessRef.current?.getModel(),
             ...(spec.getApiKeyAndHeaders !== undefined ? { parentGetApiKeyAndHeaders: spec.getApiKeyAndHeaders } : {}),
             ...(frozenOnAsk !== undefined ? { parentOnAsk: frozenOnAsk } : {}),
             principal: spec.principal,

package/dist/core/runner/runtask.d.ts

@@ -3,7 +3,7 @@ import { type CheckpointToken, type ResumeOutcome } from "../checkpoint-store.js
 import { type TaskOutcome } from "../task-outcome.js";
 import { type SideQuerySpec, type SideQueryResult } from "../side-query.js";
 import type { SessionStore } from "../session.js";
-import type { AgentDefinition, ModelRef, RunnerDeps, TaskEvent, TaskResult, TaskSpec, TaskStream } from "../types.js";
+import type { AgentDefinition, ModelRef, ModelRoles, RunnerDeps, TaskEvent, TaskResult, TaskSpec, TaskStream } from "../types.js";
 import type { ResumeRun, ResumeTaskConfig, RunInternals, RunnerSelfSeat } from "./contracts.js";
 export type { ResumeTaskConfig } from "./contracts.js";
 /**
@@ -74,6 +74,7 @@ export declare class Runner implements RunnerSelfSeat {
         agents?: AgentDefinition[];
         builtinAgents?: boolean;
         models?: Record<string, Model>;
+        roles?: ModelRoles;
     };
     /** design/125 (实现审 B1) — the deployment-level gating baseline, exposed READ-ONLY so thin
      *  assemblers over the Runner (`runSpec`) can COMPOSE with it. The task-level engine semantic is a

package/dist/core/runner/runtask.js

@@ -138,7 +138,7 @@ export class Runner {
         return {
             ...(this.deps.agents ? { agents: [...this.deps.agents] } : {}),
             ...(this.deps.builtinAgents !== undefined ? { builtinAgents: this.deps.builtinAgents } : {}),
-            ...(this.deps.models ? { models: { ...this.deps.models } } : {}),
+            ...(this.deps.models ? { models: { ...this.deps.models } } : {}), ...(this.deps.roles ? { roles: { ...this.deps.roles } } : {}),
         };
     }
     get gateBaseline() {

package/dist/core/runner/session-rule-policy.js

@@ -2,6 +2,7 @@ import { canonicalizeTarget, writeTargetPath } from "../../tools/fs/safety.js";
 import { isWinFormPath } from "../../tools/fs/safety.js";
 import { createCoarseCommandNamePolicy, namespacedCoveringEntries, namespacedCoveringHit } from "../tool-policy.js";
 import { declaredPathTargetOf, isProtectedWrite, pathConfinableWriteToolNames, skillScopeWriteToolNames } from "../tool-registry.js";
+import { pathTargetBaseOf } from "../effective-path-target.js";
 export const PATH_WRITE_TOOLS = skillScopeWriteToolNames();
 export const PATH_CONFINABLE_WRITE_TOOLS = pathConfinableWriteToolNames();
 export function isWithin(root, p) {
@@ -65,7 +66,7 @@ export function createSessionRulePolicy(rules, opts) {
                     if (typeof path !== "string" || path.length === 0) {
                         return deny(`write tool "${req.toolName}" denied: session rule confines writes to allowDirs but the call has no resolvable path`);
                     }
-                    const canon = await canonicalizeTarget(env, path, signal, req.cwd ?? rootPath);
+                    const canon = await canonicalizeTarget(env, path, signal, pathTargetBaseOf(declared, { root: rootPath, cwd: req.cwd }));
                     if (!canon.ok) {
                         return deny(`write to "${path}" denied: its real target could not be resolved against the session-rule allowDirs`);
                     }

package/dist/core/runner/tool-face-overlay.js

@@ -1,6 +1,6 @@
 import { MCP_NAMESPACE } from "../protocol-table.js";
 import { mintNamespacePrefix } from "../protocol-naming.js";
-import { TOOL_APPROVAL_CARDS, TOOL_FAMILIES, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_LIST, TOOL_KEY_MAX_CHARS } from "../tool-face.js";
+import { TOOL_APPROVAL_CARDS, TOOL_FAMILIES, TOOL_PATH_ABSENCES, TOOL_PATH_ACCESSES, TOOL_PATH_BASES, RENDER_HINT_ACTIVITY_MAX_CHARS, RENDER_HINT_MAX_CHARS, RENDER_HINT_MAX_LIST, TOOL_KEY_MAX_CHARS, } from "../tool-face.js";
 import { inputKeysOf } from "../tool-roster.js";
 import { deliverEngineNotice } from "../engine-notice.js";
 export const APPROVAL_CARD_REQUIRED_KEYS = Object.freeze({
@@ -26,9 +26,28 @@ export function toolFaceProblem(face, schema) {
     if (face.pathTarget !== undefined) {
         if (typeof face.pathTarget.param !== "string" || !top.has(face.pathTarget.param))
             return `pathTarget.param ${JSON.stringify(face.pathTarget.param)} is not a top-level property of the tool's schema`;
-        if (!["read", "create", "edit"].includes(face.pathTarget.access))
+        if (!TOOL_PATH_ACCESSES.includes(face.pathTarget.access))
             return `pathTarget.access ${JSON.stringify(face.pathTarget.access)} is outside the closed set`;
-        const long = overlong("pathTarget.param", [face.pathTarget.param]) ?? overlong("pathTarget.aliases", face.pathTarget.aliases ?? []);
+        const base = face.pathTarget.base;
+        if (base !== undefined && !TOOL_PATH_BASES.includes(base))
+            return `pathTarget.base ${JSON.stringify(base)} is outside the closed set`;
+        if (base === "root" && face.pathTarget.access !== "read")
+            return `pathTarget.base "root" needs pathTarget.access "read" — two write guards (the session-transcript directory guard and the frozen-spec deny) resolve a write target against the call's working directory only, so a write face declaring a root base would be judged on two different files (#638)`;
+        const absent = face.pathTarget.absent;
+        if (absent !== undefined && !TOOL_PATH_ABSENCES.includes(absent))
+            return `pathTarget.absent ${JSON.stringify(absent)} is outside the closed set`;
+        if (absent === "base" && face.pathTarget.access !== "read")
+            return `pathTarget.absent "base" needs pathTarget.access "read" — it says the call is about the whole base directory when the slot is empty, which is a search SCOPE; a write with no path names no file, and the containment fences judge a write on its own target`;
+        const patternParam = face.pathTarget.patternParam;
+        if (patternParam !== undefined) {
+            if (typeof patternParam !== "string" || !top.has(patternParam))
+                return `pathTarget.patternParam ${JSON.stringify(patternParam)} is not a top-level property of the tool's schema`;
+            if (absent !== "base")
+                return `pathTarget.patternParam ${JSON.stringify(patternParam)} is declared but pathTarget.absent is ${JSON.stringify(absent ?? "none")} — the pattern base is only ever read for an absent slot, so this declaration would be inert`;
+        }
+        const long = overlong("pathTarget.param", [face.pathTarget.param]) ??
+            overlong("pathTarget.aliases", face.pathTarget.aliases ?? []) ??
+            overlong("pathTarget.patternParam", patternParam === undefined ? [] : [patternParam]);
         if (long !== undefined)
             return long;
         vocabulary.add(face.pathTarget.param);

package/dist/core/sensitive-path-policy.js

@@ -2,7 +2,8 @@ import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { canonicalizeTarget, expandHomeTilde, isAbsolutePathForm, isWinFormPath, writeTargetPath } from "../tools/fs/safety.js";
 import { compileSegmentPattern, matchSegmentPatterns } from "../tools/fs/read-deny.js";
-import { isProtectedWrite } from "./tool-registry.js";
+import { isProtectedWrite, protectivePathTargetOf } from "./tool-registry.js";
+import { pathTargetBaseOf } from "./effective-path-target.js";
 export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".env",
     ".env.*",
@@ -97,10 +98,11 @@ export function createSensitivePathPolicy(opts) {
                 return { action: "allow" };
             if (guardedByName !== undefined ? !guardedByName.has(req.toolName) : !isProtectedWrite(req))
                 return { action: "allow" };
-            const path = writeTargetPath(req);
+            const protective = protectivePathTargetOf(req);
+            const path = writeTargetPath(req, protective);
             if (typeof path !== "string" || path.length === 0)
                 return { action: "allow" };
-            const canon = await canonicalizeTarget(opts.env, path, signal, req.cwd ?? opts.rootPath);
+            const canon = await canonicalizeTarget(opts.env, path, signal, pathTargetBaseOf(protective, { root: opts.rootPath, cwd: req.cwd }));
             if (!canon.ok) {
                 if (canon.unresolvedSymlink) {
                     return {

package/dist/core/shell-lexer.d.ts

@@ -0,0 +1,47 @@
+/** One argv word as the lexer read it. */
+export interface ShellWord {
+    /** The word's value with quotes and escapes removed — meaningful only when `expands` is `false`. */
+    readonly text: string;
+    /** The unquoted source spelling (assignment and wrapper-flag tests read this, never `text`). */
+    readonly raw: string;
+    /** `false`: a literal word. `"one"`: carries an expansion but yields exactly ONE word (it was double-quoted).
+     *  `"many"`: an unquoted expansion, glob or brace pattern, or a quoted `"$@"` / array expansion — may
+     *  yield zero, one or several words. */
+    readonly expands: false | "one" | "many";
+}
+/** One program run the lexer found, after keyword stripping. */
+export interface ShellSegment {
+    /** The run as SPELLED (a leading keyword removed): the first candidate a rule is compared against. */
+    readonly argv: readonly ShellWord[];
+    /** The deeper candidates, one per peeled layer (leading assignments, then each wrapper of the table):
+     *  `sudo -u root rm -r x` ⇒ `[[rm, -r, x]]`. Empty when nothing peeled. */
+    readonly peeled: readonly (readonly ShellWord[])[];
+    /** Present when this segment's program runs cannot be known from the text at all; `argv` then holds
+     *  whatever was read before the failure and must not be matched as a run. */
+    readonly unreadable?: string;
+    /** Present when the segment's program runs are NOT fully known although its candidates could be read:
+     *  a peel that stopped before the wrapped program could be named (its options carry an expansion, a
+     *  command string, an option of unknown arity), or a command/process substitution anywhere in the
+     *  segment (it runs a program the lexer does not read). The candidates stand — a rule they reach is
+     *  reached — and every other rule reads `unreadable`. */
+    readonly peelUnreadable?: string;
+}
+/** A command line as the tightening reader sees it. */
+export interface ShellCommandShape {
+    readonly segments: readonly ShellSegment[];
+    /** The connector BETWEEN each consecutive pair of segments (`;` `&&` `||` `|` `|&` `&` `\n`). */
+    readonly connectors: readonly string[];
+    /** A subshell, group, control-structure keyword or dropped empty piece bounded the segments: the
+     *  connector list is not one flat chain a compound rule could spell. */
+    readonly grouped: boolean;
+}
+export { SHELL_WRAPPER_TABLE, type ShellWrapperName } from "./shell-wrapper-table.js";
+/** Longer than this and the command is not read at all (one unreadable segment): every pass is linear,
+ *  but a substitution nested inside quoting re-enters the quote reader once per nesting level, and the
+ *  cap is what bounds that on model-supplied text. Upstream's own reader stops at the same size. */
+export declare const MAX_SHELL_READ_CHARS = 10000;
+/** Read `source` as the tightening reader must: every program run the text could perform, or why it cannot be read. */
+export declare function readShellCommand(source: string): ShellCommandShape;
+/** Every program run of `shape` can be NAMED from the text: no segment is unreadable, no peel stopped,
+ *  and every run candidate's program word is literal. The offer/mint side's "judgeable" question. */
+export declare function isFullyReadable(shape: ShellCommandShape): boolean;