feat(commands): add /subagents spawn command

Add a `spawn` action to the /subagents command handler that invokes
spawnSubagentDirect() to deterministically launch a named subagent.

Usage: /subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]

Also includes the shared subagent-spawn module extraction (same as the
refactor/extract-shared-subagent-spawn branch) since it hasn't merged yet.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Joshua Mitchell
2026-02-16 10:07:22 -06:00
committed by Peter Steinberger
parent bb5ce3b02f
commit 5a3a448bc4
6 changed files with 616 additions and 284 deletions

View File

@@ -0,0 +1,322 @@
import crypto from "node:crypto";
import { formatThinkingLevels, normalizeThinkLevel } from "../auto-reply/thinking.js";
import { loadConfig } from "../config/config.js";
import { callGateway } from "../gateway/call.js";
import { normalizeAgentId, parseAgentSessionKey } from "../routing/session-key.js";
import { normalizeDeliveryContext } from "../utils/delivery-context.js";
import { resolveAgentConfig } from "./agent-scope.js";
import { AGENT_LANE_SUBAGENT } from "./lanes.js";
import { resolveDefaultModelForAgent } from "./model-selection.js";
import { buildSubagentSystemPrompt } from "./subagent-announce.js";
import { getSubagentDepthFromSessionStore } from "./subagent-depth.js";
import { countActiveRunsForSession, registerSubagentRun } from "./subagent-registry.js";
import { readStringParam } from "./tools/common.js";
import {
resolveDisplaySessionKey,
resolveInternalSessionKey,
resolveMainSessionAlias,
} from "./tools/sessions-helpers.js";
export type SpawnSubagentParams = {
task: string;
label?: string;
agentId?: string;
model?: string;
thinking?: string;
runTimeoutSeconds?: number;
cleanup?: "delete" | "keep";
};
export type SpawnSubagentContext = {
agentSessionKey?: string;
agentChannel?: string;
agentAccountId?: string;
agentTo?: string;
agentThreadId?: string | number;
agentGroupId?: string | null;
agentGroupChannel?: string | null;
agentGroupSpace?: string | null;
requesterAgentIdOverride?: string;
};
export type SpawnSubagentResult = {
status: "accepted" | "forbidden" | "error";
childSessionKey?: string;
runId?: string;
modelApplied?: boolean;
warning?: string;
error?: string;
};
export function splitModelRef(ref?: string) {
if (!ref) {
return { provider: undefined, model: undefined };
}
const trimmed = ref.trim();
if (!trimmed) {
return { provider: undefined, model: undefined };
}
const [provider, model] = trimmed.split("/", 2);
if (model) {
return { provider, model };
}
return { provider: undefined, model: trimmed };
}
export function normalizeModelSelection(value: unknown): string | undefined {
if (typeof value === "string") {
const trimmed = value.trim();
return trimmed || undefined;
}
if (!value || typeof value !== "object") {
return undefined;
}
const primary = (value as { primary?: unknown }).primary;
if (typeof primary === "string" && primary.trim()) {
return primary.trim();
}
return undefined;
}
export async function spawnSubagentDirect(
params: SpawnSubagentParams,
ctx: SpawnSubagentContext,
): Promise<SpawnSubagentResult> {
const task = params.task;
const label = params.label?.trim() || "";
const requestedAgentId = params.agentId;
const modelOverride = params.model;
const thinkingOverrideRaw = params.thinking;
const cleanup =
params.cleanup === "keep" || params.cleanup === "delete" ? params.cleanup : "keep";
const requesterOrigin = normalizeDeliveryContext({
channel: ctx.agentChannel,
accountId: ctx.agentAccountId,
to: ctx.agentTo,
threadId: ctx.agentThreadId,
});
const runTimeoutSeconds =
typeof params.runTimeoutSeconds === "number" && Number.isFinite(params.runTimeoutSeconds)
? Math.max(0, Math.floor(params.runTimeoutSeconds))
: 0;
let modelWarning: string | undefined;
let modelApplied = false;
const cfg = loadConfig();
const { mainKey, alias } = resolveMainSessionAlias(cfg);
const requesterSessionKey = ctx.agentSessionKey;
const requesterInternalKey = requesterSessionKey
? resolveInternalSessionKey({
key: requesterSessionKey,
alias,
mainKey,
})
: alias;
const requesterDisplayKey = resolveDisplaySessionKey({
key: requesterInternalKey,
alias,
mainKey,
});
const callerDepth = getSubagentDepthFromSessionStore(requesterInternalKey, { cfg });
const maxSpawnDepth = cfg.agents?.defaults?.subagents?.maxSpawnDepth ?? 1;
if (callerDepth >= maxSpawnDepth) {
return {
status: "forbidden",
error: `sessions_spawn is not allowed at this depth (current depth: ${callerDepth}, max: ${maxSpawnDepth})`,
};
}
const maxChildren = cfg.agents?.defaults?.subagents?.maxChildrenPerAgent ?? 5;
const activeChildren = countActiveRunsForSession(requesterInternalKey);
if (activeChildren >= maxChildren) {
return {
status: "forbidden",
error: `sessions_spawn has reached max active children for this session (${activeChildren}/${maxChildren})`,
};
}
const requesterAgentId = normalizeAgentId(
ctx.requesterAgentIdOverride ?? parseAgentSessionKey(requesterInternalKey)?.agentId,
);
const targetAgentId = requestedAgentId ? normalizeAgentId(requestedAgentId) : requesterAgentId;
if (targetAgentId !== requesterAgentId) {
const allowAgents = resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents ?? [];
const allowAny = allowAgents.some((value) => value.trim() === "*");
const normalizedTargetId = targetAgentId.toLowerCase();
const allowSet = new Set(
allowAgents
.filter((value) => value.trim() && value.trim() !== "*")
.map((value) => normalizeAgentId(value).toLowerCase()),
);
if (!allowAny && !allowSet.has(normalizedTargetId)) {
const allowedText = allowSet.size > 0 ? Array.from(allowSet).join(", ") : "none";
return {
status: "forbidden",
error: `agentId is not allowed for sessions_spawn (allowed: ${allowedText})`,
};
}
}
const childSessionKey = `agent:${targetAgentId}:subagent:${crypto.randomUUID()}`;
const childDepth = callerDepth + 1;
const spawnedByKey = requesterInternalKey;
const targetAgentConfig = resolveAgentConfig(cfg, targetAgentId);
const runtimeDefaultModel = resolveDefaultModelForAgent({
cfg,
agentId: targetAgentId,
});
const resolvedModel =
normalizeModelSelection(modelOverride) ??
normalizeModelSelection(targetAgentConfig?.subagents?.model) ??
normalizeModelSelection(cfg.agents?.defaults?.subagents?.model) ??
normalizeModelSelection(cfg.agents?.defaults?.model?.primary) ??
normalizeModelSelection(`${runtimeDefaultModel.provider}/${runtimeDefaultModel.model}`);
const resolvedThinkingDefaultRaw =
readStringParam(targetAgentConfig?.subagents ?? {}, "thinking") ??
readStringParam(cfg.agents?.defaults?.subagents ?? {}, "thinking");
let thinkingOverride: string | undefined;
const thinkingCandidateRaw = thinkingOverrideRaw || resolvedThinkingDefaultRaw;
if (thinkingCandidateRaw) {
const normalized = normalizeThinkLevel(thinkingCandidateRaw);
if (!normalized) {
const { provider, model } = splitModelRef(resolvedModel);
const hint = formatThinkingLevels(provider, model);
return {
status: "error",
error: `Invalid thinking level "${thinkingCandidateRaw}". Use one of: ${hint}.`,
};
}
thinkingOverride = normalized;
}
try {
await callGateway({
method: "sessions.patch",
params: { key: childSessionKey, spawnDepth: childDepth },
timeoutMs: 10_000,
});
} catch (err) {
const messageText =
err instanceof Error ? err.message : typeof err === "string" ? err : "error";
return {
status: "error",
error: messageText,
childSessionKey,
};
}
if (resolvedModel) {
try {
await callGateway({
method: "sessions.patch",
params: { key: childSessionKey, model: resolvedModel },
timeoutMs: 10_000,
});
modelApplied = true;
} catch (err) {
const messageText =
err instanceof Error ? err.message : typeof err === "string" ? err : "error";
const recoverable =
messageText.includes("invalid model") || messageText.includes("model not allowed");
if (!recoverable) {
return {
status: "error",
error: messageText,
childSessionKey,
};
}
modelWarning = messageText;
}
}
if (thinkingOverride !== undefined) {
try {
await callGateway({
method: "sessions.patch",
params: {
key: childSessionKey,
thinkingLevel: thinkingOverride === "off" ? null : thinkingOverride,
},
timeoutMs: 10_000,
});
} catch (err) {
const messageText =
err instanceof Error ? err.message : typeof err === "string" ? err : "error";
return {
status: "error",
error: messageText,
childSessionKey,
};
}
}
const childSystemPrompt = buildSubagentSystemPrompt({
requesterSessionKey,
requesterOrigin,
childSessionKey,
label: label || undefined,
task,
childDepth,
maxSpawnDepth,
});
const childIdem = crypto.randomUUID();
let childRunId: string = childIdem;
try {
const response = await callGateway<{ runId: string }>({
method: "agent",
params: {
message: task,
sessionKey: childSessionKey,
channel: requesterOrigin?.channel,
to: requesterOrigin?.to ?? undefined,
accountId: requesterOrigin?.accountId ?? undefined,
threadId: requesterOrigin?.threadId != null ? String(requesterOrigin.threadId) : undefined,
idempotencyKey: childIdem,
deliver: false,
lane: AGENT_LANE_SUBAGENT,
extraSystemPrompt: childSystemPrompt,
thinking: thinkingOverride,
timeout: runTimeoutSeconds,
label: label || undefined,
spawnedBy: spawnedByKey,
groupId: ctx.agentGroupId ?? undefined,
groupChannel: ctx.agentGroupChannel ?? undefined,
groupSpace: ctx.agentGroupSpace ?? undefined,
},
timeoutMs: 10_000,
});
if (typeof response?.runId === "string" && response.runId) {
childRunId = response.runId;
}
} catch (err) {
const messageText =
err instanceof Error ? err.message : typeof err === "string" ? err : "error";
return {
status: "error",
error: messageText,
childSessionKey,
runId: childRunId,
};
}
registerSubagentRun({
runId: childRunId,
childSessionKey,
requesterSessionKey: requesterInternalKey,
requesterOrigin,
requesterDisplayKey,
task,
cleanup,
label: label || undefined,
model: resolvedModel,
runTimeoutSeconds,
});
return {
status: "accepted",
childSessionKey,
runId: childRunId,
modelApplied: resolvedModel ? modelApplied : undefined,
warning: modelWarning,
};
}

