@sema-agent/core 7.45.0 → 7.46.0

package/dist/core/tool-catalog-entries.d.ts

@@ -47,3 +47,24 @@ export declare const ENGINE_CARDS: Readonly<Record<string, string>>;
 export declare function toolFace(id: string): ToolFaceDeclaration;
 /** Definition-id → face, for the modules that spread one (`...TOOL_FACES.read`). Frozen: a face is data. */
 export declare const TOOL_FACES: Readonly<Record<string, ToolFaceDeclaration>>;
+/**
+ * The engine's own tool names, once each: every catalog entry the engine mounts itself (`source: "builtin"` — the hands,
+ * the scaffolds, the memory tools, the background-task tools), whatever face or contract it is mounted under. A host that
+ * must hand the engine a tool face with NO built-ins (`TaskSpec.excludeTools`, a shell's `--tools ""`) reads this set
+ * instead of keeping a list of its own: the catalog is the one source, and a name the engine adds later lands here with it.
+ */
+export declare const ENGINE_BUILTIN_TOOL_NAMES: readonly string[];
+/**
+ * The engine's HAND tools, once each, with the other spellings they answer to: the catalog rows mounted by `hands` — what a run
+ * mounts for itself over an execution environment (the file and shell band, the worktree pair, the band's background-shell
+ * pair). A delegated child's tool-name lists govern these beside the tools the delegation tool hands it, so the spawn reads
+ * this set rather than a list of its own.
+ */
+export declare const HAND_TOOLS: ReadonlyArray<{
+    readonly name: string;
+    readonly aliases?: readonly string[];
+}>;
+/** The wire names of {@link HAND_TOOLS}. */
+export declare const HAND_TOOL_NAMES: readonly string[];
+/** Is this name one the engine mounts itself ({@link ENGINE_BUILTIN_TOOL_NAMES})? A caller tool, an MCP tool or a skill tool is not. */
+export declare function isEngineBuiltinToolName(name: string): boolean;

package/dist/core/tool-catalog-entries.js

@@ -180,3 +180,12 @@ function deepFreeze(value) {
 }
 deepFreeze(TOOL_CATALOG_ENTRIES);
 export const TOOL_FACES = Object.freeze(Object.fromEntries(TOOL_CATALOG_ENTRIES.map((e) => [e.id, e.face])));
+export const ENGINE_BUILTIN_TOOL_NAMES = Object.freeze([...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.source === "builtin").map((e) => e.name))]);
+export const HAND_TOOLS = Object.freeze([...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.mountedBy.includes("hands")).map((e) => e.name))].map((name) => {
+    const aliases = [...new Set(TOOL_CATALOG_ENTRIES.filter((e) => e.name === name && e.mountedBy.includes("hands")).flatMap((e) => e.face.aliases ?? []))];
+    return Object.freeze(aliases.length > 0 ? { name, aliases: Object.freeze(aliases) } : { name });
+}));
+export const HAND_TOOL_NAMES = Object.freeze(HAND_TOOLS.map((t) => t.name));
+export function isEngineBuiltinToolName(name) {
+    return ENGINE_BUILTIN_TOOL_NAMES.includes(name);
+}

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

