pilotswarm-sdk 0.5.64 → 0.5.65

package/dist/session-proxy.js

@@ -1,6 +1,7 @@
+import { HANDOFF_ACTIVITY_NAMES, routeHandoffActivity, routedActivityName, registerHandoffActivity } from "./activity-routing.js";
 import nodeCrypto from "node:crypto";
 import { createCopilotClient } from "./copilot-client.js";
-import { isSessionLockAcquireTimeoutError } from "./session-manager.js";
+import { BoundAgentPackageUnavailableError, isSessionLockAcquireTimeoutError, PackageToolBindingError, } from "./session-manager.js";
 import { extractCanvasAppManifest, canvasAppCard, normalizeCanvasResponseContract } from "./canvas-app-manifest.js";
 import { readCanvasKv, writeCanvasKv } from "./canvas-kv.js";
 import { publishCanvasApp, findCanvasApp } from "./canvas-app-catalog.js";
@@ -37,6 +38,13 @@ import { attemptStoreRecovery, runTurnCommit, runTurnPreamble } from "./session-
 import { supportsVersionedSnapshots, writeTurnSentinel } from "./snapshot-protocol.js";
 import { LatestValuePublisher } from "./live-turn.js";
 const SYSTEM_AGENT_IDS = new Set(["pilotswarm", "sweeper", "resourcemgr", "facts-manager"]);
+/** Same lineage principal for inline and durable agent selection. */
+async function resolveCallerAgentOwnerKey(catalog, sessionId) {
+    const owner = catalog && sessionId
+        ? await resolveEffectiveSpawnOwner((id) => catalog.getSession(id), sessionId).catch(() => null)
+        : null;
+    return owner?.provider && owner?.subject ? `${owner.provider}\u0001${owner.subject}` : null;
+}
 /**
  * THE agent-name resolver: FQN parsing, fuzzy matching, package privacy, and
  * owner shadowing in one place.
@@ -107,8 +115,10 @@ export async function resolveAgentDefinitionForCaller(opts) {
     const ownerKeyOf = (owner) => owner?.provider && owner?.subject ? `${owner.provider}\u0001${owner.subject}` : null;
     const visibleToCaller = async (agent) => {
         const agentOwnerKey = ownerKeyOf(agent?.packageOwner);
-        if (agent?.packageScope !== "user" || !agentOwnerKey)
+        if (agent?.packageScope !== "user")
             return true;
+        if (!agentOwnerKey)
+            return false;
         const key = await callerOwnerKeyOnce();
         return key !== null && key === agentOwnerKey;
     };
@@ -172,6 +182,36 @@ export async function resolveAgentDefinitionForCaller(opts) {
         packageScope: agent.packageScope ?? undefined,
     };
 }
+/** Legacy activity compatibility for frozen orchestrations. Not a spawn_agent selector. */
+export async function resolveAgentDefinitionForRequiredToolForCaller(opts) {
+    const requiredTool = String(opts.requiredTool || "").trim();
+    if (!requiredTool)
+        return { status: "not_found", candidates: [] };
+    const declaresTool = (agent) => agent?.tools?.includes(requiredTool)
+        || agent?.copies?.some((copy) => copy?.tools?.includes(requiredTool));
+    const logicalNames = [...new Set((opts.userAgents ?? [])
+            .filter(declaresTool)
+            .map((agent) => String(agent?.name || "").trim())
+            .filter(Boolean))].sort((left, right) => left.localeCompare(right));
+    const resolved = new Map();
+    for (const agentName of logicalNames) {
+        const agent = await resolveAgentDefinitionForCaller({
+            agentName,
+            userAgents: opts.userAgents,
+            systemAgents: opts.systemAgents,
+            getCallerOwnerKey: opts.getCallerOwnerKey,
+        });
+        if (!agent || agent.creatable === false || !agent.tools?.includes(requiredTool))
+            continue;
+        resolved.set(agent.name, agent);
+    }
+    const candidates = [...resolved.keys()].sort((left, right) => left.localeCompare(right));
+    if (candidates.length === 0)
+        return { status: "not_found", candidates: [] };
+    if (candidates.length > 1)
+        return { status: "ambiguous", candidates };
+    return { status: "resolved", agent: resolved.get(candidates[0]), candidates };
+}
 // The canvas helpers (filenames, slot normalization, revision derivation)
 // live in canvas-support.ts, shared with the app catalog. Re-exported so
 // existing importers keep their path.
