@stratusagent/gateway 0.12.4 → 0.12.6

package/dist/index.js

@@ -9,8 +9,8 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
-import { filePathsOf, isUnaddressedTurn, carriesKey, leastTrusted, senderTrustOf, SENDER_TRUST_METADATA_KEY, workItemState, lastResponseIsAnswer, MAX_IDEMPOTENCY_KEY_LENGTH, recordTurnFailure, completeAnsweredTurn, abortErrorFor, AgentRegistry, AgentRunner, ChannelRegistry, ContributionRegistry, createRoutedMemoryStore, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, CONTEXT_FLOOR_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, conversationContextFrom, CONVERSATION_METADATA_KEY, STRATUS_SKILL_ID, imagesWithinReplayBudget, matchesToolAllowlist, } from '@stratusagent/core';
-import { CREDENTIAL_REQUEST_TOOL_NAME, createCredentialRequestTool, createDelegateTool, createForgetTool, createPinTool, createMessageSendTool, createMessageReadTool, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, delegatingSessionIdOf, isDelegatedSession, outstandingDelegationFor, ROOT_SESSION_ID_METADATA_KEY, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, withoutDelegation, loadStratusSkill, STRATUS_SKILL_PATH, } from '@stratusagent/agents';
+import { filePathsOf, isUnaddressedTurn, carriesKey, leastTrusted, senderTrustOf, SENDER_TRUST_METADATA_KEY, workItemState, lastResponseIsAnswer, MAX_IDEMPOTENCY_KEY_LENGTH, recordTurnFailure, completeAnsweredTurn, abortErrorFor, sessionTrustOf, sessionWriteTrust, AgentRegistry, AgentRunner, ChannelRegistry, ContributionRegistry, createRoutedMemoryStore, EventBus, RunAbortedError, SkillRegistry, ToolRegistry, createSkillReadTool, missingSkillRequirements, describeToolAllowlistFinding, unmatchedToolAllowlist, CONTEXT_FLOOR_METADATA_KEY, PENDING_APPROVAL_METADATA_KEY, SESSION_TAINTED_BY_METADATA_KEY, SESSION_TRUST_METADATA_KEY, latestTurnReply, readPendingApproval, conversationContextFrom, CONVERSATION_METADATA_KEY, STRATUS_SKILL_ID, imagesWithinReplayBudget, matchesToolAllowlist, } from '@stratusagent/core';
+import { CREDENTIAL_REQUEST_TOOL_NAME, createCredentialRequestTool, createDelegateTool, DELEGATE_TOOL_NAME, createForgetTool, createPinTool, createMessageSendTool, createMessageReadTool, createRecallTool, createRememberTool, createScheduleTools, DELEGATED_BY_METADATA_KEY, DEFAULT_MAX_DELEGATION_DEPTH, DELEGATION_DEPTH_METADATA_KEY, delegatingSessionIdOf, isDelegatedSession, outstandingDelegationFor, ROOT_SESSION_ID_METADATA_KEY, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, withoutDelegation, loadStratusSkill, STRATUS_SKILL_PATH, } from '@stratusagent/agents';
 import { createSchedulerRuntime, isScheduleSessionId, SqliteScheduleStore, SCHEDULE_SESSION_ID_PREFIX, } from "./schedules.js";
 import { ShardedSessionStore } from "./sessions.js";
 export { claimHome, homeLockPath, HomeClaimedError, } from "./lock.js";
