pilotswarm-sdk 0.5.63 → 0.5.65

package/dist/session-manager.js

@@ -1,3 +1,6 @@
+import { NATIVE_BUILTIN_AGENTS, NATIVE_EXCLUDED_TOOLS, nativeSubagentGuidance, nativeSubagentDefinitions, nativeSubagentHooks, guardNativeExternalTools } from "./native-subagents.js";
+import { createFeatureTools, FEATURE_OPERATION_SPECS } from "./feature-tools.js";
+import { FeatureFlagError } from "./feature-flags.js";
 import { BYOK_CLIENT_PREFIX, createCopilotClient, needsByokRequestCompatibility } from "./copilot-client.js";
 import { ManagedSession } from "./managed-session.js";
 import { SESSION_STATE_MISSING_PREFIX } from "./types.js";
@@ -35,6 +38,7 @@ const DEHYDRATE_STORE_MAX_RETRIES = 1;
 const DEHYDRATE_STORE_RETRY_BASE_DELAY_MS = 0;
 const SESSION_LOCK_BACKOFF_MS = [5_000, 10_000, 20_000];
 const SESSION_LOCK_MAX_WAIT_MS = 120_000;
+const COPILOT_CLIENT_SHUTDOWN_TIMEOUT_MS = 10_000;
 export const SESSION_LOCK_ACQUIRE_TIMEOUT_CODE = "PILOTSWARM_SESSION_LOCK_ACQUIRE_TIMEOUT";
 export class SessionLockAcquireTimeoutError extends Error {
     code = SESSION_LOCK_ACQUIRE_TIMEOUT_CODE;
@@ -76,6 +80,24 @@ function isMissingDehydrateSnapshotError(error) {
     const message = error instanceof Error ? error.message : String(error ?? "");
     return /Session state directory not ready during dehydrate/i.test(message);
 }
+export class PackageToolBindingError extends Error {
+    toolName;
+    code = "PACKAGE_TOOL_REQUIRES_BOUND_AGENT";
+    constructor(toolName) {
+        super(`Package tool "${toolName}" requires its owning named-agent definition. Use ps_list_agents to find its named agent, then call spawn_agent with the exact agent_name and your assignment in task.`);
+        this.toolName = toolName;
+        this.name = "PackageToolBindingError";
+    }
+}
+export class BoundAgentPackageUnavailableError extends Error {
+    packageId;
+    code = "BOUND_AGENT_PACKAGE_UNAVAILABLE";
+    constructor(packageId, message = `The bound agent package "${packageId}" is no longer available to this session.`) {
+        super(message);
+        this.packageId = packageId;
+        this.name = "BoundAgentPackageUnavailableError";
+    }
+}
 /** Key under which a package copy's per-agent config (MCP) is registered. */
 export function packageAgentKey(packageId, agentName) {
     return `pkg\u0001${packageId}\u0001${agentName}`;
@@ -120,7 +142,58 @@ export function pickAgentCopyForOwner(entry, ownerKey) {
         ?? copies.find((copy) => copy.packageScope === "shared")
         ?? undefined;
 }
-function buildEffectivePromptLayers(workerDefaults, config, sessionOwnerKey = null) {
+/** Resolve an already-authorized exact package copy while rechecking owner visibility. */
+export function pickAgentCopyByPackageIdForOwner(entry, packageId, ownerKey) {
+    if (!entry || !packageId)
+        return undefined;
+    const copies = entry.copies?.length ? entry.copies : [entry];
+    const copy = copies.find((candidate) => candidate.packageId === packageId);
+    if (!copy)
+        return undefined;
+    if (copy.packageScope !== "user")
+        return copy;
+    return agentOwnerKey(copy.packageOwner) === ownerKey && ownerKey !== null
+        ? copy
+        : undefined;
+}
+/** Resolve every part of a bound agent using the same authorized package copy. */
+function resolveBoundAgentCopy(workerDefaults, config, sessionOwnerKey) {
+    const entry = config.boundAgentName
+        ? workerDefaults.agentPromptLookup?.[config.boundAgentName]
+        : undefined;
+    if (config.boundAgentSource === "deployment") {
+        const copies = entry?.copies?.length ? entry.copies : entry ? [entry] : [];
+        const deployment = copies.find(copy => !copy.packageId && copy.packageScope == null);
+        if (config.boundAgentPackageId || !deployment) {
+            throw new BoundAgentPackageUnavailableError(`deployment:${config.boundAgentName ?? ""}`, `The bound deployment agent "${config.boundAgentName ?? ""}" is no longer available or has a conflicting package binding.`);
+        }
+        return deployment;
+    }
+    const copy = config.boundAgentPackageId
+        ? pickAgentCopyByPackageIdForOwner(entry, config.boundAgentPackageId, sessionOwnerKey)
+        : pickAgentCopyForOwner(entry, sessionOwnerKey);
+    if (config.boundAgentPackageId && !copy) {
+        throw new BoundAgentPackageUnavailableError(config.boundAgentPackageId);
+    }
+    return copy;
+}
+/** Match the SDK wire declaration, including schemas supplied through Zod. */
+function toolDeclarationForFingerprint(tool) {
+    const parameters = tool.parameters;
+    return {
+        name: tool.name,
+        description: tool.description,
+        parameters: parameters != null && typeof parameters === "object" && typeof parameters.toJSONSchema === "function"
+            ? parameters.toJSONSchema()
+            : parameters,
+        overridesBuiltInTool: tool.overridesBuiltInTool,
+        skipPermission: tool.skipPermission,
+        defer: tool.defer ?? "never",
+        metadata: tool.metadata,
+        isTerminal: tool.isTerminal,
+    };
+}
+function buildEffectivePromptLayers(workerDefaults, config, sessionOwnerKey = null, boundAgentCopy = resolveBoundAgentCopy(workerDefaults, config, sessionOwnerKey) ?? null) {
     const boundAgentName = config.boundAgentName;
     const layerKind = config.promptLayering?.kind ?? (boundAgentName ? "app-agent" : undefined);
     const isPilotSwarmSystemAgent = layerKind === "pilotswarm-system-agent";
@@ -130,9 +203,8 @@ function buildEffectivePromptLayers(workerDefaults, config, sessionOwnerKey = nu
     if (!isPilotSwarmSystemAgent && workerDefaults.appDefaultDescriptor)
         layers.push(workerDefaults.appDefaultDescriptor);
     if (boundAgentName) {
-        const copy = pickAgentCopyForOwner(workerDefaults.agentPromptLookup?.[boundAgentName], sessionOwnerKey);
-        if (copy?.descriptor)
-            layers.push(copy.descriptor);
+        if (boundAgentCopy?.descriptor)
+            layers.push(boundAgentCopy.descriptor);
     }
     return layers;
 }
@@ -287,6 +359,8 @@ export class SessionManager {
         }
     }
     sessions = new Map();
+    featureFlags = null;
+    unsubscribeFeatureFlags = null;
     /** Live in-memory session count — worker-registry health reporting. */
     get activeSessionCount() {
         return this.sessions.size;
@@ -304,10 +378,18 @@ export class SessionManager {
     sessionStore = null;
     /** In-memory configs with non-serializable fields (tools, hooks). */
     sessionConfigs = new Map();
+    /** Only application-supplied tools; resolved registry/platform handlers are never cached as inputs. */
+    sessionApplicationTools = new Map();
+    /** One authorized agent snapshot per turn, also used by dynamic prompt callbacks. */
+    sessionAgentCopies = new Map();
+    /** CLI declarations and MCP grants require a new SDK handle when they change. */
+    sessionBindingFingerprints = new Map();
     /** Worker-level tool registry — shared reference from PilotSwarmWorker. */
     toolRegistry = new Map();
     /** Per-package tool maps, so a session prefers ITS package's handler on a name collision. */
     packageToolRegistry = null;
+    /** Package-owned names cannot be attached without the matching agent package binding. */
+    packageToolNames = new Set();
     /** Names registered by deployment code — a package tool must never shadow these. */
     staticToolNames = null;
     /** Worker-level defaults for building blocks. */
@@ -363,6 +445,10 @@ export class SessionManager {
     /** Store full config (with tools/hooks) for a session. Called by PilotSwarmClient. */
     setConfig(sessionId, config) {
         this.sessionConfigs.set(sessionId, config);
+        if (config.tools?.length)
+            this.sessionApplicationTools.set(sessionId, [...config.tools]);
+        else
+            this.sessionApplicationTools.delete(sessionId);
     }
     async _allowedModelProviderIds(sessionId) {
         const registry = this.workerDefaults.modelProviders;
@@ -596,6 +682,12 @@ export class SessionManager {
         this.toolRegistry = registry;
         this.packageToolRegistry = opts?.byPackage ?? null;
         this.staticToolNames = opts?.staticNames ?? null;
+        // Remember ownership after removal as well: a stale application-supplied
+        // handler must not become an ordinary tool when its package disappears.
+        for (const tools of this.packageToolRegistry?.values() ?? []) {
+            for (const name of tools.keys())
+                this.packageToolNames.add(name);
+        }
     }
     /** Set the cluster facts store for always-on facts tools. */
     setFactStore(factStore) {
@@ -609,6 +701,16 @@ export class SessionManager {
     setSessionCatalog(catalog) {
         this.sessionCatalog = catalog;
     }
+    setFeatureFlagCache(cache) {
+        this.unsubscribeFeatureFlags?.();
+        this.featureFlags = cache;
+        this.unsubscribeFeatureFlags = cache?.onChange(() => {
+            for (const managed of this.sessions.values())
+                managed.refreshNativeFeaturePolicy();
+        }) ?? null;
+        for (const managed of this.sessions.values())
+            managed.refreshNativeFeaturePolicy();
+    }
     /**
      * Hot-swap the model-provider registry after a config-file change on
      * disk (ConfigMap update). Applies to all subsequent model resolution;
@@ -830,7 +932,7 @@ export class SessionManager {
                 await existing.destroy();
             }
             catch { }
-            this.sessions.delete(sessionId);
+            this._forgetWarmSession(sessionId);
         }
         try {
             const client = await this._ensureClientForSession(sessionId);
@@ -866,7 +968,7 @@ export class SessionManager {
                 await existing.destroy();
             }
             catch { }
-            this.sessions.delete(sessionId);
+            this._forgetWarmSession(sessionId);
         }
         try {
             const client = await this._ensureClientForSession(sessionId);
@@ -983,7 +1085,7 @@ export class SessionManager {
                             await existing.destroy();
                         }
                         catch { }
-                        this.sessions.delete(sessionId);
+                        this._forgetWarmSession(sessionId);
                     }
                     if (!dirExists) {
                         this.sessionLastTouchedAt.delete(sessionId);
@@ -1128,7 +1230,7 @@ export class SessionManager {
             ...(this.workerDefaults.appDefaultToolNames ?? []),
             ...(serializableConfig.toolNames ?? []),
         ]));
-        const effectiveSerializableConfig = inheritedToolNames.length > 0
+        let effectiveSerializableConfig = inheritedToolNames.length > 0
             ? { ...serializableConfig, toolNames: inheritedToolNames }
             : serializableConfig;
         // Which copy of the bound agent does this session get? Owner-aware:
@@ -1136,20 +1238,69 @@ export class SessionManager {
         // one, the same rule the registry resolver applies at create time.
         // Resolved once here; prompt, descriptor, MCP, and tool-handler picks
         // below all follow the same copy so a session can never mix copies.
-        const boundAgentEntry = effectiveSerializableConfig.boundAgentName
-            ? this.workerDefaults.agentPromptLookup?.[effectiveSerializableConfig.boundAgentName]
-            : undefined;
-        // A PACKAGE agent (as opposed to a deployment/inline agent) carries a
-        // packageId on its entry or on any of its copies. This is load-bearing
-        // for MCP resolution: a package agent must never fall back to the
-        // bare-name MCP key, which another copy of a shadowed name also wrote.
         const sessionOwnerKey = effectiveSerializableConfig.boundAgentName
             ? await this._sessionAgentOwnerKey(sessionId)
             : null;
-        const boundAgentCopy = pickAgentCopyForOwner(boundAgentEntry, sessionOwnerKey);
-        // Resolve tools: merge per-session (setConfig) + registry (toolNames)
         const storedConfig = this.sessionConfigs.get(sessionId);
-        const resolvedTools = this._resolveTools(storedConfig, effectiveSerializableConfig, boundAgentCopy?.packageId);
+        let boundAgentCopy;
+        let resolvedTools;
+        try {
+            boundAgentCopy = resolveBoundAgentCopy(this.workerDefaults, effectiveSerializableConfig, sessionOwnerKey);
+            // Snapshot the selected prompt and descriptor. A registry refresh in the
+            // middle of a turn must not change instructions while handlers still
+            // belong to the previously selected version.
+            if (boundAgentCopy)
+                boundAgentCopy = {
+                    ...boundAgentCopy,
+                    ...(boundAgentCopy.toolNames ? { toolNames: [...boundAgentCopy.toolNames] } : {}),
+                    ...(boundAgentCopy.descriptor ? { descriptor: { ...boundAgentCopy.descriptor } } : {}),
+                };
+            if (boundAgentCopy?.toolNames && effectiveSerializableConfig.boundAgentName
+                && (effectiveSerializableConfig.boundAgentPackageId || effectiveSerializableConfig.detachedPackageToolPolicy
+                    || effectiveSerializableConfig.namedAgentToolAdditions !== undefined)) {
+                // Named definitions refresh as a unit. Roots may add ordinary
+                // application tools; protected children receive only defaults and
+                // their definition. Legacy package roots have no provenance, so
+                // retain their ordinary names but never stale package capabilities.
+                const additions = effectiveSerializableConfig.detachedPackageToolPolicy
+                    ? []
+                    : (effectiveSerializableConfig.namedAgentToolAdditions ?? effectiveSerializableConfig.toolNames ?? [])
+                        .filter(name => this.staticToolNames?.has(name) || !this.packageToolNames.has(name));
+                effectiveSerializableConfig = {
+                    ...effectiveSerializableConfig,
+                    toolNames: [...new Set([
+                            ...(this.workerDefaults.frameworkBaseToolNames ?? []),
+                            ...(this.workerDefaults.appDefaultToolNames ?? []),
+                            ...boundAgentCopy.toolNames,
+                            ...additions,
+                        ])],
+                };
+            }
+            if (effectiveSerializableConfig.boundAgentSource === "deployment") {
+                // A deployment definition is bound, but owns no registry package.
+                // It cannot borrow a shared/private package's exported handlers.
+                effectiveSerializableConfig = { ...effectiveSerializableConfig, detachedPackageToolPolicy: "reject" };
+            }
+            resolvedTools = this._resolveTools({ tools: this.sessionApplicationTools.get(sessionId) }, effectiveSerializableConfig, boundAgentCopy?.packageId);
+        }
+        catch (error) {
+            // Failed authorization/removal must not leave a reusable handle with
+            // the previous package's handlers or MCP grants.
+            await this.dropWarmSession(sessionId);
+            this.sessionAgentCopies.delete(sessionId);
+            throw error;
+        }
+        // Capture MCP grants with the same registry snapshot, before asynchronous
+        // provider/catalog work below can allow a package reload to intervene.
+        const boundAgentMcpServers = !effectiveSerializableConfig.boundAgentName || !boundAgentCopy
+            ? undefined
+            : boundAgentCopy.packageId
+                ? this.workerDefaults.agentMcpServers?.[packageAgentKey(boundAgentCopy.packageId, effectiveSerializableConfig.boundAgentName)]
+                : this.workerDefaults.agentMcpServers?.[effectiveSerializableConfig.boundAgentName];
+        const effectiveMcpServers = {
+            ...(this.workerDefaults.baseMcpServers ?? {}),
+            ...(boundAgentMcpServers ?? {}),
+        };
         const config = {
             ...storedConfig,
             ...effectiveSerializableConfig,
@@ -1274,7 +1425,7 @@ export class SessionManager {
                     await existingWarm.destroy();
                 }
                 catch { }
-                this.sessions.delete(sessionId);
+                this._forgetWarmSession(sessionId);
             }
         }
         const client = await this.ensureClient(userGithubToken, byokOpenAi);
@@ -1451,16 +1602,36 @@ export class SessionManager {
         // sub-agent, fact, inspect, or graph tools. Mirrors the per-turn gate
         // in managed-session.ts runTurn — hard exclusion beats instructions.
         const isServiceSession = effectiveSerializableConfig.agentIdentity === "regen-distiller";
+        const featureTools = this.sessionCatalog?.features
+            && ["resourcemgr", "pilotswarm", "agent-manager"].includes(effectiveSerializableConfig.agentIdentity ?? "")
+            && (await this._resolveFeatureViewer(sessionId)).isAdmin
+            ? createFeatureTools(this.sessionCatalog.features, () => this._resolveFeatureViewer(sessionId)) : [];
+        // Handler refresh alone cannot change the CLI's tool declarations.
+        // Role transitions must recreate the warm SDK handle at the next turn.
+        config.featureToolFingerprint = createHash("sha256")
+            .update(JSON.stringify(featureTools.map(({ name, description, parameters }) => ({ name, description, parameters }))))
+            .digest("hex");
+        const nativeOwner = catalogRow?.owner ?? null;
+        // An unreadable owner must not bypass a user-level OFF by resolving
+        // cluster policy. Ownerless resolution is only for standalone managers.
+        const nativeOwnerKnown = !this.sessionCatalog || Boolean(nativeOwner?.provider && nativeOwner?.subject);
+        config.nativeFeatureAllowed = () => nativeOwnerKnown
+            && (this.featureFlags?.resolve("copilot.native_tasks", nativeOwner, { fallback: false }).enabled ?? false);
+        const nativeEnabled = this.workerDefaults.nativeSubagents === "sync" && config.nativeFeatureAllowed()
+            && !catalogRow?.isSystem && !isServiceSession && !isTunerSession
+            && config.promptLayering?.kind !== "pilotswarm-system-agent";
+        config.nativeSubagents = nativeEnabled ? "sync" : "off";
         const unlessService = (tools) => (isServiceSession ? [] : tools);
         const SYSTEM_TOOL_NAMES = new Set([
             ...systemTools, ...subAgentTools, ...factTools, ...inspectTools, ...graphTools,
-        ].map((t) => t.name));
+        ].map((t) => t.name).concat(FEATURE_OPERATION_SPECS.map(spec => spec.name)));
         const persistentSessionTools = [
             ...userTools.filter((t) => !SYSTEM_TOOL_NAMES.has(t.name)),
             ...unlessService(factTools),
             ...unlessService(inspectTools),
             ...unlessService(graphTools),
             ...unlessService(providerTools),
+            ...unlessService(featureTools),
         ];
         const allTools = [
             ...persistentSessionTools.filter((t) => !SYSTEM_TOOL_NAMES.has(t.name)),
@@ -1470,38 +1641,23 @@ export class SessionManager {
             ...unlessService(inspectTools),
             ...unlessService(graphTools),
             ...unlessService(providerTools),
+            ...unlessService(featureTools),
         ];
         config.tools = persistentSessionTools;
         // Build system message: worker base + client override
-        const systemMessage = this._buildSystemMessage(sessionId, config, sessionOwnerKey);
-        // Per-agent MCP (capability-profiles Phase 1): a session gets the
-        // base map (base-agent opt-ins + direct worker-config servers) plus
-        // its bound agent's resolved server map — resolved worker-side at the
-        // same chokepoint as the agent prompt. The deployment catalog is
-        // never applied wholesale.
-        //
-        // Read the MCP map of the copy THIS session actually resolved to.
-        // The worker registers a package agent's MCP under a package-qualified
-        // key only, and reserves the bare name for deployment/inline agents —
-        // so the resolved copy's own packageId is the discriminator:
-        //   • package copy resolved  → its qualified key (never the bare name,
-        //     which another copy of a shadowed name could have written);
-        //   • deployment/inline copy → the bare name (its own MCP);
-        //   • no copy resolved (a foreign-private-only name) → no grants.
-        // Keying off `boundAgentCopy.packageId` rather than "is any copy a
-        // package" is load-bearing: when a deployment agent and a package
-        // share a name and this session resolved the DEPLOYMENT copy, it must
-        // still get the deployment agent's bare-key MCP, not an empty
-        // qualified lookup.
-        const boundAgentMcpServers = !effectiveSerializableConfig.boundAgentName || !boundAgentCopy
-            ? undefined
-            : boundAgentCopy.packageId
-                ? this.workerDefaults.agentMcpServers?.[packageAgentKey(boundAgentCopy.packageId, effectiveSerializableConfig.boundAgentName)]
-                : this.workerDefaults.agentMcpServers?.[effectiveSerializableConfig.boundAgentName];
-        const effectiveMcpServers = {
-            ...(this.workerDefaults.baseMcpServers ?? {}),
-            ...(boundAgentMcpServers ?? {}),
-        };
+        const systemMessage = this._buildSystemMessage(sessionId, config, sessionOwnerKey, boundAgentCopy ?? null);
+        // Handler changes use updateConfig; declaration, MCP and authored prompt
+        // changes need a fresh CLI handle at this turn boundary. Do not include
+        // per-turn runtime context or newly allocated handler function identity.
+        const bindingFingerprint = createHash("sha256").update(JSON.stringify({
+            boundAgentName: config.boundAgentName,
+            boundAgentSource: config.boundAgentSource,
+            boundAgentCopy,
+            mcpServers: effectiveMcpServers,
+            tools: allTools.map(toolDeclarationForFingerprint),
+        })).digest("hex");
+        const bindingChanged = this.sessionBindingFingerprints.has(sessionId)
+            && this.sessionBindingFingerprints.get(sessionId) !== bindingFingerprint;
         const sessionConfig = {
             sessionId,
             // Sole chokepoint where tool DECLARATIONS reach the CLI (create and
@@ -1509,7 +1665,7 @@ export class SessionManager {
             // refreshes the client-side handler map). Pinned so tool search
             // cannot defer PilotSwarm tools out of the prompt — see
             // tool-pinning.ts for the why and the phase-2 opt-out path.
-            tools: pinToolsNeverDefer(allTools),
+            tools: pinToolsNeverDefer(nativeEnabled ? guardNativeExternalTools(allTools, sessionId) : allTools),
             model: sdkModelName,
             // Tell the runtime what a BYOK model can do.
             //
@@ -1542,7 +1698,7 @@ export class SessionManager {
             // state placement (verified against @github/copilot 1.0.36). State location is
             // controlled exclusively via COPILOT_HOME, set on the spawned CLI in ensureClient().
             workingDirectory: config.workingDirectory,
-            hooks: config.hooks,
+            hooks: nativeEnabled ? nativeSubagentHooks(sdkModelName, config.hooks, () => this.sessions.get(sessionId)?.canAdmitNativeTask() ?? false) : config.hooks,
             onPermissionRequest: config.onPermissionRequest ?? approvePermissionForSession,
             infiniteSessions: { enabled: true },
             // Enable token-level streaming so the catch-all event handler in
@@ -1555,17 +1711,20 @@ export class SessionManager {
             // Suppress sub-agent streaming events — we never want the parent
             // session's event log polluted with grandchild deltas.
             includeSubAgentStreamingEvents: false,
-            // Exclude the Copilot SDK's built-in "task" tool — PilotSwarm provides
-            // its own durable sub-agent mechanism via spawn_agent / check_agents.
-            // The native "task" tool spawns in-process sub-agents that bypass the
-            // durable orchestration layer, causing the LLM to use the wrong mechanism.
-            excludedTools: ["task"],
+            // Native workers are explicitly scoped: built-ins inherit external
+            // tools, and loaded PilotSwarm agents expect durable child contracts.
+            excludedTools: nativeEnabled ? NATIVE_EXCLUDED_TOOLS : ["task"],
+            ...(nativeEnabled ? {
+                customAgents: nativeSubagentDefinitions(sdkModelName),
+                customAgentsLocalOnly: true,
+                excludedBuiltinAgents: NATIVE_BUILTIN_AGENTS,
+            } : {}),
             // Custom LLM provider — resolve from registry or legacy single provider
             ...resolvedProviderConfig,
             // Pass loaded skills and agents from worker defaults; MCP servers
             // are the bound agent's own resolved map (see above).
             ...(this.workerDefaults.skillDirectories?.length && { skillDirectories: this.workerDefaults.skillDirectories }),
-            ...(this.workerDefaults.customAgents?.length && { customAgents: this.workerDefaults.customAgents }),
+            ...(!nativeEnabled && this.workerDefaults.customAgents?.length && { customAgents: this.workerDefaults.customAgents }),
             ...(Object.keys(effectiveMcpServers).length > 0 && { mcpServers: effectiveMcpServers }),
         };
         let copilotSession;
@@ -1582,15 +1741,16 @@ export class SessionManager {
                 console.warn(`[SessionManager] epoch-start for ${sessionId} (epoch ${transcriptEpoch}); ` +
                     `discarding the warm Copilot session of the previous epoch.`);
                 await existing.destroy();
-                this.sessions.delete(sessionId);
+                this._forgetWarmSession(sessionId);
             }
-            else if (existing.requiresModelRebind(config)) {
-                console.warn(`[SessionManager] model config changed for ${sessionId}; ` +
-                    `disconnecting warm Copilot session so it can resume with the new model config.`);
+            else if (bindingChanged || existing.requiresModelRebind(config)) {
+                console.warn(`[SessionManager] model or agent configuration changed for ${sessionId}; ` +
+                    `disconnecting warm Copilot session so it can resume with the updated configuration.`);
                 await existing.destroy();
-                this.sessions.delete(sessionId);
+                this._forgetWarmSession(sessionId);
             }
             else {
+                this.sessionAgentCopies.set(sessionId, boundAgentCopy);
                 existing.updateConfig(config);
                 return existing;
             }
@@ -1698,7 +1858,9 @@ export class SessionManager {
             agentId: effectiveSerializableConfig.agentIdentity ?? null,
         }));
         this.sessions.set(sessionId, managed);
-        const promptLayers = buildEffectivePromptLayers(this.workerDefaults, config);
+        this.sessionAgentCopies.set(sessionId, boundAgentCopy);
+        this.sessionBindingFingerprints.set(sessionId, bindingFingerprint);
+        const promptLayers = buildEffectivePromptLayers(this.workerDefaults, config, sessionOwnerKey, boundAgentCopy ?? null);
         if (promptLayers.length > 0 && this.sessionCatalog) {
             void this.sessionCatalog.recordEvents(sessionId, [{
                     eventType: "session.prompt_layers",
@@ -1715,6 +1877,12 @@ export class SessionManager {
     getSessionStateDir() {
         return this.sessionStateDir;
     }
+    /** Release snapshots with their SDK handle; application tools survive ordinary hydration. */
+    _forgetWarmSession(sessionId) {
+        this.sessions.delete(sessionId);
+        this.sessionAgentCopies.delete(sessionId);
+        this.sessionBindingFingerprints.delete(sessionId);
+    }
     /**
      * Destroy the in-memory ManagedSession only — disk state untouched.
      * Used by the lifecycle preamble before overwriting local files with a
@@ -1723,13 +1891,13 @@ export class SessionManager {
      */
     async dropWarmSession(sessionId) {
         const existing = this.sessions.get(sessionId);
-        if (!existing)
-            return;
-        try {
-            await existing.destroy();
+        if (existing) {
+            try {
+                await existing.destroy();
+            }
+            catch { }
         }
-        catch { }
-        this.sessions.delete(sessionId);
+        this._forgetWarmSession(sessionId);
     }
     /**
      * Dehydrate a session: snapshot to the session store, release in-memory state.
@@ -1785,13 +1953,13 @@ export class SessionManager {
             try {
                 emitSessionManagerTrace(sessionId, `destroy attempt ${attempt}/${DESTROY_MAX_RETRIES}`, { trace });
                 await session.destroy();
-                this.sessions.delete(sessionId);
+                this._forgetWarmSession(sessionId);
                 emitSessionManagerTrace(sessionId, `destroy complete on attempt ${attempt}/${DESTROY_MAX_RETRIES}`, { trace });
                 break; // Success
             }
             catch (err) {
                 lastDestroyError = normalizeError(err);
-                this.sessions.delete(sessionId); // Remove broken session from map
+                this._forgetWarmSession(sessionId); // Remove broken session from map
                 emitSessionManagerTrace(sessionId, `destroy failed on attempt ${attempt}/${DESTROY_MAX_RETRIES} error=${lastDestroyError.message}`, { trace, level: "warn" });
                 if (attempt < DESTROY_MAX_RETRIES) {
                     // Re-create the session from local files so we can try destroy again.
@@ -1952,10 +2120,11 @@ export class SessionManager {
             return this._withSessionLock(sessionId, "destroySession", () => this.destroySession(sessionId, { lockHeld: true }));
         }
         const session = this.sessions.get(sessionId);
-        if (session) {
+        if (session)
             await session.destroy();
-            this.sessions.delete(sessionId);
-        }
+        this._forgetWarmSession(sessionId);
+        this.sessionApplicationTools.delete(sessionId);
+        this.sessionConfigs.delete(sessionId);
     }
     /**
      * Drop the warm in-memory session handle without deleting any persisted
@@ -1973,7 +2142,7 @@ export class SessionManager {
             await session.destroy();
         }
         catch { }
-        this.sessions.delete(sessionId);
+        this._forgetWarmSession(sessionId);
     }
     /**
      * Fully reset a session's live and persisted Copilot state.
@@ -2002,23 +2171,51 @@ export class SessionManager {
     activeSessionIds() {
         return [...this.sessions.keys()];
     }
-    /** Shutdown: destroy all sessions, stop CopilotClient. */
+    /** Final worker cleanup, after the durable runtime has drained. */
     async shutdown() {
-        for (const [_, session] of this.sessions) {
-            try {
-                await session.destroy();
-            }
-            catch { }
-        }
+        this.unsubscribeFeatureFlags?.();
+        this.unsubscribeFeatureFlags = null;
+        // CopilotClient.stop owns session detachment. Detaching each session
+        // first can hang forever in the SDK's unbounded session.detach RPC.
+        // Snapshot and release this pool before awaiting: late SDK cleanup
+        // must never clear clients/configuration installed by a later start.
+        const clients = [...new Set(this.clients.values())];
+        this.clients.clear();
         this.sessions.clear();
+        this.sessionAgentCopies.clear();
+        this.sessionBindingFingerprints.clear();
+        this.sessionApplicationTools.clear();
+        this.sessionConfigs.clear();
         this.sessionClientKeys.clear();
-        for (const [, client] of this.clients) {
+        // Each process gets the same deadline concurrently; one stuck client
+        // cannot block another or multiply the worker's termination budget.
+        // This is final cleanup only, not the individual-session eviction path.
+        await Promise.all(clients.map(async (client) => {
+            let timer;
             try {
-                await client.stop();
+                const errors = await Promise.race([
+                    client.stop(),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => reject(new Error("Copilot shutdown timed out")), COPILOT_CLIENT_SHUTDOWN_TIMEOUT_MS);
+                    }),
+                ]);
+                if (errors?.length)
+                    throw errors[0];
             }
-            catch { }
-        }
-        this.clients.clear();
+            catch {
+                console.warn("[SessionManager] Copilot did not shut down cleanly; forcing its local process to stop.");
+                try {
+                    await client.forceStop();
+                }
+                catch {
+                    console.warn("[SessionManager] Copilot force-stop failed.");
+                }
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        }));
     }
     /**
      * Resolve tools from per-session config + worker-level registry.
@@ -2037,15 +2234,42 @@ export class SessionManager {
             : undefined;
         if (serializableConfig.toolNames?.length) {
             for (const name of serializableConfig.toolNames) {
-                const tool = (this.staticToolNames?.has(name) ? this.toolRegistry.get(name) : undefined)
-                    ?? packageTools?.get(name)
-                    ?? this.toolRegistry.get(name);
+                const staticTool = this.staticToolNames?.has(name)
+                    ? this.toolRegistry.get(name)
+                    : undefined;
+                const packageTool = packageTools?.get(name);
+                if (!staticTool && !packageTool && this.packageToolNames.has(name)) {
+                    if (serializableConfig.detachedPackageToolPolicy === "drop")
+                        continue;
+                    if (serializableConfig.detachedPackageToolPolicy === "reject" || preferredPackageId) {
+                        throw new PackageToolBindingError(name);
+                    }
+                }
+                const tool = staticTool ?? packageTool ?? this.toolRegistry.get(name);
                 if (tool)
                     registryTools.push(tool);
             }
         }
+        const storedTools = (storedConfig?.tools ?? []).filter((tool) => {
+            const name = String(tool?.name || "");
+            if (!name || this.staticToolNames?.has(name) || !this.packageToolNames.has(name))
+                return true;
+            // An explicitly supplied package handler follows the current package
+            // copy, never a stale object retained by the caller across a reload.
+            if (packageTools?.has(name) && serializableConfig.toolNames?.includes(name))
+                return true;
+            if (serializableConfig.detachedPackageToolPolicy === "drop")
+                return false;
+            if (serializableConfig.detachedPackageToolPolicy === "reject" || preferredPackageId) {
+                throw new PackageToolBindingError(name);
+            }
+            return true;
+        }).map((tool) => {
+            const name = String(tool?.name || "");
+            return this.staticToolNames?.has(name) ? tool : packageTools?.get(name) ?? tool;
+        });
         const combined = [
-            ...(storedConfig?.tools ?? []),
+            ...storedTools,
             ...registryTools,
         ];
         // Deduplicate by name — per-session tools take precedence
@@ -2177,18 +2401,17 @@ export class SessionManager {
             },
         };
     }
-    _buildLastInstructionsSection(sessionId, initialConfig) {
+    _buildLastInstructionsSection(sessionId, initialConfig, initialAgentCopy) {
         return {
             action: async (currentContent) => {
                 const latest = this.sessionConfigs.get(sessionId) ?? initialConfig;
                 const runtimeContext = extractPromptContent(latest.systemMessage);
-                // Owner-aware copy pick, re-resolved here because this action
-                // runs per compose: with scope shadowing one agent name can be
-                // served by several packages, and this session must get the
-                // copy its OWNER resolves to — not whichever loaded last.
-                const activeAgentPrompt = latest.boundAgentName
-                    ? pickAgentCopyForOwner(this.workerDefaults.agentPromptLookup?.[latest.boundAgentName], await this._sessionAgentOwnerKey(sessionId))?.prompt
-                    : undefined;
+                // Follow the same per-turn snapshot as tools/MCP/descriptor.
+                // Re-selecting by bare name here could both defeat an explicit
+                // shared-package pin and adopt refreshed instructions mid-turn.
+                const activeAgentPrompt = (this.sessionAgentCopies.has(sessionId)
+                    ? this.sessionAgentCopies.get(sessionId)
+                    : initialAgentCopy)?.prompt;
                 // Orchestration ≥1.0.71 delivers the per-turn note inside the
                 // user turn (see prompt-system-context.ts) and flags it. For
                 // those turns the note must NOT land here: this section is
@@ -2209,6 +2432,10 @@ export class SessionManager {
                     runtimeContext,
                     ownSkillsIndex,
                     latest.systemContextInPrompt ? undefined : latest.turnSystemPrompt,
+                    // The SDK ignores sibling `content` when `action` is a
+                    // transform callback. Include worker guidance in the actual
+                    // rendered section, using the current session policy.
+                    latest.nativeSubagents === "sync" ? nativeSubagentGuidance() : undefined,
                 ]);
                 return this._notePromptSection(sessionId, "last_instructions", mergePromptSections([currentContent, overlay]) ?? currentContent);
             },
@@ -2365,6 +2592,20 @@ export class SessionManager {
             return false;
         }
     }
+    async _resolveFeatureViewer(sessionId) {
+        // Never use the inspect-viewer TTL for feature mutations: demotion must
+        // apply on the next invocation, including an already-hydrated session.
+        const row = await this.sessionCatalog?.getSession(sessionId);
+        // CMS deliberately leaves worker-provisioned system sessions ownerless.
+        // Their persisted service classification supplies the same identity used
+        // by credential and inspect resolution; an agent name grants nothing.
+        const principal = row?.owner ?? (row?.isSystem === true ? SYSTEM_USER_PRINCIPAL : null);
+        if (!principal?.provider || !principal.subject)
+            throw new FeatureFlagError("FEATURE_FORBIDDEN", "Feature tools require an authenticated session owner", 403);
+        const system = row?.isSystem === true && principal.provider === SYSTEM_USER_PRINCIPAL.provider
+            && principal.subject === SYSTEM_USER_PRINCIPAL.subject;
+        return { principal, isAdmin: system || await this._resolveOwnerIsAdmin(principal) };
+    }
     /**
      * A one-line-per-skill index of the private skills this session's owner
      * published, or undefined when there are none. Mirrors the wording of the
@@ -2425,17 +2666,17 @@ export class SessionManager {
         const names = new Set(own.map((s) => s.name));
         return [...own, ...shared.filter((s) => !names.has(s.name))];
     }
-    _buildSystemMessage(sessionId, config, sessionOwnerKey = null) {
+    _buildSystemMessage(sessionId, config, sessionOwnerKey = null, boundAgentCopy = resolveBoundAgentCopy(this.workerDefaults, config, sessionOwnerKey) ?? null) {
         const frameworkBase = this.workerDefaults.frameworkBasePrompt ?? this.workerDefaults.systemMessage;
         const boundAgentName = config.boundAgentName;
         const layerKind = config.promptLayering?.kind ?? (boundAgentName ? "app-agent" : undefined);
         const knowledgeToolInstructions = this._buildKnowledgeToolInstructionsSection(sessionId, config.agentIdentity);
-        const lastInstructions = this._buildLastInstructionsSection(sessionId, config);
+        const lastInstructions = this._buildLastInstructionsSection(sessionId, config, boundAgentCopy);
         const additionalSections = knowledgeToolInstructions
             ? { tool_instructions: knowledgeToolInstructions, last_instructions: lastInstructions }
             : { last_instructions: lastInstructions };
         const isPilotSwarmSystemAgent = layerKind === "pilotswarm-system-agent";
-        const layerManifest = buildEffectivePromptLayers(this.workerDefaults, config, sessionOwnerKey);
+        const layerManifest = buildEffectivePromptLayers(this.workerDefaults, config, sessionOwnerKey, boundAgentCopy);
         return composeStructuredSystemMessage({
             frameworkBase,
             appDefault: isPilotSwarmSystemAgent