@@ -521,15 +561,15 @@ function normalizeDistillerEffort(value) {
 function normalizeDistillerTier(value) {
     return value && DISTILLER_TIERS.has(value) ? value : undefined;
 }
-export function createSessionProxy(ctx, sessionId, affinityKey, config) {
+export function createSessionProxy(ctx, sessionId, affinityKey, config, routingContract) {
     return {
         runTurn(prompt, bootstrap, turnIndex, turnMeta) {
-            return ctx.scheduleActivityOnSession(
+            return routeHandoffActivity(ctx.scheduleActivityOnSession(
             // The epoch-start turn is a distinct activity name (runTurn2):
-            // pre-1.0.67 workers don't register it, so a rolling deploy can
-            // never hand the fresh-epoch create to a worker that would
-            // silently resume the dead transcript instead.
-            turnMeta?.epochStart ? "runTurn2" : "runTurn", {
+            // with an explicit contract since 1.0.67. New handoffs ALSO
+            // require a capability tag: activity names alone do not stop
+            // old workers from dequeuing work they cannot execute.
+            routedActivityName(turnMeta?.epochStart ? "runTurn2" : "runTurn", routingContract), {
                 sessionId,
                 prompt,
                 config,
@@ -566,7 +606,7 @@ export function createSessionProxy(ctx, sessionId, affinityKey, config) {
                 ...(turnMeta?.stashedPrompts && turnMeta.stashedPrompts.length > 0
                     ? { stashedPrompts: turnMeta.stashedPrompts }
                     : {}),
-            }, affinityKey);
+            }, affinityKey), routingContract);
         },
         dehydrate(reason, eventData) {
             return ctx.scheduleActivityOnSession("dehydrateSession", {
@@ -734,7 +774,7 @@ export function bootstrapTurnOptions(requiredTool) {
 // ─── SessionManagerProxy ─────────────────────────────────────────
 // The orchestration's view of the SessionManager singleton.
 // Operations that don't require session affinity.
-export function createSessionManagerProxy(ctx) {
+export function createSessionManagerProxy(ctx, routingContract, options) {
     return {
         listModels() {
             return ctx.scheduleActivity("listModels", {});
@@ -744,10 +784,10 @@ export function createSessionManagerProxy(ctx) {
         },
         /** Spawn a child session via the PilotSwarmClient SDK. Returns the generated child session ID. */
         spawnChildSession(parentSessionId, config, task, nestingLevel, isSystem, title, agentId, splash, titleIsExplicit, requiredTool) {
-            return ctx.scheduleActivity("spawnChildSession", {
+            return routeHandoffActivity(ctx.scheduleActivity(routedActivityName("spawnChildSession", routingContract), {
                 parentSessionId, config, task, nestingLevel, isSystem, title, agentId, splash, titleIsExplicit,
                 ...(requiredTool ? { requiredTool } : {}),
-            });
+            }), routingContract);
         },
         /**
          * Resolve a loaded agent config by name. Returns null if not found.
@@ -758,8 +798,18 @@ export function createSessionManagerProxy(ctx) {
          * the orchestration generator keeps the yield sequence byte-identical, so
          * this is not an orchestration version change.
          */
-        resolveAgentConfig(agentName) {
-            return ctx.scheduleActivity("resolveAgentConfig", { agentName, callerSessionId: ctx.instanceId });
+        resolveAgentConfig(agentName, callerSessionId, binding) {
+            return routeHandoffActivity(ctx.scheduleActivity(routedActivityName("resolveAgentConfig", routingContract), {
+                agentName,
+                callerSessionId: callerSessionId ?? ctx.instanceId,
+                ...(binding ? { binding } : {}),
+            }), routingContract);
+        },
+        resolveAgentForRequiredTool(requiredTool, callerSessionId) {
+            return routeHandoffActivity(ctx.scheduleActivity(routedActivityName("resolveAgentForRequiredTool", routingContract), {
+                requiredTool,
+                callerSessionId: callerSessionId ?? ctx.instanceId,
+            }), routingContract);
         },
         /** Send a message to a session via the PilotSwarmClient SDK. */
         sendToSession(sessionId, message) {
@@ -771,6 +821,9 @@ export function createSessionManagerProxy(ctx) {
         },
         /** Get the status of a session via the PilotSwarmClient SDK. */
         getSessionStatus(sessionId) {
+            if (options?.childResultProvenance) {
+                return routeHandoffActivity(ctx.scheduleActivity(HANDOFF_ACTIVITY_NAMES.getSessionStatus, { sessionId }), routingContract);
+            }
             return ctx.scheduleActivity("getSessionStatus", { sessionId });
         },
         /** Get orchestration runtime stats for a session. */
@@ -783,6 +836,9 @@ export function createSessionManagerProxy(ctx) {
         },
         /** List direct child sessions of a session. */
         listChildSessions(parentSessionId) {
+            if (options?.childResultProvenance) {
+                return routeHandoffActivity(ctx.scheduleActivity(HANDOFF_ACTIVITY_NAMES.listChildSessions, { parentSessionId }), routingContract);
+            }
             return ctx.scheduleActivity("listChildSessions", { parentSessionId });
         },
         /** @deprecated Send a child_updates event to a parent orchestration. Use sendToSession instead. */
@@ -1367,18 +1423,12 @@ artifactStore) {
                     // previous inline copy had none of that: it could hand another user's
                     // private agent to this session and could not address the shared copy
                     // of a shadowed name.
+                    const getCallerOwnerKeyInline = () => resolveCallerAgentOwnerKey(catalog, input.sessionId);
                     const resolveAgentConfigInline = (agentName) => resolveAgentDefinitionForCaller({
                         agentName,
                         userAgents,
                         systemAgents,
-                        getCallerOwnerKey: async () => {
-                            const owner = catalog
-                                ? await resolveEffectiveSpawnOwner((id) => catalog.getSession(id), input.sessionId).catch(() => null)
-                                : null;
-                            return owner?.provider && owner?.subject
-                                ? `${owner.provider}\u0001${owner.subject}`
-                                : null;
-                        },
+                        getCallerOwnerKey: getCallerOwnerKeyInline,
                     });
                     const loadDirectChildSessions = async () => {
                         const sdkClient = await getInlineClient();
@@ -1664,15 +1714,18 @@ artifactStore) {
                                     nestingLevel: 0,
                                     ...(normalizedModel ? { model: normalizedModel } : {}),
                                     ...(args.reasoning_effort ? { reasoningEffort: args.reasoning_effort } : {}),
-                                    boundAgentName: agentDef.name,
+                                    boundAgentName: !agentDef.packageId && agentDef.namespace ? `${agentDef.namespace}:${agentDef.name}` : agentDef.name,
+                                    ...(agentDef.packageId ? { boundAgentPackageId: agentDef.packageId } : {}),
+                                    ...(!agentDef.packageId ? { boundAgentSource: "deployment" } : {}),
+                                    namedAgentToolAdditions: [],
                                     promptLayering: { kind: "app-agent" },
                                     ...(agentDef.tools ? { toolNames: agentDef.tools } : {}),
-                                    agentId: agentDef.id ?? agentName,
+                                    agentId: agentDef.id ?? agentDef.name,
                                     ...(owner ? { owner } : {}),
                                 });
                                 if (catalog) {
                                     const meta = {
-                                        agentId: agentDef.id ?? agentName,
+                                        agentId: agentDef.id ?? agentDef.name,
                                         title: typeof args.title === "string" && args.title.trim()
                                             ? args.title.trim()
                                             : `${agentDef.title || agentName}: ${newSessionId.slice(0, 8)}`,
@@ -1716,6 +1769,9 @@ artifactStore) {
                         },
                         spawnAgent: async (args) => {
                             try {
+                                if (Object.hasOwn(args, "required_tool") || Object.hasOwn(args, "requiredTool")) {
+                                    return `[SYSTEM: spawn_agent failed — required_tool is no longer supported by spawn_agent. Use ps_list_agents to find a suitable named agent, then pass its exact agent_name and your assignment in task.]`;
+                                }
                                 const childNestingLevel = (input.nestingLevel ?? 0) + 1;
                                 if (childNestingLevel > MAX_NESTING_LEVEL) {
                                     return `[SYSTEM: spawn_agent failed — you are already at nesting level ${input.nestingLevel ?? 0} (max ${MAX_NESTING_LEVEL}). ` +
@@ -1741,24 +1797,24 @@ artifactStore) {
                                 let agentSplashMobile;
                                 let bootstrapRequiredTool;
                                 let boundAgentName;
+                                let boundAgentPackageId;
                                 let promptLayeringKind;
                                 let resolvedAgentName = args.agent_name;
-                                const applyAgentDef = (agentDef, useDefinitionDefaults = false) => {
-                                    agentTask = useDefinitionDefaults
-                                        ? (agentDef.initialPrompt || `You are the ${agentDef.name} agent. Begin your work.`)
-                                        : (args.task || agentDef.initialPrompt || `You are the ${agentDef.name} agent. Begin your work.`);
-                                    agentSystemMessage = useDefinitionDefaults ? undefined : args.system_message;
-                                    agentToolNames = useDefinitionDefaults
-                                        ? (agentDef.tools ?? undefined)
-                                        : (args.tool_names ?? agentDef.tools ?? undefined);
+                                const applyAgentDef = (agentDef) => {
+                                    agentTask = args.task || agentDef.initialPrompt || `You are the ${agentDef.name} agent. Begin your work.`;
+                                    agentSystemMessage = undefined;
+                                    // Match durable spawning: no parent package tools when
+                                    // the selected definition declares no extra tools.
+                                    agentToolNames = agentDef.tools ?? [];
                                     agentIsSystem = agentDef.system ?? false;
                                     if (!agentTitleIsExplicit)
                                         agentTitle = agentDef.title;
-                                    agentId = agentDef.id ?? resolvedAgentName;
+                                    agentId = agentDef.id ?? agentDef.name;
                                     agentSplash = agentDef.splash;
                                     agentSplashMobile = agentDef.splashMobile;
                                     bootstrapRequiredTool = agentDef.initialRequiredTool;
-                                    boundAgentName = agentDef.name;
+                                    boundAgentName = !agentDef.packageId && agentDef.namespace ? `${agentDef.namespace}:${agentDef.name}` : agentDef.name;
+                                    boundAgentPackageId = agentDef.packageId;
                                     promptLayeringKind = agentDef.promptLayerKind
                                         ?? (agentDef.system
                                             ? ((agentDef.namespace || "pilotswarm") === "pilotswarm"
@@ -1766,16 +1822,26 @@ artifactStore) {
                                                 : "app-system-agent")
                                             : "app-agent");
                                 };
+                                let agentDef = null;
                                 if (resolvedAgentName) {
-                                    const agentDef = await resolveAgentConfigInline(resolvedAgentName);
+                                    agentDef = await resolveAgentConfigInline(resolvedAgentName);
                                     if (!agentDef) {
                                         return `[SYSTEM: spawn_agent failed — agent "${resolvedAgentName}" not found. Use ps_list_agents to see available agents.]`;
                                     }
+                                }
+                                if (agentDef) {
                                     if (agentDef.system && agentDef.creatable === false) {
                                         return `[SYSTEM: spawn_agent failed — agent "${resolvedAgentName}" is a worker-managed system agent and cannot be spawned from a session. ` +
                                             `If it is missing, the workers likely need to be restarted.]`;
                                     }
-                                    applyAgentDef(agentDef, resolvedAgentName !== args.agent_name);
+                                    if (args.tool_names !== undefined) {
+                                        return `[SYSTEM: spawn_agent failed — tool_names cannot override a bound named-agent definition. Use a custom task without agent_name, or remove tool_names.]`;
+                                    }
+                                    if (args.system_message !== undefined) {
+                                        return `[SYSTEM: spawn_agent failed — system_message cannot override a bound named-agent definition. Put the bounded assignment in task instead.]`;
+                                    }
+                                    // The named definition owns its startup requirement.
+                                    applyAgentDef(agentDef);
                                 }
                                 // Spawned children inherit the parent lineage's EFFECTIVE
                                 // owner instead of any system flag: the nearest owned
@@ -1803,14 +1869,18 @@ artifactStore) {
                                 // still apply. The parent is responsible for closing
                                 // each instance with complete_agent / cancel_agent /
                                 // delete_agent when it no longer needs the child.
-                                const { boundAgentName: _parentBoundAgentName, promptLayering: _parentPromptLayering, isCrawler: _parentIsCrawler, isHarvester: _parentIsHarvester, ...parentConfig } = input.config;
+                                const { boundAgentName: _parentBoundAgentName, boundAgentPackageId: _parentBoundAgentPackageId, boundAgentSource: _parentBoundAgentSource, namedAgentToolAdditions: _parentNamedAgentToolAdditions, childContract: _parentChildContract, detachedPackageToolPolicy: _parentDetachedPackageToolPolicy, promptLayering: _parentPromptLayering, agentIdentity: _parentAgentIdentity, isCrawler: _parentIsCrawler, isHarvester: _parentIsHarvester, ...parentConfig } = input.config;
                                 const childConfig = {
                                     ...parentConfig,
+                                    ...(boundAgentName ? { systemMessage: undefined } : {}),
                                     ...(agentModel ? { model: agentModel } : {}),
                                     ...(agentReasoningEffort ? { reasoningEffort: agentReasoningEffort } : {}),
                                     ...(args.context_tier !== undefined ? { contextTier: args.context_tier } : {}),
                                     ...(agentSystemMessage ? { systemMessage: agentSystemMessage } : {}),
                                     ...(boundAgentName ? { boundAgentName } : {}),
+                                    ...(boundAgentPackageId ? { boundAgentPackageId } : {}),
+                                    ...(boundAgentName && !boundAgentPackageId ? { boundAgentSource: "deployment" } : {}),
+                                    detachedPackageToolPolicy: boundAgentName || args.tool_names?.length ? "reject" : "drop",
                                     ...(promptLayeringKind ? { promptLayering: { kind: promptLayeringKind } } : {}),
                                     ...(agentToolNames ? { toolNames: agentToolNames } : {}),
                                     ...(args.contract ? { childContract: args.contract } : {}),
@@ -1850,6 +1920,9 @@ artifactStore) {
                                     ...childModelCreationOptions(childConfig),
                                     systemMessage: childConfig.systemMessage,
                                     boundAgentName: childConfig.boundAgentName,
+                                    boundAgentPackageId: childConfig.boundAgentPackageId,
+                                    boundAgentSource: childConfig.boundAgentSource,
+                                    detachedPackageToolPolicy: childConfig.detachedPackageToolPolicy,
                                     promptLayering: childConfig.promptLayering,
                                     toolNames: childConfig.toolNames,
                                     waitThreshold: childConfig.waitThreshold,
@@ -2225,7 +2298,7 @@ artifactStore) {
                                 }
                                 const sdkClient = await getInlineClient();
                                 const cmdId = `done-inline-${Date.now()}`;
-                                await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "done", id: cmdId, args: { reason: "Completed by parent" } }));
+                                await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "done", id: cmdId, args: { reason: "Completed by parent" }, requestedBy: input.sessionId }));
                                 return `[SYSTEM: Graceful completion requested for sub-agent ${child.orchId}. ` +
                                     `Use check_agents or wait_for_agents to observe final completion.]`;
                             }
@@ -2256,7 +2329,7 @@ artifactStore) {
                                 }
                                 const sdkClient = await getInlineClient();
                                 const cmdId = `cancel-inline-${Date.now()}`;
-                                await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "cancel", id: cmdId, args: { reason: args.reason ?? "Cancelled by parent" } }));
+                                await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "cancel", id: cmdId, args: { reason: args.reason ?? "Cancelled by parent" }, requestedBy: input.sessionId }));
                                 return `[SYSTEM: Graceful cancellation requested for sub-agent ${child.orchId}. ` +
                                     `Use check_agents or wait_for_agents to observe final termination.${args.reason ? ` Reason: ${args.reason}` : ""}]`;
                             }
@@ -2273,7 +2346,7 @@ artifactStore) {
                                     return `[SYSTEM: Sub-agent ${child.orchId} has been deleted.${args.reason ? ` Reason: ${args.reason}` : ""}]`;
                                 }
                                 const cmdId = `delete-inline-${Date.now()}`;
-                                await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "delete", id: cmdId, args: { reason: args.reason ?? "Deleted by parent" } }));
+                                await sdkClient._getDuroxideClient().enqueueEvent(child.orchId, "messages", JSON.stringify({ type: "cmd", cmd: "delete", id: cmdId, args: { reason: args.reason ?? "Deleted by parent" }, requestedBy: input.sessionId }));
                                 return `[SYSTEM: Graceful deletion requested for sub-agent ${child.orchId}. ` +
                                     `It will cancel its descendants first and then delete itself.${args.reason ? ` Reason: ${args.reason}` : ""}]`;
                             }