View File

@@ -1,25 +1,9 @@
import { Type } from "@sinclair/typebox";
import crypto from "node:crypto";
import type { GatewayMessageChannel } from "../../utils/message-channel.js";
import type { AnyAgentTool } from "./common.js";
import { formatThinkingLevels, normalizeThinkLevel } from "../../auto-reply/thinking.js";
import { loadConfig } from "../../config/config.js";
import { callGateway } from "../../gateway/call.js";
import { normalizeAgentId, parseAgentSessionKey } from "../../routing/session-key.js";
import { normalizeDeliveryContext } from "../../utils/delivery-context.js";
import { resolveAgentConfig } from "../agent-scope.js";
import { AGENT_LANE_SUBAGENT } from "../lanes.js";
import { resolveDefaultModelForAgent } from "../model-selection.js";
import { optionalStringEnum } from "../schema/typebox.js";
import { buildSubagentSystemPrompt } from "../subagent-announce.js";
import { getSubagentDepthFromSessionStore } from "../subagent-depth.js";
import { countActiveRunsForSession, registerSubagentRun } from "../subagent-registry.js";
import { spawnSubagentDirect } from "../subagent-spawn.js";
import { jsonResult, readStringParam } from "./common.js";
import {
resolveDisplaySessionKey,
resolveInternalSessionKey,
resolveMainSessionAlias,
} from "./sessions-helpers.js";
const SessionsSpawnToolSchema = Type.Object({
task: Type.String(),
@@ -33,36 +17,6 @@ const SessionsSpawnToolSchema = Type.Object({
cleanup: optionalStringEnum(["delete", "keep"] as const),
});
function splitModelRef(ref?: string) {
if (!ref) {
return { provider: undefined, model: undefined };
}
const trimmed = ref.trim();
if (!trimmed) {
return { provider: undefined, model: undefined };
}
const [provider, model] = trimmed.split("/", 2);
if (model) {
return { provider, model };
}
return { provider: undefined, model: trimmed };
}
function normalizeModelSelection(value: unknown): string | undefined {
if (typeof value === "string") {
const trimmed = value.trim();
return trimmed || undefined;
}
if (!value || typeof value !== "object") {
return undefined;
}
const primary = (value as { primary?: unknown }).primary;
if (typeof primary === "string" && primary.trim()) {
return primary.trim();
}
return undefined;
}
export function createSessionsSpawnTool(opts?: {
agentSessionKey?: string;
agentChannel?: GatewayMessageChannel;
@@ -91,14 +45,7 @@ export function createSessionsSpawnTool(opts?: {
const thinkingOverrideRaw = readStringParam(params, "thinking");
const cleanup =
params.cleanup === "keep" || params.cleanup === "delete" ? params.cleanup : "keep";
const requesterOrigin = normalizeDeliveryContext({
channel: opts?.agentChannel,
accountId: opts?.agentAccountId,
to: opts?.agentTo,
threadId: opts?.agentThreadId,
});
// Default to 0 (no timeout) when omitted. Sub-agent runs are long-lived
// by default and should not inherit the main agent 600s timeout.
// Back-compat: older callers used timeoutSeconds for this tool.
const timeoutSecondsCandidate =
typeof params.runTimeoutSeconds === "number"
? params.runTimeoutSeconds
@@ -108,234 +55,32 @@ export function createSessionsSpawnTool(opts?: {
const runTimeoutSeconds =
typeof timeoutSecondsCandidate === "number" && Number.isFinite(timeoutSecondsCandidate)
? Math.max(0, Math.floor(timeoutSecondsCandidate))
: 0;
let modelWarning: string | undefined;
let modelApplied = false;
: undefined;
const cfg = loadConfig();
const { mainKey, alias } = resolveMainSessionAlias(cfg);
const requesterSessionKey = opts?.agentSessionKey;
const requesterInternalKey = requesterSessionKey
? resolveInternalSessionKey({
key: requesterSessionKey,
alias,
mainKey,
})
: alias;
const requesterDisplayKey = resolveDisplaySessionKey({
key: requesterInternalKey,
alias,
mainKey,
});
const callerDepth = getSubagentDepthFromSessionStore(requesterInternalKey, { cfg });
const maxSpawnDepth = cfg.agents?.defaults?.subagents?.maxSpawnDepth ?? 1;
if (callerDepth >= maxSpawnDepth) {
return jsonResult({
status: "forbidden",
error: `sessions_spawn is not allowed at this depth (current depth: ${callerDepth}, max: ${maxSpawnDepth})`,
});
}
const maxChildren = cfg.agents?.defaults?.subagents?.maxChildrenPerAgent ?? 5;
const activeChildren = countActiveRunsForSession(requesterInternalKey);
if (activeChildren >= maxChildren) {
return jsonResult({
status: "forbidden",
error: `sessions_spawn has reached max active children for this session (${activeChildren}/${maxChildren})`,
});
}
const requesterAgentId = normalizeAgentId(
opts?.requesterAgentIdOverride ?? parseAgentSessionKey(requesterInternalKey)?.agentId,
const result = await spawnSubagentDirect(
{
task,
label: label || undefined,
agentId: requestedAgentId,
model: modelOverride,
thinking: thinkingOverrideRaw,
runTimeoutSeconds,
cleanup,
},
{
agentSessionKey: opts?.agentSessionKey,
agentChannel: opts?.agentChannel,
agentAccountId: opts?.agentAccountId,
agentTo: opts?.agentTo,
agentThreadId: opts?.agentThreadId,
agentGroupId: opts?.agentGroupId,
agentGroupChannel: opts?.agentGroupChannel,
agentGroupSpace: opts?.agentGroupSpace,
requesterAgentIdOverride: opts?.requesterAgentIdOverride,
},
);
const targetAgentId = requestedAgentId
? normalizeAgentId(requestedAgentId)
: requesterAgentId;
if (targetAgentId !== requesterAgentId) {
const allowAgents = resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents ?? [];
const allowAny = allowAgents.some((value) => value.trim() === "*");
const normalizedTargetId = targetAgentId.toLowerCase();
const allowSet = new Set(
allowAgents
.filter((value) => value.trim() && value.trim() !== "*")
.map((value) => normalizeAgentId(value).toLowerCase()),
);
if (!allowAny && !allowSet.has(normalizedTargetId)) {
const allowedText = allowAny
? "*"
: allowSet.size > 0
? Array.from(allowSet).join(", ")
: "none";
return jsonResult({
status: "forbidden",
error: `agentId is not allowed for sessions_spawn (allowed: ${allowedText})`,
});
}
}
const childSessionKey = `agent:${targetAgentId}:subagent:${crypto.randomUUID()}`;
const childDepth = callerDepth + 1;
const spawnedByKey = requesterInternalKey;
const targetAgentConfig = resolveAgentConfig(cfg, targetAgentId);
const runtimeDefaultModel = resolveDefaultModelForAgent({
cfg,
agentId: targetAgentId,
});
const resolvedModel =
normalizeModelSelection(modelOverride) ??
normalizeModelSelection(targetAgentConfig?.subagents?.model) ??
normalizeModelSelection(cfg.agents?.defaults?.subagents?.model) ??
normalizeModelSelection(cfg.agents?.defaults?.model?.primary) ??
normalizeModelSelection(`${runtimeDefaultModel.provider}/${runtimeDefaultModel.model}`);
const resolvedThinkingDefaultRaw =
readStringParam(targetAgentConfig?.subagents ?? {}, "thinking") ??
readStringParam(cfg.agents?.defaults?.subagents ?? {}, "thinking");
let thinkingOverride: string | undefined;
const thinkingCandidateRaw = thinkingOverrideRaw || resolvedThinkingDefaultRaw;
if (thinkingCandidateRaw) {
const normalized = normalizeThinkLevel(thinkingCandidateRaw);
if (!normalized) {
const { provider, model } = splitModelRef(resolvedModel);
const hint = formatThinkingLevels(provider, model);
return jsonResult({
status: "error",
error: `Invalid thinking level "${thinkingCandidateRaw}". Use one of: ${hint}.`,
});
}
thinkingOverride = normalized;
}
try {
await callGateway({
method: "sessions.patch",
params: { key: childSessionKey, spawnDepth: childDepth },
timeoutMs: 10_000,
});
} catch (err) {
const messageText =
err instanceof Error ? err.message : typeof err === "string" ? err : "error";
return jsonResult({
status: "error",
error: messageText,
childSessionKey,
});
}
if (resolvedModel) {
try {
await callGateway({
method: "sessions.patch",
params: { key: childSessionKey, model: resolvedModel },
timeoutMs: 10_000,
});
modelApplied = true;
} catch (err) {
const messageText =
err instanceof Error ? err.message : typeof err === "string" ? err : "error";
const recoverable =
messageText.includes("invalid model") || messageText.includes("model not allowed");
if (!recoverable) {
return jsonResult({
status: "error",
error: messageText,
childSessionKey,
});
}
modelWarning = messageText;
}
}
if (thinkingOverride !== undefined) {
try {
await callGateway({
method: "sessions.patch",
params: {
key: childSessionKey,
thinkingLevel: thinkingOverride === "off" ? null : thinkingOverride,
},
timeoutMs: 10_000,
});
} catch (err) {
const messageText =
err instanceof Error ? err.message : typeof err === "string" ? err : "error";
return jsonResult({
status: "error",
error: messageText,
childSessionKey,
});
}
}
const childSystemPrompt = buildSubagentSystemPrompt({
requesterSessionKey,
requesterOrigin,
childSessionKey,
label: label || undefined,
task,
childDepth,
maxSpawnDepth,
});
const childIdem = crypto.randomUUID();
let childRunId: string = childIdem;
try {
const response = await callGateway<{ runId: string }>({
method: "agent",
params: {
message: task,
sessionKey: childSessionKey,
channel: requesterOrigin?.channel,
to: requesterOrigin?.to ?? undefined,
accountId: requesterOrigin?.accountId ?? undefined,
threadId:
requesterOrigin?.threadId != null ? String(requesterOrigin.threadId) : undefined,
idempotencyKey: childIdem,
deliver: false,
lane: AGENT_LANE_SUBAGENT,
extraSystemPrompt: childSystemPrompt,
thinking: thinkingOverride,
timeout: runTimeoutSeconds,
label: label || undefined,
spawnedBy: spawnedByKey,
groupId: opts?.agentGroupId ?? undefined,
groupChannel: opts?.agentGroupChannel ?? undefined,
groupSpace: opts?.agentGroupSpace ?? undefined,
},
timeoutMs: 10_000,
});
if (typeof response?.runId === "string" && response.runId) {
childRunId = response.runId;
}
} catch (err) {
const messageText =
err instanceof Error ? err.message : typeof err === "string" ? err : "error";
return jsonResult({
status: "error",
error: messageText,
childSessionKey,
runId: childRunId,
});
}
registerSubagentRun({
runId: childRunId,
childSessionKey,
requesterSessionKey: requesterInternalKey,
requesterOrigin,
requesterDisplayKey,
task,
cleanup,
label: label || undefined,
model: resolvedModel,
runTimeoutSeconds,
});
return jsonResult({
status: "accepted",
childSessionKey,
runId: childRunId,
modelApplied: resolvedModel ? modelApplied : undefined,
warning: modelWarning,
});
return jsonResult(result);
},
};
}