agent-relay-server 0.20.0 → 0.22.0

package/src/mcp.ts

@@ -9,22 +9,30 @@ import { bytesToStream, readBodyBytes } from "./http-body";
 import { MAX_BODY_BYTES, VERSION } from "./config";
 import { getManagedAgentState, getSpawnPolicy, listSpawnPolicies } from "./config-store";
 import {
+  countLiveSpawnedAgents,
   createArtifact,
   createActivityEvent,
   getAgent,
   getArtifact,
   getMessage,
   getOrchestrator,
+  getRepoSteward,
   getTask,
   getThread,
+  getWorkspace,
   linkArtifact,
   listAgents,
+  listWorkspaces,
+  searchAgents,
+  type AgentSearchFilter,
+  type AgentSearchSort,
   listArtifactsForEntity,
   listOrchestrators,
   sendMessageWithResult,
   upsertArtifactBlob,
   ValidationError,
 } from "./db";
+import { planSend, type DeliveryReceipt } from "./agent-ref";
 import { emitRelayEvent } from "./events";
 import { emitMessageQueued, emitNewMessage } from "./sse";
 import {
@@ -35,10 +43,12 @@ import {
   isComponentAuthorizedFor,
   isIntegrationAllowed,
 } from "./security";
-import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider } from "./types";
+import type { ActivityKind, AgentCard, ArtifactKind, ArtifactSensitivity, AttachmentRef, Command, SendMessageInput, Message, SpawnApprovalMode, SpawnProvider, WorkspaceMergeStrategy, WorkspaceRecord } from "./types";
+import { applyWorkspaceAction, waitForWorkspaceStatus, type WorkspaceAction } from "./workspace-actions";
+import { describeWorkspacePhase, landReceipt, readyContract, TERMINAL_WORKSPACE_STATUSES, worktreeMcpInstructions } from "./workspace-phase";
 import { type ProviderEffort } from "agent-relay-sdk/provider-catalog";
 import { errMessage, isRecord, SPAWN_PROVIDERS, APPROVAL_MODES, VALID_EFFORTS } from "agent-relay-sdk";
-import { childRunnerRuntimeTokenEnv, runnerRuntimeTokenEnv } from "./runtime-tokens";
+import { runnerRuntimeTokenEnv } from "./runtime-tokens";
 
 type JsonRpcId = string | number | null;
 
@@ -62,6 +72,12 @@ type ToolDefinition = {
   description: string;
   requiredScopes: string[];
   inputSchema: Record<string, unknown>;
+  // Emit `_meta: { "anthropic/alwaysLoad": true }` in tools/list so Claude Code
+  // (v2.1.121+) loads this tool's schema EAGERLY instead of deferring it behind a
+  // ToolSearch round-trip. Reserve for the few verbs most agents use every session
+  // (the doc warns each one costs context every turn). Verified convention; same
+  // mechanism callmux's per-tool alwaysLoad uses.
+  alwaysLoad?: boolean;
 };
 
 const MCP_PROTOCOL_VERSION = "2024-11-05";
