@sema-agent/core 5.12.0 → 5.14.0

package/dist/core/governance-codes.d.ts

@@ -0,0 +1,12 @@
+export type GovernanceRetryClass = "transient" | "terminal";
+export declare const GOVERNANCE_CODES: {
+    readonly "usage.window_exhausted": "terminal";
+    readonly "memory.admission_required": "transient";
+    readonly "memory.admission_denied": "terminal";
+    readonly "config.compliance_required": "transient";
+    readonly "config.compliance_denied": "terminal";
+    readonly "config.locked_key": "terminal";
+};
+export type GovernanceCode = keyof typeof GOVERNANCE_CODES;
+export declare const NON_GOVERNANCE_MEMORY_CODES: ReadonlySet<string>;
+export declare function governanceRetryClass(code: string): GovernanceRetryClass | undefined;

package/dist/core/governance-codes.js

@@ -0,0 +1,24 @@
+export const GOVERNANCE_CODES = {
+    "usage.window_exhausted": "terminal",
+    "memory.admission_required": "transient",
+    "memory.admission_denied": "terminal",
+    "config.compliance_required": "transient",
+    "config.compliance_denied": "terminal",
+    "config.locked_key": "terminal",
+};
+export const NON_GOVERNANCE_MEMORY_CODES = new Set([
+    "memory.secret_detected",
+    "memory.promotable_ungated",
+    "memory.announce_failed",
+    "memory.partition_adopt_failed",
+    "memory.partition_split",
+    "memory.tail",
+]);
+export function governanceRetryClass(code) {
+    if (Object.prototype.hasOwnProperty.call(GOVERNANCE_CODES, code)) {
+        return GOVERNANCE_CODES[code];
+    }
+    if (code.startsWith("usage."))
+        return "terminal";
+    return undefined;
+}

package/dist/core/hooks.d.ts

@@ -1,5 +1,5 @@
 import type { DocumentContent, ImageContent, TextContent } from "../internal/llm.js";
