@sema-agent/core 7.55.0 → 7.56.0

package/dist/agents/subagent.js

@@ -2,6 +2,7 @@ import { Type } from "typebox";
 import { isAbsolute } from "node:path";
 import { backgroundChildTerminal } from "../core/delegation-frames.js";
 import { bindDelegationName } from "../core/delegation-name.js";
+import { principalNameOf } from "../core/principal-name.js";
 import { resumeRefusalDetailOf, resumeStartupCauseOf } from "../core/resume-startup-cause.js";
 import { errorCodeOf, thrownFailureOf } from "../core/runner/terminal-account.js";
 import { applyParentSpecSeat, parentSpecSeatOfCtx } from "../core/parent-spec-seat.js";
@@ -11,6 +12,7 @@ import { assertNoRetiredKeys } from "../core/retired-keys.js";
 import { stripSpawnTurnQuestionFace } from "../core/ask-question.js";
 import { withDelegationProvenance } from "../core/tool-policy.js";
 import { errorResult } from "../core/tools.js";
+import { notStartedResult } from "../core/delegation-not-started.js";
 import { isHighSurrogate, isLowSurrogate } from "../core/surrogate-safe-slice.js";
 import { newDelegationProvenanceAggregate, reduceDelegationAttestation } from "../core/memory-engine/delegation-provenance.js";
 import { registerDelegationLaunch, replayExternalSettlementEffects, settleDelegation } from "../core/memory-engine/delegation-settlement.js";
