feat(subagents): add model-facing delegation control plane

docs/agent-profile-schema.md

@@ -5,6 +5,16 @@ frontmatter. They describe roles such as reviewer, explorer, or implementer.
 The internal on-demand `devspace-agentd` process owns provider invocation. The
 CLI and MCP server use it as clients when they need agent execution.
 
+When subagents are enabled, DevSpace also exposes provider-neutral MCP tools:
+`agent_targets`, `agent_spawn`, `agent_send`, `agent_status`, `agent_wait`,
+`agent_cancel`, and `agent_list`. Codex, Claude, OpenCode, Pi, and ACP-backed local
+agents receive a project-scoped copy of this control plane so they can perform
+bounded recursive or cross-provider delegation. Provider-native session ids
+remain internal. Child authority is monotonic: `read_only < allowed <
+full_access`, and a child cannot request a mode above its caller. Injected child
+control planes use a daemon-signed capability, so changing environment variables
+cannot widen workspace scope or write authority.
+
 When subagents are enabled, the internal `devspace-agentd` process owns the
 durable agent manager and live provider runtimes. `devspace agents run` is a
 thin local client that starts or reuses the daemon automatically; `devspace

package.json

@@ -72,6 +72,7 @@
     "react": "^19.2.6",
     "react-dom": "^19.2.6",
     "semver": "^7.8.4",
+    "typebox": "1.1.38",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },

skills/subagents/SKILL.md

@@ -5,6 +5,12 @@ description: Delegate focused coding, research, review, or verification work to
 
 # DevSpace subagents
 
+When the host exposes `agent_targets`, `agent_spawn`, `agent_send`, `agent_status`,
+`agent_wait`, `agent_cancel`, and `agent_list` directly, prefer those tools.
+They use the same durable agent manager as the CLI below, avoid shell parsing,
+and keep provider-native session ids internal. Use the CLI as the fallback
+surface when those tools are not available.
+
 Subagents are optional. Use the normal workspace tools for routine work; delegate only when a separate worker materially helps through independent context, specialization, or follow-up.
 
 Run the DevSpace CLI through the shell or process tool from the project the subagent should use. Agent commands print compact XML fragments by default. Read that output directly. Do not add `--json`.
@@ -68,6 +74,10 @@ devspace agents stop <id>
 
 Stopping is scoped to the current project and preserves the durable agent record as `stopped`.
 
+Child agents that receive the scoped DevSpace agent MCP can delegate again.
+Their child `write_mode` can be equal to or less permissive than their own
+authority, never more permissive.
+
 ## Good uses
 
 - Review a change for correctness, security, or missing tests.

src/cli.ts

@@ -24,6 +24,9 @@ import {
   parseLocalAgentRunArgs,
 } from "./local-agent-targets.js";
 import { createLocalAgentClient } from "./local-agent-client.js";
+import { runLocalAgentMcpStdio } from "./local-agent-mcp-server.js";
+import { verifyLocalAgentMcpCapability } from "./local-agent-mcp-capability.js";
+import { ensureLocalAgentDaemonSecret, localAgentDaemonPaths } from "./local-agent-daemon-lifecycle.js";
 import { toAgentErrorPayload, type LocalAgentError } from "./local-agent-errors.js";
 import {
   formatAgentCommandError,
@@ -551,6 +554,9 @@ async function runAgentsCommand(args: string[]): Promise<void> {
     case "targets":
       await runAgentWorkflowCommand(json, () => runAgentsTargets(commandArgs, json));
       return;
+    case "mcp":
+      await runAgentsMcp(commandArgs);
+      return;
     case "daemon":
       await runAgentsDaemon(commandArgs, json);
       return;
@@ -565,6 +571,26 @@ async function runAgentsCommand(args: string[]): Promise<void> {
   }
 }
 
+async function runAgentsMcp(args: string[]): Promise<void> {
+  if (args.length > 0) throw new Error("Usage: devspace agents mcp");
+  const config = loadConfig();
+  const token = requiredAgentMcpEnv("DEVSPACE_AGENT_MCP_CAPABILITY");
+  const secret = ensureLocalAgentDaemonSecret(localAgentDaemonPaths(config.stateDir));
+  const capability = verifyLocalAgentMcpCapability(secret, token);
+  await runLocalAgentMcpStdio(config, {
+    parentAgentId: capability.parentAgentId,
+    workspaceId: capability.workspaceId,
+    workspaceRoot: capability.workspaceRoot,
+    maxWriteMode: capability.maxWriteMode,
+  });
+}
+
+function requiredAgentMcpEnv(name: string): string {
+  const value = process.env[name]?.trim();
+  if (!value) throw new Error(`Missing ${name} for DevSpace agent MCP server.`);
+  return value;
+}
+
 async function runAgentsTargets(args: string[], json: boolean): Promise<void> {
   if (args.length > 0) throw new Error("Usage: devspace agents targets [--json]");
   const config = loadConfig();

src/local-agent-acp.test.ts

@@ -64,6 +64,9 @@ const runtime = new AcpRuntime({
 }, connection);
 
 const firstResult = await runtime.run({
+  agentId: "agt_cursor",
+  workspaceId: "ws_cursor",
+  mcpCapability: "cap_cursor",
   prompt: "first",
   workspaceRoot: "/tmp/project",
   model: "model-a",
@@ -99,6 +102,13 @@ assert.equal(
   Object.hasOwn(requests.find(({ method }) => method === "session/new")?.params as object, "additionalDirectories"),
   false,
 );
+const newSessionParams = requests.find(({ method }) => method === "session/new")?.params as {
+  mcpServers?: Array<{ name: string; env: Array<{ name: string; value: string }> }>;
+};
+assert.equal(newSessionParams.mcpServers?.[0]?.name, "devspace-agents-agt_cursor");
+assert.ok(newSessionParams.mcpServers?.[0]?.env.some((entry) => (
+  entry.name === "DEVSPACE_AGENT_MCP_CAPABILITY" && entry.value === "cap_cursor"
+)));
 
 await runtime.releaseSession("cursor_session_1");
 assert.equal(queues.has("cursor_session_1"), false);

src/local-agent-acp.ts

@@ -9,6 +9,7 @@ import {
   isProgrammerDefect,
 } from "./local-agent-errors.js";
 import { bindLocalAgentAbort, localAgentCancelledError } from "./local-agent-cancellation.js";
+import { localAgentMcpLaunch } from "./local-agent-mcp-launch.js";
 import { terminateProcessTree } from "./process-platform.js";
 import { DEVSPACE_VERSION } from "./version.js";
 import {
@@ -249,6 +250,13 @@ export class AcpRuntime implements LocalAgentRuntime {
   }
 
   private async openSession(input: LocalAgentRunInput, callbacks?: LocalAgentRunCallbacks): Promise<string> {
+    const mcp = localAgentMcpLaunch(input);
+    const mcpServers = mcp ? [{
+      name: mcp.name,
+      command: mcp.command,
+      args: mcp.args,
+      env: Object.entries(mcp.env).map(([name, value]) => ({ name, value })),
+    }] : [];
     if (input.providerSessionId) {
       if (this.liveSessions.has(input.providerSessionId)) {
         this.sessionWriteModes.set(input.providerSessionId, input.writeMode ?? "allowed");
@@ -273,7 +281,7 @@ export class AcpRuntime implements LocalAgentRuntime {
       const response = await this.connection.agent.request("session/resume", {
         sessionId: input.providerSessionId,
         cwd: input.workspaceRoot,
-        mcpServers: [],
+        mcpServers,
         ...this.additionalDirectoryParams(),
       });
       this.cacheSessionMetadata(input.providerSessionId, response);
@@ -287,7 +295,7 @@ export class AcpRuntime implements LocalAgentRuntime {
 
     const response = await this.connection.agent.request("session/new", {
       cwd: input.workspaceRoot,
-      mcpServers: [],
+      mcpServers,
       ...this.additionalDirectoryParams(),
     });
     const sessionId = readString(response, "sessionId");

src/local-agent-claude.test.ts

@@ -15,6 +15,7 @@ class FakeClaudeQuery implements ClaudeQueryLike, AsyncIterator<unknown> {
   model?: string;
   permissionModes: string[] = [];
   flagSettings: Array<Record<string, unknown>> = [];
+  mcpServerUpdates: Array<Record<string, unknown>> = [];
 
   constructor(prompt: AsyncIterable<ClaudeUserMessage>) {
     this.iterator = prompt[Symbol.asyncIterator]();
@@ -43,6 +44,10 @@ class FakeClaudeQuery implements ClaudeQueryLike, AsyncIterator<unknown> {
 
   async interrupt(): Promise<void> {}
 
+  async setMcpServers(servers: Record<string, unknown>): Promise<void> {
+    this.mcpServerUpdates.push(servers);
+  }
+
   async setPermissionMode(mode: string): Promise<void> {
     this.permissionModes.push(mode);
   }
@@ -58,6 +63,8 @@ class FakeClaudeQuery implements ClaudeQueryLike, AsyncIterator<unknown> {
 
 const context: LocalAgentRuntimeContext = {
   agentId: "agt_claude",
+  workspaceId: "ws_claude",
+  mcpCapability: "cap_claude",
   providerInstanceId: "claude",
   provider: "claude",
   workspaceRoot: "/tmp/project",
@@ -73,7 +80,7 @@ const driver = new ClaudeLocalAgentDriver(({ prompt, options }) => {
   lastOptions = options;
   query = new FakeClaudeQuery(prompt);
   return query;
-}, { PATH: "/usr/bin" });
+}, { PATH: "/usr/bin", DEVSPACE_CONFIG_DIR: "/tmp/devspace-config" });
 assert.deepEqual(driver.runtimePolicy, {
   scope: "agent",
   authority: "full_access_boundary",
@@ -100,6 +107,7 @@ const first = firstResult.value;
 const secondResult = await runtime.run({
   prompt: "second",
   workspaceRoot: "/tmp/project",
+  mcpCapability: "cap_claude_allowed",
   effort: "low",
   writeMode: "allowed",
 });
@@ -120,7 +128,18 @@ assert.equal(query?.model, "sonnet");
 assert.equal(lastOptions?.resume, undefined);
 assert.equal(lastOptions?.permissionMode, "dontAsk");
 assert.equal(lastOptions?.allowDangerouslySkipPermissions, undefined);
-assert.deepEqual(lastOptions?.allowedTools, ["Read(/**)", "Edit(/**)", "Bash"]);
+assert.deepEqual(lastOptions?.allowedTools, [
+  "Read(/**)",
+  "Edit(/**)",
+  "Bash",
+  "mcp__devspace-agents-agt_claude__*",
+]);
+const mcpServers = lastOptions?.mcpServers as Record<string, Record<string, unknown>>;
+assert.equal(mcpServers["devspace-agents-agt_claude"]?.type, "stdio");
+assert.deepEqual(mcpServers["devspace-agents-agt_claude"]?.env, {
+  DEVSPACE_CONFIG_DIR: "/tmp/devspace-config",
+  DEVSPACE_AGENT_MCP_CAPABILITY: "cap_claude",
+});
 assert.equal(lastOptions?.pathToClaudeCodeExecutable, undefined);
 const initialSandbox = lastOptions?.sandbox as Record<string, unknown>;
 assert.equal(initialSandbox.enabled, true);
@@ -160,6 +179,16 @@ assert.equal(
   "dontAsk",
 );
 assert.equal(query?.flagSettings[1]?.effortLevel, "low");
+assert.equal(
+  ((query?.mcpServerUpdates[0]?.["devspace-agents-agt_claude"] as Record<string, unknown>)?.env as Record<string, string>)
+    ?.DEVSPACE_AGENT_MCP_CAPABILITY,
+  "cap_claude_allowed",
+);
+assert.equal(
+  ((query?.mcpServerUpdates[1]?.["devspace-agents-agt_claude"] as Record<string, unknown>)?.env as Record<string, string>)
+    ?.DEVSPACE_AGENT_MCP_CAPABILITY,
+  "cap_claude",
+);
 assert.equal(
   ((query?.flagSettings[1]?.permissions as Record<string, unknown>).deny as string[]).includes("Edit"),
   false,
@@ -210,6 +239,7 @@ const brokenStreamQuery: ClaudeQueryLike = {
   },
   close() {},
   async interrupt() {},
+  async setMcpServers() {},
   async setPermissionMode() {},
   async applyFlagSettings() {},
 };

src/local-agent-claude.ts

@@ -6,6 +6,7 @@ import {
   isProgrammerDefect,
 } from "./local-agent-errors.js";
 import { bindLocalAgentAbort, localAgentCancelledError } from "./local-agent-cancellation.js";
+import { localAgentMcpLaunch, localAgentMcpLaunchFromContext } from "./local-agent-mcp-launch.js";
 import type { LocalAgentDriverKind } from "./local-agent-provider.js";
 import type {
   LocalAgentDriver,
@@ -30,6 +31,7 @@ const CLAUDE_WORKSPACE_ALLOWED_TOOLS = [
 export interface ClaudeQueryLike extends AsyncIterable<unknown> {
   close(): void;
   interrupt(): Promise<void>;
+  setMcpServers(servers: Record<string, unknown>): Promise<unknown>;
   setPermissionMode(mode: ClaudePermissionMode): Promise<void>;
   applyFlagSettings(settings: Record<string, unknown>): Promise<void>;
   setModel?(model?: string): Promise<void>;
@@ -84,13 +86,16 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
   private alive = true;
   private closed = false;
   private providerSessionId?: string;
+  private currentMcpCapability?: string;
 
   constructor(
     private readonly query: ClaudeQueryLike,
     private readonly inputQueue: AsyncInputQueue<ClaudeUserMessage>,
-    context: LocalAgentRuntimeContext,
+    private readonly context: LocalAgentRuntimeContext,
+    private readonly env: NodeJS.ProcessEnv,
   ) {
     this.providerSessionId = context.providerSessionId;
+    this.currentMcpCapability = context.mcpCapability;
     this.iterator = query[Symbol.asyncIterator]();
   }
 
@@ -111,6 +116,23 @@ export class ClaudeQueryRuntime implements LocalAgentRuntime {
         const removeAbort = bindLocalAgentAbort(input.signal, () => this.query.interrupt());
         try {
         if (this.providerSessionId) await callbacks?.onSessionId?.(this.providerSessionId);
+        const mcp = localAgentMcpLaunch({
+          ...input,
+          agentId: input.agentId ?? this.context.agentId,
+          workspaceId: input.workspaceId ?? this.context.workspaceId,
+          mcpCapability: input.mcpCapability ?? this.context.mcpCapability,
+        }, this.env);
+        if (mcp && mcp.env.DEVSPACE_AGENT_MCP_CAPABILITY !== this.currentMcpCapability) {
+          await this.query.setMcpServers({
+            [mcp.name]: {
+              type: "stdio",
+              command: mcp.command,
+              args: mcp.args,
+              env: mcp.env,
+            },
+          });
+          this.currentMcpCapability = mcp.env.DEVSPACE_AGENT_MCP_CAPABILITY;
+        }
         const flagSettings = claudeAuthoritySettings(input.workspaceRoot, input.writeMode);
         if (input.effort) {
           Object.assign(flagSettings, {
@@ -261,7 +283,7 @@ export class ClaudeLocalAgentDriver implements LocalAgentDriver {
           options: claudeQueryOptions(context, input, this.env),
           prompt: inputQueue,
         });
-        return new ClaudeQueryRuntime(query, inputQueue, context);
+        return new ClaudeQueryRuntime(query, inputQueue, context, this.env);
       },
     });
   }
@@ -284,6 +306,7 @@ export function claudeQueryOptions(
   env: NodeJS.ProcessEnv = process.env,
 ): Record<string, unknown> {
   const executable = env.CLAUDE_COMMAND;
+  const mcp = localAgentMcpLaunchFromContext(context, env);
   const permissionMode = claudePermissionMode(input.writeMode);
   const authority = claudeAuthorityOptions(input.workspaceRoot, input.writeMode);
   return {
@@ -294,9 +317,31 @@ export function claudeQueryOptions(
     permissionMode,
     // Restricted runtimes stay warm across read_only/allowed turns. Keep the
     // workspace capabilities static and narrow individual turns with deny rules.
-    ...(input.writeMode === "full_access"
+    ...(input.writeMode === "full_access" && !mcp
       ? {}
-      : { allowedTools: [...CLAUDE_WORKSPACE_ALLOWED_TOOLS] }),
+      : {
+          allowedTools: [
+            ...(input.writeMode === "full_access" ? [] : CLAUDE_WORKSPACE_ALLOWED_TOOLS),
+            ...(mcp ? [`mcp__${mcp.name}__*`] : []),
+          ],
+        }),
+    ...(mcp
+      ? {
+          mcpServers: {
+            [mcp.name]: {
+              type: "stdio",
+              command: mcp.command,
+              args: mcp.args,
+              env: mcp.env,
+            },
+          },
+          systemPrompt: {
+            type: "preset",
+            preset: "claude_code",
+            append: "Use the DevSpace agent MCP tools for bounded delegation when separate context or specialization materially helps. Discover targets before spawning; prefer waiting over polling; never request child authority above your current mode.",
+          },
+        }
+      : {}),
     sandbox: authority.sandbox,
     settings: authority.settings,
     ...(input.writeMode === "full_access" ? { allowDangerouslySkipPermissions: true } : {}),