@@ -267,6 +267,27 @@ class CrossIdentityError extends Error {
 const crossIdentityError = (sessionId, owner, claimed) => new CrossIdentityError(sessionId, owner, claimed);
 /** Where the session's tool calls ran: `local-command`, or a contributed executor's registered name. */
 export const EXECUTOR_METADATA_KEY = 'executor';
+/**
+ * Marks a sub-agent's session (roadmap 24). Reserved: it is what makes the
+ * daemon deny the session's gated calls without asking anyone, so a caller
+ * that could set it could also clear it.
+ */
+export const SUB_AGENT_METADATA_KEY = 'subAgent';
+export const SUB_AGENT_SESSION_ID_MARKER = ':subagent:';
+/** How many sub-agents one parent turn runs at once unless the host says otherwise. */
+export const DEFAULT_SUB_AGENTS_PER_TURN = 4;
+export const isSubAgentSession = (session) => session.metadata?.[SUB_AGENT_METADATA_KEY] === true && session.id.includes(SUB_AGENT_SESSION_ID_MARKER);
+/**
+ * Tools a sub-agent never gets, whatever its parent holds. `agent.spawn`
+ * would fan out inside a fan-out; `agent.delegate` runs a roster agent
+ * under that agent's own allowlist, which is the way out of a narrowed
+ * slice; `memory.*` would let it persist what nobody reviewed; and
+ * `credential.request` asks a person, which a sub-agent never does.
+ */
+const subAgentNeverGets = (name) => name === 'agent.spawn'
+    || name === DELEGATE_TOOL_NAME
+    || name.startsWith('memory.')
+    || name === CREDENTIAL_REQUEST_TOOL_NAME;
 export const RESERVED_SESSION_METADATA_KEYS = [
     PENDING_APPROVAL_METADATA_KEY,
     FALLBACK_ACTIVE_METADATA_KEY,
@@ -292,6 +313,7 @@ export const RESERVED_SESSION_METADATA_KEYS = [
     // no messages and, once it grows past that index, silently stops sending
     // its own earliest turns, with no overflow and no trim event to say so.
     CONTEXT_FLOOR_METADATA_KEY,
+    SUB_AGENT_METADATA_KEY,
 ];
 /**
  * The first reserved key `metadata` carries, or undefined when it carries
@@ -387,7 +409,7 @@ export const createGateway = (options = {}) => {
      * "cannot address" rather than a stale reference — and rejecting is how
      * both callers (schedule creation, `message.send`) hear why.
      */
-    const outboundFor = async (agentId, destination, thread) => {
+    const outboundFor = async (agentId, destination, thread, speaker) => {
         const { adapter, carriesOthers } = channelCarrying(destination.channel, agentId, (candidate) => candidate.resolveOutbound !== undefined);
         if (!adapter?.resolveOutbound && carriesOthers) {
             throw new Error(`No running '${destination.channel}' channel carries agent ${agentId} — `
@@ -399,7 +421,7 @@ export const createGateway = (options = {}) => {
                     ? 'no channel adapters are running.'
                     : `running channels: ${startedChannels.map((candidate) => candidate.name).join(', ')}.`));
         }
-        return adapter.resolveOutbound({ agentId, to: destination.to, ...(thread !== undefined ? { thread } : {}) });
+        return adapter.resolveOutbound({ agentId, to: destination.to, ...(thread !== undefined ? { thread } : {}), ...(speaker !== undefined ? { speaker } : {}) });
     };
     const scheduler = createSchedulerRuntime({
         store: scheduleStore,
@@ -489,7 +511,35 @@ export const createGateway = (options = {}) => {
         }
         return { agentId: root.agent.id, sessionId: root.id, ...(root.metadata ? { metadata: root.metadata } : {}) };
     };
+    /**
+     * Which sessions are sub-agents, as the host knows it rather than as the
+     * session says (roadmap 24). Every tool in a slice is handed the same
+     * mutable Session, so the metadata marker and the id are claims a tool
+     * can rewrite. The ids are the ones `subAgents.run` minted, held while
+     * the sub-agent runs. A session object's id is read once, by the
+     * executor on its first tool call, before any tool has been handed it,
+     * so a session a tool renamed is still known by the id it ran under.
+     */
+    const liveSubAgentIds = new Set();
+    const idAtFirstCall = new WeakMap();
+    const hostIdOf = (session) => idAtFirstCall.get(session) ?? session.id;
+    const isHostSubAgent = (session) => liveSubAgentIds.has(hostIdOf(session)) || isSubAgentSession(session);
     const requestApproval = async (request) => {
+        // A sub-agent asks no one (roadmap 24): its parent turn is the one a
+        // person is accountable for, and that turn gets the refusal back as a
+        // result and decides what to do. Denied as undeliverable, since nobody
+        // was asked, and announced only as a resolution, so no channel renders
+        // a question nobody may answer.
+        if (isHostSubAgent(request.session)) {
+            void bus.emit({
+                type: 'tool.approval-resolved',
+                sessionId: request.session.id,
+                requestId: randomUUID(),
+                answer: 'deny',
+                reason: 'undeliverable',
+            });
+            return { answer: 'deny' };
+        }
         const delegatedFrom = await delegationOriginOf(request.session);
         return requestApprovalFrom(request, delegatedFrom);
     };
@@ -533,6 +583,10 @@ export const createGateway = (options = {}) => {
          * all and its denial should not wait on an emission that never runs.
          */
         let announced = Promise.resolve();
+        // Read when the request is made, from the scheduler's own records: a
+        // live firing of a schedule approved with a destination, nothing else.
+        // Delegated work is not included yet; its sub-session is not a firing.
+        const scheduleDestination = scheduler.approvalDestinationFor(request.session);
         // Work one agent does for another is allowed one call at a time. The
         // people asked are the delegating conversation's, and a standing grant
         // would widen what the other agent may do on its own work for good —
@@ -594,6 +648,7 @@ export const createGateway = (options = {}) => {
                 ...(expiresAt ? { expiresAt } : {}),
                 ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
                 ...(delegatedFrom ? { delegatedFrom } : {}),
+                ...(scheduleDestination ? { scheduleDestination } : {}),
             },
         });
         if (effectiveApprovalTimeoutMs > 0 && remainingTimeoutMs <= 0) {
@@ -641,6 +696,7 @@ export const createGateway = (options = {}) => {
             ...(always !== undefined ? { always } : {}),
             ...(request.session.metadata ? { metadata: request.session.metadata } : {}),
             ...(delegatedFrom ? { delegatedFrom } : {}),
+            ...(scheduleDestination ? { scheduleDestination } : {}),
             ...(expiresAt ? { expiresAt } : {}),
         });
         // Drained at shutdown alongside the resolutions: a channel that has not
@@ -719,6 +775,21 @@ export const createGateway = (options = {}) => {
                     return channelCarrying(kind, agentId, (candidate) => candidate.accountFor !== undefined)
                         .adapter?.accountFor?.(agentId);
                 },
+                conversationKindFor: async (agentId, destination) => {
+                    const separator = destination.indexOf(':');
+                    if (separator <= 0) {
+                        return undefined;
+                    }
+                    const kind = destination.slice(0, separator);
+                    const adapter = channelCarrying(kind, agentId, (candidate) => candidate.conversationKindFor !== undefined).adapter;
+                    try {
+                        return await adapter?.conversationKindFor?.(agentId, destination.slice(separator + 1));
+                    }
+                    catch {
+                        // Unknown, so the call asks: never a reason to allow.
+                        return undefined;
+                    }
+                },
             },
             contributorOf: (toolName) => toolProvenance().get(toolName)?.package,
         })