-import type { SessionTreeEntry } from "../internal/harness-types.js";
+import type { ExecutionEnv, FileError, Result, SessionTreeEntry } from "../internal/harness-types.js";
 import type { PermissionResult, ResolvedAsk, ToolCallRequest } from "./tool-policy.js";
 export interface Hooks {
     preToolUse?(toolName: string, input: unknown, ctx: HookToolContext): PreToolUseResult | undefined | Promise<PreToolUseResult | undefined>;
@@ -72,9 +72,17 @@ export interface StopHookResult {
     block?: string;
     additionalContext?: string;
 }
+export interface HookEnvCapabilities {
+    canonicalPath?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    exists?(path: string, abortSignal?: AbortSignal): Promise<Result<boolean, FileError>>;
+    readLink?(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
+    cwd?(): string;
+}
+export declare function createHookEnvCapabilities(env: ExecutionEnv): HookEnvCapabilities;
 export interface HookToolContext {
     toolCallId: string;
     toolName: string;
+    env?: HookEnvCapabilities;
 }
 export interface HookToolOutput {
     content: Array<TextContent | ImageContent | DocumentContent>;
@@ -103,6 +111,18 @@ export interface ToolGateResult {
     };
     preToolContext: string[];
 }
+export type ContentAskOutcome = {
+    kind: "answered";
+    presentedInput: unknown;
+} | {
+    kind: "unavailable";
+    presentedInput?: unknown;
+    parkDeclined: boolean;
+} | {
+    kind: "delivery_failure";
+    code: string;
+    presentedInput?: unknown;
+};
 export interface ToolGateInput {
     onNotifyError?: (failure: import("./safe-notify.js").SafeNotifyFailure) => void;
     event: {
@@ -111,9 +131,11 @@ export interface ToolGateInput {
         input: Record<string, unknown>;
     };
     preToolUse?: Hooks["preToolUse"];
+    hookEnv?: HookEnvCapabilities;
     adjudicate?: (req: ToolCallRequest) => Promise<PermissionResult>;
     resolveAsk: (decision: PermissionResult, req: ToolCallRequest) => Promise<ResolvedAsk>;
-    suspendAsk?: (req: ToolCallRequest, postHookArgs: unknown, safety?: import("./checkpoint-store.js").SafetyAxis, approverUnavailable?: boolean) => Promise<ToolGateResult["suspend"] | undefined>;
+    suspendAsk?: (req: ToolCallRequest, postHookArgs: unknown, safety?: import("./checkpoint-store.js").SafetyAxis, liveFaceUnavailable?: boolean) => Promise<ToolGateResult["suspend"] | undefined>;
+    resolveContentAsk?: (req: ToolCallRequest) => Promise<ContentAskOutcome>;
     egress?: boolean;
     irreversibility?: "never" | "maybe" | "always";
     reversibilityProbe?: (args: unknown) => {

package/dist/core/hooks.js

@@ -14,6 +14,67 @@ export function cloneObserverInput(input) {
         return input;
     }
 }
+const reflectApply = Reflect.apply;
+const getOwnPropertyDescriptor = Object.getOwnPropertyDescriptor;
+const getPrototypeOf = Object.getPrototypeOf;
+const objectPrototype = Object.prototype;
+function findEnvSlot(env, key) {
+    for (let o = env; o !== null && o !== objectPrototype; o = getPrototypeOf(o)) {
+        const desc = getOwnPropertyDescriptor(o, key);
+        if (desc !== undefined)
+            return { holder: o, desc };
+    }
+    return undefined;
+}
+function readEnvPrimitive(env, key) {
+    const slot = findEnvSlot(env, key);
+    if (slot === undefined)
+        return undefined;
+    return slot.desc.get !== undefined ? reflectApply(slot.desc.get, env, []) : slot.desc.value;
+}
+function createCwdReader(env) {
+    const slot = findEnvSlot(env, "cwd");
+    if (slot === undefined)
+        return undefined;
+    const getter = slot.desc.get;
+    const initial = getter !== undefined ? reflectApply(getter, env, []) : slot.desc.value;
+    if (typeof initial !== "string")
+        return undefined;
+    let last = initial;
+    return () => {
+        const desc = getOwnPropertyDescriptor(slot.holder, "cwd");
+        const value = desc === undefined
+            ? undefined
+            : desc.get !== undefined
+                ? desc.get === getter
+                    ? reflectApply(desc.get, env, [])
+                    : undefined
+                : desc.value;
+        if (typeof value === "string")
+            last = value;
+        return last;
+    };
+}
+export function createHookEnvCapabilities(env) {
+    const face = Object.create(null);
+    const canonicalPath = readEnvPrimitive(env, "canonicalPath");
+    const exists = readEnvPrimitive(env, "exists");
+    const readLink = readEnvPrimitive(env, "readLink");
+    const cwd = createCwdReader(env);
+    if (typeof canonicalPath === "function") {
+        face.canonicalPath = (path, abortSignal) => reflectApply(canonicalPath, env, [path, abortSignal]);
+    }
+    if (typeof exists === "function") {
+        face.exists = (path, abortSignal) => reflectApply(exists, env, [path, abortSignal]);
+    }
+    if (typeof readLink === "function") {
+        face.readLink = (path, abortSignal) => reflectApply(readLink, env, [path, abortSignal]);
+    }
+    if (cwd !== undefined) {
+        face.cwd = cwd;
+    }
+    return Object.freeze(face);
+}
 export function formatHookFeedback(text) {
     return `<system-reminder>\n${text}\n</system-reminder>`;
 }
@@ -61,6 +122,7 @@ function withProbeTimeout(p, ms, signal) {
 export async function runToolGate(input) {
     const { event, preToolUse, adjudicate, resolveAsk, suspendAsk } = input;
     const { toolCallId, toolName } = event;
+    const hookCtx = () => ({ toolCallId, toolName, ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}) });
     let currentInput = event.input;
     const preToolContext = [];
     let hookAsk;
@@ -68,7 +130,7 @@ export async function runToolGate(input) {
     if (preToolUse) {
         let r;
         try {
-            r = screenPreToolUseResult(await preToolUse(toolName, currentInput, { toolCallId, toolName }));
+            r = screenPreToolUseResult(await preToolUse(toolName, currentInput, hookCtx()));
         }
         catch (err) {
             const reason = preToolUseCrashReason(`this call to "${toolName}"`, err);
@@ -147,7 +209,10 @@ export async function runToolGate(input) {
             currentInput = policyRewrite;
             req.args = policyRewrite;
         }
-        if (input.autoMode && decision.action === "ask" && input.isMarkedUnresolvable?.(input.event.toolCallId) !== true) {
+        if (input.autoMode &&
+            decision.action === "ask" &&
+            req.toolName !== ASK_USER_QUESTION_TOOL_NAME &&
+            input.isMarkedUnresolvable?.(input.event.toolCallId) !== true) {
             const verdict = await input.autoMode.decider
                 .decide({ req, askMessage: decisionText(decision) }, input.abortSignal)
                 .catch(() => ({ kind: "unavailable", cause: "error" }));
@@ -180,13 +245,35 @@ export async function runToolGate(input) {
             }
         }
         if (decision.action === "ask" && req.toolName === ASK_USER_QUESTION_TOOL_NAME) {
-            decision = {
-                action: "deny",
-                message: "AskUserQuestion could not be parked for a durable human answer on this path (no checkpoint " +
-                    "facility, or the suspend failed) and a synchronous permission approver cannot carry an answer — " +
-                    "the question was NOT shown to anyone. Proceed with your best judgment and state the assumption " +
-                    "you made.",
-            };
+            const outcome = input.resolveContentAsk !== undefined ? await input.resolveContentAsk(req) : { kind: "unavailable", parkDeclined: false };
+            if (outcome.kind === "answered") {
+                decision = { action: "allow", updatedInput: outcome.presentedInput };
+            }
+            else if (outcome.kind === "unavailable") {
+                if (outcome.presentedInput !== undefined) {
+                    currentInput = outcome.presentedInput;
+                    req.args = outcome.presentedInput;
+                }
+                if (suspendAsk && outcome.parkDeclined) {
+                    const suspended = await suspendAsk(req, currentInput, safety, true);
+                    if (suspended) {
+                        return { suspend: suspended, preToolContext };
+                    }
+                }
+                decision = {
+                    action: "deny",
+                    message: "AskUserQuestion could not be parked for a durable human answer on this path (no checkpoint " +
+                        "facility, or the suspend failed) and a synchronous permission approver cannot carry an answer — " +
+                        "the question was NOT shown to anyone. Proceed with your best judgment and state the assumption " +
+                        "you made.",
+                };
+            }
+            else {
+                if (outcome.presentedInput !== undefined)
+                    decision = { action: "allow", updatedInput: outcome.presentedInput };
+                else
+                    decision = { action: "allow" };
+            }
         }
         if (decision.action === "ask") {
             const resolved = await resolveAsk(decision, req);
@@ -212,7 +299,7 @@ export async function runToolGate(input) {
                     if (preToolUse) {
                         let hr;
                         try {
-                            hr = screenPreToolUseResult(await preToolUse(toolName, editArgs, { toolCallId, toolName }));
+                            hr = screenPreToolUseResult(await preToolUse(toolName, editArgs, hookCtx()));
                         }
                         catch (err) {
                             traceHookCrash(input, err, notifier);

package/dist/core/human-input-projection.d.ts

@@ -0,0 +1,12 @@
+import { type ActorAssertion } from "../internal/llm.js";
+import type { HumanInputEvent, HumanInputSource, TaskEventIdentity } from "./types.js";
+export type { HumanInputSource, HumanInputDelivery, HumanInputEvent } from "./types.js";
+export interface HumanInputFrame {
+    text: string;
+    actor?: ActorAssertion;
+    source: HumanInputSource;
+}
+export declare function projectHumanInput(frame: HumanInputFrame): string;
+export declare function buildHumanInputEvent(input: Omit<HumanInputEvent, "type" | "inputId" | keyof TaskEventIdentity> & {
+    inputId?: string;
+}): HumanInputEvent;

package/dist/core/human-input-projection.js

@@ -0,0 +1,27 @@
+import { snapshotActorAssertion } from "../internal/llm.js";
+import { uuidv7 } from "../internal/harness.js";
+import { inlineUntrusted } from "./untrusted-text.js";
+import { attrEscape, EXTERNAL_SOURCE_MAX } from "./task-notification.js";
+export function projectHumanInput(frame) {
+    if (frame.actor === undefined || frame.source === "system")
+        return frame.text;
+    if (frame.text.trim().length === 0)
+        return frame.text;
+    const label = attrEscape(inlineUntrusted(frame.actor.id, EXTERNAL_SOURCE_MAX));
+    const mark = frame.actor.hostAsserted ? "" : " (unverified)";
+    return `[from "${label}"${mark}]\n${frame.text}`;
+}
+export function buildHumanInputEvent(input) {
+    return {
+        type: "human_input",
+        inputId: input.inputId ?? uuidv7(),
+        sessionSeq: input.sessionSeq,
+        carrier: input.carrier,
+        source: input.source,
+        delivery: input.delivery,
+        ...(input.issuer !== undefined ? { issuer: input.issuer } : {}),
+        ...(input.actor !== undefined ? { actor: snapshotActorAssertion(input.actor) } : {}),
+        ...(input.principal !== undefined ? { principal: input.principal } : {}),
+        ...(input.entryId !== undefined ? { entryId: input.entryId } : {}),
+    };
+}

package/dist/core/locked-config.d.ts

@@ -0,0 +1,27 @@
+import type { RunnerDeps, TaskSpec } from "./types.js";
+import type { ToolPolicy } from "./tool-policy.js";
+export type LockedKey = "mcp" | "toolPolicy" | "compliancePosture" | "retentionPolicy";
+export declare const LOCKED_KEY_REGISTRY: {
+    readonly mcp: {
+        readonly specFields: readonly ["mcp"];
+    };
+    readonly toolPolicy: {
+        readonly specFields: readonly ["toolPolicy"];
+    };
+    readonly compliancePosture: {
+        readonly specFields: readonly [];
+    };
+    readonly retentionPolicy: {
+        readonly specFields: readonly [];
+    };
+};
+export interface LockedConfig {
+    keys: readonly LockedKey[];
+}
+export interface LockedPreflight {
+    lockedKeys: ReadonlySet<LockedKey>;
+    mcp: TaskSpec["mcp"];
+    toolPolicy: ToolPolicy | undefined;
+}
+export declare function resolveLockedKeys(config: LockedConfig | undefined): ReadonlySet<LockedKey>;
+export declare function preflightLockedConfig(spec: TaskSpec, deps: RunnerDeps): LockedPreflight;

package/dist/core/locked-config.js

@@ -0,0 +1,42 @@
+export const LOCKED_KEY_REGISTRY = {
+    mcp: { specFields: ["mcp"] },
+    toolPolicy: { specFields: ["toolPolicy"] },
+    compliancePosture: { specFields: [] },
+    retentionPolicy: { specFields: [] },
+};
+function codedError(code, message) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+export function resolveLockedKeys(config) {
+    if (config === undefined)
+        return new Set();
+    const keys = new Set();
+    for (const key of config.keys) {
+        if (!Object.prototype.hasOwnProperty.call(LOCKED_KEY_REGISTRY, key)) {
+            throw codedError("config.locked_registry", `lockedConfig.keys contains "${String(key)}", which is not a member of the locked-key registry ` +
+                `(${Object.keys(LOCKED_KEY_REGISTRY).join(", ")}). A lock that does not parse must not half-arm — ` +
+                `fix the deployment's lock declaration.`);
+        }
+        keys.add(key);
+    }
+    return keys;
+}
+export function preflightLockedConfig(spec, deps) {
+    const lockedKeys = resolveLockedKeys(deps.lockedConfig);
+    for (const key of lockedKeys) {
+        for (const field of LOCKED_KEY_REGISTRY[key].specFields) {
+            if (spec[field] !== undefined) {
+                throw codedError("config.locked_key", `TaskSpec.${field} is administratively locked by this deployment (locked key "${key}") — ` +
+                    `the task-supplied value is refused wholesale (locks are config-time; there is no request-time ` +
+                    `unlock). Remove the field from the task, or change the deployment's lock configuration.`);
+            }
+        }
+    }
+    return {
+        lockedKeys,
+        mcp: lockedKeys.has("mcp") ? undefined : spec.mcp,
+        toolPolicy: lockedKeys.has("toolPolicy") ? deps.toolPolicy : (spec.toolPolicy ?? deps.toolPolicy),
+    };
+}

package/dist/core/mcp.d.ts

@@ -5,8 +5,8 @@ import { type McpImageResizer } from "./image-downsample.js";
 import type { McpServerSpec, OnElicit, ToolEffect } from "./types.js";
 export interface McpToolAxis {
     name: string;
-    irreversibility?: "always";
-    egress?: true;
+    irreversibility?: "always" | "never";
+    egress?: boolean;
     effect?: ToolEffect;
 }
 export interface McpDroppedTool {
@@ -114,6 +114,11 @@ export type McpSchemaNormalizeResult = {
 export declare function normalizeMcpToolSchema(schema: unknown): McpSchemaNormalizeResult;
 export declare function mcpToolSchemaProblem(schema: unknown): string | undefined;
 export declare function materializeMcpTools(specs: McpServerSpec[], principal?: string, onElicit?: OnElicit, imageResizer?: McpImageResizer): Promise<MaterializedMcp>;
+export declare function applyCallerAxisOverride(name: string, hint: McpToolAxis | undefined, override: {
+    effect?: ToolEffect;
+    egress?: boolean;
+    irreversibility?: "always" | "never";
+} | undefined): McpToolAxis | undefined;
 export declare function classifyDirReadInvalidParams(message: string): "not_found" | "not_directory";
 export declare function parseCallToolResultLenient(data: unknown): {
     success: true;

package/dist/core/mcp.js

@@ -720,7 +720,7 @@ function mcpAxisFor(namespacedName, annotations) {
     }
     return any ? axis : undefined;
 }
-function applyCallerAxisOverride(name, hint, override) {
+export function applyCallerAxisOverride(name, hint, override) {
     if (!override)
         return hint;
     let effect = hint?.effect;
@@ -729,16 +729,16 @@ function applyCallerAxisOverride(name, hint, override) {
     if (override.effect !== undefined)
         effect = override.effect;
     if (override.egress !== undefined)
-        egress = override.egress ? true : undefined;
+        egress = override.egress;
     if (override.irreversibility !== undefined)
-        irrev = override.irreversibility === "always" ? "always" : undefined;
+        irrev = override.irreversibility;
     const axis = { name };
     if (effect !== undefined)
         axis.effect = effect;
-    if (egress)
-        axis.egress = true;
-    if (irrev)
-        axis.irreversibility = "always";
+    if (egress !== undefined)
+        axis.egress = egress;
+    if (irrev !== undefined)
+        axis.irreversibility = irrev;
     return axis.effect !== undefined || axis.egress !== undefined || axis.irreversibility !== undefined ? axis : undefined;
 }
 const LIST_MCP_RESOURCES = "ListMcpResourcesTool";

package/dist/core/memory-admission.d.ts

@@ -0,0 +1,51 @@
+import type { NormalizedMemorySpec } from "./memory.js";
+export type MemoryScopeOrigin = "deployment" | "request";
+export interface MemoryScopeRequest {
+    scope: string;
+    origin: MemoryScopeOrigin;
+}
+export type MemoryAdmissionVerdict = {
+    ok: true;
+    scopes: readonly string[];
+    writeScope: string | null;
+} | {
+    ok: false;
+    reason: string;
+};
+export type MemoryScopeAdmission = (input: {
+    principal: string | undefined;
+    requested: ReadonlyArray<MemoryScopeRequest>;
+    requestedWriteScope: MemoryScopeRequest | null;
+}) => MemoryAdmissionVerdict | Promise<MemoryAdmissionVerdict>;
+export interface MemoryAdmissionInput {
+    memorySpec: NormalizedMemorySpec;
+    principal: string | undefined;
+    admission: MemoryScopeAdmission | undefined;
+    deploymentScopes: ReadonlySet<string>;
+    orgMemoryDenied: boolean;
+    complianceDegraded: boolean;
+    parentAdmittedOrgScopes: readonly string[] | undefined;
+    priorOwnVerdict: OwnOrgAdmissionVerdict | undefined;
+    governedProvenance: boolean;
+}
+export interface MemoryAdmissionOutcome {
+    scopes: string[];
+    writeScope: string | null;
+    admittedOrgScopes: string[];
+    droppedDeploymentScopes: string[];
+    writeScopeNarrowed: boolean;
+    ownVerdict: OwnOrgAdmissionVerdict | undefined;
+}
+export declare function foldAdmissionFreeze(input: {
+    delegated: boolean;
+    inherited: readonly string[] | undefined;
+}): readonly string[] | undefined;
+export interface OwnOrgAdmissionVerdict {
+    scopes: readonly string[];
+    writeScope: string | null;
+}
+export declare function readDurableOrgAdmission(row: {
+    admittedOrgScopes?: readonly string[];
+    admittedOrgWriteScope?: string | null;
+}): OwnOrgAdmissionVerdict;
+export declare function admitMemoryScopes(input: MemoryAdmissionInput): Promise<MemoryAdmissionOutcome>;

package/dist/core/memory-admission.js

@@ -0,0 +1,159 @@
+import { parseScopeKey } from "./memory-engine/scope-contract.js";
+function codedError(code, message) {
+    const e = new Error(message);
+    e.code = code;
+    return e;
+}
+export function foldAdmissionFreeze(input) {
+    return input.delegated ? (input.inherited ?? []) : input.inherited;
+}
+export function readDurableOrgAdmission(row) {
+    return { scopes: row.admittedOrgScopes ?? [], writeScope: row.admittedOrgWriteScope ?? null };
+}
+const ORG_SHAPE = /^org:/;
+function orgScopesOf(spec) {
+    if (spec.scopeContract !== "v2")
+        return { readOrg: [], writeOrg: null };
+    const readOrg = spec.scopes.filter((s) => parseScopeKey(s).kind === "org");
+    const writeOrg = spec.writeScope !== null && parseScopeKey(spec.writeScope).kind === "org" ? spec.writeScope : null;
+    return { readOrg, writeOrg };
+}
+export async function admitMemoryScopes(input) {
+    const { memorySpec, principal, admission, deploymentScopes, parentAdmittedOrgScopes } = input;
+    const governed = admission !== undefined ||
+        deploymentScopes.size > 0 ||
+        input.priorOwnVerdict !== undefined ||
+        input.governedProvenance ||
+        input.orgMemoryDenied ||
+        (parentAdmittedOrgScopes !== undefined && parentAdmittedOrgScopes.length > 0);
+    if (governed && memorySpec.scopeContract !== "v2") {
+        const shaped = [...memorySpec.scopes, ...(memorySpec.writeScope !== null ? [memorySpec.writeScope] : [])].find((s) => ORG_SHAPE.test(s));
+        if (shaped !== undefined) {
+            throw codedError("memory.admission_denied", `memory scope "${shaped}" is org-shaped but the task did not opt into the v2 scope contract ` +
+                `(memory.scopeContract: "v2") — on a deployment with org-memory admission configured, org scopes ` +
+                `outside the contract are refused (fail-closed), not mounted as opaque keys.`);
+        }
+    }
+    const { readOrg, writeOrg } = orgScopesOf(memorySpec);
+    const allOrg = [...readOrg, ...(writeOrg !== null && !readOrg.includes(writeOrg) ? [writeOrg] : [])];
+    if (allOrg.length === 0) {
+        return {
+            scopes: [...memorySpec.scopes],
+            writeScope: memorySpec.writeScope,
+            admittedOrgScopes: [],
+            droppedDeploymentScopes: [],
+            writeScopeNarrowed: false,
+            ownVerdict: undefined,
+        };
+    }
+    const priorOwn = input.priorOwnVerdict;
+    const applySessionFreeze = (proj) => {
+        let { admitted, scopes, writeScope, dropped, writeScopeNarrowed } = proj;
+        if (priorOwn !== undefined) {
+            const outsideRequest = admitted.filter((s) => !deploymentScopes.has(s) && !priorOwn.scopes.includes(s));
+            if (outsideRequest.length > 0) {
+                throw codedError("memory.admission_denied", `org memory scope(s) ${outsideRequest.map((s) => `"${s}"`).join(", ")} are outside this session's frozen ` +
+                    `admission verdict (recorded at suspend) — a session's org grant can only narrow across suspend/resume.`);
+            }
+            const frozenOut = admitted.filter((s) => !priorOwn.scopes.includes(s));
+            if (frozenOut.length > 0) {
+                dropped = [...dropped, ...frozenOut];
+                admitted = admitted.filter((s) => priorOwn.scopes.includes(s));
+                scopes = scopes.filter((s) => !frozenOut.includes(s));
+            }
+            if (writeScope !== null && writeOrg !== null && writeScope === writeOrg && priorOwn.writeScope !== writeScope) {
+                writeScope = null;
+                writeScopeNarrowed = true;
+            }
+        }
+        return {
+            scopes,
+            writeScope,
+            admittedOrgScopes: admitted,
+            droppedDeploymentScopes: dropped,
+            writeScopeNarrowed,
+            ownVerdict: { scopes: admitted, writeScope: writeScope !== null && writeOrg !== null && writeScope === writeOrg ? writeScope : null },
+        };
+    };
+    const stampedOrigins = memorySpec.scopeOrigins;
+    const originOf = (scope) => stampedOrigins !== undefined
+        ? (stampedOrigins[scope] === "deployment" ? "deployment" : "request")
+        : deploymentScopes.has(scope)
+            ? "deployment"
+            : "request";
+    const requests = allOrg.map((scope) => ({ scope, origin: originOf(scope) }));
+    const requestOrigin = requests.filter((r) => r.origin === "request");
+    if (input.orgMemoryDenied && requestOrigin.length > 0) {
+        throw codedError(input.complianceDegraded ? "config.compliance_required" : "config.compliance_denied", `org memory scope(s) ${requestOrigin.map((r) => `"${r.scope}"`).join(", ")} are denied for this principal by the ` +
+            `compliance posture (capability "org_memory_mount"${input.complianceDegraded ? "; posture resolver failing, fail-closed" : ""}).`);
+    }
+    if (parentAdmittedOrgScopes !== undefined) {
+        const exceeding = requestOrigin.filter((r) => !parentAdmittedOrgScopes.includes(r.scope));
+        if (exceeding.length > 0) {
+            throw codedError("memory.admission_denied", `delegated child requests org memory scope(s) ${exceeding.map((r) => `"${r.scope}"`).join(", ")} outside the ` +
+                `parent's frozen admission verdict — a child plane can only narrow the parent's org grant, never exceed it.`);
+        }
+    }
+    if (admission === undefined) {
+        if (requestOrigin.length > 0) {
+            throw codedError("memory.admission_required", `org memory scope(s) ${requestOrigin.map((r) => `"${r.scope}"`).join(", ")} come from the request side but this ` +
+                `deployment has no memory-scope admission resolver (RunnerDeps.memoryScopeAdmission) — refused fail-closed. ` +
+                `Deployment-pinned org scopes belong in RunnerDeps.deploymentMemoryScopes.`);
+        }
+        return applySessionFreeze({
+            admitted: allOrg,
+            scopes: [...memorySpec.scopes],
+            writeScope: memorySpec.writeScope,
+            dropped: [],
+            writeScopeNarrowed: false,
+        });
+    }
+    if (requestOrigin.length > 0 && principal === undefined) {
+        throw codedError("memory.admission_denied", `org memory scope(s) ${requestOrigin.map((r) => `"${r.scope}"`).join(", ")} require an authenticated ` +
+            `TaskSpec.principal for admission — a principal-less request cannot be admitted to a tenant plane.`);
+    }
+    let verdict;
+    try {
+        verdict = await admission({
+            principal,
+            requested: requests,
+            requestedWriteScope: writeOrg !== null ? { scope: writeOrg, origin: originOf(writeOrg) } : null,
+        });
+    }
+    catch (err) {
+        const hinted = err.retryAfterMs;
+        const e = codedError("memory.admission_required", `memory-scope admission resolver failed (${err instanceof Error ? err.message : String(err)}) — refused fail-closed.`);
+        if (typeof hinted === "number" && Number.isFinite(hinted) && hinted > 0)
+            e.retryAfterMs = hinted;
+        throw e;
+    }
+    if (!verdict.ok) {
+        throw codedError("memory.admission_denied", `org memory admission denied: ${verdict.reason}`);
+    }
+    const unrequested = verdict.scopes.filter((s) => !allOrg.includes(s));
+    if (unrequested.length > 0 || (verdict.writeScope !== null && verdict.writeScope !== writeOrg)) {
+        throw codedError("memory.admission_denied", `memory-scope admission verdict granted unrequested scope(s) ` +
+            `${[...unrequested, ...(verdict.writeScope !== null && verdict.writeScope !== writeOrg ? [String(verdict.writeScope)] : [])].map((s) => `"${s}"`).join(", ")} — ` +
+            `admission can only narrow a request, never extend it; treating the verdict as a resolver fault.`);
+    }
+    const refusedRequest = requestOrigin.filter((r) => !verdict.scopes.includes(r.scope));
+    if (refusedRequest.length > 0) {
+        throw codedError("memory.admission_denied", `org memory scope(s) ${refusedRequest.map((r) => `"${r.scope}"`).join(", ")} were not admitted — the whole ` +
+            `prepare is refused (two-state verdict; partial admission is never applied silently).`);
+    }
+    const dropped = requests.filter((r) => r.origin === "deployment" && !verdict.scopes.includes(r.scope)).map((r) => r.scope);
+    const admitted = allOrg.filter((s) => !dropped.includes(s));
+    const scopes = memorySpec.scopes.filter((s) => !dropped.includes(s));
+    let writeScope = memorySpec.writeScope;
+    let writeScopeNarrowed = false;
+    if (writeOrg !== null) {
+        if (verdict.writeScope === writeOrg && !dropped.includes(writeOrg)) {
+            writeScope = writeOrg;
+        }
+        else {
+            writeScope = null;
+            writeScopeNarrowed = true;
+        }
+    }
+    return applySessionFreeze({ admitted, scopes, writeScope, dropped, writeScopeNarrowed });
+}

package/dist/core/memory.d.ts

@@ -94,12 +94,14 @@ export interface NormalizedMemorySpec {
     writeScope: string | null;
     enabled: boolean;
     scopeContract?: "v2";
+    scopeOrigins?: Readonly<Record<string, "deployment" | "request">>;
 }
 export type MemorySpecInput = {
     scopes?: ReadonlyArray<string>;
     writeScope?: string | null;
     enabled?: boolean;
     scopeContract?: "v2";
+    scopeOrigins?: Readonly<Record<string, "deployment" | "request">>;
 };
 export declare function normalizeMemorySpec(input: MemorySpecInput | undefined): NormalizedMemorySpec | undefined;
 export declare const MAX_MEMORY_BYTES: number;

package/dist/core/memory.js

@@ -384,12 +384,13 @@ export function normalizeMemorySpec(input) {
     else {
         writeScope = scopes[scopes.length - 1];
     }
+    const origins = input.scopeOrigins !== undefined ? { scopeOrigins: input.scopeOrigins } : {};
     if (input.scopeContract === "v2") {
         for (const key of writeScope !== null ? [...scopes, writeScope] : scopes)
             parseScopeKey(key);
-        return { scopes, writeScope, enabled: input.enabled !== false, scopeContract: "v2" };
+        return { scopes, writeScope, enabled: input.enabled !== false, scopeContract: "v2", ...origins };
     }
-    return { scopes, writeScope, enabled: input.enabled !== false };
+    return { scopes, writeScope, enabled: input.enabled !== false, ...origins };
 }
 export const MAX_MEMORY_BYTES = 100 * 1024;
 export const MEMORY_WRAPPER_TAGS = ["user_memory"];