@@ -21,12 +23,14 @@ export { childThinkingSeat, deploymentSubagentThinking, deploymentSubagentTierMo
 import { REPORT_BLOCKED_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { TOOL_SEARCH_NAME } from "../core/runner/tool-disclosure.js";
 import { OFFLOAD_TOOL_NAME } from "../core/tool-result-store.js";
-import { compileToolSelector, delegationListWhere, snapshotDefinitionLists, toolListsDigest, toolNameAllowed, toolNameListFlaw } from "./tool-filter.js";
+import { compileToolSelector, delegationListWhere, namesEveryTool, snapshotDefinitionLists, toolListsDigest, toolNameAllowed, toolNameListFlaw } from "./tool-filter.js";
 import { readToolNameList, snapshotToolNameList } from "../core/tool-name-list.js";
 import { EXTRA_TOOL_NAMES_CODE, delegationPoolFace, extraToolNamesError, firstUndeclaredExtraTool, readExtraToolNames } from "./extra-tool-names.js";
 import { builtinAgentDefinitions } from "./builtin-agents.js";
 import { normalizePeerName, reservedPeerNameReason } from "./cross-session-ref.js";
 import { SUBAGENT_PROMPT } from "../prompts/default.js";
+import { roleBaseOf } from "../prompt-assembly/role-base.js";
+import { readPromptRole } from "../prompt-assembly/select.js";
 import { hasSessionFork } from "../core/session.js";
 import { isDurablePause, pauseFamily } from "./suspend-guard.js";
 import { childRejection, childTerminalFace, childThrownText } from "./child-failure.js";
@@ -280,19 +284,6 @@ const WORKTREE_UNAVAILABLE = {
     seatSilent: worktreeUnavailableSentence("the runner this tool runs children on does not declare whether it can place a child in a tree other than the caller's (its seat has no canRerootChild), and an undeclared answer is read as no; use a Runner, or add that method to the seat"),
 };
 const placementRefused = (terminal) => terminal?.kind === "failed" && terminal.code === "isolation.unavailable";
-const NOT_STARTED_RESULTS = new WeakSet();
-function notStartedResult(result) {
-    const details = result.details;
-    if (typeof details === "object" && details !== null)
-        NOT_STARTED_RESULTS.add(details);
-    return result;
-}
-export function isNotStartedDelegationResult(result) {
-    if (typeof result !== "object" || result === null)
-        return false;
-    const details = result.details;
-    return typeof details === "object" && details !== null && NOT_STARTED_RESULTS.has(details);
-}
 const isolationUnavailable = (content) => notStartedResult({
     isError: true,
     content,
@@ -352,6 +343,14 @@ const ccElapsedTag = (ms) => {
     return sec >= 60 ? ` \u00b7 ${Math.floor(sec / 60)}m${sec % 60}s` : ` \u00b7 ${sec}s`;
 };
 const ccCompletionText = (desc, settled, rawStatus, elapsedMs) => `Agent "${desc}" ${settled === "killed" ? "stopped" : settled === "completed" ? "finished" : rawStatus}${ccElapsedTag(elapsedMs)}`;
+const SYNC_ESCAPE_SENTENCE = "Pass `run_in_background: false` for a synchronous run when you need the result before continuing (a named agent always runs in the background).";
+function continuationSentence(toolName, durableRevival, forkOffered) {
+    return (`Where the SendMessage tool is mounted, use it with the agent's ID or name to message a RUNNING agent, or — when session retention${durableRevival ? " or durable named-agent revival" : ""} is enabled — ` +
+        `to continue a COMPLETED one with its context intact; a new ${toolName} call starts fresh${forkOffered ? ` (except subagent_type: "${FORK_SUBAGENT_TYPE}", which inherits your context)` : ""}.`);
+}
+function launchContinuationSentence(taskId) {
+    return `Where the SendMessage tool is mounted, use it with to: '${taskId}', summary: '<5-10 word recap>' to continue this agent.`;
+}
 function resumabilityClaim(f) {
     if (f.status === "killed" && f.stoppedBy === "user")
         return false;
@@ -1248,7 +1247,7 @@ export function asyncLaunchedReceipt(p) {
     const noteLines = (p.notes ?? []).filter((n) => n !== undefined && n !== "");
     const oneShotBlocked = p.notify && p.oneShot === true;
     return (`Async agent launched successfully. (${launchReceiptNoQuoteClause(", including the task_id below,")})\n` +
-        `task_id: ${p.taskId} (internal ID - do not mention to user. Use SendMessage with to: '${p.taskId}', summary: '<5-10 word recap>' to continue this agent.)\n` +
+        `task_id: ${p.taskId} (internal ID - do not mention to user. ${launchContinuationSentence(p.taskId)})\n` +
         (oneShotBlocked
             ? `${p.workingLine} 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: "${p.taskId}", 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.\n`
             : p.notify
@@ -1270,6 +1269,7 @@ function runnerModelCatalog(runner) {
     }
 }
 export function createSubagentTool(opts) {
+    readPromptRole("SubagentToolOptions.promptRole", opts.promptRole);
     const catalog = opts.runner.agentCatalog;
     if (opts.agents === undefined && catalog?.agents)
         opts = { ...opts, agents: catalog.agents };
@@ -1326,7 +1326,7 @@ export function createSubagentTool(opts) {
 export function agentToolsNote(def) {
     const allowRead = readToolNameList(def.allowTools);
     const allow = allowRead.kind === "entries" ? allowRead.entries.filter((entry) => typeof entry === "string") : [];
-    const hasAllow = allow.length > 0 && !allow.includes("*");
+    const hasAllow = allow.length > 0 && !allow.some(namesEveryTool);
     const denyRead = readToolNameList(def.denyTools);
     const deny = denyRead.kind === "entries" ? denyRead.entries.filter((entry) => typeof entry === "string") : [];
     const hasDeny = deny.length > 0;
@@ -1427,41 +1427,41 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 : `- Each agent type's model, thinking level, and tools come from its agent definition.\n`) +
             `- \`isolation: "worktree"\` gives the agent its own git worktree (auto-cleaned if unchanged).` +
             (opts.background
-                ? `\n- Subagents run in the background by default${opts.background.notify ? "; you'll be notified when one completes" : "; the receipt's task_id retrieves progress and results via the TaskOutput tool where mounted"}. Pass \`run_in_background: false\` for a synchronous run when you need the result before continuing. Never fabricate or predict a pending agent's results — ${opts.background.notify ? "the notification is never something you write yourself; " : ""}if the user asks before it arrives, say it's still running.\n` +
-                    `- Where the SendMessage tool is mounted, use it with the agent's ID or name to message a RUNNING agent, or — when session retention${opts.background.agentStore !== undefined ? " or durable named-agent revival" : ""} is enabled — to continue a COMPLETED one with its context intact; a new ${opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME} call starts fresh${forkOffered ? ` (except subagent_type: "${FORK_SUBAGENT_TYPE}", which inherits your context)` : ""}.`
+                ? `\n- Subagents run in the background by default${opts.background.notify ? "; you'll be notified when one completes" : "; the receipt's task_id retrieves progress and results via the TaskOutput tool where mounted"}. ${SYNC_ESCAPE_SENTENCE} Never fabricate or predict a pending agent's results — ${opts.background.notify ? "the notification is never something you write yourself; " : ""}if the user asks before it arrives, say it's still running.\n` +
+                    `- ${continuationSentence(opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME, opts.background.agentStore !== undefined, forkOffered)}`
                 : `\n- \`run_in_background\` is unavailable here — only synchronous subagents.`),
-        descriptionClassic: `Launch a new agent. Delegate a self-contained subtask to an isolated sub-agent and get back a single report. ` +
-            (opts.purpose ? `This sub-agent is for: ${opts.purpose}. ` : "") +
-            (hasAgents ? `Available agent types are listed in <system-reminder> messages in the conversation. If \`subagent_type\` is omitted, a general-purpose sub-agent is used.\n` : "") +
-            `The sub-agent starts with a clean context (it does NOT see this conversation), so put everything it needs in 'prompt'. ` +
-            `It returns status (completed/blocked/failed) and a result you must verify before deciding the overall task is done.\n\n` +
-            `When NOT to delegate (do it yourself — it's faster and you keep the understanding):\n` +
-            `- Reading a specific known file → use Read directly.\n` +
-            `- Finding a known symbol/class/definition, or searching within 2-3 known files → use Grep/Glob/Read.\n` +
-            `- A lookup where you already know what you want and roughly where it is → just do it. Delegate open-ended INVESTIGATIONS (you don't know where the answer is), not lookups.\n\n` +
-            `Writing the 'prompt' — brief the agent like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters:\n` +
-            `- Make it fully self-contained and highly detailed: the sub-agent does the whole task end-to-end in one shot — you can't course-correct mid-run.\n` +
-            `- State exactly what it must RETURN (e.g. "report the file:line of each call site", not "look into the call sites").\n` +
-            `- Say explicitly whether you want it to WRITE CODE or only RESEARCH/REPORT — otherwise it may guess wrong.\n` +
-            `- Never delegate understanding. Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.\n\n` +
-            `Use it for self-contained, parallelizable subtasks (e.g. independent searches/investigations) — it protects your main context; don't overuse it for trivial steps you can do directly. ` +
-            `Once you delegate a piece of research, rely on the sub-agent's report rather than repeating that search yourself. ` +
-            `The agent's final message is returned to you as the tool result; it is not shown to the user — relay what matters.\n\n` +
-            `If the agent reports an action was refused because an approval could not be resolved, do not send the approval back as a message — messages never clear a permission gate. Surface the agent's report of the prepared action and its refusal text to your user. (An agent PARKED at an approval gate is not refused — it is waiting, and resumes when the pending approval is decided.)\n\n` +
-            `Orchestration: When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently. Keep anything that needs shared context single-threaded. Once you've delegated a piece of work, don't also do it yourself — wait for the report.` +
-            (forkOffered
-                ? `\n\nsubagent_type "${FORK_SUBAGENT_TYPE}" is built in: it spawns a child that INHERITS your full current context (this entire conversation — no re-explaining, shared prompt cache) and works on 'prompt' as its directive. The fork always runs on YOUR model (the 'model' parameter is ignored for forks) and is not available inside a forked agent.`
-                : `\n\nNote: this deployment defines its own "${FORK_SUBAGENT_TYPE}" agent type, which OVERRIDES the built-in context-inheriting fork routing — subagent_type "${FORK_SUBAGENT_TYPE}" delegates to that definition instead.`) +
-            `\n\nThe 'model' parameter optionally overrides the sub-agent's model. If omitted, the agent definition's model (or the inherited default) applies.` +
-            `\nSet isolation: "worktree" to give the agent its own detached git worktree (auto-removed if it made no changes; kept for you to inspect/merge when it did).` +
-            (opts.background
-                ?
-                    (opts.background.notify
-                        ? `\n\nAgents run in the background by default. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead. Pass \`run_in_background: false\` for a synchronous run when you need the result before continuing.`
-                        : `\n\nAgents run in the background by default. A background agent's result is not pushed automatically — the launch receipt's task_id retrieves progress and results via the TaskOutput tool where mounted. Pass \`run_in_background: false\` for a synchronous run when you need the result before continuing.`) +
-                        ` Use SendMessage with a completed agent's ID to continue it with its context intact; a new ${opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME} call starts fresh.` +
-                        `\n\n**Don't race.** After launching, you know nothing about what the agent found. Never fabricate or predict agent results in any format — not as prose, summary, or structured output. ${opts.background.notify ? "The notification arrives as a user-role message in a later turn; it is never something you write yourself." : "The result exists only when you retrieve it; it is never something you write yourself."}`
-                : `\n\nThe run_in_background parameter is not available in this context. Only synchronous subagents are supported.`),
+        descriptionVariants: [{ id: "classic", traits: { noneOf: ["lean_prompt"] }, text: `Launch a new agent. Delegate a self-contained subtask to an isolated sub-agent and get back a single report. ` +
+                    (opts.purpose ? `This sub-agent is for: ${opts.purpose}. ` : "") +
+                    (hasAgents ? `Available agent types are listed in <system-reminder> messages in the conversation. If \`subagent_type\` is omitted, a general-purpose sub-agent is used.\n` : "") +
+                    `The sub-agent starts with a clean context (it does NOT see this conversation), so put everything it needs in 'prompt'. ` +
+                    `It returns status (completed/blocked/failed) and a result you must verify before deciding the overall task is done.\n\n` +
+                    `When NOT to delegate (do it yourself — it's faster and you keep the understanding):\n` +
+                    `- Reading a specific known file → use Read directly.\n` +
+                    `- Finding a known symbol/class/definition, or searching within 2-3 known files → use Grep/Glob/Read.\n` +
+                    `- A lookup where you already know what you want and roughly where it is → just do it. Delegate open-ended INVESTIGATIONS (you don't know where the answer is), not lookups.\n\n` +
+                    `Writing the 'prompt' — brief the agent like a smart colleague who just walked into the room — it hasn't seen this conversation, doesn't know what you've tried, doesn't understand why this task matters:\n` +
+                    `- Make it fully self-contained and highly detailed: the sub-agent does the whole task end-to-end in one shot — you can't course-correct mid-run.\n` +
+                    `- State exactly what it must RETURN (e.g. "report the file:line of each call site", not "look into the call sites").\n` +
+                    `- Say explicitly whether you want it to WRITE CODE or only RESEARCH/REPORT — otherwise it may guess wrong.\n` +
+                    `- Never delegate understanding. Don't write "based on your findings, fix the bug" or "based on the research, implement it." Those phrases push synthesis onto the agent instead of doing it yourself. Write prompts that prove you understood: include file paths, line numbers, what specifically to change.\n\n` +
+                    `Use it for self-contained, parallelizable subtasks (e.g. independent searches/investigations) — it protects your main context; don't overuse it for trivial steps you can do directly. ` +
+                    `Once you delegate a piece of research, rely on the sub-agent's report rather than repeating that search yourself. ` +
+                    `The agent's final message is returned to you as the tool result; it is not shown to the user — relay what matters.\n\n` +
+                    `If the agent reports an action was refused because an approval could not be resolved, do not send the approval back as a message — messages never clear a permission gate. Surface the agent's report of the prepared action and its refusal text to your user. (An agent PARKED at an approval gate is not refused — it is waiting, and resumes when the pending approval is decided.)\n\n` +
+                    `Orchestration: When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently. Keep anything that needs shared context single-threaded. Once you've delegated a piece of work, don't also do it yourself — wait for the report.` +
+                    (forkOffered
+                        ? `\n\nsubagent_type "${FORK_SUBAGENT_TYPE}" is built in: it spawns a child that INHERITS your full current context (this entire conversation — no re-explaining, shared prompt cache) and works on 'prompt' as its directive. The fork always runs on YOUR model (the 'model' parameter is ignored for forks) and is not available inside a forked agent.`
+                        : `\n\nNote: this deployment defines its own "${FORK_SUBAGENT_TYPE}" agent type, which OVERRIDES the built-in context-inheriting fork routing — subagent_type "${FORK_SUBAGENT_TYPE}" delegates to that definition instead.`) +
+                    `\n\nThe 'model' parameter optionally overrides the sub-agent's model. If omitted, the agent definition's model (or the inherited default) applies.` +
+                    `\nSet isolation: "worktree" to give the agent its own detached git worktree (auto-removed if it made no changes; kept for you to inspect/merge when it did).` +
+                    (opts.background
+                        ?
+                            (opts.background.notify
+                                ? `\n\nAgents run in the background by default. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead. ${SYNC_ESCAPE_SENTENCE}`
+                                : `\n\nAgents run in the background by default. A background agent's result is not pushed automatically — the launch receipt's task_id retrieves progress and results via the TaskOutput tool where mounted. ${SYNC_ESCAPE_SENTENCE}`) +
+                                ` ${continuationSentence(opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME, opts.background.agentStore !== undefined, forkOffered)}` +
+                                `\n\n**Don't race.** After launching, you know nothing about what the agent found. Never fabricate or predict agent results in any format — not as prose, summary, or structured output. ${opts.background.notify ? "The notification arrives as a user-role message in a later turn; it is never something you write yourself." : "The result exists only when you retrieve it; it is never something you write yourself."}`
+                        : `\n\nThe run_in_background parameter is not available in this context. Only synchronous subagents are supported.`) }],
         parameters: Type.Object({
             subagent_type: Type.Optional(Type.String({ description: "The type of specialized agent to use for this task" })),
             description: Type.String({ description: "A short (3-5 word) description of the task." }),
@@ -1469,7 +1469,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             name: Type.Optional(Type.String({
                 maxLength: 64,
                 pattern: "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$",
-                description: 'Name for the spawned agent. Where the SendMessage tool is mounted, it makes a background agent addressable via SendMessage({to: name}). "main" is reserved.',
+                description: opts.background
+                    ? 'Name for the spawned agent. Where the SendMessage tool is mounted, the name makes the agent addressable via SendMessage({to: name}); either way a named agent always runs in the background (omit name to run one synchronously). "main" is reserved.'
+                    : 'Name for the spawned agent — a label only: agents on this mount run synchronously, so a name does not make one addressable. "main" is reserved.',
             })),
             cwd: Type.Optional(Type.String({
                 description: 'Absolute path to run the agent in. Overrides the working directory for all filesystem and shell operations within this agent. Mutually exclusive with isolation: "worktree".',
@@ -1486,8 +1488,8 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ? {
                     run_in_background: Type.Optional(Type.Boolean({
                         description: opts.background.notify
-                            ? "Agents run in the background by default; you will be notified when one completes. Set to false to run this agent synchronously when you need its result before continuing."
-                            : "Agents run in the background by default; the launch receipt's task_id retrieves progress and results via the TaskOutput tool where mounted. Set to false to run this agent synchronously when you need its result before continuing.",
+                            ? "Agents run in the background by default; you will be notified when one completes. Set to false to run this agent synchronously when you need its result before continuing (a named agent always runs in the background)."
+                            : "Agents run in the background by default; the launch receipt's task_id retrieves progress and results via the TaskOutput tool where mounted. Set to false to run this agent synchronously when you need its result before continuing (a named agent always runs in the background).",
                     })),
                 }
                 : {}),
@@ -1522,7 +1524,6 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             }
             const omitted = rawType === "" || (!generalPurposeShadowed && rawType === GENERAL_PURPOSE_SUBAGENT_TYPE);
             const def = hasAgents && !wantsFork && !omitted ? agentMap.get(rawType) : undefined;
-            const wantsBackground = opts.background !== undefined && (a.run_in_background !== false || def?.background === true);
             const spawnAgentType = wantsFork ? FORK_SUBAGENT_TYPE : omitted ? GENERAL_PURPOSE_SUBAGENT_TYPE : rawType;
             const allowFlaw = toolNameListFlaw(delegationListWhere(toolName, def?.name), "allowed", def !== undefined ? def.allowTools : opts.allowTools);
             if (allowFlaw !== undefined)
@@ -1553,6 +1554,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     });
                 }
             }
+            const wantsBackground = opts.background !== undefined && (a.run_in_background !== false || def?.background === true || agentName !== undefined);
             if (a.cwd !== undefined && typeof a.cwd !== "string") {
                 return notStartedResult({ isError: true, content: "Sub-agent not started: cwd must be an absolute path string.", details: { error: "cwd.relative" } });
             }
@@ -1843,8 +1845,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             const parentMcp = opts.tools === undefined && extraToolsNote === undefined ? ctx.mountedMcp?.() : undefined;
             const childMcp = parentMcp !== undefined ? inheritedMcpDeclarations(parentMcp, compileToolSelector([...childCeiling, childOwnLayer])) : undefined;
             const childTools = [...childPool];
-            const childSystemPrompt = def?.systemPrompt ?? opts.systemPrompt;
-            const childDefaultPersona = childSystemPrompt === undefined && !wantsFork ? SUBAGENT_PROMPT : undefined;
+            const childRoleBase = roleBaseOf([def !== undefined ? { systemPrompt: def.systemPrompt } : undefined, { promptRole: opts.promptRole, systemPrompt: opts.systemPrompt }]);
+            const childSystemPrompt = childRoleBase?.systemPrompt;
+            const childDefaultPersona = childRoleBase === undefined && !wantsFork ? SUBAGENT_PROMPT : undefined;
             const defMaxTurns = typeof def?.maxTurns === "number" && Number.isFinite(def.maxTurns) && def.maxTurns > 0 ? def.maxTurns : undefined;
             const childLimits = defMaxTurns !== undefined ? { ...opts.limits, maxTurns: defMaxTurns } : opts.limits;
             const nextExcluded = def ? new Set([...excluded, def.name]) : excluded;
@@ -1923,7 +1926,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     ...(ctx.deferTools !== undefined ? { deferTools: [...ctx.deferTools] } : {}),
                     ...(ctx.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...ctx.alwaysLoadTools] } : {}),
                     ...(ctx.restoreGatedTools !== undefined ? { restoreGatedTools: ctx.restoreGatedTools === true ? true : [...ctx.restoreGatedTools] } : {}),
-                    ...(ctx.promptProfile !== undefined ? { promptProfile: ctx.promptProfile } : {}),
+                    ...(ctx.promptLean !== undefined ? { promptLean: ctx.promptLean } : {}),
                     ...engineHeadlessLegSeats(),
                     ...childClampSeats(clampSourceOf(ctx)),
                     enableBlockedReport: false,
@@ -2200,6 +2203,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 tools: childTools,
                 ...(childMcp !== undefined && childMcp.length > 0 ? { mcp: childMcp } : {}),
                 systemPrompt: childSystemPrompt,
+                ...(childRoleBase?.promptRole !== undefined ? { promptRole: childRoleBase.promptRole } : {}),
                 ...(def?.memory ? { memory: def.memory } : {}),
                 ...(def?.skills?.length ? { skills: def.skills } : {}),
                 ...(def?.memoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: def.memoryPersistenceCapable } : {}),
@@ -2211,7 +2215,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(ctx.deferTools !== undefined ? { deferTools: [...ctx.deferTools] } : {}),
                 ...(ctx.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...ctx.alwaysLoadTools] } : {}),
                 ...(ctx.restoreGatedTools !== undefined ? { restoreGatedTools: ctx.restoreGatedTools === true ? true : [...ctx.restoreGatedTools] } : {}),
-                ...(ctx.promptProfile !== undefined ? { promptProfile: ctx.promptProfile } : {}),
+                ...(ctx.promptLean !== undefined ? { promptLean: ctx.promptLean } : {}),
                 ...(ctx.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: ctx.getApiKeyAndHeaders } : {}),
                 enableBlockedReport: true,
                 limits: childLimits,
@@ -2376,6 +2380,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             objective: objectiveSample.text,
                             tools: spawnToolNames,
                             systemPrompt: systemPromptSample?.text,
+                            ...(childRoleBase?.promptRole !== undefined ? { promptRole: childRoleBase.promptRole } : {}),
                             ...(spawnCoverage ? { reviewCoverage: spawnCoverage } : {}),
                         },
                         toolCallId: ctx.toolCallId,
@@ -2408,7 +2413,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         releaseForked = forkHandle?.release;
                     }
                     else {
-                        forkedId = (await opts.runner.sessions.fork?.(ctx.sessionId, ctx.principal ?? null)) ?? null;
+                        forkedId = (await opts.runner.sessions.fork?.(ctx.sessionId, principalNameOf(ctx.principal) ?? null)) ?? null;
                     }
                 }
                 catch (e) {
@@ -3834,7 +3839,6 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         : "",
                 `stats: turns=${child.stats.turns} tokens=${child.stats.tokens}`,
                 !retainEntry && failureRetained ? `transcript_id: ${child.sessionId} (internal ID - do not mention to user; inspect via AgentTranscript where mounted)` : "",
-                retainEntry ? `resumable: true` : "",
                 failureRetained
                     ? `session_retained: this child's session is kept for a short time (~15 min) so its transcript stays inspectable via transcript_id; it is released automatically afterwards.`
                     : "",

package/dist/agents/tool-filter.d.ts

@@ -14,8 +14,8 @@ import { type ToolNameListReading } from "../core/tool-name-list.js";
  *  - a layer above a run (its ceiling) bounds it: a child's `"*"` never widens what its parent could use.
  *
  * An entry is read by the rule syntax ({@link readDeniedEntry}); a protocol spelling (`mcp__srv`, `mcp__srv__*`, a glob over the
- * tool segment) reaches the tools of that peer, including ones it lists later; an entry no tool answers to is kept by name and
- * reaches one mounted later. Judged at the prepare that receives it (`sub-agent-deny-lists.ts`).
+ * tool segment) reaches the tools of that peer, including ones it lists later, and on a denied list any glob (`Re*d`, `*`) the
+ * names it matches; an entry no tool answers to is kept by name and reaches one mounted later. Judged at the prepare that receives it.
  *
  * `"*"` in an allowed list is the "allow all" sentinel and never a name (`caller-tool-name.ts` refuses it at the mount).
  */
