@sema-agent/core 7.40.0 → 7.41.0

package/dist/core/skills-directory.js

@@ -1,7 +1,7 @@
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { isAbsolute, join, relative } from "node:path";
 import { physicalPathOf } from "./physical-path.js";
-import { isSkillSpecifierEnforced, parseSkillToolEntry } from "./skill-tool-specifier.js";
+import { assertNoRetiredKeys } from "./retired-keys.js";
 import { thrownText } from "./thrown-value.js";
 const SKILL_FILE = "SKILL.md";
 const RESOURCE_DIRS = ["assets", "references", "scripts"];
@@ -285,7 +285,6 @@ function isDecodableText(bytes) {
 function errText(err) {
     return thrownText(err);
 }
-const ALL_TOOLS_WILDCARD = "*";
 function splitToolNames(declared) {
     let text = declared.trim();
     if (text.startsWith("[") && text.endsWith("]"))
@@ -319,52 +318,11 @@ function splitToolNames(declared) {
     flush();
     return names;
 }
-function manifestFromAllowedTools(declared, disallowed, skillName, deployedTools, warn) {
-    const names = [];
-    const seen = new Set();
-    for (const n of splitToolNames(declared)) {
-        const entry = parseSkillToolEntry(n);
-        const key = entry.specifier === undefined ? entry.name : `${entry.name}(${entry.specifier})`;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        names.push(n);
-    }
-    for (const n of names) {
-        const entry = parseSkillToolEntry(n);
-        if (entry.specifier !== undefined && !isSkillSpecifierEnforced(entry.name)) {
-            warn({
-                code: "allowed_tool_pattern_unsupported",
-                skill: skillName,
-                detail: `allowed-tools entry "${n}" narrows a tool whose calls cannot be matched against a command pattern — only shell tools carry one, so the entry is not enforced and the tool is DISABLED inside this skill frame. Use the bare tool name to allow it fully.`,
-            });
-        }
-    }
-    if (names.length === 0)
-        return undefined;
-    if (names.some((n) => n === ALL_TOOLS_WILDCARD))
-        return undefined;
-    let allowTools = names;
-    if (deployedTools !== undefined) {
-        const mounted = new Set(deployedTools);
-        allowTools = names.filter((n) => mounted.has(parseSkillToolEntry(n).name));
-        for (const n of names) {
-            if (!mounted.has(parseSkillToolEntry(n).name)) {
-                warn({
-                    code: "allowed_tool_not_mounted",
-                    skill: skillName,
-                    detail: `allowed-tools names "${n}", which this deployment does not mount — dropped (a skill declaration may only narrow capability, never add a tool)`,
-                });
-            }
-        }
-    }
-    if (disallowed.length > 0) {
-        const denied = new Set(disallowed);
-        allowTools = allowTools.filter((n) => !denied.has(parseSkillToolEntry(n).name));
-    }
-    return { allowTools, lineageId: `skill:${skillName}` };
-}
+const RETIRED_SKILLS_DIRECTORY_OPTION_KEYS = Object.freeze({
+    deployedTools: "the loader copies a skill's `allowed-tools` / `disallowed-tools` into `SkillSpec.allowedTools` / `disallowedTools` as written and the run's grant table judges them (an entry naming a tool nothing mounts simply never matches) — drop the option",
+});
 export function createSkillsFromDirectory(dir, options = {}) {
+    assertNoRetiredKeys(options, RETIRED_SKILLS_DIRECTORY_OPTION_KEYS, "SkillsDirectoryOptions");
     const warn = (w) => {
         options.onWarning?.(w);
     };
@@ -438,16 +396,8 @@ export function createSkillsFromDirectory(dir, options = {}) {
             warn({ code: "description_too_long", skill: name, detail: `\`description\` is ${description.length} chars, over the ${DESCRIPTION_MAX_CHARS} cap — skipped` });
             continue;
         }
-        const allowed = parsed.fields.get("allowed-tools");
-        const disallowed = splitToolNames(parsed.fields.get("disallowed-tools") ?? "");
-        const manifest = allowed === undefined ? undefined : manifestFromAllowedTools(allowed, disallowed, name, options.deployedTools, warn);
-        if (disallowed.length > 0 && manifest === undefined) {
-            warn({
-                code: "disallowed_tools_unenforced",
-                skill: name,
-                detail: `disallowed-tools names ${disallowed.map((n) => `"${n}"`).join(", ")}, but this skill produced no allowlist to subtract from (allowed-tools is absent or claims every tool) — the deny declaration is NOT enforced (express it in the task's own tool policy)`,
-            });
-        }
+        const allowedTools = splitToolNames(parsed.fields.get("allowed-tools") ?? "");
+        const disallowedTools = splitToolNames(parsed.fields.get("disallowed-tools") ?? "");
         const baseDir = skillPhysicalRoot(skillDir, name, warn);
         const files = baseDir === undefined ? [] : readAttachments(skillDir, baseDir, name, budget, warn);
         skills.push({
@@ -455,7 +405,8 @@ export function createSkillsFromDirectory(dir, options = {}) {
             description,
             content: parsed.body,
             ...(baseDir !== undefined ? { baseDir } : {}),
-            ...(manifest !== undefined ? { manifest } : {}),
+            ...(allowedTools.length > 0 ? { allowedTools } : {}),
+            ...(disallowedTools.length > 0 ? { disallowedTools } : {}),
             ...(files.length > 0 ? { files } : {}),
         });
     }

package/dist/core/task-registry-agent.d.ts

@@ -1,6 +1,8 @@
 import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./background-agent-store.js";
 import { type StopSource, type TaskAccess, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
 import { type ToolResultStore } from "./tool-result-store.js";
+import { type AgentState } from "./agent-state.js";
+import type { CheckpointSeat } from "./checkpoint-seat.js";
 /**
  * Subagent transcript persistence (delegation entry caps) — the ACTIVE handles of one delegation
  * tree in THIS process's registry: `background_agent` handles whose status is running/pending
@@ -493,6 +495,9 @@ export interface AgentPollDetailsInput {
     errorRetryAfterMs?: number;
     resultIsPartial?: boolean;
     completionId?: string;
+    /** The agent's current state ({@link import("./agent-state.js").readAgentState}) — rides as
+     *  `agentState` when given; the poll arms always give it, a serving layer may omit it. */
+    agentState?: AgentState;
 }
 /** PUBLIC (see the doc above): a serving layer that renders its own protocol projection of a row
  *  builds the structured facts HERE, so the status gates and the untrusted-text fencing apply to it
@@ -510,7 +515,11 @@ export declare function buildAgentPollDetails(input: AgentPollDetailsInput): Uni
  *  caller has ALREADY read and authorized — it reads no store and applies no predicate, so a
  *  deployment passes every row through
  *  {@link import("./background-agent-store.js").canAccessAgentRecord} before it gets here. */
-export declare function serveDurableAgentRowLane(row: BackgroundAgentRecord): UnifiedTaskResult;
+export declare function serveDurableAgentRowLane(row: BackgroundAgentRecord, 
+/** The row's current state ({@link import("./agent-state.js").readAgentState} over
+ *  {@link import("./agent-state.js").agentStateSourceOfRecord}(row)): rendered as the `state:` line and
+ *  carried as `details.agentState`. Absent ⇒ neither appears (a serving layer that does not read it). */
+agentState?: AgentState): UnifiedTaskResult;
 /**
  * design/158 S1 (RB-205-B 半) — spill the FULL text behind a CLIPPED background_agent result to the
  * offload store, and append a ref-disclosure so the middle `clipTaskOutput` drops is not gone for good.
@@ -553,5 +562,8 @@ oneShot?: boolean,
 store?: ToolResultStore, 
 /** design/158 S1 — the caller's session id, folded into the minted ref for global uniqueness (same
  *  role `sessionId` plays at every other {@link buildToolResultRef} call site). */
-sessionId?: string): Promise<UnifiedTaskResult>;
+sessionId?: string, 
+/** The run's checkpoint seat — the store a parked row's approval card is read from
+ *  ({@link import("./agent-state.js").readAgentState}). Absent ⇒ a parked row reads `approval unreadable`. */
+checkpointSeat?: CheckpointSeat): Promise<UnifiedTaskResult>;
 export declare function stopBackgroundAgentLane(core: DurableAgentCore, handle: BackgroundAgentTaskHandle): Promise<UnifiedTaskResult>;

package/dist/core/task-registry-agent.js

@@ -8,6 +8,7 @@ import { boundedRedactedSummary } from "./untrusted-egress.js";
 import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
 import { buildToolResultRef, OFFLOAD_TOOL_NAME, toolResultProvenanceOf } from "./tool-result-store.js";
 import { thrownLabel } from "./thrown-value.js";
+import { agentStateSourceOfHandle, agentStateSummary, readAgentState } from "./agent-state.js";
 export function activeDelegationHandlesLane(core, scope, rootSessionId) {
     const out = [];
     for (const h of core.handles.values()) {
@@ -1292,18 +1293,21 @@ export function buildAgentPollDetails(input) {
         ...(failed && input.errorRetryAfterMs !== undefined ? { retryAfterMs: input.errorRetryAfterMs } : {}),
         ...(input.resultIsPartial === true ? { partial_result: true } : {}),
         ...(input.completionId !== undefined ? { completionId: input.completionId } : {}),
+        ...(input.agentState !== undefined ? { agentState: input.agentState } : {}),
     };
 }
-export function serveDurableAgentRowLane(row) {
+export function serveDurableAgentRowLane(row, agentState) {
+    const stateLine = agentState !== undefined ? `state: ${agentStateSummary(agentState)}\n` : "";
     if (row.status === "parked") {
         return {
             content: delimitUntrusted(`TaskOutput ${row.handle}`, `status: parked
-The agent is durably suspended, waiting for an approval decision. It resumes when the pending approval is decided (durable approval inbox), or lands failed if the approval expires.`),
+${stateLine}The agent is durably suspended, waiting for an approval decision. It resumes when the pending approval is decided (durable approval inbox), or lands failed if the approval expires.`),
             details: buildAgentPollDetails({
                 taskId: row.handle,
                 status: "parked",
                 retrievalStatus: "success",
                 ...(row.seq !== undefined ? { seq: row.seq } : {}),
+                ...(agentState !== undefined ? { agentState } : {}),
             }),
         };
     }
@@ -1311,7 +1315,7 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
         ? ` (error_kind: ${row.errorKind}, retryable: ${row.errorRetryable}${row.errorRetryAfterMs !== undefined ? `, retry_after_ms: ${row.errorRetryAfterMs}` : ""})`
         : "";
     const body = `status: ${row.status}
-${row.error ? `error: ${row.error}${kindClause}
+${stateLine}${row.error ? `error: ${row.error}${kindClause}
 ` : ""}${row.finalOutput ? `--- result${row.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
 ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}`;
     return {
@@ -1328,6 +1332,7 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
             ...(row.errorRetryAfterMs !== undefined ? { errorRetryAfterMs: row.errorRetryAfterMs } : {}),
             ...(row.resultIsPartial === true ? { resultIsPartial: true } : {}),
             ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
+            ...(agentState !== undefined ? { agentState } : {}),
         }),
         ...(row.status === "failed" ? { isError: true } : {}),
     };
@@ -1360,21 +1365,26 @@ export async function spillClippedAgentResult(handle, full, clipped, store, sess
         handle.spillRef = ref;
     return disclose(ref);
 }
-export async function pollBackgroundAgentLane(handle, deadline, signal, oneShot, store, sessionId) {
+export async function pollBackgroundAgentLane(handle, deadline, signal, oneShot, store, sessionId, checkpointSeat) {
     while (handle.status === "running" && deadline !== undefined && Date.now() < deadline && !signal?.aborted) {
         await sleepPollStep(deadline, signal);
     }
     const running = handle.status === "running";
     const retrieval = running && deadline !== undefined && Date.now() >= deadline ? "timeout" : "success";
     if (handle.status === "parked") {
+        const parkedSource = agentStateSourceOfHandle(handle);
+        const parkedSeq = handle.cycleSeq;
+        const agentState = await readAgentState(parkedSource, checkpointSeat, Date.now());
         return {
             content: delimitUntrusted(`TaskOutput ${handle.id}`, `status: parked
+state: ${agentStateSummary(agentState)}
 The agent is durably suspended, waiting for an approval decision. It resumes when the pending approval is decided (durable approval inbox), or lands failed if the approval expires.`),
             details: buildAgentPollDetails({
                 taskId: handle.id,
                 status: "parked",
                 retrievalStatus: "success",
-                ...(handle.cycleSeq !== undefined ? { seq: handle.cycleSeq } : {}),
+                ...(parkedSeq !== undefined ? { seq: parkedSeq } : {}),
+                agentState,
             }),
         };
     }
@@ -1390,20 +1400,24 @@ The agent is durably suspended, waiting for an approval decision. It resumes whe
         cycleSeq: handle.cycleSeq,
         stoppedBy: handle.stoppedBy,
         completionId: handle.completionId,
+        updatedAt: handle.updatedAt,
     };
+    const stateRead = readAgentState(agentStateSourceOfHandle({ status: snap.status, updatedAt: snap.updatedAt }), checkpointSeat, Date.now());
+    const agentState = stateRead instanceof Promise ? await stateRead : stateRead;
     const fullResult = snap.result ? (handle.resultFull ?? snap.result) : undefined;
     const resultText = fullResult !== undefined ? await spillClippedAgentResult(handle, fullResult, clipTaskOutput(fullResult, handle.outputFile), store, sessionId) : undefined;
     const kindClause = snap.status === "failed" && snap.errorKind !== undefined && snap.errorRetryable !== undefined
         ? ` (error_kind: ${snap.errorKind}, retryable: ${snap.errorRetryable}${snap.errorRetryAfterMs !== undefined ? `, retry_after_ms: ${snap.errorRetryAfterMs}` : ""})`
         : "";
+    const stateLine = `state: ${agentStateSummary(agentState)}\n`;
     const body = running
         ? oneShot === true
             ? `status: running
-This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput({ task_id: "${handle.id}", block: true }). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget.`
+${stateLine}This is a ONE-SHOT submission — there is no later turn for a background notification to land in, so do NOT end your turn expecting one. Actively wait instead: TaskOutput({ task_id: "${handle.id}", block: true }). If it is still running after the wait, wait again (bounded) rather than ending the turn, or write out your best available answer now if you are near your own time budget.`
             : `status: running
-The agent is still working — you will be notified when it completes.`
+${stateLine}The agent is still working — you will be notified when it completes.`
         : `status: ${snap.status}
-${snap.error ? `error: ${snap.error}${kindClause}
+${stateLine}${snap.error ? `error: ${snap.error}${kindClause}
 ` : ""}${snap.result ? `--- result${snap.resultIsPartial ? " (partial — produced before the task was stopped)" : ""} ---
 ${resultText}` : "(no result text)"}`;
     return {
@@ -1420,6 +1434,7 @@ ${resultText}` : "(no result text)"}`;
             ...(snap.errorRetryAfterMs !== undefined ? { errorRetryAfterMs: snap.errorRetryAfterMs } : {}),
             ...(snap.resultIsPartial === true ? { resultIsPartial: true } : {}),
             ...(snap.completionId !== undefined ? { completionId: snap.completionId } : {}),
+            agentState,
         }),
         ...(snap.status === "failed" ? { isError: true } : {}),
     };

package/dist/core/task-registry-shared.d.ts

@@ -72,6 +72,12 @@ export interface UnifiedTaskOutput {
      *  not contractually required to stay one); absent when the underlying task hasn't reached a terminal
      *  settle yet, or on a pre-P1-3 core build that never minted one. */
     completionId?: string;
+    /** A background agent's current state (status word, last activity, the approval card a parked row
+     *  waits on) — {@link import("./agent-state.js").readAgentState}, the one reading AgentTranscript and
+     *  ListAgents render too. Present on every background_agent POLL answer that resolved a row (live,
+     *  durable terminal, durable parked, durable still-running); absent on other lanes, on not-found, and on
+     *  the stop face. */
+    agentState?: import("./agent-state.js").AgentState;
     details?: unknown;
 }
 /**

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

@@ -9,6 +9,8 @@ import { type SemaTaskType, type StopSource, type SemaTaskStatus, type TaskRetri
 export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR } from "./task-registry-shared.js";
 export type { ParkedClaimTicket, RegisterBackgroundAgentInput } from "./task-registry-shared.js";
 import type { RegisterBackgroundAgentInput, ParkedClaimTicket } from "./task-registry-shared.js";
+import { type AgentStateSource } from "./agent-state.js";
+import type { CheckpointSeat } from "./checkpoint-seat.js";
 export type { SemaTaskType, StopSource, SemaTaskStatus, TaskRetrievalStatus, UnifiedTaskOutput, SemaTaskHandle, TaskAccess, MonitorTimers, RegisterMonitorInput, RegisterWorkflowInput, };
 export { canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE };
 export interface TaskKind {
@@ -78,6 +80,10 @@ export interface TaskPollOptions {
      *  good (see {@link import("./task-registry-agent.js").spillClippedAgentResult}). Absent (a
      *  deployment that never wired a tool-result store) ⇒ legal degrade, byte-identical to pre-S1 output. */
     toolResultStore?: ToolResultStore;
+    /** The run's checkpoint seat: a PARKED background_agent row's approval card is read from it for the
+     *  answer's `agentState` ({@link import("./agent-state.js").readAgentState}). Absent ⇒ the card reads
+     *  `unreadable`; nothing else changes. */
+    checkpointSeat?: CheckpointSeat;
 }
 export interface TaskStopOptions {
     workflowStore?: WorkflowRunStore;
@@ -116,6 +122,9 @@ export interface TaskToolOptions extends TaskAccess {
      *  spills to — see {@link TaskPollOptions.toolResultStore} (forwarded verbatim into `pollTask`).
      *  Absent ⇒ legal degrade, byte-identical to pre-S1 output. */
     toolResultStore?: ToolResultStore;
+    /** The run's checkpoint seat — see {@link TaskPollOptions.checkpointSeat} (forwarded verbatim into
+     *  `pollTask`). The first-party mount passes the same seat the Agent tool parks children into. */
+    checkpointSeat?: CheckpointSeat;
 }
 /**
  * RB-49 B-3 (2026-07-25): the row-metadata projection `getAccessibleTask` returns. Was spelled out as a
@@ -281,7 +290,14 @@ export declare class TaskRegistry {
         skipSessionScoped?: boolean;
         sessionScopedOnly?: boolean;
     }): number;
+    /** A durable row's answer with its state: only a parked row waits on the card read; any other row is
+     *  answered in place. */
     private serveDurableAgentRow;
+    /** The row facts {@link import("./agent-state.js").readAgentState} reads for a background agent this
+     *  caller can see — the live handle only (a durable-only row is projected by its reader from the record,
+     *  {@link import("./agent-state.js").agentStateSourceOfRecord}). Same access guard as a poll; unknown and
+     *  out-of-scope ids read identically (undefined). */
+    agentStateSource(taskId: string, access: TaskAccess): AgentStateSource | undefined;
     resolveBackgroundAgentByName(name: string, access: TaskAccess, opts?: {
         preferRunning?: boolean;
     }): {

package/dist/core/task-registry.js

@@ -14,6 +14,7 @@ import { TASK_OUTPUT_TOOL_NAME, TASK_STOP_TOOL_NAME, TASK_OUTPUT_MISSING_ID_MESS
 import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
 import { toolFace } from "./tool-catalog-entries.js";
 import { thrownText } from "./thrown-value.js";
+import { agentStateSourceOfHandle, agentStateSourceOfRecord, agentStateSummary, readAgentState } from "./agent-state.js";
 export { canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE };
 function shellRowRetained(h) {
     return retainsBackgroundProcesses({ marked: h.retained === true, env: envDeclaresRetain(h.env) });
@@ -188,8 +189,15 @@ export class TaskRegistry {
     abortBackgroundAgentsForOwner(access, opts) {
         return abortBackgroundAgentsForOwnerLane(this.core, access, opts);
     }
-    serveDurableAgentRow(row) {
-        return serveDurableAgentRowLane(row);
+    serveDurableAgentRow(row, checkpointSeat) {
+        const read = readAgentState(agentStateSourceOfRecord(row), checkpointSeat, Date.now());
+        return read instanceof Promise ? read.then((agentState) => serveDurableAgentRowLane(row, agentState)) : serveDurableAgentRowLane(row, read);
+    }
+    agentStateSource(taskId, access) {
+        const h = this.handles.get(taskId);
+        if (!h || h.type !== "background_agent" || !canAccess(h, access))
+            return undefined;
+        return agentStateSourceOfHandle(h);
     }
     resolveBackgroundAgentByName(name, access, opts) {
         return resolveBackgroundAgentByNameLane(this.core, name, access, opts);
@@ -238,8 +246,8 @@ export class TaskRegistry {
     runningBackgroundAgentLabels(access) {
         return runningBackgroundAgentLabelsLane(this.core, access);
     }
-    async pollBackgroundAgent(handle, deadline, signal, oneShot, toolResultStore, sessionId) {
-        return pollBackgroundAgentLane(handle, deadline, signal, oneShot, toolResultStore, sessionId);
+    async pollBackgroundAgent(handle, deadline, signal, oneShot, toolResultStore, sessionId, checkpointSeat) {
+        return pollBackgroundAgentLane(handle, deadline, signal, oneShot, toolResultStore, sessionId, checkpointSeat);
     }
     async stopBackgroundAgent(handle) {
         return stopBackgroundAgentLane(this.core, handle);
@@ -863,7 +871,7 @@ export class TaskRegistry {
             if (handle.type === "background_bash")
                 return this.pollBackgroundBash(handle, taskId, access, opts.filter, deadline, opts.signal);
             if (handle.type === "background_agent")
-                return this.pollBackgroundAgent(handle, deadline, opts.signal, opts.oneShot, opts.toolResultStore, access.sessionId);
+                return this.pollBackgroundAgent(handle, deadline, opts.signal, opts.oneShot, opts.toolResultStore, access.sessionId, opts.checkpointSeat);
             if (handle.type === "monitor")
                 return this.pollMonitor(handle, opts.filter, deadline, opts.signal);
             return this.pollWorkflow(handle, access, deadline, opts.signal);
@@ -896,9 +904,12 @@ export class TaskRegistry {
                 if (row.status === "running" && row.writerId === this.writerId)
                     break;
                 if (row.status !== "running")
-                    return this.serveDurableAgentRow(row);
+                    return this.serveDurableAgentRow(row, opts.checkpointSeat);
                 if (deadline === undefined || Date.now() >= deadline || opts.signal?.aborted) {
+                    const stateRead = readAgentState(agentStateSourceOfRecord(row), opts.checkpointSeat, Date.now());
+                    const agentState = stateRead instanceof Promise ? await stateRead : stateRead;
                     const body = `status: unknown (not running on this engine instance)
+state: ${agentStateSummary(agentState)}
 The durable record is still marked running (last update ${new Date(row.updatedAt).toISOString()}), but this engine instance is not executing it — the outcome is unknown here. If its host process is gone, a retention sweep (staleRunningMaxAgeMs) settles the record as interrupted.`;
                     return {
                         content: delimitUntrusted(`TaskOutput ${row.handle}`, body),
@@ -910,6 +921,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
                             retrieval_status: "not_ready",
                             error: "not_local",
                             code: "not_local",
+                            agentState,
                         },
                     };
                 }
@@ -1321,6 +1333,7 @@ export function createTaskOutputTool(opts) {
                 signal: ctx.signal,
                 oneShot: opts.oneShot,
                 toolResultStore: opts.toolResultStore,
+                checkpointSeat: opts.checkpointSeat,
             });
             const { type: taskType, ...rest } = r.details;
             return {

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

@@ -965,6 +965,16 @@ export interface TaskSpec {
      * end-user-authored skills are responsible for vetting them: a skill IS instructions by design.
      */
     skills?: SkillSpec[];
+    /**
+     * The skills THIS run's human input invoked by name (a shell that parsed `/name` from the person's line), by
+     * {@link SkillSpec.name}. Each one's {@link SkillSpec.allowedTools} / {@link SkillSpec.disallowedTools} take effect
+     * at the start of the run with no `Skill` call and no card — the person's own invocation is the statement — and last
+     * for this run (a steer does not end them; the next runTask starts without them), like a grant the model's activation wrote. Delivering the skill's body
+     * stays the caller's business (this key carries names only). Every name must be one of this run's {@link skills};
+     * anything else refuses the run before it starts (`config.user_invoked_skill_unknown`), never dropped. Present only
+     * when the person actually invoked one; a mid-turn invocation (one riding a steer) grants nothing.
+     */
+    userInvokedSkills?: string[];
     /**
      * Fraction of the model's context window the `<skills>` listing may spend. Absent ⇒ `0.01` (1%).
      * Domain `(0, 1]`; anything else — including `0`, a string, `NaN` — REFUSES at the door with

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

@@ -76,8 +76,9 @@ export type ToolPathAbsence = (typeof TOOL_PATH_ABSENCES)[number];
  * slot RESOLVES — as a READER sees it, whichever side it came from. Present ⇔ the tool can be confirmed BY
  * PATH (write confinement, sensitive-path guards, edited-file tracking, the transcript-directory gate, the
  * permission-rule path family). `param` outranks every alias (NotebookEdit's `notebook_path` beats a decoy
- * `file_path`). `skillScopeEligible` (default false) is the SEPARATE authorization domain of the
- * active-skill `allowPaths` face — a confinable write tool is not automatically eligible there.
+ * `file_path`). `skillScopeEligible` (default false) is a SEPARATE authorization domain (its one reader, the
+ * skill-scope write fence, is retired and no reader remains; the bit stays a declared member of the roster row) — a
+ * confinable write tool is not automatically eligible there.
  *
  * ONE shape, two spellings: a DECLARATION ({@link ToolPathTarget}, what a catalog row / a `ToolSpec` / an
  * MCP overlay writes) and the roster row's NORMALIZED form (`aliases` always an array, `skillScopeEligible`

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

@@ -12,17 +12,43 @@
  *  - `TOMBSTONED_TOOLS` (per-name re-education messages) is gone: a retired name now gets the same
  *    loud generic roster miss as any unknown tool.
  *
- * What REMAINS is validation data only: {@link RETIRED_TOOL_NAMES} maps every name the engine ever
- * retired to a one-line guidance string. It exists because deleting the mapping flips stale POLICY
- * entries from "silently matched" to "silently matches nothing" — and for a deny/requireApproval
- * entry that direction WIDENS the surface. The prepare-time policy-name audit (runner/prepare-task.ts)
- * escalates a retired name that matches nothing in the run's roster from advisory to a HARD,
- * coordinates-carrying failure (`config.legacy_tool_name`) — `validatePermissionRules`
- * (permission-rules.ts) does NOT classify retired names itself; a retired-name entry is a raw,
- * ordinary-looking tool name to its compile pass by design (RB-476-A: that classification is the
- * roster-aware prepare-time audit's job, not the compile pass's, since compile time cannot know
- * which names a deployment mounts its OWN tool under). A deployment that mounts its OWN tool under
- * one of these names is unaffected either way: the name is then in the roster, matches, and is never
- * audited as stale.
+ * What REMAINS is validation data: {@link RETIRED_TOOL_NAMES} maps every name the engine ever
+ * retired to a one-line guidance string, and {@link judgeRuleToolName} is the ONE reading of it a rule's
+ * tool name gets. They exist because deleting the mapping flips stale POLICY entries from "silently
+ * matched" to "silently matches nothing" — and for a deny/requireApproval entry that direction WIDENS
+ * the surface. `validatePermissionRules` (permission-rules.ts) does NOT classify retired names itself:
+ * which names a deployment mounts its OWN tool under is a roster fact, and the judgment takes the roster.
+ * A deployment that mounts its OWN tool under one of these names is unaffected: the name is then in the
+ * roster and the judgment answers `current`.
+ *
+ * GRAMMAR of a guidance string, read by {@link judgeRuleToolName} and held by a pin: it opens with
+ * `renamed "<name>"` (a 1:1 successor — the judgment's `currentName`), `folded into "<name>"` (merged into a
+ * wider tool: writing it would deny more than the entry did, so it is no current name), or `removed — `.
  */
 export declare const RETIRED_TOOL_NAMES: ReadonlyMap<string, string>;
+/** The three answers {@link judgeRuleToolName} gives — a closed set. */
+export declare const RULE_TOOL_NAME_VERDICTS: readonly ["current", "retired", "unprefixed_namespace"];
+/**
+ * Whether a tool name written in a rule is a stale name — one that, against `roster`, names no tool and never can:
+ *  - `current` — not a stale name: the roster mounts it, or it is neither retired nor a prefix-less `__` name. (Whether a
+ *    current name matches anything THIS run is a different question — an unknown name is the prepare audit's advisory.)
+ *  - `retired` — a name in {@link RETIRED_TOOL_NAMES} the roster does not mount; `guidance` is that table's line, and
+ *    `currentName` the 1:1 successor when there is one (see the module header's grammar).
+ *  - `unprefixed_namespace` — carries the `__` namespace separator with no protocol prefix. The roster cannot clear it:
+ *    a caller tool name or alias carrying `__` is refused at prepare, every engine tool name is `__`-free, and every
+ *    protocol tool is minted with its prefix.
+ *
+ * `roster` = the tool names (aliases included) the reader knows are mounted: a run's assembled roster at prepare, the
+ * names a deployment DECLARES it mounts its own tools under at a session-rule store (an empty set when it declares none).
+ */
+export type RuleToolNameVerdict = {
+    readonly kind: "current";
+} | {
+    readonly kind: "retired";
+    readonly guidance: string;
+    readonly currentName?: string;
+} | {
+    readonly kind: "unprefixed_namespace";
+};
+/** See {@link RuleToolNameVerdict}. Pure; the one answer to "is this rule's tool name a retired or prefix-less name". */
+export declare function judgeRuleToolName(name: string, roster: ReadonlySet<string>): RuleToolNameVerdict;

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

@@ -1,3 +1,4 @@
+import { carriesNamespaceSeparator, protocolOf } from "./protocol-table.js";
 export const RETIRED_TOOL_NAMES = new Map([
     ["read_file", 'renamed "Read"'],
     ["edit_file", 'renamed "Edit"'],
@@ -40,3 +41,18 @@ export const RETIRED_TOOL_NAMES = new Map([
     ["Recall", "removed — memory is file-based; read the memory directory with the ordinary file tools"],
     ["recall", "removed — memory is file-based; read the memory directory with the ordinary file tools"],
 ]);
+export const RULE_TOOL_NAME_VERDICTS = Object.freeze(["current", "retired", "unprefixed_namespace"]);
+const CURRENT = Object.freeze({ kind: "current" });
+const UNPREFIXED = Object.freeze({ kind: "unprefixed_namespace" });
+export function judgeRuleToolName(name, roster) {
+    if (roster.has(name))
+        return CURRENT;
+    const guidance = RETIRED_TOOL_NAMES.get(name);
+    if (guidance !== undefined) {
+        const currentName = /^renamed "([^"]+)"/.exec(guidance)?.[1];
+        return currentName !== undefined ? { kind: "retired", guidance, currentName } : { kind: "retired", guidance };
+    }
+    if (carriesNamespaceSeparator(name) && protocolOf(name) === undefined)
+        return UNPREFIXED;
+    return CURRENT;
+}

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

@@ -130,11 +130,15 @@ export declare const NAME_READINGS: {
         readonly kind: "wire";
         readonly file: string;
     };
-    readonly "policy.skillScope": {
+    readonly "skillGrant.names": {
         readonly kind: "any";
         readonly file: string;
     };
-    readonly "policy.skillScope.effect": {
+    readonly "skillGrant.binding": {
+        readonly kind: "wire";
+        readonly file: string;
+    };
+    readonly "gate.skillActivationSeat": {
         readonly kind: "wire";
         readonly file: string;
     };

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

@@ -5,6 +5,7 @@ const POLICY = "src/core/tool-policy.ts";
 const OFFER = "src/core/runner/permission-rule-lanes.ts";
 const PARK = "src/core/runner/prepare-park-ask.ts";
 const HANDLERS = "src/core/runner/run-harness-handlers.ts";
+const STATIONS = "src/core/runner/call-hook-stations.ts";
 const any = (file) => ({ kind: "any", file });
 const wire = (file) => ({ kind: "wire", file });
 const spelling = (file) => ({ kind: "spelling", file });
@@ -33,8 +34,9 @@ export const NAME_READINGS = {
     "policy.projectionReplay": any(POLICY),
     "policy.sessionRules": any("src/core/runner/session-rule-policy.ts"),
     "policy.sessionRules.effect": wire("src/core/runner/session-rule-policy.ts"),
-    "policy.skillScope": any("src/core/runner/active-skill-scope.ts"),
-    "policy.skillScope.effect": wire("src/core/runner/active-skill-scope.ts"),
+    "skillGrant.names": any("src/core/skill-grant.ts"),
+    "skillGrant.binding": wire("src/core/skill-grant.ts"),
+    "gate.skillActivationSeat": wire(GATE),
     "policy.permissionRules": any("src/core/permission-rules.ts"),
     "policy.persistedGrammar": any("src/core/permission-rule-model.ts"),
     "policy.durableQuestion": any("src/core/ask-question.ts"),
@@ -54,8 +56,8 @@ export const NAME_READINGS = {
     "verify.wroteThisRun": wire(HANDLERS),
     "verify.wroteThisRunSeed": wire("src/core/runner/run-attachment-seats.ts"),
     "event.toolStartEnd": spelling(HANDLERS),
-    "hook.postToolUse": wire(GATE),
-    "hook.postToolUseFailure": wire(GATE),
+    "hook.postToolUse": wire(STATIONS),
+    "hook.postToolUseFailure": wire(STATIONS),
     "hook.postToolBatch": spelling(HANDLERS),
     "stats.subagentToolCounter": spelling("src/agents/subagent.ts"),
     "activity.sink": spelling(HANDLERS),

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

@@ -42,7 +42,7 @@ export interface ToolCallRequest {
      * against, read at adjudication time from the same tracked `cwdRef` the fs hand tools resolve with
      * (design/64 §16.3: a resident shell's `cd` persists and moves the fs tools' relative base with it).
      *
-     * WHY IT EXISTS: every path guard here (sensitive-path, fs-write gate, session rules, skill scope,
+     * WHY IT EXISTS: every path guard here (sensitive-path, fs-write gate, session rules,
      * transcript integrity) re-resolves the model's spelling itself, and each was handed a STATIC root at
      * wiring time. After a `cd` the two sides of a single call disagreed about which file it was: the tool
      * wrote `<liveCwd>/pre-commit` while the guard judged `<wiringRoot>/pre-commit` — measured on a host
@@ -50,7 +50,7 @@ export interface ToolCallRequest {
      * Reading THIS field makes the guard's resolution base the same value the tool will use.
      *
      * Applies to the call's TARGET only. A guard's own configured directories (accept/exempt domains,
-     * `allowDirs`, manifest `allowPaths`) are DEPLOYMENT text and keep resolving against the static root —
+     * `allowDirs`) are DEPLOYMENT text and keep resolving against the static root —
      * a shell `cd` must never relocate an allow-domain.
      *
      * ABSENT when the run has no tracked cwd (read-only hands, no execution env) or when a policy is

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

@@ -23,9 +23,6 @@ export declare function catalogToolNames(): ReadonlySet<string>;
 /** A-11/12/13/14 — tools this engine can CONFINE BY PATH on a write: `pathTarget.access ≠ read`.
  *  Today {Write, Edit, NotebookEdit}. */
 export declare function pathConfinableWriteToolNames(): ReadonlySet<string>;
-/** A-11 (the SECOND authorization domain) — the active-skill `allowPaths` face: confinable AND the
- *  definition opted into skill scoping. Today {Write, Edit} — NotebookEdit is deliberately outside. */
-export declare function skillScopeWriteToolNames(): ReadonlySet<string>;
 /** A-8 — every definition that names a path target at all (read or write): the file-tool glob lane. */
 export declare function pathTargetingToolNames(): ReadonlySet<string>;
 /** The tools whose declared path target is a READ (a file read, a search root): the file read station's membership. */
@@ -75,7 +72,7 @@ export declare function protectivePathTargetOf(call: ToolCallLike): CallPathTarg
 export declare const BARE_REQUEST_CODE = "policy.bare_request";
 /**
  * The path target a CONTAINMENT fence reads (a grant admitting a write BY its path: session `allowDirs`, the fs-write
- * gate's accept/exempt dirs; the active-skill allowPaths face reads its own eligibility bit the same way): the object
+ * gate's accept/exempt dirs): the object
  * face's OWN declaration only — a same-name tool that declares no path target is an UNCONFIRMABLE write (the catalog's
  * slot may not be the one it writes; a decoy in that slot would buy an admission), so the fence fails closed.
  *

package/dist/core/tool-registry.js

@@ -26,9 +26,6 @@ const names = (pred) => {
 export function pathConfinableWriteToolNames() {
     return names((e) => e.face.pathTarget !== undefined && e.face.pathTarget.access !== "read");
 }
-export function skillScopeWriteToolNames() {
-    return names((e) => e.face.pathTarget !== undefined && e.face.pathTarget.access !== "read" && e.face.pathTarget.skillScopeEligible === true);
-}
 export function pathTargetingToolNames() {
     return names((e) => e.face.pathTarget !== undefined);
 }