@@ -79,6 +79,17 @@ export interface ToolCallRequest {
      * Read-only, like `cwd`.
      */
     root?: string;
+    /** The call's target reading (`readCallTarget`: lexical / canonical / hop views per reading of the path slot), stamped by the Runner on a
+     *  leg whose lanes can hold a path rule; it describes only the `args` object it was taken for (`callTargetReadingOf`). Read-only. */
+    targetReading?: import("./effective-path-target.js").CallTargetReading;
+    /**
+     * An ENGINE-INTERNAL seat, not a fact of the call: the anchors of the policy now judging this request — the leg its
+     * path rules were installed on (`installPolicyAnchors`). Present only on the copy an installed policy hands its own
+     * inner `check` (where `createPermissionRulePolicy` reads it; an inner installation's anchors win over an outer one's);
+     * the request the gate holds, an `AskRequest`, a hook's input and a parked row never carry it. A host neither sets nor
+     * reads it.
+     */
+    pathRuleAnchors?: import("./permission-rule-model.js").PathRuleBases;
     /**
      * The CANONICAL directories THIS RUN'S PROMPT ADVERTISES AS WRITABLE — the admitted list of the root
      * fence's advertised-writable-directory seat (the memory engine's write home, the deployment's
@@ -537,11 +548,14 @@ export interface ToolPolicy {
      * describes the policy must read that bit, not the field's presence.
      */
     readonly projection?: ToolPolicyProjection;
-    /** The policy's path DENY rules that speak for a face of the engine's deny table (a `Read(<pattern>)` / `Edit(<pattern>)`
-     *  deny compiled by `createPermissionRulePolicy`), as rows the prepared leg joins to its read and write tables — so the
-     *  shell's reads and writes and the traversals meet the rule, not only the tool it names. Carried through
-     *  {@link combinePolicies}; read with {@link toolPolicyPathDenyRules}. Deny-only: a row can only refuse more. */
-    readonly pathDenyRules?: readonly import("../tools/fs/read-deny.js").PathRuleDenyRow[];
+    /** The policy's PATH rules as a function of the ANCHORS of the leg they are installed on (`createPermissionRulePolicy`
+     *  sets it; present exactly when the policy judges a path target): given the leg's root and home, every path rule
+     *  bound there — the face-keyed deny rows the prepared leg joins to its read and write tables (so the shell's reads and
+     *  writes and the traversals meet the rule, not only the tool it names), and the rows its own `check` judges at the
+     *  gate. A policy the Runner already installed answers with its own installation's rows whatever it is given. Carried
+     *  through {@link combinePolicies}; read with {@link toolPolicyPathRules}. Its presence also tells the Runner to read
+     *  each call's target ({@link ToolCallRequest.targetReading}). */
+    readonly pathRules?: (anchors: import("./permission-rule-model.js").PathRuleBases) => readonly import("./path-rule-binding.js").BoundPathRule[];
     /** Does this policy guard a write to this ABSOLUTE target — would it refuse the write if a write tool made it? The
      *  policy's answer for a writer it cannot see as a call (the shell's file commands), read by the shell station's
      *  `writesPlaced` fact alone: a guarded target is not placed, so no permission mode answers the command and its ask
@@ -558,9 +572,15 @@ export interface ToolPolicy {
  * each by name off the wrapped policy, {@link combinePolicies} folds each. The fence makes a new {@link ToolPolicy} member
  * a compile error until the table names it.
  */
-declare const TOOL_POLICY_CARRIED_MEMBERS: readonly ["projection", "pathDenyRules", "writeTargetGuard", "nameSets"];
+declare const TOOL_POLICY_CARRIED_MEMBERS: readonly ["projection", "pathRules", "writeTargetGuard", "nameSets"];
 type ToolPolicyCarriedMember = (typeof TOOL_POLICY_CARRIED_MEMBERS)[number];
 export type ToolPolicyCarriesEveryMember = AssertAllKeysHandled<Exclude<Exclude<keyof ToolPolicy, "check">, ToolPolicyCarriedMember>>;
+/** The carried members that are set on `p`, each read by name — an accessor or a non-enumerable member included. */
+export declare function carriedMembersOf(p: {
+    readonly [K in ToolPolicyCarriedMember]?: ToolPolicy[K];
+}): {
+    -readonly [K in ToolPolicyCarriedMember]?: ToolPolicy[K];
+};
 /**
  * The ONE way to wrap a policy: the wrapper decides through `check`; every member {@link ToolPolicy} declares beside it
  * (projection, name sets, path deny rows, write-target guard — the carried-member table) rides as `inner` holds it, read
@@ -570,8 +590,10 @@ export type ToolPolicyCarriesEveryMember = AssertAllKeysHandled<Exclude<Exclude<
  * The ask-class brand is not carried: it attests the replaced `check`.
  */
 export declare function wrapToolPolicy<P extends ToolPolicy>(inner: P, check: ToolPolicy["check"]): Pick<P, ToolPolicyCarriedMember> & ToolPolicy;
-/** Every path deny row the given policies carry (combined policies included), in order — the deny tables' rule rows. */
-export declare function toolPolicyPathDenyRules(policies: readonly (ToolPolicy | undefined)[]): readonly import("../tools/fs/read-deny.js").PathRuleDenyRow[];
+/** Every path rule the given policies carry (combined policies included), in order, bound at `anchors` — the anchors of
+ *  the leg the policies are installed on (a policy already installed answers with its own installation's rows). The deny
+ *  tables take the rows that guard a face (`faces` non-empty) of a deny rule. */
+export declare function toolPolicyPathRules(policies: readonly (ToolPolicy | undefined)[], anchors: import("./permission-rule-model.js").PathRuleBases): readonly import("./path-rule-binding.js").BoundPathRule[];
 /** The one write-target guard the given policies carry together (combined policies included): `true` when any member
  *  guards the target, a member that throws counting as guarding it. `undefined` when none carries one. */
 export declare function toolPolicyWriteTargetGuard(policies: readonly (ToolPolicy | undefined)[]): ToolPolicy["writeTargetGuard"];

package/dist/core/tool-policy.js

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { homedir } from "node:os";
+import { withArgsReading } from "./effective-path-target.js";
 import { brandPolicyAskClass } from "./ask-class.js";
 import { decisionAskClassesOf, headlessDenialMessage } from "./ask-origin.js";
 import { ownReadRootCandidate, readRootGrantSeat } from "./read-root-grant-screen.js";
@@ -137,8 +138,8 @@ export const ASK_EVIDENCE_ABSENCE_VALUES = ["not_wired", "not_adjudicated", "una
 export function decisionText(d) {
     return d.message;
 }
-const TOOL_POLICY_CARRIED_MEMBERS = ["projection", "pathDenyRules", "writeTargetGuard", "nameSets"];
-function carriedMembersOf(p) {
+const TOOL_POLICY_CARRIED_MEMBERS = ["projection", "pathRules", "writeTargetGuard", "nameSets"];
+export function carriedMembersOf(p) {
     const out = {};
     const carry = (k) => {
         const v = p[k];
@@ -152,8 +153,8 @@ function carriedMembersOf(p) {
 export function wrapToolPolicy(inner, check) {
     return { ...carriedMembersOf(inner), check };
 }
-export function toolPolicyPathDenyRules(policies) {
-    return policies.flatMap((p) => (Array.isArray(p?.pathDenyRules) ? p.pathDenyRules : []));
+export function toolPolicyPathRules(policies, anchors) {
+    return policies.flatMap((p) => (typeof p?.pathRules === "function" ? p.pathRules(anchors) : []));
 }
 export function toolPolicyWriteTargetGuard(policies) {
     const guards = policies.flatMap((p) => (typeof p?.writeTargetGuard === "function" ? [p.writeTargetGuard] : []));
@@ -514,7 +515,7 @@ export function createApprovalPolicy(opts) {
 }
 export function combinePolicies(...policies) {
     const nameSets = policies.flatMap(toolPolicyNameSets);
-    const pathDenyRules = toolPolicyPathDenyRules(policies);
+    const pathRuled = policies.filter((p) => typeof p?.pathRules === "function");
     const writeTargetGuard = toolPolicyWriteTargetGuard(policies);
     const childProjections = policies.map((p) => p.projection);
     const projectedComponents = [];
@@ -536,7 +537,7 @@ export function combinePolicies(...policies) {
     const folded = {
         projection: combinedProjection,
         nameSets: nameSets.length > 0 ? nameSets : undefined,
-        pathDenyRules: pathDenyRules.length > 0 ? pathDenyRules : undefined,
+        pathRules: pathRuled.length > 0 ? (anchors) => toolPolicyPathRules(pathRuled, anchors) : undefined,
         writeTargetGuard,
     };
     return {
@@ -576,7 +577,8 @@ export function combinePolicies(...policies) {
                     continue;
                 }
                 if (d.updatedInput !== undefined) {
-                    current = { ...current, args: d.updatedInput };
+                    const reread = withArgsReading(current, d.updatedInput, signal);
+                    current = reread !== undefined ? await reread : { ...current, args: d.updatedInput };
                     rewrite = d;
                     stated = d.action === "allow" ? d.decisionReason : undefined;
                 }

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

@@ -212,8 +212,9 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * carries its own tool set, and a parent that mounts nothing but the delegation tool can still hand
      * its children a network tool, so the parent's roster is the wrong thing to look at.
      *
-     * ABSENT ⇔ the pool is not statically knowable — a spawn-time tool factory can inject tools whose
-     * identity does not exist until the call happens — and the reader fails closed on that.
+     * ABSENT ⇔ the pool is not statically knowable — a spawn-time tool factory with no declared roster
+     * (`SubagentToolOptions.extraToolNames`) can inject tools whose identity does not exist until the call
+     * happens — and the reader fails closed on that. A declared roster's tools are rows of the pool.
      */
     agentToolPool?: ReadonlyArray<{
         name: string;

package/dist/core/write-protect.d.ts

@@ -173,6 +173,10 @@ export interface WriteProtectionCompileOptions {
      *  path-family source when the call carries no cwd. Omitted ⇒ relative spellings resolve against the
      *  cwd, then the environment's own working directory. */
     readonly rootPath?: string;
+    /** The host's configuration root when it keeps the agent's configuration directory somewhere other than the home's
+     *  `.sema` (`RunnerDeps.agentConfigDir`, absolute, already screened): every row that names the `.sema` directory also
+     *  names the same tail below this root, and a hit there cites the row. Omitted ⇒ the table is judged as it stands. */
+    readonly agentConfigDir?: string;
     /**
      * Called at most ONCE per judgment, at the moment the ENVIRONMENT half is found unable to contribute
      * ({@link WriteProtectionViewAbsence}) — before the judgment returns, and on the hit arm as well as the

package/dist/core/write-protect.js

@@ -4,6 +4,7 @@ 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 +197,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 +211,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 +246,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 +311,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 +320,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" };

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,7 +194,7 @@ 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";
@@ -202,12 +203,13 @@ export type { PermissionSeatInputs, PermissionSeatReading } from "./core/mode-po
 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 { 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

@@ -248,6 +248,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) => ({

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
@@ -140,6 +56,9 @@ export type ProgramPositionRefusal = {
     /** 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;
+    /** The launcher hands the shell its operands as text (`watch "S"`); absent beside `runsShell`, the shell is handed
+     *  nothing (`sudo -s`, `chroot DIR`) and runs its standard input. */
+    readonly handsText?: true;
 };
 export interface ProgramPosition {
     /** Indices of the bare control words stripped in front (`!`, `if`, `time`, …), in order; their declared options
@@ -159,6 +78,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 +105,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 +118,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;