@@ -3371,6 +3444,12 @@ artifactStore) {
             return finalTurnResult;
         }
         catch (err) {
+            if (err instanceof PackageToolBindingError || err instanceof BoundAgentPackageUnavailableError) {
+                const message = err.message || String(err);
+                activityCtx.traceInfo(`[runTurn] deterministic package-tool binding failure: ${message}`);
+                finalTurnResult = { type: "error", message, retryable: false };
+                return finalTurnResult;
+            }
             if (isSessionLockAcquireTimeoutError(err)) {
                 const message = err.message || String(err);
                 activityCtx.traceInfo(`[runTurn] ${message}`);
@@ -3427,11 +3506,10 @@ artifactStore) {
             }
         }
     };
-    runtime.registerActivity("runTurn", runTurnHandler);
-    // Session regeneration: the epoch-start turn dispatches under a NEW
-    // activity name so pre-1.0.67 workers — which would silently resume the
-    // dead transcript — structurally cannot receive it (deployment gate §4).
-    runtime.registerActivity("runTurn2", runTurnHandler);
+    registerHandoffActivity(runtime, "runTurn", runTurnHandler);
+    // Keep the historical epoch activity for replay. 1.0.75 uses a renamed,
+    // capability-tagged alias; the tag filter performs actual worker routing.
+    registerHandoffActivity(runtime, "runTurn2", runTurnHandler);
     // ── abortTurn ────────────────────────────────────────────
     // Stop-turn fast-path interrupt. Routed on the session affinity key so it
     // lands on the worker owning the warm ManagedSession and runs CONCURRENTLY