@@ -1107,10 +1178,12 @@ export const createGateway = (options = {}) => {
     const runtimeContextFor = (source, config, onFallback, 
     // The turn's own metadata, where a channel records who can read the
     // conversation now; a recovered turn has none and passes the session's.
-    metadata) => {
+    metadata, 
+    // A sub-agent has no soul of its own, and its parent's is not its to edit.
+    subAgent = false) => {
         const conversation = conversationContextFrom(metadata);
         return {
-            ...(source.soulPath !== undefined ? { soulPath: source.soulPath, soulReloads: true } : {}),
+            ...(source.soulPath !== undefined && !subAgent ? { soulPath: source.soulPath, soulReloads: true } : {}),
             workspace: agentWorkspaces.forAgent(source.definition.id),
             ...(config.language !== undefined ? { language: config.language } : {}),
             model: describeServingModel(config, onFallback),
@@ -1178,8 +1251,8 @@ export const createGateway = (options = {}) => {
     for (const scheduleTool of createScheduleTools(scheduler.handle)) {
         tools.register(scheduleTool);
     }
-    tools.register(createMessageSendTool(async ({ agentId, destination, text, thread }) => {
-        const connection = await outboundFor(agentId, destination, thread);
+    tools.register(createMessageSendTool(async ({ agentId, destination, text, thread, speaker }) => {
+        const connection = await outboundFor(agentId, destination, thread, speaker);
         const posted = await connection.post(text);
         // The channel contract's `OutboundMessageRef`, read structurally: the
         // gateway's mirror of the adapter types `post` loosely, and an adapter
@@ -1473,6 +1546,229 @@ export const createGateway = (options = {}) => {
             ...(input.signal ? { signal: input.signal } : {}),
         }),
     }));
+    // ---- sub-agents (roadmap 24) -------------------------------------------
+    /**
+     * Running sub-agents per parent session, and who waits for a slot. A
+     * parent session runs one turn at a time, so this is per turn.
+     */
+    const maxSubAgentsPerTurn = options.subAgents?.maxConcurrentPerTurn ?? DEFAULT_SUB_AGENTS_PER_TURN;
+    // NaN, 0, a fraction or Infinity would queue every sub-agent forever or
+    // defeat the cap, so refuse it here instead of failing later in a turn.
+    if (!Number.isInteger(maxSubAgentsPerTurn) || maxSubAgentsPerTurn < 1) {
+        throw new Error(`subAgents.maxConcurrentPerTurn must be a whole number of at least 1 (got ${String(maxSubAgentsPerTurn)}).`);
+    }
+    const subAgentSlots = new Map();
+    let subAgentCount = 0;
+    /**
+     * The session object each in-flight tool call was handed, with that
+     * call's turn signal. `subAgents.run` accepts only a parent found here:
+     * the session a running tool was given, by identity, never an id, so a
+     * plugin cannot start sub-agents of another turn (another agent's
+     * included) just because that turn is running. The signal is how the
+     * parent's cancel reaches its sub-agents whether or not the plugin
+     * passes one.
+     */
+    const toolCallsInFlight = new Map();
+    const bindToolCalls = (inner) => ({
+        async execute(call, tool, session, context) {
+            if (!idAtFirstCall.has(session)) {
+                idAtFirstCall.set(session, session.id);
+            }
+            const entry = toolCallsInFlight.get(session) ?? [];
+            toolCallsInFlight.set(session, entry);
+            const signal = context?.signal;
+            entry.push(signal);
+            try {
+                return await inner.execute(call, tool, session, context);
+            }
+            finally {
+                entry.splice(entry.indexOf(signal), 1);
+                if (entry.length === 0) {
+                    toolCallsInFlight.delete(session);
+                }
+            }
+        },
+    });
+    const subAgentSlot = (parentId, signal) => new Promise((resolve, reject) => {
+        const entry = subAgentSlots.get(parentId) ?? { running: 0, waiting: [] };
+        subAgentSlots.set(parentId, entry);
+        const release = () => {
+            entry.running -= 1;
+            const next = entry.waiting.shift();
+            if (next) {
+                next();
+            }
+            else if (entry.running === 0) {
+                subAgentSlots.delete(parentId);
+            }
+        };
+        const take = () => {
+            entry.running += 1;
+            resolve(release);
+        };
+        if (entry.running < maxSubAgentsPerTurn) {
+            take();
+            return;
+        }
+        const onAbort = () => {
+            const at = entry.waiting.indexOf(waiter);
+            if (at >= 0) {
+                entry.waiting.splice(at, 1);
+            }
+            reject(abortErrorFor(signal));
+        };
+        const waiter = () => {
+            signal?.removeEventListener('abort', onAbort);
+            take();
+        };
+        entry.waiting.push(waiter);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+    /** Why this slice cannot be a sub-agent's, or undefined when it can. */
+    const subAgentSliceProblem = (parent, requested) => {
+        if (!Array.isArray(requested) || requested.some((name) => typeof name !== 'string' || name.length === 0)) {
+            return 'A sub-agent\'s tools are a list of tool names.';
+        }
+        const allowlist = parent.agent.tools;
+        for (const name of requested) {
+            if (/[*?]/.test(name)) {
+                return `A sub-agent's tools are exact names, and ${name} is a pattern.`;
+            }
+            if (subAgentNeverGets(name)) {
+                return `${name} is never given to a sub-agent, even by an agent that holds it.`;
+            }
+            if (!tools.get(name)) {
+                return `There is no tool named ${name}.`;
+            }
+            // The parent's allowlist as its running turn holds it: a slice can
+            // only narrow what that turn may already do.
+            if (allowlist !== undefined && !matchesToolAllowlist(name, allowlist)) {
+                return `${name} is not one of ${parent.agent.id}'s tools, so a sub-agent of it cannot have it.`;
+            }
+        }
+        return undefined;
+    };
+    const subAgents = {
+        async run(request) {
+            // Copied before the first await, and only the copy is read from here
+            // on: the plugin keeps its own objects and can change them while this
+            // request is checked or waits for a slot, and a slice changed after
+            // it was checked must not be the slice the sub-agent runs with.
+            const handed = request?.parent;
+            const callSignals = handed ? toolCallsInFlight.get(handed) : undefined;
+            if (!callSignals) {
+                throw new Error('subAgents.run starts sub-agents only for the session your tool was handed, while that call is running. Pass that session object as "parent".');
+            }
+            // The parent turn's own stop, and the caller's as an extra one: a
+            // plugin that passes no signal still has its sub-agents cancelled
+            // with the turn.
+            const stops = [...callSignals, request.signal].filter((signal) => signal !== undefined);
+            const input = {
+                parent: { id: hostIdOf(handed) },
+                instruction: request?.instruction,
+                tools: Array.isArray(request?.tools) ? [...request.tools] : request?.tools,
+                model: request?.model,
+                signal: stops.length === 0 ? undefined : stops.length === 1 ? stops[0] : AbortSignal.any(stops),
+            };
+            const parentId = typeof input.parent.id === 'string' ? input.parent.id : '';
+            if (!parentId) {
+                throw new Error('subAgents.run needs the session of the turn asking.');
+            }
+            const instruction = typeof input.instruction === 'string' ? input.instruction.trim() : '';
+            if (!instruction) {
+                throw new Error('subAgents.run needs an instruction.');
+            }
+            if (input.model !== undefined) {
+                throw new Error('A sub-agent\'s model cannot be chosen yet: it runs on its parent\'s. Leave "model" out.');
+            }
+            const parent = await store.get(parentId);
+            if (!parent) {
+                throw new Error(`There is no session ${parentId} to start a sub-agent from.`);
+            }
+            if (isHostSubAgent(handed) || isSubAgentSession(parent)) {
+                throw new Error('A sub-agent cannot start sub-agents.');
+            }
+            if (parent.status !== 'running') {
+                throw new Error(`Session ${parentId} is not running a turn, and sub-agents start only from one.`);
+            }
+            const depth = typeof parent.metadata?.[DELEGATION_DEPTH_METADATA_KEY] === 'number'
+                ? parent.metadata[DELEGATION_DEPTH_METADATA_KEY]
+                : 0;
+            if (depth >= DEFAULT_MAX_DELEGATION_DEPTH) {
+                throw new Error(`Delegation depth limit reached (${DEFAULT_MAX_DELEGATION_DEPTH}).`);
+            }
+            const problem = subAgentSliceProblem(parent, input.tools);
+            if (problem) {
+                throw new Error(problem);
+            }
+            if (input.signal?.aborted) {
+                throw abortErrorFor(input.signal);
+            }
+            const release = await subAgentSlot(parent.id, input.signal);
+            subAgentCount += 1;
+            const sessionId = `${parent.id}${SUB_AGENT_SESSION_ID_MARKER}${depth + 1}:${subAgentCount}-${randomUUID().slice(0, 8)}`;
+            // The parent agent, narrowed: its id, provider and credentials, the
+            // slice for tools, and nothing else — no instructions (the persona),
+            // no skills, no delegates.
+            const definition = {
+                id: parent.agent.id,
+                name: parent.agent.name,
+                tools: [...new Set(input.tools)],
+                skills: [],
+                delegates: [],
+                ...(parent.agent.credentials !== undefined ? { credentials: [...parent.agent.credentials] } : {}),
+            };
+            let session;
+            liveSubAgentIds.add(sessionId);
+            try {
+                session = await onSessionChain(sessionId, () => dispatchInternal({
+                    sessionId,
+                    agentId: parent.agent.id,
+                    userMessage: instruction,
+                    metadata: {
+                        [SUB_AGENT_METADATA_KEY]: true,
+                        [DELEGATION_DEPTH_METADATA_KEY]: depth + 1,
+                        [DELEGATED_BY_METADATA_KEY]: parent.agent.id,
+                        [ROOT_SESSION_ID_METADATA_KEY]: typeof parent.metadata?.[ROOT_SESSION_ID_METADATA_KEY] === 'string'
+                            ? parent.metadata[ROOT_SESSION_ID_METADATA_KEY]
+                            : parent.id,
+                        // The instruction is the parent's text, at the parent's label:
+                        // a tainted parent must not hand a stranger's words to a
+                        // session that has seen nothing.
+                        [SENDER_TRUST_METADATA_KEY]: sessionWriteTrust(parent),
+                        // On the runtime serving the parent's turn: a parent that has
+                        // switched to its sticky fallback must not have its helpers
+                        // retry the primary it left.
+                        ...(parent.metadata?.[FALLBACK_ACTIVE_METADATA_KEY] === true ? { [FALLBACK_ACTIVE_METADATA_KEY]: true } : {}),
+                    },
+                    ...(input.signal ? { signal: input.signal } : {}),
+                }, [], definition));
+            }
+            catch (error) {
+                if (input.signal?.aborted) {
+                    throw error;
+                }
+                // The error text may be the provider quoting what it refused,
+                // which is this sub-agent's context: labelled as nobody can vouch.
+                return { status: 'error', error: error instanceof Error ? error.message : String(error), sessionId, trust: 'unknown' };
+            }
+            finally {
+                liveSubAgentIds.delete(sessionId);
+                release();
+            }
+            const trust = sessionTrustOf(session);
+            if (session.status === 'failed') {
+                return { status: 'error', error: session.lastError ?? 'The sub-agent failed.', sessionId, trust: 'unknown' };
+            }
+            const reply = [...session.messages]
+                .reverse()
+                .find((message) => message.role === 'assistant' && message.content.trim().length > 0);
+            const outcome = reply
+                ? { status: 'result', text: reply.content, sessionId, trust }
+                : { status: 'empty', sessionId, trust };
+            return outcome;
+        },
+    };
     const runners = new Map();
     // Every provider-construction input participates in the key — model,
     // endpoint, credentials, system prompt, fallback config. A rotated
@@ -1484,13 +1780,17 @@ export const createGateway = (options = {}) => {
         const { soul: _soul, soulPath: _soulPath, fetch: _fetch, ...providerInputs } = config;
         return createHash('sha256').update(JSON.stringify(providerInputs)).digest('hex');
     };
-    const runnerFor = (config, agentId) => {
+    // A sub-agent's runner has no memory store, so no turn of it injects or
+    // reads the agent's memory; no skill catalog, so its prompt is its
+    // instruction and its tools; and grants nothing to every agent, since
+    // the credential request asks a person.
+    const runnerFor = (config, agentId, subAgent = false) => {
         // The budget is a provider-construction input too (the harness
         // runtimes take it as their inner limit), so it is part of the key:
         // two agents on one model with different budgets get their own runners.
         const maxTurns = options.maxTurnsFor?.(agentId) ?? options.maxTurns;
         const autoContinue = options.autoContinueFor?.(agentId);
-        const key = `${runnerKeyFor(config)}:${maxTurns ?? 'default'}:${autoContinue ?? 'off'}`;
+        const key = `${runnerKeyFor(config)}:${maxTurns ?? 'default'}:${autoContinue ?? 'off'}${subAgent ? ':sub' : ''}`;
         const existing = runners.get(key);
         if (existing) {
             return existing;
@@ -1515,16 +1815,15 @@ export const createGateway = (options = {}) => {
             // Runners are built on dispatch, after the plugins loaded and the
             // selection below ran, so a contributed executor is in place for
             // the first turn.
-            executor: selectedExecutor ?? createLocalCommandExecutor(),
+            executor: bindToolCalls(selectedExecutor ?? createLocalCommandExecutor()),
             ...(approvals ? { approvals } : {}),
             store,
             bus,
             agents: registry,
             // Asking a person for a key is harmless to grant: they decide
             // everything after the question, so no soul has to list it.
-            grantedToEveryAgent: [CREDENTIAL_REQUEST_TOOL_NAME],
-            skills: skillCatalog,
-            memory,
+            grantedToEveryAgent: subAgent ? [] : [CREDENTIAL_REQUEST_TOOL_NAME],
+            ...(subAgent ? {} : { skills: skillCatalog, memory }),
             streaming: true,
             ...(maxTurns !== undefined ? { maxTurns } : {}),
             ...(autoContinue !== undefined
@@ -1978,7 +2277,12 @@ export const createGateway = (options = {}) => {
             ? runsOnHarness(fallback)
             : runsOnHarness(config) || (fallback !== undefined && runsOnHarness(fallback));
     };
-    const dispatchInternal = async (input, absorbedKeys = []) => {
+    /**
+     * `subAgent` is the narrowed definition `subAgents.run` built: the turn
+     * runs as that, on the parent's resolved provider, with no memory and no
+     * soul. Only that path passes it.
+     */
+    const dispatchInternal = async (input, absorbedKeys = [], subAgent) => {
         // Re-read on every turn, not once at start: a newer build that stamps
         // the home while this daemon is serving has formats this build does not
         // understand, and a daemon that kept writing into them would be the
@@ -2001,7 +2305,10 @@ export const createGateway = (options = {}) => {
         const existing = await store.get(input.sessionId);
         const agentId = input.agentId ?? existing?.agent.id ?? await defaultAgentId();
         const source = await refreshAgent(agentId);
-        const agent = source.definition;
+        const agent = subAgent ?? source.definition;
+        if (subAgent !== undefined && existing) {
+            throw new Error(`Session ${input.sessionId} already exists; a sub-agent's session is new every time.`);
+        }
         // An archived transcript is the record of a conversation that has moved
         // on. Continuing it would revive a session the operator deliberately
         // left behind, under an id nothing routes to any more.
@@ -2010,7 +2317,7 @@ export const createGateway = (options = {}) => {
             throw new Error(`Session ${input.sessionId} was rolled over; it is an archived transcript and the conversation continues as ${continuedAs}.`);
         }
         const config = await runtimeForAgent(source);
-        const runner = runnerFor(config, source.definition.id);
+        const runner = runnerFor(config, source.definition.id, subAgent !== undefined);
         // Which executor the turn's tool calls run through — the built-in
         // under the name `stratus run` has always recorded, a contributed one
         // under its registered name — so a transcript says where a command
@@ -2030,7 +2337,8 @@ export const createGateway = (options = {}) => {
         if (existing && existing.agent.id !== agent.id) {
             throw crossIdentityError(input.sessionId, existing.agent.id, agent.id);
         }
-        const { switchedToFallback, effectiveStreams, fallbackStreams } = watchdogStreamsFor(existing, config);
+        // A sub-agent's session is new, but may start on its parent's fallback.
+        const { switchedToFallback, effectiveStreams, fallbackStreams } = watchdogStreamsFor(existing ?? (subAgent !== undefined ? { metadata } : undefined), config);
         // Recorded with a keyed message so a restart judges the turn by what it
         // could have run on, not by whatever the config resolves to by then.
         // The fallback counts: a turn can switch to it mid-run. Once a session
@@ -2057,6 +2365,13 @@ export const createGateway = (options = {}) => {
                 if (isDelegatedSession(existing) && existing.metadata) {
                     existing.metadata = withoutDelegation(existing.metadata);
                 }
+                // The same for a sub-agent's session, continued as the agent itself:
+                // the marker that denies its approvals unasked comes off with the
+                // delegation markers it carries.
+                if (isSubAgentSession(existing) && existing.metadata) {
+                    const { [SUB_AGENT_METADATA_KEY]: _subAgent, ...rest } = withoutDelegation(existing.metadata);
+                    existing.metadata = rest;
+                }
                 // The executor record follows the daemon, not the session's first
                 // turn: a restart that selected another executor runs this turn's
                 // commands there, and a session from before the record existed
@@ -2106,7 +2421,7 @@ export const createGateway = (options = {}) => {
                 ...(hostedLoop ? { hostedLoop } : {}),
                 ...(input.earlier !== undefined && input.earlier.length > 0 ? { earlier: input.earlier } : {}),
                 metadata,
-                runtime: runtimeContextFor(source, config, switchedToFallback, input.metadata),
+                runtime: runtimeContextFor(source, config, switchedToFallback, input.metadata, subAgent !== undefined),
                 signal,
             });
         });
@@ -2220,6 +2535,14 @@ export const createGateway = (options = {}) => {
             // Whether it IS an orphan was decided before the channels started
             // (`listOrphanedDelegations`), from the parent's transcript, which
             // a message arriving since may already have rewritten.
+            // A sub-agent never parks (nobody is asked for it), and if one ever
+            // did, its parent's turn died with the last process: nothing would
+            // read its answer, and recovering it would run it as the full agent.
+            if (isSubAgentSession(session) && session.status === 'pending_approval') {
+                log(`${sessionId}: a sub-agent parked when the last stratusd stopped; failing it`);
+                await failParked(session, ABANDONED_TURN_ERROR);
+                return;
+            }
             if (orphaned && isDelegatedSession(session) && session.status === 'pending_approval' && record) {
                 log(`${sessionId}: parked on ${record.call.toolName} for a delegating turn the last stratusd was still running; failing it`);
                 await failOrphanedDelegation(session);
@@ -2449,6 +2772,12 @@ export const createGateway = (options = {}) => {
      * completes it first.)
      */
     const continueAbandonedTurn = async (session) => {
+        // Its parent's turn died with the last process, and continuing it here
+        // would run it as the full agent. (Sub-agent turns carry no key today,
+        // so this is a guard, not a path.)
+        if (isSubAgentSession(session)) {
+            return failAbandoned(session);
+        }
         // Settled either way: a turn whose agent left the roster, or whose
         // provider no longer resolves, must not stay `running` for every later
         // start and every redelivery to find unfinished and trip over again.
@@ -3091,6 +3420,7 @@ export const createGateway = (options = {}) => {
             // not only on a stderr the service manager owns.
             log,
             warn,
+            subAgents,
         });
         loadedPlugins = result.loaded;
         pluginFailures = result.failures;