@@ -66,8 +66,8 @@ export declare function toolNameListFlaw(where: string, side: ToolNameListSide,
 export declare function snapshotDefinitionLists(def: AgentDefinition): AgentDefinition;
 /**
  * What ONE tool-name list reaches — the single reading every consumer of an allowed or a denied list takes: `names` are exact
- * spellings (a tool answers to its wire name and every alias it declares); `covering` the protocol spellings that cover a SET
- * (`mcp__srv`, `mcp__srv__*`, `mcp__srv__get_*`; on a denied list also `mcp__*` / `mcp__*__*`, which an allowed list reads as nothing).
+ * spellings (a tool answers to its wire name and every alias it declares); `covering` the spellings that cover a SET
+ * ({@link isCoveringRuleName}: `mcp__srv`, `mcp__srv__get_*`; on a denied list any glob, `Re*d`, `*`).
  */
 export interface ToolNameListReach {
     readonly names: ReadonlySet<string>;
@@ -89,9 +89,11 @@ export declare function isCanonicalToolName(entry: unknown): boolean;
  * refuses it before the park, the reader again.
  */
 export declare function persistedToolNameList(entries: readonly string[], side: ToolNameListSide): string[];
+/** Is this allowed-tools entry the selector's wildcard (`*`, `*()`, `*(*)`) — no allowlist on its layer? The one test every reader asks. */
+export declare function namesEveryTool(entry: unknown): boolean;
 /**
  * What an allowed-tools value admits, or `undefined` when it names no allowlist: absent, `null`, or a list holding the wildcard
- * ({@link toolNameOfEntry} reads `*`, `*()`, `*(*)` as it). A value that is not a list admits NOTHING (refused before the run).
+ * ({@link namesEveryTool}). A value that is not a list admits NOTHING (refused before the run).
  */
 export declare function readAllowedToolList(allowTools: unknown): ToolNameListReach | undefined;
 /** What a denied value hides: its string entries read as {@link readDeniedEntry} reads them (an entry it reads as `unreadable` or not a string, or a value that is not a list, hides nothing here — the judgment before the run refuses each). */

package/dist/agents/tool-filter.js

@@ -3,8 +3,8 @@ import { canonicalize, UNCANONICALIZABLE } from "../core/canonical-json.js";
 import { SPAWNER_SURFACE_LEG_KINDS } from "../core/tool-face.js";
 import { ruleSpellingOf } from "../core/permission-rule-syntax.js";
 import { TOOL_CATALOG_ENTRIES } from "../core/tool-catalog-entries.js";
-import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, namespacedRuleReachInto } from "../core/namespaced-rule-name.js";
-import { splitNamespacedName, wholeProtocolOf } from "../core/tool-name-aliases.js";
+import { isCoveringRuleName, ruleNameCovers, ruleNameReachIntoPeer } from "../core/namespaced-rule-name.js";
+import { splitNamespacedName } from "../core/tool-name-aliases.js";
 import { readToolNameList, snapshotToolNameList, valueTypeLabel } from "../core/tool-name-list.js";
 export function readDeniedEntry(entry) {
     if (typeof entry !== "string")
@@ -75,20 +75,23 @@ function reachOf(entries, side) {
         const name = toolNameOfEntry(entry, side);
         if (name === undefined)
             continue;
-        if (isNamespacedCoveringRuleName(name, side === "denied" ? "deny" : "allow"))
+        if (isCoveringRuleName(name, side === "denied" ? "deny" : "allow"))
             covering.push(name);
-        else if (wholeProtocolOf(name) === undefined)
+        else if (!name.includes("*"))
             names.add(name);
     }
     return { names, covering };
 }
+export function namesEveryTool(entry) {
+    return toolNameOfEntry(entry, "allowed") === "*";
+}
 export function readAllowedToolList(allowTools) {
     if (allowTools === undefined || allowTools === null)
         return undefined;
     const list = readToolNameList(allowTools);
     if (list.kind !== "entries")
         return reachOf([], "allowed");
-    if (list.entries.some((entry) => toolNameOfEntry(entry, "allowed") === "*"))
+    if (list.entries.some(namesEveryTool))
         return undefined;
     return reachOf(list.entries, "allowed");
 }
@@ -101,7 +104,7 @@ export function listReaches(reach, tool) {
         if (reach.names.has(spelling))
             return true;
         for (const pattern of reach.covering)
-            if (namespacedRuleNameCovers(pattern, spelling))
+            if (ruleNameCovers(pattern, spelling))
                 return true;
     }
     return false;
@@ -114,11 +117,11 @@ export function protocolToolNames(legs) {
     return [...new Set(PROTOCOL_ROWS.filter((r) => r.legs.some((l) => legs.includes(l))).map((r) => r.name))];
 }
 function reachTouchesPeer(reach, peer) {
-    const into = (spelling) => namespacedRuleReachInto(spelling, peer.ns, peer.peer) !== "none";
+    const into = (spelling) => ruleNameReachIntoPeer(spelling, peer.ns, peer.peer) !== "none";
     return [...reach.names].some(into) || reach.covering.some(into);
 }
 function reachCoversPeer(reach, peer) {
-    return reach.covering.some((pattern) => namespacedRuleReachInto(pattern, peer.ns, peer.peer) === "all");
+    return reach.covering.some((pattern) => ruleNameReachIntoPeer(pattern, peer.ns, peer.peer) === "all");
 }
 export function isToolSelectorLayer(layer) {
     return typeof layer === "object" && layer !== null && !Array.isArray(layer);
@@ -143,7 +146,7 @@ export function compileToolSelector(layers, legs = []) {
             const split = splitNamespacedName(prefix);
             if (split === undefined)
                 return false;
-            const peer = { ns: split.ns.id, peer: split.peer };
+            const peer = { ns: split.ns, peer: split.peer };
             return compiled.every((l) => (l.allow === undefined || reachTouchesPeer(l.allow, peer)) && !reachCoversPeer(l.deny, peer));
         },
     });

