@sema-agent/core 7.45.0 → 7.47.0

package/dist/core/write-protect.js

@@ -1,9 +1,11 @@
+import { releasableAskClassesFor } from "./ask-origin.js";
 import { canonicalizeTarget, isWinFormPath, writeTargetPath, isUncPath, isAbsoluteForFamily, joinForFamily, pathFamilyOf } from "../tools/fs/safety.js";
 import { protectivePathTargetOf } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
 import { canonicalDataRootKeys, dataRootSpellings, relativeUnderRoot } from "./sensitive-path-policy.js";
 import { symlinkChainHops } from "./path-identity.js";
 import { readDenyPatternRun } from "../tools/fs/read-deny.js";
+import { agentConfigDirSegments, agentConfigDirTail } from "./agent-config-dir.js";
 import { thrownText } from "./thrown-value.js";
 const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
 export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
@@ -196,6 +198,7 @@ export function compileWriteProtection(entries, opts) {
     const basenames = new Map();
     const segments = new Map();
     const runs = [];
+    const configTails = [];
     for (const row of rows) {
         const folded = foldWriteProtectName(row.name);
         if (row.kind === "basename") {
@@ -209,8 +212,23 @@ export function compileWriteProtection(entries, opts) {
         else {
             runs.push({ name: row.name, parts: folded.split("/").filter((s) => s.length > 0) });
         }
+        const tail = row.kind === "basename" ? undefined : agentConfigDirTail(row.name);
+        if (tail !== undefined && opts?.agentConfigDir !== undefined)
+            configTails.push({ hit: { name: row.name, kind: row.kind }, tail: foldWriteProtectName(tail).split("/").filter((s) => s.length > 0) });
     }
-    const judgeSegments = (raw) => {
+    const configRootSpelled = opts?.agentConfigDir === undefined ? [] : [agentConfigDirSegments(opts.agentConfigDir)];
+    const judgeAtConfigRoots = (segs, roots) => {
+        for (const root of roots) {
+            const at = root.map(foldWriteProtectSegment);
+            if (segs.length < at.length || !at.every((a, i) => segs[i] === a))
+                continue;
+            for (const { hit, tail } of configTails)
+                if (segs.length >= at.length + tail.length && tail.every((t, i) => segs[at.length + i] === t))
+                    return hit;
+        }
+        return null;
+    };
+    const judgeSegments = (raw, configRoots) => {
         if (raw.length === 0)
             return null;
         const segs = raw.map(foldWriteProtectSegment);
@@ -229,23 +247,26 @@ export function compileWriteProtection(entries, opts) {
                     return { name: run.name, kind: "segment-run" };
             }
         }
-        return null;
+        return configTails.length === 0 ? null : judgeAtConfigRoots(segs, configRoots);
     };
-    const judgeViews = (spelling) => {
-        const posix = judgeSegments(pathViewSegments(spelling, "literal", POSIX_SEPARATOR_FAMILY, uncAnchorSegments(spelling)));
+    const judgeViews = (spelling, configRoots = configRootSpelled) => {
+        const posix = judgeSegments(pathViewSegments(spelling, "literal", POSIX_SEPARATOR_FAMILY, uncAnchorSegments(spelling)), configRoots);
         if (posix !== null)
             return posix;
-        const bothSeparators = judgeSegments(pathViewSegments(spelling, "literal"));
+        const bothSeparators = judgeSegments(pathViewSegments(spelling, "literal"), configRoots);
         if (bothSeparators !== null)
             return bothSeparators;
         for (const normalization of WIN32_NORMALIZATIONS) {
-            const hit = judgeSegments(pathViewSegments(spelling, normalization));
+            const hit = judgeSegments(pathViewSegments(spelling, normalization), configRoots);
             if (hit !== null)
                 return hit;
         }
         return null;
     };
-    const judgeSpelled = (spelled) => judgeViews(relativeUnderDataRoot(spelled, rootViews) ?? spelled);
+    const judgeSpelled = (spelled) => {
+        const remainder = relativeUnderDataRoot(spelled, rootViews);
+        return remainder === null ? judgeViews(spelled) : judgeViews(remainder, []);
+    };
     const judgeSpelling = (path, cwd) => {
         const base = typeof cwd === "string" && cwd.length > 0 ? cwd : undefined;
         const family = pathFamilyOf({ cwd: base });
@@ -291,7 +312,8 @@ export function compileWriteProtection(entries, opts) {
             }
             try {
                 if (canonKey !== undefined) {
-                    const byTarget = judgeViews(canonKey);
+                    const canonicalRoots = configTails.length === 0 || opts?.agentConfigDir === undefined ? [] : (await canonicalDataRootKeys(env, [opts.agentConfigDir], ctx.signal)).map(agentConfigDirSegments);
+                    const byTarget = judgeViews(canonKey, [...configRootSpelled, ...canonicalRoots]);
                     if (byTarget !== null) {
                         for (const rootKey of await canonicalDataRootKeys(env, dataRootPaths, ctx.signal)) {
                             const relative = relativeUnderRoot(canonKey, rootKey);
@@ -299,7 +321,7 @@ export function compileWriteProtection(entries, opts) {
                                 continue;
                             if (relative === "")
                                 return { kind: "clear" };
-                            const remainder = judgeViews(relative);
+                            const remainder = judgeViews(relative, []);
                             return remainder === null ? { kind: "clear" } : { kind: "hit", hit: remainder, via: "target" };
                         }
                         return { kind: "hit", hit: byTarget, via: "target" };
@@ -325,7 +347,7 @@ export function compileWriteProtection(entries, opts) {
         },
     };
 }
-export function writeProtectionTightenDecision(toolName, verdict) {
+export function writeProtectionTightenDecision(toolName, verdict, face) {
     if (verdict.kind === "hit") {
         return {
             action: "ask",
@@ -338,6 +360,15 @@ export function writeProtectionTightenDecision(toolName, verdict) {
         };
     }
     if (verdict.kind === "unresolvable") {
+        if (releasableAskClassesFor(face).includes("write_protection_unresolved")) {
+            return {
+                action: "ask",
+                message: verdict.unresolvedSymlink
+                    ? `tool "${toolName}" writes to a symlink whose real target could not be resolved, so the write-protection judge cannot tell whether it lands on a protected path (${verdict.cause}) — explicit approval required`
+                    : `tool "${toolName}" writes to a target that could not be resolved on this tree, so the write-protection judge cannot tell whether it lands on a protected path (${verdict.cause}) — explicit approval required`,
+                decisionReason: "safety",
+            };
+        }
         return {
             action: "deny",
             message: verdict.unresolvedSymlink

package/dist/index.d.ts

@@ -151,7 +151,8 @@ export { TOOL_FAMILIES, TOOL_MOUNT_TAGS, TOOL_APPROVAL_CARDS, TOOL_PATH_ACCESSES
 export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRuleFaceOf, pathTargetOf, pathTargetValue, protectivePathTargetOf, declaredPathTargetOf, BARE_REQUEST_CODE, isProtectedWrite, isDeclaredWrite, fileOpAccessOf, type ToolCallLike, pathConfinableWriteToolNames, pathTargetingToolNames, compactableToolNames, budgetExemptToolNames, handBandEffects, engineCardTypes, predictMountedToolNames, HANDS_BAND_TAGS, MOUNT_TAG_IN_HANDS_BAND, } from "./core/tool-registry.js";
 export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, type RosterSource, type ToolIdentity, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, rosterToolName, ruleNamesOf, inputKeysOf, ruleFaceOfInstance, rosterMemberBoundProblem, type RosterBoundMembers, type RosterBoundCode, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
 export { type ToolCallFace } from "./core/tool-policy.js";
-export { effectivePathTargetOf, pathTargetBaseOf, type ToolPathBases, type PathTargetReading } from "./core/effective-path-target.js";
+export { effectivePathTargetOf, pathTargetBaseOf, type ToolPathBases, type PathTargetReading, type CallTargetReading, type CallTargetView } from "./core/effective-path-target.js";
+export { type BoundPathRule, type PathRuleSpec } from "./core/path-rule-binding.js";
 export { pathFamilyOf, isAbsoluteForFamily, pathIdentityOf, win32NamespaceScreen, WIN32_NAMESPACE_REFUSALS, type PathFamily, type PathIdentity, type PathIdentityReading, type Win32NamespaceRefusal } from "./tools/fs/safety.js";
 export { judgeShellRead, type ShellReadJudgeInput, type ShellReadJudgment, type ShellReadVerdict, type ShellReadStationSeat, type ShellReadAdmission, } from "./tools/fs/shell-read-check.js";
 export { SHELL_READ_FINDINGS, SHELL_READ_SEATS, SHELL_READ_DECISION, SHELL_READ_FINDING_RANK, type ShellReadFinding, type ShellReadSeat, type ShellReadDisposition, type ShellReadBoundary, type ReadEstablishment, type EstablishedRead, type ReadFinding, } from "./tools/fs/shell-read-judge.js";
@@ -193,21 +194,22 @@ export { createAllowDenyPolicy, createApprovalPolicy,
  *  members that seat has no lane for (`"unavailable"`, a routing answer; `updatedInput`, an operator edit a
  *  policy verdict cannot get re-adjudicated). Exported so a host can NAME it instead of deriving it through
  *  `Parameters<typeof createApprovalPolicy>[0]["approve"]`. */
-type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, abortedSeatDeny, receiveHookResult, isEngineRefusal, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
+type ApprovalSeatOutcome, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, abortedSeatDeny, receiveHookResult, isEngineRefusal, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathRules, type ToolPolicyNameSets, type NamedToolPolicy, type ToolPolicyProjection, type ToolPolicyProjectionComponent, type ConstraintChainEntry, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, type ToolPolicy, type ToolCallRequest, type PermissionResult, type DecisionReason, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, type OnAsk, type AskOutcome, type ResolvedAsk, type AskRequest, type AskDelegationProvenance, type AskRuleEvidence, type AskEvidenceAbsence, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 export { type ReadRootGrantScreen } from "./core/read-root-grant-screen.js";
 export { type AskOrigin, ASK_ORIGINS, isAskOrigin, ORIGIN_IMPLIES_REAL_APPROVAL, PERSISTED_RULE_MANDATES, type PersistedRuleMandate, isPersistedRuleMandate, screenAskClassMembers } from "./core/ask-origin.js";
-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 { PERMISSION_MODES, type PermissionMode, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, type AskClass, isAskClass, MODE_ARBITRATION, type ModeArbitrationRow, ASK_FACES, type AskFace, askFaceOf, releasableAskClassesFor, 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, SkillGrantOrigin, SkillGrantRecord } from "./core/skill-grant.js";
 export { SKILL_GRANT_ORIGINS } from "./core/skill-grant.js";
 export type { BoundSkillGrants } from "./core/skill-grant-binding.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_ENTRY_INERT_REASONS, compileAllowEntry, compileAllowList, renderListEntry, 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, HOST_DECIDERS, type HostDecider, isHostDecider, 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";
+export { ENGINE_BUILTIN_TOOL_NAMES, isEngineBuiltinToolName } from "./core/tool-catalog-entries.js";
 export { policyCannotAnswer, type HeldQuestion } from "./core/real-approval.js";
 export { type AskCarry } from "./core/hooks.js";
 export { SWAPPABLE_DEP_SEATS, SWAP_SEAT_NOTICE, isSwappableDepSeat, screenSwappableDeps, type SwappableDepSeat, type SwappableDeps } from "./core/swappable-deps.js";

package/dist/index.js

@@ -124,6 +124,7 @@ export { describeToolCatalog, catalogEntriesNamed, catalogToolNames, catalogRule
 export { ToolRosterEntry, ToolRoster, ToolRosterDelta, ToolRosterRenderHints, ROSTER_SOURCES, toolIdentityOf, mintCapabilityId, diffToolRoster, judgeParkedToolIdentity, ruleFacesFromRoster, toolCallFaceOf, rosterToolName, ruleNamesOf, inputKeysOf, ruleFaceOfInstance, rosterMemberBoundProblem, ToolRosterDeltaSeat, } from "./core/tool-roster.js";
 export {} from "./core/tool-policy.js";
 export { effectivePathTargetOf, pathTargetBaseOf } from "./core/effective-path-target.js";
+export {} from "./core/path-rule-binding.js";
 export { pathFamilyOf, isAbsoluteForFamily, pathIdentityOf, win32NamespaceScreen, WIN32_NAMESPACE_REFUSALS } from "./tools/fs/safety.js";
 export { judgeShellRead, } from "./tools/fs/shell-read-check.js";
 export { SHELL_READ_FINDINGS, SHELL_READ_SEATS, SHELL_READ_DECISION, SHELL_READ_FINDING_RANK, } from "./tools/fs/shell-read-judge.js";
@@ -158,18 +159,19 @@ export { hasScheduler, isValidCronExpr, SchedulerError } from "./core/scheduler.
 export { createSchedulerTools, SCHEDULE_WAKEUP_TOOL_NAME, AUTONOMOUS_LOOP_SENTINEL, AUTONOMOUS_LOOP_DYNAMIC_SENTINEL, } from "./tools/scheduler-tools.js";
 export { resolveAutonomousLoopPrompt, AUTONOMOUS_LOOP_PREAMBLE, AUTONOMOUS_LOOP_PREAMBLE_PERSISTENT, } from "./tools/loop-tick.js";
 export { tightenTaskSpec, TaskSpecTightenError } from "./core/tighten-task-spec.js";
-export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, abortedSeatDeny, receiveHookResult, isEngineRefusal, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathDenyRules, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
+export { createAllowDenyPolicy, createApprovalPolicy, COARSE_SHELL_TOOLS, createCoarseCommandNamePolicy, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, findUnverifiableRecursiveDelete, combinePolicies, abortedSeatDeny, receiveHookResult, isEngineRefusal, wrapToolPolicy, decisionText, resolveAsk, toolPolicyNameSets, toolPolicyPathRules, checkToolPolicyProjection, constraintChainEntryOf, constraintChainDigest, screenApproverAttribution, APPROVER_ATTRIBUTION_MAX_CHARS, ASK_EVIDENCE_ABSENCE_VALUES, } from "./core/tool-policy.js";
 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 { PERMISSION_MODES, isPermissionMode, PERMISSION_MODE_RANK, clampPermissionMode, ASK_CLASSES, isAskClass, MODE_ARBITRATION, ASK_FACES, askFaceOf, releasableAskClassesFor, 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_ENTRY_INERT_REASONS, compileAllowEntry, compileAllowList, renderListEntry } 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, HOST_DECIDERS, isHostDecider, 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";
+export { ENGINE_BUILTIN_TOOL_NAMES, isEngineBuiltinToolName } from "./core/tool-catalog-entries.js";
 export { policyCannotAnswer } from "./core/real-approval.js";
 export {} from "./core/hooks.js";
 export { SWAPPABLE_DEP_SEATS, SWAP_SEAT_NOTICE, isSwappableDepSeat, screenSwappableDeps } from "./core/swappable-deps.js";

package/dist/orchestration/run-spec.js

@@ -5,7 +5,8 @@ import { combinePolicies } from "../core/tool-policy.js";
 import { delimitUntrusted } from "../core/untrusted-text.js";
 import { isDurablePause } from "../agents/suspend-guard.js";
 import { terminalProjection } from "../core/runner/terminal-projection.js";
-import { isAbsoluteForFamily, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
+import { writeTargetPath } from "../tools/fs/safety.js";
+import { callTargetViewsOf } from "../core/effective-path-target.js";
 import { captureBaseline, resolveFrozenPaths, restoreFrozenPaths, runOracle, snapshotFrozenPaths, specError, } from "../core/spec-contract.js";
 import { isProtectedWrite } from "../core/tool-registry.js";
 const CASE_INSENSITIVE_FS = process.platform === "darwin" || process.platform === "win32";
@@ -21,13 +22,13 @@ export function frozenDenyPolicy(rootDir, frozenResolved) {
         check(req) {
             if (!isProtectedWrite(req))
                 return { action: "allow" };
-            const raw = writeTargetPath(req);
-            if (typeof raw !== "string" || raw.length === 0)
+            const views = callTargetViewsOf(req, "tighten", { root: rootDir });
+            if (views === undefined || views.spellings.length === 0)
                 return { action: "allow" };
-            const absForm = isAbsoluteForFamily(pathFamilyOf({ root: rootDir, cwd: req.cwd }), raw);
-            const abs = pathKey(absForm ? raw : resolve(req.cwd || rootDir, raw));
-            if (frozen.has(abs)) {
-                return { action: "deny", message: `${raw} is part of the frozen specification surface (read-only).` };
+            const raw = writeTargetPath(req);
+            const hit = views.spellings.some((v) => frozen.has(pathKey(v)));
+            if (hit) {
+                return { action: "deny", message: `${typeof raw === "string" && raw.length > 0 ? raw : views.spellings[0]} is part of the frozen specification surface (read-only).` };
             }
             return { action: "allow" };
         },

package/dist/orchestration/workflow.js

@@ -1579,7 +1579,7 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         opts.onForwardEvent(e.type === "task_progress" ? { ...e, workflowRunId: runId, workflowAgentLabel: label } : e);
                     }
                     : undefined;
-                const baseInternals = { ...(agentOpts.isolation ? { isolation: agentOpts.isolation } : {}), ...(opts.parentCwd !== undefined ? { parentCwd: opts.parentCwd } : {}), ...spawnAttribution, ...(await captureFloorSeatsNow()), ...(enrichedForward !== undefined ? { onForwardEvent: enrichedForward } : {}), delegationTaskType: "workflow", agentName: label, onWorkspaceResolved: createWorkspaceObserver(rec) };
+                const baseInternals = { ...(agentOpts.isolation ? { isolation: agentOpts.isolation } : {}), ...(opts.parentCwd !== undefined ? { parentCwd: opts.parentCwd, callerRoot: opts.parentCwd } : {}), ...spawnAttribution, ...(await captureFloorSeatsNow()), ...(enrichedForward !== undefined ? { onForwardEvent: enrichedForward } : {}), delegationTaskType: "workflow", agentName: label, onWorkspaceResolved: createWorkspaceObserver(rec) };
                 let attempts = 0;
                 let throttleRetried = false;
                 let lastAttemptReason;

package/dist/shell/lex.d.ts

@@ -103,6 +103,17 @@ export interface WordExpansion {
     readonly body?: string;
     /** The parameter name, where the expansion names one. */
     readonly name?: string;
+    /** A glob's pattern — absent where an expansion stands inside it (its text is not the pattern): `folded`, what the
+     *  program receives where it matches nothing — quotes removed, the spelling {@link LexedWord.folded} carries at its place
+     *  (`[^.]`); `written`, as written, quoting kept (`[^\.]`, `["!"a]`) — the text a shell re-reading it matches by;
+     *  `judged`, the spelling a reader judges the names it matches by — `folded`, save a class the judge reads as any one
+     *  character: one holding a quoted or escaped character (its quote-removed text reads another class: `["!"a]` is not
+     *  the negation `[!a]`) or a `[:…:]` / `[=…=]` / `[.….]` unit — spelled `?`, a superset of its members. */
+    readonly pattern?: {
+        readonly folded: string;
+        readonly written: string;
+        readonly judged: string;
+    };
 }
 export interface QuotedSpan {
     /** Offsets into {@link LexedWord.raw}, `[start, end)`; the quote characters belong to their span. */
@@ -143,6 +154,10 @@ export interface LexedWord {
     readonly kind: "word";
     readonly raw: string;
     readonly folded: string;
+    /** The spelling a reader judges the word's names by, where it is not `folded`: each bracket class holding a quoted or
+     *  escaped character or a `[:…:]` / `[=…=]` / `[.….]` unit spelled `?` (`["!"a]*`, `[[:alpha:]]*` ⇒ `?*`,
+     *  {@link WordExpansion.pattern}). */
+    readonly judged?: string;
     readonly pieces: readonly WordPiece[];
     readonly quotedSpans: readonly QuotedSpan[];
     /** The pieces that carry an expansion, in order. */
@@ -248,6 +263,13 @@ export declare function substitutionsInHeredocBody(body: string): {
     readonly body: string;
     readonly kind: "command" | "arithmetic";
 }[] | undefined;
+/** The text a word's pieces hand the program when every piece is literal; `undefined` when one is an expansion or
+ *  unresolved. */
+export declare function literalTextOf(pieces: readonly WordPiece[]): string | undefined;
+/** The text an UNQUOTED here-document body delivers when the shell expands nothing in it: a backslash before `$`, a
+ *  backquote or a backslash is removed (a line continuation was joined when the body was read), every other character
+ *  stands. `undefined` when an unescaped `$` or backquote stands in it: the program reads what the expansion makes. */
+export declare function literalHeredocBody(body: string): string | undefined;
 /** Lex a command: its segments, or the one reason bash (or this lexer) cannot delimit them. */
 export declare function lexShell(source: string): ShellLex;
 /**

package/dist/shell/lex.js

@@ -319,6 +319,23 @@ export function substitutionsInHeredocBody(body) {
     }
     return out;
 }
+export function literalTextOf(pieces) {
+    return pieces.every((q) => q.literal !== undefined) ? pieces.map((q) => q.literal).join("") : undefined;
+}
+export function literalHeredocBody(body) {
+    let out = "";
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (ch === "$" || ch === "`")
+            return undefined;
+        if (ch === "\\" && i + 1 < body.length && "$`\\".includes(body[i + 1])) {
+            out += body[++i];
+            continue;
+        }
+        out += ch;
+    }
+    return out;
+}
 const BLANK = /[ \t]/;
 const fail = (reason, at) => ({ parseFailure: { reason, at } });
 const publicPiece = (p) => ({
@@ -340,6 +357,7 @@ class WordBuilder {
     marks = [];
     subscript;
     compound = false;
+    widenedClasses = [];
     begin(src) { if (!this.started)
         this.at = src; }
     push(w, f, by, src) {
@@ -385,6 +403,17 @@ class WordBuilder {
     mark(reason, rawAt) { this.marks.push({ at: rawAt, reason }); }
     inSubscript() { return this.subscript !== undefined && this.subscript.rawEnd === undefined; }
     foldedOf(r) { return r >= this.foldedAt.length ? this.folded.length : this.foldedAt[r]; }
+    classSpelled(from, to) {
+        let out = "";
+        let at = from;
+        for (const [a, b] of this.widenedClasses) {
+            if (a < at || b > to)
+                continue;
+            out += `${this.folded.slice(at, a)}?`;
+            at = b;
+        }
+        return out + this.folded.slice(at, to);
+    }
     slice(from, to) {
         const out = [];
         for (const p of this.pieces) {
@@ -502,9 +531,23 @@ class WordBuilder {
             else if (stack.length > 0 && (d === "," || (d === "." && this.raw[j + 1] === ".")))
                 stack[stack.length - 1].listed = true;
         }
-        const nextBracketClose = new Array(n + 1).fill(-1);
-        for (let j = n - 1; j >= 0; j--)
-            nextBracketClose[j] = readable(j) && this.raw[j] === "]" ? j : nextBracketClose[j + 1];
+        const text = this.folded;
+        const nf = text.length;
+        const readableAt = (f) => f < nf && readable(this.rawOfFolded[f]);
+        const unitClose = (d) => {
+            const at = new Array(nf + 2).fill(-1);
+            for (let f = nf - 2; f >= 0; f--)
+                at[f] = readableAt(f) && readableAt(f + 1) && text[f] === d && text[f + 1] === "]" ? f : at[f + 1];
+            return at;
+        };
+        const unitCloses = new Map([":", "=", "."].map((d) => [d, unitClose(d)]));
+        const nextBracketClose = new Array(nf + 2).fill(-1);
+        const nextSlash = new Array(nf + 1).fill(nf);
+        for (let f = nf - 1; f >= 0; f--) {
+            const unitEnd = readableAt(f) && text[f] === "[" && readableAt(f + 1) ? unitCloses.get(text[f + 1] ?? "")?.[f + 2] ?? -1 : -1;
+            nextBracketClose[f] = readableAt(f) && text[f] === "]" ? f : unitEnd >= 0 ? nextBracketClose[unitEnd + 2] : nextBracketClose[f + 1];
+            nextSlash[f] = text[f] === "/" ? f : nextSlash[f + 1];
+        }
         const ranges = [];
         for (let k = 0; k < n; k++) {
             if (!readable(k))
@@ -519,19 +562,35 @@ class WordBuilder {
                 continue;
             }
             if (c === "*" || c === "?") {
-                ranges.push({ from: k, to: k + 1, exp: { kind: "glob", yields: "many" } });
+                ranges.push({ from: k, to: k + 1, exp: { kind: "glob", yields: "many", pattern: { folded: c, written: c, judged: c } } });
                 continue;
             }
             if (c === "[") {
-                let j = k + 1;
-                if (this.raw[j] === "!" || this.raw[j] === "^")
+                if (this.rawOfFolded[this.foldedOf(k)] !== k)
+                    continue;
+                let j = this.foldedOf(k) + 1;
+                if ((text[j] === "!" || text[j] === "^") && readableAt(j))
                     j++;
-                if (this.raw[j] === "]")
+                if (text[j] === "]" && readableAt(j))
                     j++;
-                const close = j < n ? nextBracketClose[j] : -1;
-                if (close < 0)
+                const closeAt = j < nf ? nextBracketClose[j] : -1;
+                if (closeAt < 0 || nextSlash[j] < closeAt)
                     continue;
-                ranges.push({ from: k, to: close + 1, exp: { kind: "glob", yields: "many", body: this.raw.slice(k + 1, close) } });
+                const close = this.rawOfFolded[closeAt];
+                let expands = false;
+                for (let m = k + 1; m < close && !expands; m++)
+                    expands = inExp[m] || braceClose.get(m)?.listed === true;
+                let widened = false;
+                for (let m = k + 1; m < close && !widened; m++)
+                    widened = this.rawQuoted[m] !== undefined;
+                for (let f = j; f < closeAt && !widened; f++)
+                    widened = readableAt(f) && text[f] === "[" && readableAt(f + 1) && (unitCloses.get(text[f + 1] ?? "")?.[f + 2] ?? -1) >= 0;
+                const from = this.foldedOf(k);
+                const to = this.foldedOf(close + 1);
+                if (!expands && widened)
+                    this.widenedClasses.push([from, to]);
+                const pattern = expands ? {} : { pattern: { folded: this.folded.slice(from, to), written: this.raw.slice(k, close + 1), judged: widened ? "?" : this.folded.slice(from, to) } };
+                ranges.push({ from: k, to: close + 1, exp: { kind: "glob", yields: "many", body: this.raw.slice(k + 1, close), ...pattern } });
                 k = close;
             }
         }
@@ -630,18 +689,20 @@ class WordBuilder {
     }
     finish(atCommandPosition, tildeSpelling = true) {
         const rawText = this.raw;
-        let foldedText = this.folded;
+        let literalTilde = false;
         let assignment;
         const tildeEnd = this.tildePrefixEnd(0, false);
         if (tildeEnd !== undefined)
             this.carveTilde(0, tildeEnd);
         else {
-            if (tildeSpelling)
-                foldedText = literalTildeSpelling(foldedText);
+            literalTilde = tildeSpelling;
             assignment = this.readAssignment();
         }
         if (!(assignment !== undefined && assignment.bare && atCommandPosition))
             this.carveBraceAndGlob();
+        const spelled = (text) => (literalTilde ? literalTildeSpelling(text) : text);
+        const foldedText = spelled(this.folded);
+        const judged = this.widenedClasses.length > 0 ? spelled(this.classSpelled(0, this.folded.length)) : undefined;
         if (assignment !== undefined && this.subscript?.text)
             this.mark("subscript_text", this.subscript.rawStart);
         const marks = this.marks.filter((m) => m.reason !== "subscript_text" || assignment?.subscript !== undefined).sort((a, b) => a.at - b.at);
@@ -662,6 +723,7 @@ class WordBuilder {
             kind: "word",
             raw: rawText,
             folded: foldedText,
+            ...(judged !== undefined ? { judged } : {}),
             pieces,
             quotedSpans: spans,
             expansions: pieces.filter((p) => p.expansion !== undefined),

package/dist/tools/fs/bash-program-position.d.ts

@@ -31,8 +31,6 @@ export declare function writtenAssignmentPrefix(token: string): {
     readonly settlesWholeName: boolean;
 } | undefined;
 export { SHELL_CONTROL_PREFIXES };
-/** Shell block words that name no command of their own (a loop head, a block close, a case head). */
-export declare const SHELL_BLOCK_WORDS: ReadonlySet<string>;
 /** A control word is a keyword only when bash sees it BARE: `'if'` / `"do"` / `\\!` are command names (a program
  *  looked up on PATH, whose failure changes nothing), so a quoted or escaped spelling never counts as one. */
 export declare function isBareControlWord(words: readonly LexedWord[], i: number, set: ReadonlySet<string>): boolean;
@@ -43,88 +41,6 @@ export declare function isBareControlWord(words: readonly LexedWord[], i: number
  * over control words and earlier assignments re-traces). One fact, two readers that must agree.
  */
 export declare function isLeadingAssignmentWord(words: readonly LexedWord[], i: number): boolean;
-/**
- * Programs that turn their STANDARD INPUT into the OPERANDS of another program, and EXEC that program directly.
- *
- * The same class as the shell re-entry programs, one level down: there the unseen text is COMMANDS; here the
- * command's name IS visible and its argv is not — `echo <path> | xargs cat` opens a file no token of this walk
- * ever named, because the operand arrives on a stream. The membership criterion is that behaviour and only that
- * behaviour; a program that consumes stdin as DATA (`sort`, `wc`, a reader the deployment never listed) is NOT a
- * member, because its stdin never becomes a filename. Spelled as a pattern — these are program names, never tool
- * names.
- *
- * "EXECS DIRECTLY" is what separates this class from the shell re-entry class, and it is why GNU `parallel` is
- * NOT a member: parallel BUILDS A COMMAND LINE and hands it to a shell, and with no command word at all it runs
- * each input line as a command — so parallel belongs to the shell re-entry class and is refused whole with no
- * exemption at all. A spelling this file has no name for (an aliased or wrapped `xargs`) is judged as any other
- * unlisted program is — the name-table floor the re-entry class records for itself.
- */
-export declare const ARGV_REENTRY_PROGRAM_RE: RegExp;
-/** The program an {@link ARGV_REENTRY_PROGRAM_RE} launcher runs when the chain names none: `xargs` defaults to
- *  `echo`, which is why a bare one reads nothing. */
-export declare const ARGV_REENTRY_DEFAULT_PROGRAM = "echo";
-/**
- * What a launcher declares about its OWN options: each exact spelling with its ARITY — `0` for a switch, `1` for an
- * option whose value is the next token. Every spelling not in the map falls to the refusal (the conservative side,
- * and the verdict those spellings always had); a `1` with no token left to take is not readable either.
- *
- * THREE SPELLINGS OF ONE DECLARATION, because getopt has three: an arity-1 entry is honoured separated (`-k 5`),
- * fused to its long name (`--signal=TERM`) and fused to its short letter (`-k5`), and an arity-0 short entry inside
- * a cluster of arity-0 letters (`-pv`). Reading only the exact spelling made one program two.
- *
- * WHAT A ROW MAY NOT GET WRONG: declaring an arity-1 option as arity 0 steps onto its VALUE and reads the value as
- * the program — the one direction that turns a refusal into a wrong answer rather than a lost one. A row carries
- * only options whose arity every supported implementation agrees on; a flag no row declares still refuses.
- */
-export interface LauncherRow {
-    /** Consulted ONLY for the launcher the command line itself names — a bare keyword in front of the command
-     *  (`time -p …`) or the written command word (`"time" -p …`, `X=1 time -p …`, `/usr/bin/time -p …`). A launcher
-     *  nested behind another (`env time -p …`) is that launcher's operand, and its options refuse: resolving past
-     *  them would turn a whole refusal into an ordinary walked segment — a widening, where every other read of this
-     *  table only ever finds MORE program to judge. */
-    readonly optionArity: ReadonlyMap<string, 0 | 1>;
-    /** A bare NEGATIVE integer in this launcher's option section is its OWN argument (`nice -5 <cmd>`), not a flag
-     *  the table cannot read. Per row: elsewhere a dash-leading token is an option, and reading one as a number
-     *  would step over a flag whose meaning this table does not know. */
-    readonly negativeIntegerIsOwnArgument?: true;
-    /** Positional operands the launcher takes BEFORE the program, consumed whatever they spell (`timeout DURATION
-     *  COMMAND`); a spelling-based reading under-accepted, and every spelling it missed became the program word. */
-    readonly requiredOperands?: number;
-    /** The launcher reads NAME=VALUE operands with ITS OWN name grammar (`env 1=x …`), wider than the shell's. */
-    readonly assignmentOperands?: true;
-    /** The launcher hands its operands to a SHELL as text (`watch "cat /x"` runs `sh -c`): no program word to read. */
-    readonly shellText?: true;
-    /** With no program word the launcher runs a SHELL: piped text would reach it, so an empty program position refuses. */
-    readonly whenNoProgram?: "shell";
-    /** Options whose value is a WHOLE COMMAND LINE the launcher splits and runs (`env -S "cmd arg"`,
-     *  `--split-string=…`). Not an arity this reader steps over — the program is inside the value, so the
-     *  program-position walk still refuses here — but the candidate extraction reads the value as nested shell
-     *  text instead of as one opaque word. */
-    readonly commandString?: readonly string[];
-}
-/**
- * The ONE launcher truth: programs that RUN ANOTHER PROGRAM named in ordinary argv tokens, so a declared reader can
- * sit behind one (`env cat <path>`, `sudo cat <path>`, `timeout 5 cat <path>`), each with the option grammar this
- * file reads for it.
- *
- * Membership is the key set. A row with no declared options means every option-shaped word after that launcher
- * refuses ("which program runs is not readable without the launcher's option table") — the answer every launcher
- * but `time` has always had, now stated per row rather than by omission. Declaring a row's options is a behaviour
- * decision with its own criteria; adding a launcher is a row.
- *
- * `time` carries both spellings a deployment can meet: the shell builtin takes `-p` alone, and the standalone
- * program adds a format, an output file, and three switches.
- *
- * A deliberate SUBSET of the rule lane's own `BARE_INTERPRETER_NAMES`, mirrored rather than imported because that
- * module imports the classifier — the dependency runs that way, and a cycle is a worse problem than a mirror whose
- * subset relation is pinned by test. GNU `parallel` is absent for the reason the shells are absent: it does not run
- * a program named in token-visible argv — it BUILDS a command line and hands it to a shell — so it is a shell
- * re-entry member instead. Language interpreters and shells are excluded as a scope statement: their program
- * argument is a script path or a quoted code string, not a token-visible program with token-visible operands.
- */
-export declare const LAUNCHER_TABLE: ReadonlyMap<string, LauncherRow>;
-/** The launcher names — derived from the table, never kept beside it. */
-export declare const COMMAND_LAUNCHERS: ReadonlySet<string>;
 export declare const PROGRAM_POSITION_REFUSAL_KINDS: readonly ["option_at_program_position", "control_syntax_at_program_position"];
 export type ProgramPositionRefusalKind = (typeof PROGRAM_POSITION_REFUSAL_KINDS)[number];
 /** Why the program could not be read — a closed set, each member minted into one sentence. `owner` is the word
@@ -137,9 +53,15 @@ export type ProgramPositionRefusal = {
     readonly kind: "control_syntax_at_program_position";
     readonly owner: string;
     readonly word: string;
-    /** Not a DECLINE ({@link programPositionRunsShell}): the row WAS read and a SHELL stands at the program
-     *  position. Absent ⇒ genuine control syntax, which IS one. */
-    readonly runsShell?: true;
+    /** Not a DECLINE ({@link programPositionRunsShell}): the row WAS read and a SHELL — or a program the launcher
+     *  names by an option of its own (`su -s PROGRAM`) — stands at the program position, run by the launcher at argv
+     *  index `launcher` and handed the words from index `from` on (none where `from` is the argv's end: `sudo -s`,
+     *  `chroot DIR`), as that launcher's row composes them (`launchedCommands`, shell-reentry-text.ts). Absent ⇒
+     *  genuine control syntax, which IS one. */
+    readonly runsShell?: {
+        readonly launcher: number;
+        readonly from: number;
+    };
 };
 export interface ProgramPosition {
     /** Indices of the bare control words stripped in front (`!`, `if`, `time`, …), in order; their declared options
@@ -159,6 +81,8 @@ export interface ProgramPosition {
     readonly argvFromStdin: boolean;
     /** The chain ends ON the re-entry program (nothing follows it), so it runs its default program. */
     readonly runsDefaultProgram: boolean;
+    /** The program the stream-fed chain member runs when the chain names none (`xargs` runs `echo`). */
+    readonly defaultProgram?: string;
     /** The program bash RUNS: the first word past the chain. `name` is the folded word as written, `basename` what
      *  bash resolves (`/usr/bin/cat` is `cat`). `undefined` when the chain names none or the read was refused. */
     readonly program: {
@@ -184,7 +108,7 @@ export declare function readProgramPosition(words: readonly LexedWord[]): Progra
 /** Does this program position hand a program operands the walk cannot see? True when the chain re-enters through
  *  stdin AND the program it runs is not one the caller accepts as a stream target. ONE reading, shared by every
  *  consumer; WHICH targets are accepted is the caller's declaration, not this reader's. */
-export declare function argvReentryUnjudged(pos: ProgramPosition, acceptedTargets: ReadonlySet<string>): boolean;
+export declare function argvReentryUnjudged(pos: ProgramPosition, acceptsTarget: (basename: string) => boolean): boolean;
 /**
  * The two ways this reader DECLINES rather than judges — a CLOSED set (`docs/CLOSED-SETS.md`), because what a
  * seat does with a declined segment is a ROW of the shell read decision table (`shell-read-judge.ts`, the
@@ -197,9 +121,9 @@ export type ShellScanDecline = (typeof SHELL_SCAN_DECLINES)[number];
 /** Does a SHELL stand where this segment's program would be — as the program itself (`sh -c`), or as a launcher
  *  ROW handing its operands to one (`watch "…"`)? ONE predicate for the re-entry class, so the two spellings
  *  cannot be answered differently; which names are shells is the caller's declaration. Not a decline. */
-export declare function programPositionRunsShell(pos: ProgramPosition, shellProgram: RegExp): boolean;
+export declare function programPositionRunsShell(pos: ProgramPosition, runsShell: (basename: string) => boolean): boolean;
 /** Which decline, if any, this program position raises — ONE reading of the two facts above, so no consumer
  *  re-derives either. A refusal that says a SHELL runs is NOT one: it names what runs. */
-export declare function shellScanDeclineOf(pos: ProgramPosition, acceptedStreamTargets: ReadonlySet<string>): ShellScanDecline | undefined;
+export declare function shellScanDeclineOf(pos: ProgramPosition, acceptsStreamTarget: (basename: string) => boolean): ShellScanDecline | undefined;
 /** ONE sentence per refusal kind, minted here and nowhere else. */
 export declare function programPositionRefusalSentence(refusal: ProgramPositionRefusal): string;