@@ -75,13 +91,13 @@ const VALID_ARTIFACT_ENTITY_TYPES = ["message", "task", "recipeRun", "recipeStep
 const TOOLS: ToolDefinition[] = [
   {
     name: "relay_send_message",
-    description: "Send an Agent Relay message with structured fields instead of shell quoting.",
+    description: "Send an Agent Relay message. Returns a delivery receipt (delivered/expectReply/recipients): if expectReply is false, no live recipient exists — don't wait for a reply. Unknown or ambiguous targets are rejected up front, never silently dropped.",
     requiredScopes: ["messages:write", "message:send"],
     inputSchema: {
       type: "object",
       properties: {
-        from: { type: "string", description: "Sender Relay agent id." },
-        to: { type: "string", description: "Target agent id, label, tag:, cap:, policy:, or broadcast." },
+        from: { type: "string", description: "Deprecated/optional. Your identity is taken from your auth token; ignored for managed agents. You never need to set this." },
+        to: { type: "string", description: "Target: an agent id, label, name, or a unique id segment (e.g. the number part) — resolved automatically. Or a fan-out selector: tag:, cap:, label:, policy:, or broadcast." },
         body: { type: "string" },
         subject: { type: "string" },
         channel: { type: "string" },
@@ -91,18 +107,18 @@ const TOOLS: ToolDefinition[] = [
         payload: { type: "object" },
         meta: { type: "object" },
       },
-      required: ["from", "to", "body"],
+      required: ["to", "body"],
       additionalProperties: false,
     },
   },
   {
     name: "relay_reply",
-    description: "Reply to an Agent Relay message by id, preserving reply/thread/channel context.",
+    description: "Reply to an Agent Relay message by id, preserving reply/thread/channel context. Returns a delivery receipt; expectReply:false means the original sender is no longer reachable.",
     requiredScopes: ["messages:write", "message:send"],
     inputSchema: {
       type: "object",
       properties: {
-        from: { type: "string", description: "Sender Relay agent id." },
+        from: { type: "string", description: "Deprecated/optional. Your identity is taken from your auth token; ignored for managed agents. You never need to set this." },
         messageId: { type: "integer", minimum: 1 },
         body: { type: "string" },
         subject: { type: "string" },
@@ -111,7 +127,7 @@ const TOOLS: ToolDefinition[] = [
         payload: { type: "object" },
         meta: { type: "object" },
       },
-      required: ["from", "messageId", "body"],
+      required: ["messageId", "body"],
       additionalProperties: false,
     },
   },
@@ -184,7 +200,7 @@ const TOOLS: ToolDefinition[] = [
   },
   {
     name: "relay_agent_status",
-    description: "Inspect Relay agent, orchestrator, and managed spawn-policy status.",
+    description: "Inspect Relay agent, orchestrator, and managed spawn-policy status. The default agent list shows only RUNNING agents (the ones you can actually message/reply/pair with); pass includeOffline:true for the full roster.",
     requiredScopes: ["agents:read", "agent:read"],
     inputSchema: {
       type: "object",
@@ -192,14 +208,47 @@ const TOOLS: ToolDefinition[] = [
         agentId: { type: "string" },
         policyName: { type: "string" },
         orchestratorId: { type: "string" },
+        includeOffline: { type: "boolean", description: "Include offline/stale agents in the default list (default false)." },
       },
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_find_agents",
+    description: "Search the fleet for agents by label, capability, provider, tag, machine, status, or kind, sorted by last-active/created/label. Defaults to running agents only. Use this to find a reachable, capable peer before messaging or pairing — instead of dumping the whole roster.",
+    requiredScopes: ["agents:read", "agent:read"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        label: { type: "string", description: "Substring match on label or name." },
+        capability: { type: ["string", "array"], items: { type: "string" }, description: "One or more capabilities (OR within)." },
+        provider: { type: ["string", "array"], items: { type: "string" }, description: "Model provider, e.g. claude or codex." },
+        tag: { type: ["string", "array"], items: { type: "string" } },
+        machine: { type: ["string", "array"], items: { type: "string" } },
+        kind: { type: ["string", "array"], items: { type: "string" } },
+        status: { type: ["string", "array"], items: { type: "string" }, description: "online/idle/busy/offline/stale, the 'running' shorthand, or 'all'. Default 'running'." },
+        spawnedBy: { type: "string", description: "Parent agent id, or 'me' for your own spawned children (#221)." },
+        sortBy: { type: "string", enum: ["lastActive", "created", "label"] },
+        order: { type: "string", enum: ["asc", "desc"] },
+        limit: { type: "integer", minimum: 1, maximum: 200 },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_whoami",
+    description: "Return your own Relay identity and agent card (id, label, status, tags, capabilities). Your identity comes from your auth token — you do NOT need this to send, reply, or pair; use it only when you need to reason about yourself.",
+    requiredScopes: ["mcp:use"],
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
   {
     name: "relay_spawn_agent",
-    description: "Request a provider agent spawn through Relay's orchestrator command bus.",
-    requiredScopes: ["agents:write", "agent:write"],
+    description: "Spawn a long-living provider agent through Relay's orchestrator. Gated: requires the command:spawn scope, granted only to agents whose profile sets maxSpawnedAgents>0, up to that live-children quota. Spawned agents cannot themselves spawn (no grandchildren).",
+    requiredScopes: ["command:spawn"],
     inputSchema: {
       type: "object",
       properties: {
@@ -212,6 +261,7 @@ const TOOLS: ToolDefinition[] = [
         approvalMode: { type: "string", enum: APPROVAL_MODES },
         prompt: { type: "string" },
         systemPromptAppend: { type: "string" },
+        profile: { type: "string", description: "Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota)." },
         tags: { type: "array", items: { type: "string" } },
         capabilities: { type: "array", items: { type: "string" } },
         providerArgs: { type: "array", items: { type: "string" } },
@@ -224,8 +274,8 @@ const TOOLS: ToolDefinition[] = [
   },
   {
     name: "relay_shutdown_agent",
-    description: "Request an agent shutdown through Relay's orchestrator command bus.",
-    requiredScopes: ["agents:write", "agent:write"],
+    description: "Shut down an agent through Relay's orchestrator. Gated: requires the command:shutdown scope; an agent caller may only target its OWN live spawned children. Admin tokens keep full reach.",
+    requiredScopes: ["command:shutdown"],
     inputSchema: {
       type: "object",
       properties: {
@@ -240,6 +290,108 @@ const TOOLS: ToolDefinition[] = [
       additionalProperties: false,
     },
   },
+  {
+    name: "relay_workspace_status",
+    description: "Get your isolated workspace's lifecycle status (active/ready/conflict/review_requested/merged/...). With wait:true this BLOCKS until the status changes — use it after relay_workspace_ready to wait for the auto-merge to land your branch on main (status leaves 'ready' → merged/recycled-to-active with a fresh rebased branch) or to surface a conflict/review_requested the steward couldn't auto-resolve. Defaults to the workspace you own; pass workspaceId to target another.",
+    requiredScopes: ["agents:read", "agent:read", "agent:write"],
+    alwaysLoad: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace (resolved from your identity)." },
+        wait: { type: "boolean", description: "Block until the workspace status changes (the actionable signal), or until the timeout." },
+        timeoutSeconds: { type: "integer", minimum: 1, maximum: 600, description: "Max seconds to wait when wait:true (default 300, max 600). Returns early on any transition." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_ready",
+    description: "Signal that your branch work is finished and ready to merge back to main. This kicks off the auto-merge-back: a clean merge lands immediately; on conflict a steward agent reconciles and lands it (escalating if it can't). After this, poll relay_workspace_status with wait:true until it lands and you get a fresh rebased branch to continue on. Defaults to your own workspace.",
+    requiredScopes: ["agent:write"],
+    alwaysLoad: true,
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
+        detail: { type: "string", description: "Optional note recorded on the activity feed." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_deps",
+    description: "Re-provision your worktree's dependencies when the shared symlinked node_modules has gone stale (e.g. typecheck reports a missing module). checkOnly:true just reports staleness without changing anything. Self-service — acts only on your own worktree.",
+    requiredScopes: ["agent:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
+        checkOnly: { type: "boolean", description: "Report staleness only; do not re-provision." },
+        detail: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_list",
+    description: "List the isolated workspaces you own (id, branch, status, repo). Use it when you're unsure which workspace is yours or to see a workspace's current state. Admin/server tokens may pass all:true to list every workspace.",
+    requiredScopes: ["agents:read", "agent:read", "agent:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        all: { type: "boolean", description: "Admin/server only: list all workspaces, not just your own." },
+        ownerAgentId: { type: "string", description: "Admin/server + all:true: filter to one owner." },
+        repoRoot: { type: "string", description: "Filter to one repository root." },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_claim",
+    description: "Take a TTL'd steward claim on a workspace so the deterministic auto-merge yields to you while you reconcile a conflict. Renew/hold while validating; relay_workspace_release frees it. Owner or assigned steward only.",
+    requiredScopes: ["agent:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
+        purpose: { type: "string", description: "Why you're claiming (shown in the activity feed)." },
+        detail: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_release",
+    description: "Release a steward claim taken with relay_workspace_claim, letting the auto-merge resume. Owner or assigned steward only.",
+    requiredScopes: ["agent:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
+        purpose: { type: "string" },
+        detail: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "relay_workspace_land",
+    description: "Dispatch a base merge for your workspace directly (lease-serialized per repo, same path the auto-merge job uses). Most branch agents should use relay_workspace_ready instead and let the relay land it; this is the explicit/steward path and requires the command:write scope.",
+    requiredScopes: ["command:write"],
+    inputSchema: {
+      type: "object",
+      properties: {
+        workspaceId: { type: "string", description: "Defaults to your own isolated workspace." },
+        strategy: { type: "string", enum: ["pr", "rebase-ff", "auto"], description: "Merge strategy (default auto)." },
+        deleteBranch: { type: "boolean", description: "Delete the branch after a successful merge (default true)." },
+        prTitle: { type: "string" },
+        prBody: { type: "string" },
+        detail: { type: "string" },
+      },
+      additionalProperties: false,
+    },
+  },
 ];
 
 export async function postMcp(req: Request): Promise<Response> {
@@ -257,10 +409,14 @@ export async function postMcp(req: Request): Promise<Response> {
     }
 
     if (method === "initialize") {
+      // Mode-tailored primer (#214 §3): surface the worktree merge-back map only
+      // to callers that own an isolated worktree; shared-workspace agents omit it.
+      const worktree = callerIsolatedWorkspace(auth);
       return Response.json(jsonRpcResult(id, {
         protocolVersion: MCP_PROTOCOL_VERSION,
         capabilities: { tools: {} },
         serverInfo: { name: "agent-relay", title: "Agent Relay", version: VERSION },
+        ...(worktree ? { instructions: worktreeMcpInstructions(worktree) } : {}),
       }));
     }
     if (method === "notifications/initialized") {
@@ -327,8 +483,17 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
     else if (name === "relay_upload_artifact") result = await relayUploadArtifact(auth, args);
     else if (name === "relay_attach_artifact") result = relayAttachArtifact(auth, args);
     else if (name === "relay_agent_status") result = relayAgentStatus(args);
+    else if (name === "relay_find_agents") result = relayFindAgents(auth, args);
+    else if (name === "relay_whoami") result = relayWhoami(auth);
     else if (name === "relay_spawn_agent") result = relaySpawnAgent(auth, args);
     else if (name === "relay_shutdown_agent") result = relayShutdownAgent(auth, args);
+    else if (name === "relay_workspace_status") result = await relayWorkspaceStatus(auth, args);
+    else if (name === "relay_workspace_list") result = relayWorkspaceList(auth, args);
+    else if (name === "relay_workspace_ready") result = relayWorkspaceMutation(auth, "ready", args);
+    else if (name === "relay_workspace_deps") result = relayWorkspaceMutation(auth, "deps-refresh", args);
+    else if (name === "relay_workspace_claim") result = relayWorkspaceMutation(auth, "claim", args);
+    else if (name === "relay_workspace_release") result = relayWorkspaceMutation(auth, "release-claim", args);
+    else if (name === "relay_workspace_land") result = relayWorkspaceMutation(auth, "merge", args);
     else throw new ValidationError(`unknown tool: ${name}`);
 
     auditToolCall(auth, name, "ok", result);
@@ -340,12 +505,67 @@ async function callTool(auth: McpAuthContext, params: unknown): Promise<Record<s
   }
 }
 
-function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>): Message {
+// A managed/runtime MCP token is minted with `constraints.agents = [its own agent id]`
+// (see issueMcpRuntimeToken). That single allowed agent IS the caller's identity, and the
+// security layer already treats it as the only `from` this token may use. Derive it so
+// agents never need to know — or type — their own id.
+function senderIdentity(auth: McpAuthContext): string | undefined {
+  if (auth.kind !== "component") return undefined;
+  const agents = auth.component?.constraints?.agents;
+  return agents?.length === 1 ? agents[0] : undefined;
+}
+
+// Caller's own agent id for spawn/shutdown gating (#221). `senderIdentity` covers
+// identity-bearing tokens (interactive/mcp, constraints.agents). Managed agents spawned by
+// the orchestrator authenticate with a runner token that carries no `agents` constraint but
+// DOES carry its spawnRequestId/policy — resolve those back to the registered agent card.
+// Returns undefined for server/admin tokens (unrestricted by design).
+function callerAgentId(auth: McpAuthContext): string | undefined {
+  const direct = senderIdentity(auth);
+  if (direct) return direct;
+  if (auth.kind !== "component") return undefined;
+  const c = auth.component?.constraints;
+  const spawnRequestId = c?.spawnRequestIds?.length === 1 ? c.spawnRequestIds[0] : undefined;
+  const policyName = c?.policies?.length === 1 ? c.policies[0] : undefined;
+  if (!spawnRequestId && !policyName) return undefined;
+  const match = listAgents().find((a) =>
+    (spawnRequestId !== undefined && a.meta?.spawnRequestId === spawnRequestId) ||
+    (policyName !== undefined && a.meta?.policyName === policyName));
+  return match?.id;
+}
+
+function resolveSender(auth: McpAuthContext, rawFrom: unknown): string {
+  // Token identity wins and cannot be spoofed; any provided `from` is ignored when known.
+  const identity = senderIdentity(auth);
+  if (identity) return identity;
+  // Server/integration/multi-agent tokens carry no single identity — keep requiring `from`.
+  return stringField(rawFrom, "from", { required: true, max: 200 });
+}
+
+function relayWhoami(auth: McpAuthContext): Record<string, unknown> {
+  const agentId = senderIdentity(auth);
+  const agent = agentId ? getAgent(agentId) : null;
+  return {
+    agentId: agentId ?? null,
+    actor: auth.actor,
+    kind: auth.kind,
+    scopes: auth.scopes,
+    agent: agent ?? null,
+  };
+}
+
+function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>): Message & { delivery: DeliveryReceipt } {
   const attachments = optionalAttachments(args.attachments);
   const payload = payloadWithAttachments(optionalRecord(args.payload, "payload"), attachments);
+  const requestedTo = stringField(args.to, "to", { required: true, max: 200 });
+  // Resolve the target to a canonical agent id (so poll-time matching works) and refuse
+  // up front when it's unknown or ambiguous — never store a message no one will receive.
+  const plan = planSend(requestedTo, listAgents());
+  if (plan.kind === "not_found") throw new McpNotFoundError(plan.message);
+  if (plan.kind === "ambiguous") throw new ValidationError(plan.message);
   const input: SendMessageInput = {
-    from: stringField(args.from, "from", { required: true, max: 200 }),
-    to: stringField(args.to, "to", { required: true, max: 200 }),
+    from: resolveSender(auth, args.from),
+    to: plan.to,
     body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
     subject: optionalString(args.subject, "subject", 200),
     channel: optionalString(args.channel, "channel", 120),
@@ -359,10 +579,10 @@ function relaySendMessage(auth: McpAuthContext, args: Record<string, unknown>):
   assertComponentResourceAllowed(auth, { scope: "message:send", resource: { target: input.to, channel: input.channel, agentId: input.from } });
   const result = sendMessageWithResult(input);
   emitMessage(result.message, result.created);
-  return result.message;
+  return { ...result.message, delivery: plan.receipt };
 }
 
-function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Message {
+function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Message & { delivery: DeliveryReceipt } {
   const messageId = positiveId(args.messageId, "messageId");
   const parent = getMessage(messageId);
   if (!parent) throw new McpNotFoundError(`message ${messageId} not found`);
@@ -375,7 +595,7 @@ function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Messag
     ...replyContext(parent),
   }, attachments);
   const input: SendMessageInput = {
-    from: stringField(args.from, "from", { required: true, max: 200 }),
+    from: resolveSender(auth, args.from),
     to: parent.from,
     body: stringField(args.body, "body", { required: true, maxBytes: MAX_BODY_BYTES }),
     subject: optionalString(args.subject, "subject", 200),
@@ -389,7 +609,13 @@ function relayReply(auth: McpAuthContext, args: Record<string, unknown>): Messag
   assertComponentResourceAllowed(auth, { scope: "message:send", resource: { target: input.to, channel: input.channel, agentId: input.from } });
   const result = sendMessageWithResult(input);
   emitMessage(result.message, result.created);
-  return result.message;
+  // Reply routing is fixed to the parent's sender — never reject, but report whether
+  // that original sender is still reachable so the agent doesn't wait forever.
+  const plan = planSend(input.to, listAgents());
+  const delivery: DeliveryReceipt = plan.kind === "not_found" || plan.kind === "ambiguous"
+    ? { delivered: false, expectReply: false, recipients: [], reason: "original sender no longer reachable" }
+    : plan.receipt;
+  return { ...result.message, delivery };
 }
 
 function relayGetMessage(args: Record<string, unknown>): Record<string, unknown> {
@@ -490,13 +716,49 @@ function relayAgentStatus(args: Record<string, unknown>): Record<string, unknown
     if (!orchestrator) throw new McpNotFoundError(`orchestrator ${orchestratorId} not found`);
     return { orchestrator };
   }
+  // Default to running agents only — offline/stale rows are pure noise (you can only
+  // message/reply/pair with a live agent) and bloat the payload. includeOffline opts back in.
+  const includeOffline = optionalBoolean(args.includeOffline, "includeOffline") === true;
   return {
-    agents: listAgents(),
+    agents: searchAgents({ status: includeOffline ? "all" : "running" }),
     spawnPolicies: listSpawnPolicies().map((entry) => policyStatusPayload(entry.value)),
     orchestrators: listOrchestrators(),
   };
 }
 
+function optionalStringOrArray(value: unknown, field: string): string | string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    return value.map((item, i) => stringField(item, `${field}[${i}]`, { required: true, max: 200 }));
+  }
+  throw new ValidationError(`${field} must be a string or string array`);
+}
+
+function relayFindAgents(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  // `spawnedBy: "me"` resolves to the caller's own id — list the children you spawned (#221).
+  const spawnedByArg = optionalString(args.spawnedBy, "spawnedBy", 240);
+  const spawnedBy = spawnedByArg === "me" ? callerAgentId(auth) ?? "\0unresolved" : spawnedByArg;
+  const filter: AgentSearchFilter = {
+    label: optionalString(args.label, "label", 200),
+    capability: optionalStringOrArray(args.capability, "capability"),
+    provider: optionalStringOrArray(args.provider, "provider"),
+    tag: optionalStringOrArray(args.tag, "tag"),
+    machine: optionalStringOrArray(args.machine, "machine"),
+    kind: optionalStringOrArray(args.kind, "kind"),
+    spawnedBy,
+    // Default to running — you can only act on a live agent (consistent with #218).
+    status: optionalStringOrArray(args.status, "status") ?? "running",
+  };
+  const sort: AgentSearchSort = {
+    sortBy: optionalEnum(args.sortBy, "sortBy", ["lastActive", "created", "label"] as const),
+    order: optionalEnum(args.order, "order", ["asc", "desc"] as const),
+    limit: optionalPositiveInt(args.limit, "limit"),
+  };
+  const agents = searchAgents(filter, sort);
+  return { agents, count: agents.length };
+}
+
 function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
   const provider = enumField(args.provider, "provider", SPAWN_PROVIDERS) as SpawnProvider;
   const cwd = optionalString(args.cwd, "cwd", 500);
@@ -510,28 +772,43 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
   const spawnRequestId = optionalString(args.spawnRequestId, "spawnRequestId", 160) ?? generateSpawnRequestId();
   const label = optionalString(args.label, "label", 120);
   const policyName = optionalString(args.policyName, "policyName", 120);
+  const profile = optionalString(args.profile, "profile", 120);
+
+  // #221 runtime gate (belt; the coarse `command:spawn` scope is enforced in callTool, and is
+  // granted only to agents whose profile sets maxSpawnedAgents>0 and never to children).
+  // Server/admin tokens have no caller identity → unrestricted by design.
+  const callerId = callerAgentId(auth);
+  if (callerId) {
+    const me = getAgent(callerId);
+    if (me?.spawnedBy) {
+      throw new McpAuthError("spawned agents cannot spawn further agents (no grandchildren)");
+    }
+    const quota = auth.component?.constraints?.maxSpawnedAgents ?? 0;
+    const live = countLiveSpawnedAgents(callerId);
+    if (live >= quota) {
+      throw new ValidationError(`spawn quota reached (${live}/${quota} live children) — shut one down or wait for one to exit`);
+    }
+  }
+
   assertComponentResourceAllowed(auth, {
     scope: "agent:write",
     resource: { orchestratorId: orchestrator.id, cwd: resolvedCwd, policyName, spawnRequestId },
   });
-  const env = auth.component?.role === "provider"
-    ? childRunnerEnvForDelegatingComponent(auth, {
-      orchestratorId: orchestrator.id,
-      cwd: resolvedCwd,
-      provider,
-      label,
-      policyName,
-      spawnRequestId,
-    })
-    : runnerRuntimeTokenEnv({
-      orchestratorId: orchestrator.id,
-      cwd: resolvedCwd,
-      provider,
-      label,
-      policyName,
-      spawnRequestId,
-      createdBy: auth.actor,
-    });
+
+  // Child runner token: a normal long-living agent that is NOT itself spawn-capable
+  // (canSpawn:false → no grandchildren), stamped with authoritative lineage so it registers
+  // with spawnedBy = caller (the child can't forge it; it's read from the signed token).
+  const env = runnerRuntimeTokenEnv({
+    orchestratorId: orchestrator.id,
+    cwd: resolvedCwd,
+    provider,
+    label,
+    policyName,
+    spawnRequestId,
+    createdBy: callerId ?? auth.actor,
+    canSpawn: false,
+    ...(callerId ? { spawnedBy: callerId } : {}),
+  });
   const command = createCommand({
     type: "agent.spawn",
     source: "system",
@@ -542,6 +819,7 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
       modelParams: selection,
       cwd: resolvedCwd,
       label,
+      profile: profile || undefined,
       tags: optionalStringArray(args.tags, "tags") ?? [],
       capabilities: optionalStringArray(args.capabilities, "capabilities") ?? [],
       approvalMode,
@@ -562,34 +840,6 @@ function relaySpawnAgent(auth: McpAuthContext, args: Record<string, unknown>): R
   return { ok: true, orchestratorId: orchestrator.id, provider, command };
 }
 
-function childRunnerEnvForDelegatingComponent(
-  auth: McpAuthContext,
-  input: {
-    orchestratorId: string;
-    cwd: string;
-    provider: SpawnProvider;
-    label?: string;
-    policyName?: string;
-    spawnRequestId: string;
-  },
-): Record<string, string> {
-  const component = auth.component;
-  if (!component) throw new McpAuthError("component token required for child-agent delegation");
-  if (component.constraints?.canDelegate !== true) {
-    throw new McpAuthError("component token cannot delegate child agents");
-  }
-  return childRunnerRuntimeTokenEnv({
-    parentAgentId: component.sub,
-    orchestratorId: input.orchestratorId,
-    cwd: input.cwd,
-    provider: input.provider,
-    label: input.label,
-    policyName: input.policyName,
-    spawnRequestId: input.spawnRequestId,
-    createdBy: component.sub,
-  });
-}
-
 function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
   const agentId = optionalString(args.agentId, "agentId", 240);
   const policyName = optionalString(args.policyName, "policyName", 120);
@@ -598,6 +848,21 @@ function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>)
   if (!agentId && !policyName && !spawnRequestId && !tmuxSession) {
     throw new ValidationError("agentId, policyName, spawnRequestId, or tmuxSession required");
   }
+
+  // #221: an agent caller may only shut down its OWN live spawned children, addressed by
+  // agentId. Broad targeting (policy/spawnRequestId/tmux) and cross-agent kills stay admin-only
+  // — otherwise spawn permission silently becomes kill-anyone permission. Server/admin tokens
+  // (no caller identity) keep full reach.
+  const callerId = callerAgentId(auth);
+  if (callerId) {
+    if (!agentId || policyName || spawnRequestId || tmuxSession) {
+      throw new McpAuthError("agents may only shut down their own spawned children, addressed by agentId");
+    }
+    const target = getAgent(agentId);
+    if (!target || target.spawnedBy !== callerId) {
+      throw new McpAuthError(`agent ${agentId} is not one of your spawned children`);
+    }
+  }
   const orchestrator = selectControlOrchestrator({
     orchestratorId: optionalString(args.orchestratorId, "orchestratorId", 200),
     agentId,
@@ -630,6 +895,119 @@ function relayShutdownAgent(auth: McpAuthContext, args: Record<string, unknown>)
   return { ok: true, action: "shutdown", orchestratorId: orchestrator.id, command };
 }
 
+// --- Workspace lifecycle tools (#215) -------------------------------------
+// Thin MCP surface over the shared applyWorkspaceAction core. Coarse scope is
+// enforced in callTool; here we add the resource check the routes' authorizeRoute
+// does: an agent may only act on a workspace it OWNS or stewards (server/wildcard
+// tokens keep full reach). Defaults the target to the caller's own workspace so a
+// branch agent never has to hunt for its workspace id.
+
+function isWorkspaceAdmin(auth: McpAuthContext): boolean {
+  return auth.kind === "server" || hasScope(auth, "*");
+}
+
+function assertWorkspaceAccess(auth: McpAuthContext, ws: WorkspaceRecord, caller: string | undefined): void {
+  if (isWorkspaceAdmin(auth)) return;
+  if (!caller) throw new McpAuthError(`not authorized for workspace ${ws.id} (its owner or assigned steward only)`);
+  if (caller === ws.ownerAgentId) return;
+  // The repo's elected steward (authoritative repo_stewards record, not the mirrored
+  // workspace column which only updates on steward change) may reconcile any
+  // workspace in its repo — the conflict-landing flow it exists for.
+  if (caller === getRepoSteward(ws.repoRoot)?.stewardAgentId) return;
+  throw new McpAuthError(`not authorized for workspace ${ws.id} (its owner or assigned steward only)`);
+}
+
+function resolveWorkspaceForCaller(auth: McpAuthContext, args: Record<string, unknown>): WorkspaceRecord {
+  const explicitId = optionalString(args.workspaceId, "workspaceId", 240);
+  const caller = callerAgentId(auth);
+  if (explicitId) {
+    const ws = getWorkspace(explicitId);
+    if (!ws) throw new McpNotFoundError(`workspace ${explicitId} not found`);
+    assertWorkspaceAccess(auth, ws, caller);
+    return ws;
+  }
+  if (!caller) throw new ValidationError("workspaceId is required: no caller agent identity to resolve your own workspace");
+  const first = callerIsolatedWorkspace(auth);
+  if (!first) throw new McpNotFoundError("you don't own an isolated workspace; pass workspaceId");
+  return first;
+}
+
+// Non-throwing variant for the initialize primer: the caller's most recently
+// active isolated worktree, or undefined (no caller identity / shared-only).
+// listWorkspaces is ORDER BY updated_at DESC → most recent worktree first.
+function callerIsolatedWorkspace(auth: McpAuthContext): WorkspaceRecord | undefined {
+  const caller = callerAgentId(auth);
+  if (!caller) return undefined;
+  return listWorkspaces({ ownerAgentId: caller }).find((w) => w.mode === "isolated" && !TERMINAL_WORKSPACE_STATUSES.has(w.status));
+}
+
+async function relayWorkspaceStatus(auth: McpAuthContext, args: Record<string, unknown>): Promise<Record<string, unknown>> {
+  const ws = resolveWorkspaceForCaller(auth, args);
+  if (optionalBoolean(args.wait, "wait") !== true) {
+    return { workspace: ws, guidance: describeWorkspacePhase(ws), transitioned: false, timedOut: false };
+  }
+  const timeoutSeconds = optionalPositiveInt(args.timeoutSeconds, "timeoutSeconds");
+  const result = await waitForWorkspaceStatus(ws.id, timeoutSeconds ? { timeoutMs: timeoutSeconds * 1000 } : {});
+  if (!result.workspace) throw new McpNotFoundError(`workspace ${ws.id} not found`);
+  const landed = result.transitioned ? landReceipt(result.fromStatus, result.workspace) : null;
+  return {
+    workspace: result.workspace,
+    guidance: describeWorkspacePhase(result.workspace),
+    ...(landed ? { landed } : {}),
+    fromStatus: result.fromStatus,
+    transitioned: result.transitioned,
+    timedOut: result.timedOut,
+  };
+}
+
+function relayWorkspaceList(auth: McpAuthContext, args: Record<string, unknown>): Record<string, unknown> {
+  const filter: { ownerAgentId?: string; repoRoot?: string } = {};
+  const repoRoot = optionalString(args.repoRoot, "repoRoot", 1024);
+  if (repoRoot) filter.repoRoot = repoRoot;
+  if (isWorkspaceAdmin(auth) && optionalBoolean(args.all, "all") === true) {
+    const owner = optionalString(args.ownerAgentId, "ownerAgentId", 240);
+    if (owner) filter.ownerAgentId = owner;
+  } else {
+    const caller = callerAgentId(auth);
+    if (!caller) throw new ValidationError("no caller agent identity to list your workspaces");
+    filter.ownerAgentId = caller;
+  }
+  const workspaces = listWorkspaces(filter);
+  return { workspaces, count: workspaces.length };
+}
+
+function relayWorkspaceMutation(auth: McpAuthContext, action: WorkspaceAction, args: Record<string, unknown>): Record<string, unknown> {
+  const ws = resolveWorkspaceForCaller(auth, args);
+  const result = applyWorkspaceAction(ws, {
+    action,
+    agentId: callerAgentId(auth) ?? auth.actor,
+    detail: optionalString(args.detail, "detail", 4000),
+    strategy: action === "merge" ? (optionalEnum(args.strategy, "strategy", ["pr", "rebase-ff", "auto"] as const) as WorkspaceMergeStrategy | undefined) : undefined,
+    deleteBranch: action === "merge" ? optionalBoolean(args.deleteBranch, "deleteBranch") : undefined,
+    prTitle: optionalString(args.prTitle, "prTitle", 240),
+    prBody: optionalString(args.prBody, "prBody", 8000),
+    purpose: optionalString(args.purpose, "purpose", 120),
+    checkOnly: action === "deps-refresh" ? optionalBoolean(args.checkOnly, "checkOnly") === true : undefined,
+    auditMetadata: { via: "mcp", actor: auth.actor },
+  });
+  if (!result.ok) {
+    if (result.httpStatus === 404) throw new McpNotFoundError(result.error);
+    if (result.httpStatus === 403) throw new McpAuthError(result.error);
+    throw new ValidationError(result.error);
+  }
+  if (result.command) emitCommand(result.command);
+  const payload: Record<string, unknown> = { workspace: result.workspace };
+  if (result.command) payload.command = result.command;
+  if (result.claim !== undefined) payload.claim = result.claim;
+  // After a `ready` hand-off, state the whole contract up front + the directive
+  // next-step, so the agent doesn't decode status enums over the next minutes (#235).
+  if (action === "ready") {
+    payload.contract = readyContract(result.workspace);
+    payload.guidance = describeWorkspacePhase(result.workspace);
+  }
+  return payload;
+}
+
 function replyContext(parent: Message): Record<string, unknown> {
   const parentPayload = parent.payload ?? {};
   if (parentPayload.schema !== "agent-relay.channel.v1" && !parentPayload.conversation) return {};
@@ -793,7 +1171,12 @@ function emitMessage(message: Message, created: boolean): void {
 function visibleTools(auth: McpAuthContext): Array<Record<string, unknown>> {
   return TOOLS
     .filter((tool) => hasAnyScope(auth, tool.requiredScopes))
-    .map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));
+    .map(({ name, description, inputSchema, alwaysLoad }) => ({
+      name,
+      description,
+      inputSchema,
+      ...(alwaysLoad ? { _meta: { "anthropic/alwaysLoad": true } } : {}),
+    }));
 }
 
 function toolResult(result: unknown): Record<string, unknown> {