package/dist/agents/verify.d.ts

@@ -338,8 +338,9 @@ export interface DeveloperTaskConfig extends VerifyConfig {
     verify?: boolean;
 }
 /**
- * One-stop developer-mode convenience: applies {@link CODE_AGENT_PROMPT} (unless the task supplies its
- * own `systemPrompt`) and, by default, runs the {@link runWithVerification} gate. Equivalent to wiring
+ * One-stop developer-mode convenience: gives the task the catalog's coding role base by word (`promptRole: "code"`, on
+ * the task's own seat, so no role preset overtakes it) unless the task names a role base of its own (`promptRole` or
+ * `systemPrompt`), and, by default, runs the {@link runWithVerification} gate. Equivalent to wiring
  * the building blocks by hand — use the building blocks directly when you want full control.
  *
  * Pair with a role map that gives a strong implementation model and cheaper helper/verifier models for

package/dist/agents/verify.js

@@ -1,5 +1,5 @@
 import { Type } from "typebox";
-import { CODE_AGENT_PROMPT } from "../prompts/default.js";
+import { namesRoleBase } from "../prompt-assembly/role-base.js";
 import { releaseSession } from "./session-util.js";
 import { childClampSeats, clampSourceOf, engineHeadlessLegSeats } from "../core/child-clamp-seats.js";
 import { mapNestedSuspend, isDurablePause, pauseFamily } from "./suspend-guard.js";
@@ -179,7 +179,7 @@ export async function verifyCompleted(runner, result, specBase, objective, confi
                 ? { restoreGatedTools: Array.isArray(specBase.restoreGatedTools) ? [...specBase.restoreGatedTools] : specBase.restoreGatedTools }
                 : {}),
             ...(specBase.clientContext !== undefined ? { clientContext: { ...specBase.clientContext } } : {}),
-            ...(specBase.promptProfile !== undefined ? { promptProfile: specBase.promptProfile } : {}),
+            ...(specBase.promptLean !== undefined ? { promptLean: specBase.promptLean } : {}),
             signal: specBase.signal,
         };
         const v = await runner.runTask(verifierSpec, withLegIdentity(legInternals(), { kind: "verifier", round }));
@@ -297,7 +297,7 @@ export async function resumeWithVerification(runner, token, outcome, taskConfig,
     return verifyCompleted(runner, result, taskConfig, objective, config, internals);
 }
 export async function runDeveloperTask(runner, spec, config = {}, internals) {
-    const implSpec = { systemPrompt: CODE_AGENT_PROMPT, ...spec };
+    const implSpec = namesRoleBase(spec) ? spec : { ...spec, promptRole: "code" };
     if (config.verify === false) {
         const result = await runner.runTask(implSpec, withLegIdentity(internals, IMPL_LEG));
         return { ...result, verification: { verdict: "unverified", unverifiedReason: "opted_out", rounds: 0, findings: [] } };

package/dist/brain/anthropic.js

@@ -5,21 +5,15 @@ import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
 import { STREAM_TORN_WARNING, createRepetitionPoll, createStreamEndLedger, modelOutputInvalidOf, noteResponseModel, nameMissingCause, parseStreamedToolArgs, placeTurnNotes, truncationCauseClause } from "./stream-shared.js";
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } from "./tool-call-id.js";
 import { emitBrainTelemetry, reportReasoningWireFacts } from "./status-sink.js";
-import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders, takeHeaderCasefold } from "./request-params.js";
+import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imageWithholdOf, reportImagesWithheld, sendableImages } from "./media-degrade.js";
+import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders, takeHeaderSpellings } from "./request-params.js";
 import { admitRouteRequest, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { NAMES_AS_WRITTEN, resolveProviderDialect, endpointToolNames } from "./provider-dialect.js";
-import { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
+import { applyReasoningToRequest, mergeReasoningHeaders } from "./reasoning-request.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
 import { resolveFetch } from "./transport.js";
-function thinkingBudget(maxTokens, share, fixed, hardCap = false) {
-    const max = hardCap ? maxTokens : Math.max(maxTokens, MIN_THINKING_TOKENS * 2);
-    const want = fixed ?? Math.floor(max * share);
-    const budget = Math.min(Math.max(MIN_THINKING_TOKENS, want), max - 1);
-    return { max, budget };
-}
 const EPHEMERAL = { type: "ephemeral" };
 const DOCUMENT_OMITTED_NO_VISION = "[PDF document omitted: the serving model does not support document input; extract the text via Bash instead (e.g. `pdftotext`).]";
 function textOf(content) {
@@ -27,7 +21,7 @@ function textOf(content) {
         ? content
         : content.filter((c) => c.type === "text" && typeof c.text === "string").map((c) => c.text).join("");
 }
-function toUserBlocks(content, supportsVision = true) {
+function toUserBlocks(content, withhold) {
     if (typeof content === "string") {
         return content.length > 0 ? [{ type: "text", text: content }] : [];
     }
@@ -38,7 +32,7 @@ function toUserBlocks(content, supportsVision = true) {
             blocks.push({ type: "text", text: c.text });
         }
         else if (c.type === "image" && c.data && c.mimeType) {
-            if (supportsVision)
+            if (withhold === undefined)
                 blocks.push({ type: "image", source: { type: "base64", media_type: c.mimeType, data: c.data } });
             else {
                 omitted++;
@@ -46,12 +40,13 @@ function toUserBlocks(content, supportsVision = true) {
             }
         }
     }
-    if (omitted > 0)
-        emitBrainTelemetry({ kind: "vision_placeholder", count: omitted });
+    if (withhold !== undefined)
+        reportImagesWithheld(withhold, omitted);
     return blocks;
 }
 function toAnthropicMessages(ctx, model, toolNames) {
-    const supportsVision = modelSupportsVision(model);
+    const imageWithhold = imageWithholdOf(model);
+    const supportsVision = imageWithhold === undefined;
     const raw = [];
     let pendingDocs = [];
     const flushDocs = () => {
@@ -65,7 +60,7 @@ function toAnthropicMessages(ctx, model, toolNames) {
         if (m.role !== "toolResult")
             flushDocs();
         if (m.role === "user") {
-            const ub = toUserBlocks(m.content, supportsVision);
+            const ub = toUserBlocks(m.content, imageWithhold);
             raw.push({ role: "user", content: ub.length ? ub : [{ type: "text", text: NO_CONTENT }] });
         }
         else if (m.role === "assistant") {
@@ -97,7 +92,7 @@ function toAnthropicMessages(ctx, model, toolNames) {
             const docs = parts ? parts.filter((c) => c.type === "document") : [];
             const rest = docs.length > 0 && parts ? parts.filter((c) => c.type !== "document") : m.content;
             const hasImage = !m.isError && Array.isArray(rest) && rest.some((c) => c.type === "image");
-            let inner = hasImage ? toUserBlocks(rest, supportsVision) : textOf(rest);
+            let inner = hasImage ? toUserBlocks(rest, imageWithhold) : textOf(rest);
             if (docs.length > 0 && !m.isError) {
                 if (supportsVision) {
                     for (const d of docs) {
@@ -290,68 +285,30 @@ export function createAnthropicBrain(given = {}) {
                 if (options?.temperature !== undefined && anthCompat.supportsTemperature !== false) {
                     body.temperature = options.temperature;
                 }
-                let builtReasoningFacts;
-                let thinkingOn = false;
-                if (reasoningRequestCarried(model, options?.reasoning)) {
-                    if (anthCompat.thinkingMode === "adaptive") {
-                        body.thinking = { type: "adaptive" };
-                        thinkingOn = true;
-                    }
-                    else {
-                        const hardCap = overrides?.maxOutputTokens !== undefined || options?.maxTokens !== undefined;
-                        builtReasoningFacts = { outputCapTokens: body.max_tokens, hardOutputCap: hardCap };
-                        if (budgetCapSkipsThinking(builtReasoningFacts.outputCapTokens, builtReasoningFacts.hardOutputCap)) {
-                            body.thinking = undefined;
-                            delete body.thinking;
-                        }
-                        else {
-                            const share = config.thinkingBudgetShare ?? reasoningBudgetShare(options.reasoning);
-                            const { max, budget } = thinkingBudget(body.max_tokens, share, config.thinkingBudgetTokens, hardCap);
-                            body.max_tokens = max;
-                            body.thinking = { type: "enabled", budget_tokens: budget };
-                            thinkingOn = true;
-                        }
-                    }
-                    if (thinkingOn)
-                        delete body.temperature;
-                }
-                else if (model.reasoning && options?.reasoning === "off" && anthCompat.thinkingMode !== "adaptive") {
-                    body.thinking = { type: "disabled" };
-                }
-                const betas = [];
-                let sendEffortBeta = false;
-                const declaredEffort = declaredEffortLevels(anthCompat.effortLevels);
-                if (declaredEffort !== undefined && reasoningRequestCarried(model, options?.reasoning)) {
-                    const { effective } = resolveEffort(options.reasoning, declaredEffort);
-                    const wireEffort = effective === "minimal" ? "low" : effective;
-                    body.output_config = { effort: wireEffort };
-                    sendEffortBeta = true;
-                }
-                if (sendEffortBeta)
-                    betas.push("effort-2025-11-24");
-                if (anthCompat.contextManagement && thinkingOn) {
-                    body.context_management = { edits: [{ type: "clear_thinking_20251015", keep: "all" }] };
-                    betas.push("context-management-2025-06-27");
-                }
-                if (anthCompat.interleavedThinking) {
-                    betas.push("interleaved-thinking-2025-05-14");
-                }
-                const headers = mergeHeaders(modelHeaders, config.headers, optionsHeaders);
+                const hardCap = overrides?.maxOutputTokens !== undefined || options?.maxTokens !== undefined;
+                const { body: reasoningBody, headers: reasoningHeaders, wireFacts: builtReasoningFacts, } = applyReasoningToRequest({
+                    api: "anthropic-messages",
+                    model,
+                    level: options?.reasoning,
+                    body,
+                    budget: { capIsHard: hardCap, share: config.thinkingBudgetShare, tokens: config.thinkingBudgetTokens },
+                });
+                const headerLayers = [modelHeaders, config.headers, optionsHeaders];
+                const headers = mergeHeaders(...headerLayers);
                 applyRouteCredentialHeaders(headers, routeCredential);
-                if (betas.length > 0) {
-                    const existing = (takeHeaderCasefold(headers, "anthropic-beta") ?? "").split(",").map((b) => b.trim()).filter(Boolean);
-                    for (const beta of betas) {
-                        if (!existing.includes(beta))
-                            existing.push(beta);
-                    }
-                    headers["anthropic-beta"] = existing.join(",");
+                takeHeaderSpellings(headers, "anthropic-beta");
+                for (const layer of headerLayers) {
+                    for (const [name, value] of Object.entries(layer ?? {}))
+                        if (name.toLowerCase() === "anthropic-beta")
+                            mergeReasoningHeaders(headers, { [name]: value });
                 }
+                mergeReasoningHeaders(headers, reasoningHeaders);
                 lockHeader(headers, "content-type", "application/json");
                 lockHeader(headers, "anthropic-version", config.version ?? "2023-06-01");
                 if (apiKey)
                     lockHeader(headers, ANTHROPIC_KEY_HEADER, apiKey);
-                const builtThinkingRequested = body.thinking !== undefined;
-                const builtMaxTokens = body.max_tokens;
+                const builtThinkingRequested = reasoningBody.thinking !== undefined;
+                const builtMaxTokens = reasoningBody.max_tokens;
                 const builtMaxTokensLane = overrides?.maxOutputTokens !== undefined
                     ? "engine"
                     : options?.maxTokens !== undefined
@@ -359,7 +316,7 @@ export function createAnthropicBrain(given = {}) {
                         : model.maxTokens !== undefined
                             ? "model"
                             : "config-default";
-                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model, ANTHROPIC_RESERVED);
+                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(reasoningBody, model, ANTHROPIC_RESERVED);
                 return {
                     url,
                     headers,