@@ -3819,11 +3897,16 @@ artifactStore) {
     // resolveAgentDefinitionForCaller — shared with the control bridge so
     // spawn_agent/create_agent_session and this activity can never disagree
     // about which agent a name means.
-    runtime.registerActivity("resolveAgentConfig", async (_activityCtx, input) => {
+    registerHandoffActivity(runtime, "resolveAgentConfig", async (_activityCtx, input) => {
+        // Top-level verification sessions already selected a package/deployment
+        // copy at creation. Keep that selection through the startup resolver.
+        // An unavailable pin yields no definition; it never falls back by name.
+        const pinnedCandidates = (agents) => agents?.filter(agent => (!input.binding?.packageId || agent.packageId === input.binding.packageId)
+            && (input.binding?.source !== "deployment" || (!agent.packageId && agent.packageScope == null)));
         return resolveAgentDefinitionForCaller({
             agentName: input.agentName,
-            userAgents,
-            systemAgents,
+            userAgents: pinnedCandidates(userAgents),
+            systemAgents: pinnedCandidates(systemAgents),
             // PACKAGE PRIVACY, enforced at RESOLUTION rather than at creation.
             //
             // Workers install every enabled package, including other users'
@@ -3840,15 +3923,15 @@ artifactStore) {
             //
             // Deployment-owned plugin agents carry no package owner and stay
             // public, exactly as before.
-            getCallerOwnerKey: async () => {
-                const row = input.callerSessionId
-                    ? await catalog?.getSession(input.callerSessionId)
-                    : null;
-                const owner = row?.owner;
-                return owner?.provider && owner?.subject
-                    ? `${owner.provider}\u0001${owner.subject}`
-                    : null;
-            },
+            getCallerOwnerKey: () => resolveCallerAgentOwnerKey(catalog, input.callerSessionId),
+        });
+    });
+    registerHandoffActivity(runtime, "resolveAgentForRequiredTool", async (_activityCtx, input) => {
+        return resolveAgentDefinitionForRequiredToolForCaller({
+            requiredTool: input.requiredTool,
+            userAgents,
+            systemAgents,
+            getCallerOwnerKey: () => resolveCallerAgentOwnerKey(catalog, input.callerSessionId),
         });
     });
     // ── spawnChildSession ─────────────────────────────────────
@@ -3856,7 +3939,7 @@ artifactStore) {
     // System child agents with a stable agentId use a deterministic UUID.
     // Other child sessions use a random UUID.
     // Goes through the full SDK path: CMS registration + orchestration startup.
-    runtime.registerActivity("spawnChildSession", async (activityCtx, input) => {
+    registerHandoffActivity(runtime, "spawnChildSession", async (activityCtx, input) => {
         const startedAt = Date.now();
         const trace = (message) => {
             activityCtx.traceInfo(`[spawnChildSession] +${Date.now() - startedAt}ms ${message}`);
@@ -3927,6 +4010,9 @@ artifactStore) {
                 ...childModelCreationOptions(input.config),
                 systemMessage: input.config.systemMessage,
                 boundAgentName: input.config.boundAgentName,
+                boundAgentPackageId: input.config.boundAgentPackageId,
+                boundAgentSource: input.config.boundAgentSource,
+                detachedPackageToolPolicy: input.config.detachedPackageToolPolicy,
                 promptLayering: input.config.promptLayering,
                 toolNames: input.config.toolNames,
                 waitThreshold: input.config.waitThreshold,
@@ -3950,12 +4036,23 @@ artifactStore) {
                 meta.agentId = input.agentId;
             if (input.splash)
                 meta.splash = input.splash;
-            // Frozen orchestration versions don't thread splashMobile through
-            // the spawn input, so resolve it from the loaded agent definition.
+            // Resolve mobile metadata through the same package pin and caller
+            // visibility rules as the prompt/tools, including for older inputs
+            // that carry only an agent id. A bare first match can expose another
+            // user's copy when private and shared packages have the same name.
             if (input.agentId) {
-                const normalizeId = (value) => (value || "").toLowerCase().replace(/[^a-z0-9]+/g, "");
-                const lookup = normalizeId(input.agentId);
-                const agentDef = [...(userAgents ?? []), ...(systemAgents ?? [])].find((a) => [a.id, a.name].map(normalizeId).filter(Boolean).includes(lookup));
+                const packageId = input.config.boundAgentPackageId;
+                const fromBoundCopy = (agents) => packageId
+                    ? agents?.filter(a => a.packageId === packageId)
+                    : input.config.boundAgentSource === "deployment"
+                        ? agents?.filter(a => !a.packageId && a.packageScope == null)
+                        : agents;
+                const agentDef = await resolveAgentDefinitionForCaller({
+                    agentName: input.config.boundAgentName ?? input.agentId,
+                    userAgents: fromBoundCopy(userAgents),
+                    systemAgents: fromBoundCopy(systemAgents),
+                    getCallerOwnerKey: () => resolveCallerAgentOwnerKey(catalog, input.parentSessionId),
+                });
                 if (agentDef?.splashMobile)
                     meta.splashMobile = agentDef.splashMobile;
             }
@@ -4038,27 +4135,29 @@ artifactStore) {
     });
     // ── getSessionStatus ────────────────────────────────────
     // Gets the status of a session via the PilotSwarmClient SDK.
-    runtime.registerActivity("getSessionStatus", async (activityCtx, input) => {
+    const getSessionStatus = async (activityCtx, input, includeResultSource = false) => {
         activityCtx.traceInfo(`[getSessionStatus] session=${input.sessionId}`);
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmClient");
         const sdkClient = new PilotSwarmClient(internalClientConfig());
         try {
             await sdkClient.start();
-            const info = await sdkClient._getSessionInfo(input.sessionId);
+            const info = await sdkClient._getSessionInfo(input.sessionId, includeResultSource ? { includeResultSource: true } : undefined);
             return JSON.stringify({
                 sessionId: info.sessionId,
                 status: info.status,
                 title: info.title,
                 iterations: info.iterations,
                 result: info.result,
+                ...(includeResultSource && info.resultSource ? { resultSource: info.resultSource } : {}),
                 error: info.error,
             });
         }
         finally {
             await sdkClient.stop();
         }
-    });
+    };
+    registerHandoffActivity(runtime, "getSessionStatus", getSessionStatus, (ctx, input) => getSessionStatus(ctx, input, true));
     // ── getOrchestrationStats ───────────────────────────────
     // Gets duroxide orchestration runtime stats for a session.
     runtime.registerActivity("getOrchestrationStats", async (activityCtx, input) => {
@@ -4101,7 +4200,7 @@ artifactStore) {
     });
     // ── listChildSessions ───────────────────────────────────
     // Lists direct child sessions of a parent with merged live status.
-    runtime.registerActivity("listChildSessions", async (activityCtx, input) => {
+    const listChildSessions = async (activityCtx, input, includeResultSource = false) => {
         activityCtx.traceInfo(`[listChildSessions] parent=${input.parentSessionId}`);
         if (!storeUrl)
             throw new Error("No storeUrl — cannot create PilotSwarmClient");
@@ -4111,7 +4210,7 @@ artifactStore) {
             const sessions = await sdkClient.listSessions();
             const directChildren = sessions.filter(s => s.parentSessionId === input.parentSessionId);
             const enriched = await Promise.all(directChildren.map(async (child) => {
-                const info = await sdkClient._getSessionInfo(child.sessionId);
+                const info = await sdkClient._getSessionInfo(child.sessionId, includeResultSource ? { includeResultSource: true } : undefined);
                 const outcome = catalog ? await catalog.getChildOutcome(child.sessionId).catch(() => null) : null;
                 const outcomeResult = normalizeJsonObject(outcome?.resultJson?.current);
                 const contractCurrent = normalizeJsonObject(outcome?.contractJson?.current);
@@ -4125,6 +4224,10 @@ artifactStore) {
                     isSystem: child.isSystem ?? info.isSystem ?? false,
                     agentId: child.agentId ?? info.agentId,
                     result: outcome?.summary ?? (typeof outcomeResult?.summary === "string" ? outcomeResult.summary : info.result),
+                    ...(includeResultSource ? {
+                        resultSource: outcome?.summary != null || typeof outcomeResult?.summary === "string"
+                            ? "child_outcome" : info.resultSource,
+                    } : {}),
                     contract: contractCurrent ?? undefined,
                     contractStatus: outcome?.contractJson ? "contracted" : undefined,
                     verdict: outcome?.verdict ?? undefined,
@@ -4137,7 +4240,8 @@ artifactStore) {
         finally {
             await sdkClient.stop();
         }
-    });
+    };
+    registerHandoffActivity(runtime, "listChildSessions", listChildSessions, (ctx, input) => listChildSessions(ctx, input, true));
     // ── notifyParent ────────────────────────────────────────
     // Sends a child_updates event to the parent orchestration so it can
     // wake up from durable sleep and process the child's result.