@zgeoff/atc 2.11.0 → 2.12.0

package/src/daemon/target-access.ts

@@ -0,0 +1,36 @@
+/**
+ * A target a session runs on, as the name it holds and the identity the
+ * session is bound to there.
+ */
+export interface TargetGrant {
+  readonly target: string;
+  readonly targetIdentity: string;
+}
+
+/**
+ * The targets a principal may use, each as a name and an identity: a
+ * session on a granted name whose identity differs is outside the grant.
+ */
+export class TargetAccess {
+  private readonly grants: ReadonlyMap<string, TargetGrant>;
+
+  constructor(grants: readonly TargetGrant[]) {
+    this.grants = new Map(grants.map((grant) => [buildGrantKey(grant), grant]));
+  }
+
+  canUse(grant: TargetGrant): boolean {
+    return this.grants.has(buildGrantKey(grant));
+  }
+
+  /**
+   * The grants both accesses hold, so a principal on a narrowed connection
+   * never reaches past the connection.
+   */
+  merge(other: TargetAccess): TargetAccess {
+    return new TargetAccess([...this.grants.values()].filter((grant) => other.canUse(grant)));
+  }
+}
+
+function buildGrantKey(grant: TargetGrant): string {
+  return JSON.stringify([grant.target, grant.targetIdentity]);
+}

package/src/mcp/answer-mcp-request.ts

@@ -4,6 +4,7 @@ import type { GrantScope } from '../shared/grant-scope';
 import { normalizeClientName } from '../shared/normalize-client-name';
 import { isRecord } from '../shared/report';
 import { answerRPCRequest } from './answer-rpc-request';
+import { buildPrincipalCaller } from './build-principal-caller';
 import { deriveTokenHash } from './derive-token-hash';
 import { findClientName } from './find-client-name';
 import { isSupportedProtocolVersion } from './is-supported-protocol-version';
@@ -21,7 +22,8 @@ interface MCPHTTPRequest {
  * database, so a revoked grant loses access at once, and a token bound to any
  * other resource is refused. A tool call outside the token's scopes is a 403
  * that names the missing scope. A message the client sends is always from the
- * client's own name.
+ * client's own name, and every request acts as the client's id, so the
+ * daemon limits it to the targets that principal may use.
  */
 export async function answerMCPRequest(
   ctx: HTTPServerContext,
@@ -65,7 +67,7 @@ export async function answerMCPRequest(
   }
 
   const outcome = await answerRPCRequest(message, {
-    caller: ctx.caller,
+    caller: buildPrincipalCaller(ctx.caller, access.clientID),
     build: ctx.build,
     toolContext: { callerSessionID: null, sender: { kind: 'fixed', name: access.clientName } },
     scopes: access.scopes,
@@ -95,12 +97,13 @@ export async function answerMCPRequest(
 }
 
 interface VerifiedAccess {
+  readonly clientID: string;
   readonly clientName: string;
   readonly scopes: readonly GrantScope[];
 }
 
-// An inactive, unknown, or revoked token, or one bound to another resource,
-// verifies to null. Verifying stamps when the token's grant was last used.
+// An inactive, unknown, or revoked token, one bound to another resource, or
+// one without a client id verifies to null. Verifying stamps when the token's grant was last used.
 async function verifyAccessToken(
   ctx: HTTPServerContext,
   token: string,
@@ -124,11 +127,16 @@ async function verifyAccessToken(
   const granted = typeof payload['scope'] === 'string' ? payload['scope'].split(' ') : [];
   const clientID = typeof payload['client_id'] === 'string' ? payload['client_id'] : '';
 
+  if (clientID === '') {
+    return null;
+  }
+
   await upsertGrantUse(ctx, token);
 
   const storedName = await findClientName(ctx.store.db, clientID);
 
   return {
+    clientID,
     clientName: normalizeClientName(storedName, 'remote'),
     scopes: GRANT_SCOPES.filter((scope) => granted.includes(scope)),
   };

package/src/mcp/answer-rpc-request.ts

@@ -1,7 +1,9 @@
 import { match } from 'ts-pattern';
+import { z } from 'zod';
 import { DaemonError } from '../protocol/daemon-error';
 import type { GrantScope } from '../shared/grant-scope';
 import { isRecord } from '../shared/report';
+import type { RegisteredAgent } from './build-spawn-descriptions';
 import { buildToolList } from './build-tool-list';
 import { MCP_TOOLS } from './mcp-tools';
 import { pickProtocolVersion } from './pick-protocol-version';
@@ -60,9 +62,11 @@ export async function answerRPCRequest(message: unknown, deps: RPCDeps): Promise
     .with('tools/list', async () => {
       const features = await deps.caller.readFeatures();
 
+      const agents = features.has('agents.list') ? await tryReadAgents(deps) : null;
+
       return {
         kind: 'reply' as const,
-        body: buildRPCResult(id, { tools: buildToolList(features) }),
+        body: buildRPCResult(id, { tools: buildToolList(features, agents) }),
       };
     })
     .with('tools/call', async () => {
@@ -97,6 +101,29 @@ function findMissingScope(
   return scopes.includes(needed) ? null : needed;
 }
 
+// The part of an agents.list answer the spawn descriptions read.
+const ROSTER_AGENT_SCHEMA = z.object({ id: z.string(), installed: z.boolean() });
+const AGENT_ROSTER_SCHEMA = z.object({ agents: z.array(ROSTER_AGENT_SCHEMA) });
+
+// The registered agents, or null when the daemon cannot answer, so the tool
+// list still builds with descriptions that name no agent. A caller without
+// the read scope gets null too, since listing agents is a read.
+async function tryReadAgents(deps: RPCDeps): Promise<RegisteredAgent[] | null> {
+  if (deps.scopes !== undefined && !deps.scopes.includes('read')) {
+    return null;
+  }
+
+  try {
+    const answer = await deps.caller.sendRequest('agents.list');
+
+    const parsed = AGENT_ROSTER_SCHEMA.safeParse(answer);
+
+    return parsed.success ? parsed.data.agents : null;
+  } catch {
+    return null;
+  }
+}
+
 async function answerToolCall(
   deps: RPCDeps,
   params: Readonly<Record<string, unknown>>,

package/src/mcp/build-principal-caller.ts

@@ -0,0 +1,15 @@
+import type { FleetCaller } from './types';
+
+/**
+ * The caller every request of one remote MCP client rides: each request acts
+ * as the client's principal, whatever principal it asked for, and goes only
+ * to a daemon that limits a request to its principal's targets, so a daemon
+ * that would ignore the principal never answers it with the owner's reach.
+ */
+export function buildPrincipalCaller(caller: FleetCaller, principal: string): FleetCaller {
+  return {
+    sendRequest: (m, p, required = []) =>
+      caller.sendRequest(m, p, [...required, 'request.principal'], principal),
+    readFeatures: () => caller.readFeatures(),
+  };
+}

package/src/mcp/build-spawn-descriptions.ts

@@ -0,0 +1,45 @@
+/**
+ * One agent as the spawn descriptions list it: its id and whether its binary
+ * resolves on the daemon's host.
+ */
+export interface RegisteredAgent {
+  readonly id: string;
+  readonly installed: boolean;
+}
+
+interface SpawnDescriptions {
+  readonly tool: string;
+  readonly agent: string;
+}
+
+/**
+ * The `atc_session_spawn` description and its `agent` field description,
+ * naming the agents the daemon registered when the tool list was built. Only
+ * a registered id appears, and a registered agent whose binary is missing is
+ * marked not installed. null leaves every agent unnamed, for a tool list
+ * built while the daemon could not answer. Both point at `atc_agents_list`
+ * for the current list.
+ */
+export function buildSpawnDescriptions(
+  agents: readonly RegisteredAgent[] | null,
+): SpawnDescriptions {
+  const roster =
+    agents === null
+      ? ''
+      : ` When this tool list was built, the host registered: ${formatRoster(agents)}.`;
+
+  return {
+    tool: `Spawn a new session in a directory. Optional agent is a registered agent id; omitted agent is always Claude, never the TUI last-used value.${roster} atc_agents_list returns the current agents, whether each is installed, and the model and effort each takes. An unregistered agent, a registered agent that is not installed, and a model or effort the agent does not take are refused before anything spawns. Called from inside an atc session, the new session is a sub-session of the caller unless detached is true. Returns the new session descriptor. Give it a prompt to start it working immediately.`,
+    agent: `Registered agent id to spawn; defaults to claude.${roster} atc_agents_list returns the current list.`,
+  };
+}
+
+function formatRoster(agents: readonly RegisteredAgent[]): string {
+  if (agents.length === 0) {
+    return 'no agents';
+  }
+
+  return agents
+    .map((agent) => (agent.installed ? agent.id : `${agent.id} (not installed)`))
+    .join(', ');
+}

package/src/mcp/build-tool-list.ts

@@ -1,5 +1,7 @@
 import type { DaemonFeature } from '../protocol/daemon-features';
 import { isRecord } from '../shared/report';
+import { buildSpawnDescriptions } from './build-spawn-descriptions';
+import type { RegisteredAgent } from './build-spawn-descriptions';
 import { MCP_TOOLS } from './mcp-tools';
 
 interface MCPTool {
@@ -19,8 +21,16 @@ interface MCPTool {
  * features. A tool the daemon cannot serve is left out, and a tool it serves
  * in an older form is listed without the output schema and input properties
  * that form lacks, so a client never sees an option the daemon would ignore.
+ * The spawn tool's description and its agent field's description name the
+ * registered agents; null leaves them unnamed. No schema depends on which
+ * agents the host registers or installs.
  */
-export function buildToolList(features: ReadonlySet<DaemonFeature>): readonly MCPTool[] {
+export function buildToolList(
+  features: ReadonlySet<DaemonFeature>,
+  agents: readonly RegisteredAgent[] | null,
+): readonly MCPTool[] {
+  const spawn = buildSpawnDescriptions(agents);
+
   return MCP_TOOLS.flatMap((tool) => {
     const requires = tool.requires ?? {};
 
@@ -28,20 +38,23 @@ export function buildToolList(features: ReadonlySet<DaemonFeature>): readonly MC
       return [];
     }
 
-    const inputSchema = buildInputSchema(tool.inputSchema, requires.inputs ?? {}, features);
+    const gated = buildInputSchema(tool.inputSchema, requires.inputs ?? {}, features);
+    const isSpawn = tool.name === 'atc_session_spawn';
+    const description = isSpawn ? spawn.tool : tool.description;
+    const inputSchema = isSpawn ? buildAgentFieldSchema(gated, spawn.agent) : gated;
 
     return [
       tool.outputSchema === undefined ||
       (requires.output !== undefined && !features.has(requires.output))
         ? {
             name: tool.name,
-            description: tool.description,
+            description,
             inputSchema,
             annotations: tool.annotations,
           }
         : {
             name: tool.name,
-            description: tool.description,
+            description,
             inputSchema,
             outputSchema: tool.outputSchema,
             annotations: tool.annotations,
@@ -72,3 +85,18 @@ function buildInputSchema(
     ),
   };
 }
+
+// The input schema with only the agent field's description replaced.
+function buildAgentFieldSchema(
+  schema: Readonly<Record<string, unknown>>,
+  description: string,
+): Readonly<Record<string, unknown>> {
+  const properties = schema['properties'];
+  const agent = isRecord(properties) ? properties['agent'] : undefined;
+
+  if (!isRecord(properties) || !isRecord(agent)) {
+    return schema;
+  }
+
+  return { ...schema, properties: { ...properties, agent: { ...agent, description } } };
+}

package/src/mcp/mcp-tools.ts

@@ -2,6 +2,8 @@ import { z } from 'zod';
 import type { DaemonFeature } from '../protocol/daemon-features';
 import { REQUEST_PARAM_SCHEMAS } from '../protocol/request-param-schemas';
 import type { GrantScope } from '../shared/grant-scope';
+import { buildSpawnDescriptions } from './build-spawn-descriptions';
+import { IDEMPOTENCY_KEY_FIELD } from './parse-idempotency-key';
 
 const NO_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(z.strictObject({}));
 
@@ -17,14 +19,28 @@ const SESSION_ID_BASE = z.object({
 
 const SESSION_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(SESSION_ID_BASE.strict());
 const SPAWN_SCHEMA = REQUEST_PARAM_SCHEMAS['session.spawn'];
+const SPAWN_AGENT_DESCRIPTION = buildSpawnDescriptions(null).agent;
+
+// The key as a plain JSON Schema property, for an input schema written out
+// by hand.
+const { $schema: _, ...IDEMPOTENCY_KEY_INPUT } = z.toJSONSchema(IDEMPOTENCY_KEY_FIELD, {
+  io: 'input',
+});
 
 const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
   z.strictObject({
     cwd: SPAWN_SCHEMA.shape.cwd.describe('Absolute path of the working directory'),
     name: SPAWN_SCHEMA.shape.name.describe('Session name; defaults to the directory basename'),
     prompt: SPAWN_SCHEMA.shape.prompt.describe('First message for the session'),
-    agent: SPAWN_SCHEMA.shape.agent.describe(
-      'Which registered agent id to spawn; defaults to claude',
+    agent: SPAWN_SCHEMA.shape.agent.describe(SPAWN_AGENT_DESCRIPTION),
+    model: SPAWN_SCHEMA.shape.model.describe(
+      "Model for the new session: an alias or a full model name, at most 200 characters, never starting with '-'. It reaches the agent CLI as its own argument. Refused when the agent takes no model; spawnOptions.model in atc_agents_list holds each agent's support, default, and examples. Omit it to keep the agent's configured default.",
+    ),
+    effort: SPAWN_SCHEMA.shape.effort.describe(
+      "Effort level for the new session, one of the agent's spawnOptions.effort.values in atc_agents_list. Refused when the agent takes no effort. Omit it to keep the agent's configured default.",
+    ),
+    target: SPAWN_SCHEMA.shape.target.describe(
+      'Execution target for the new session, one of the target ids in atc_agents_list. Omit it to run on the default target (spawnDefaults.target). An unknown or unavailable target is refused; atc never runs the session on another target instead.',
     ),
     detached: z
       .boolean()
@@ -32,6 +48,7 @@ const SPAWN_INPUT: Readonly<Record<string, unknown>> = z.toJSONSchema(
       .describe(
         'Spawn a top-level session. By default a spawn from inside an atc session becomes a sub-session of it: listed under it, pinned with it, killed with it.',
       ),
+    idempotencyKey: IDEMPOTENCY_KEY_FIELD,
   }),
   { io: 'input' },
 );
@@ -124,6 +141,27 @@ const MESSAGE_SENT_OUTPUT: Readonly<Record<string, unknown>> = {
   required: ['message', 'status'],
 };
 
+const SPAWN_OPTION_OUTPUT: Readonly<Record<string, unknown>> = {
+  type: 'object',
+  properties: {
+    supported: { type: 'boolean' },
+    available: { type: 'boolean' },
+    values: { type: ['array', 'null'], items: { type: 'string' } },
+    examples: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: { value: { type: 'string' }, resolvesTo: { type: ['string', 'null'] } },
+        required: ['value', 'resolvesTo'],
+      },
+    },
+    default: { type: ['string', 'null'] },
+    backendEffect: { type: ['string', 'null'], enum: ['applied', 'unverified', null] },
+    note: { type: ['string', 'null'] },
+  },
+  required: ['supported', 'available', 'values', 'examples', 'default', 'backendEffect', 'note'],
+};
+
 const AGENTS_OUTPUT: Readonly<Record<string, unknown>> = {
   type: 'object',
   properties: {
@@ -159,8 +197,51 @@ const AGENTS_OUTPUT: Readonly<Record<string, unknown>> = {
             required: ['spawn', 'readTranscript', 'message', 'attach', 'screen', 'input'],
           },
           models: { type: ['object', 'null'], additionalProperties: { type: 'string' } },
+          spawnOptions: {
+            type: 'object',
+            properties: { model: SPAWN_OPTION_OUTPUT, effort: SPAWN_OPTION_OUTPUT },
+            required: ['model', 'effort'],
+          },
         },
-        required: ['id', 'label', 'kind', 'installed', 'capabilities', 'models'],
+        required: ['id', 'label', 'kind', 'installed', 'capabilities', 'models', 'spawnOptions'],
+      },
+    },
+    targets: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'string' },
+          provider: { type: 'string' },
+          identity: { type: 'string' },
+          available: { type: 'boolean' },
+          default: { type: 'boolean' },
+          capabilities: {
+            type: 'object',
+            additionalProperties: { type: 'boolean' },
+          },
+        },
+        required: ['id', 'provider', 'identity', 'available', 'default', 'capabilities'],
+      },
+    },
+    spawnDefaults: {
+      type: 'object',
+      properties: { agent: { type: 'string' }, target: { type: ['string', 'null'] } },
+      required: ['agent', 'target'],
+    },
+    configRevision: { type: 'string' },
+    targetErrors: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          scope: { type: 'string', enum: ['config', 'targets', 'target', 'defaultTarget'] },
+          target: { type: 'string' },
+          problem: { type: 'string' },
+          path: { type: 'string' },
+          detail: { type: 'string' },
+        },
+        required: ['scope', 'problem'],
       },
     },
   },
@@ -264,9 +345,16 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     name: 'atc_session_spawn',
     annotations: AGENT_FACING,
     scope: 'spawn',
-    description:
-      'Spawn a new session in a directory. Optional agent is an agent id the daemon has registered, such as claude, grok, or codex; omitted agent is always Claude, never the TUI last-used value. An unregistered id is rejected. Called from inside an atc session, the new session is a sub-session of the caller unless detached is true. Returns the new session descriptor. Give it a prompt to start it working immediately.',
+    description: buildSpawnDescriptions(null).tool,
     inputSchema: SPAWN_INPUT,
+    requires: {
+      inputs: {
+        model: 'spawn.options',
+        effort: 'spawn.options',
+        idempotencyKey: 'spawn.idempotency',
+        target: 'spawn.target',
+      },
+    },
   },
   {
     name: 'atc_session_input',
@@ -343,10 +431,10 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: READ_ONLY,
     scope: 'read',
     description:
-      "List the agents this atc host can run sessions under, plus the host itself (daemon: hostname, platform, arch, build). Each agent has its id (pass it as atc_session_spawn's agent), label, kind (the agent CLI family it runs), installed (whether its binary resolves on this host; a registered agent that is not installed cannot spawn), capabilities (spawn, readTranscript, message, attach, screen, input), and models: the model names the config sets for it, or null. It never includes credentials, environment values, or endpoints, and holds nothing about which plans or subscriptions an agent's account has.",
+      "List the agents this atc host can run sessions under, plus the host itself (daemon: hostname, platform, arch, build). Each agent has its id (pass it as atc_session_spawn's agent), label, kind (the agent CLI family it runs), installed (whether its binary resolves on this host; a registered agent that is not installed cannot spawn), capabilities (spawn, readTranscript, message, attach, screen, input), models (the model names the config sets for it, or null), and spawnOptions when the daemon supports spawn options. spawnOptions holds model and effort, each with supported (whether atc passes it to the agent CLI), available (whether a spawn on this host can pass it now), values (the accepted set, or null for any alias or model name), examples (each with the provider model it resolves to, when the config maps one), default (the configured value, or null for the CLI's own), backendEffect (applied, or unverified when the backend may ignore it), and a note. atc_session_spawn accepts exactly the available options. When the daemon supports targets, it also returns targets (each with its id, provider kind, identity, available, default, and capabilities), spawnDefaults (the agent and target a spawn without either runs with; a null target means such a spawn is refused), configRevision (a digest that changes whenever the target config does), and targetErrors (config problems that leave a target, or every target, unusable; a config file that exists but cannot be read or parsed is scope config, problem config_malformed or config_unreadable, with its path and detail, and refuses every spawn, local included). It never includes credentials, environment values, or endpoints, and holds nothing about which plans or subscriptions an agent's account has.",
     inputSchema: NO_INPUT,
     outputSchema: AGENTS_OUTPUT,
-    requires: { tool: 'agents.list' },
+    requires: { tool: 'agents.list', output: 'spawn.options' },
   },
   {
     name: 'atc_session_get',
@@ -379,7 +467,7 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
     annotations: AGENT_FACING,
     scope: 'message',
     description:
-      "Send a session a message and get its id back. Follow up with atc_message_get, passing waitMs so each call waits for the next status change instead of polling in a tight loop, until its status is answered; don't read the session's screen or transcript to check on it. The answer is the final output of the session turn that carried the message, and one turn can carry several messages. The message waits in the session inbox until the session takes it, and its status moves accepted, delivered, answered. A message is refused as unsupported when the session's agent has no message tap (Grok, Codex), or when a Claude session reported SessionStart more than 15 seconds ago and no tap has attached since. It is refused as session_dead when the session has no live process and as no_such_session for an unknown id. Otherwise it queues, including while a session restores or after its tap dropped. The message is never typed into the terminal.",
+      "Send a session a message and get its id back. Follow up with atc_message_get, passing waitMs so each call waits for the next status change instead of polling in a tight loop, until its status is answered; don't read the session's screen or transcript to check on it. The answer is the final output of the session turn that carried the message, and one turn can carry several messages. The message waits in the session inbox until the session takes it, and its status moves accepted, delivered, answered. A message is refused as unsupported when the session's agent has no message tap (capabilities.message is false in atc_agents_list), or when a Claude session reported SessionStart more than 15 seconds ago and no tap has attached since. It is refused as session_dead when the session has no live process and as no_such_session for an unknown id. Otherwise it queues, including while a session restores or after its tap dropped. The message is never typed into the terminal.",
     inputSchema: {
       type: 'object',
       properties: {
@@ -390,11 +478,13 @@ export const MCP_TOOLS: readonly MCPToolDefinition[] = [
           description:
             'Who the message is from; defaults to the calling session id, or mcp outside a session. Ignored for a remote client, whose messages are always from its own name',
         },
+        idempotencyKey: IDEMPOTENCY_KEY_INPUT,
       },
       required: ['session', 'text'],
       additionalProperties: false,
     },
     outputSchema: MESSAGE_SENT_OUTPUT,
+    requires: { inputs: { idempotencyKey: 'message.idempotency' } },
   },
   {
     name: 'atc_message_get',

package/src/mcp/parse-idempotency-key.ts

@@ -0,0 +1,29 @@
+import { z } from 'zod';
+import { DaemonError } from '../protocol/daemon-error';
+
+/**
+ * The idempotency key a spawn or message tool call may carry, as its input
+ * schema lists it.
+ */
+export const IDEMPOTENCY_KEY_FIELD = z
+  .string()
+  .min(1)
+  .max(180)
+  .optional()
+  .describe(
+    'A key, unique to this call, that makes a retry safe: retrying with the same key and arguments returns the first answer instead of acting again, and the same key with different arguments is refused as idempotency_conflict. A call interrupted mid-way is refused as outcome_unknown, with the id it acted under in data.effectRef. At most 180 characters',
+  );
+
+/**
+ * Reads a tool call's idempotency key, refusing one outside the input
+ * schema as `bad_args` before the call reaches the daemon.
+ */
+export function parseIdempotencyKey(value: unknown): string | undefined {
+  const parsed = IDEMPOTENCY_KEY_FIELD.safeParse(value);
+
+  if (!parsed.success) {
+    throw new DaemonError('bad_args', 'idempotencyKey must be a string of 1 to 180 characters');
+  }
+
+  return parsed.data;
+}

package/src/mcp/reconnecting-caller.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { DaemonClient } from '../client/daemon-client';
 import type { DaemonFeature } from '../protocol/daemon-features';
 import { parseDaemonFeatures } from '../protocol/parse-daemon-features';
@@ -18,6 +19,14 @@ const RETRYABLE_METHODS: ReadonlySet<string> = new Set([
   'session.screen',
 ]);
 
+// The effectful requests a daemon takes under an idempotency key, and the
+// feature it announces when it does. Under a key, a retry replays the first
+// answer instead of running the effect again.
+const KEYED_METHODS: ReadonlyMap<string, DaemonFeature> = new Map<string, DaemonFeature>([
+  ['session.spawn', 'spawn.idempotency'],
+  ['session.message', 'message.idempotency'],
+]);
+
 // One handshaken connection and the features its daemon announced.
 interface DaemonConnection {
   readonly client: DaemonClient;
@@ -27,9 +36,11 @@ interface DaemonConnection {
 /**
  * A daemon caller that survives a daemon restart: once the connection ends,
  * the next request opens and handshakes a fresh one. A request that was in
- * flight when the connection ended is retried once on a fresh connection only
- * when it is read-only; any other fails, because a spawn or a message must not
- * run twice.
+ * flight when the connection ended is retried once on a fresh connection when
+ * it is read-only, or when it is a spawn or a message the daemon takes under an
+ * idempotency key: the request keeps its key, minted here when the caller
+ * passed none, so the daemon runs it at most once. Any other request fails,
+ * because a spawn or a message must not run twice.
  */
 export class ReconnectingCaller implements FleetCaller {
   private readonly socketPath: string;
@@ -52,23 +63,32 @@ export class ReconnectingCaller implements FleetCaller {
     m: string,
     p?: Readonly<Record<string, unknown>>,
     required: readonly DaemonFeature[] = [],
+    principal?: string,
   ): Promise<Readonly<Record<string, unknown>>> {
     const opened = await this.openClient();
 
     requireDaemonFeatures(opened.features, required);
 
+    const keyFeature = KEYED_METHODS.get(m);
+    const keyed = keyFeature !== undefined && opened.features.has(keyFeature);
+    const params = keyed ? buildKeyedParams(p) : p;
+
     try {
-      return await opened.client.sendRequest(m, p);
+      return await opened.client.sendRequest(m, params, principal);
     } catch (error) {
-      if (!this.closed.has(opened.client) || !RETRYABLE_METHODS.has(m)) {
+      if (!this.closed.has(opened.client) || !(keyed || RETRYABLE_METHODS.has(m))) {
         throw error;
       }
 
       const fresh = await this.openClient();
 
-      requireDaemonFeatures(fresh.features, required);
+      // The fresh daemon has to take the key too, or the retry could run the
+      // effect a second time.
+      const retryRequired = keyed ? [...required, keyFeature] : required;
+
+      requireDaemonFeatures(fresh.features, retryRequired);
 
-      return fresh.client.sendRequest(m, p);
+      return fresh.client.sendRequest(m, params, principal);
     }
   }
 
@@ -149,3 +169,15 @@ export class ReconnectingCaller implements FleetCaller {
     return { client, features: parseDaemonFeatures(hello) };
   }
 }
+
+// The request's params with its idempotency key, minting one when the caller
+// passed none.
+function buildKeyedParams(
+  p: Readonly<Record<string, unknown>> | undefined,
+): Readonly<Record<string, unknown>> {
+  if (typeof p?.['idempotencyKey'] === 'string') {
+    return p;
+  }
+
+  return { ...p, idempotencyKey: randomUUID() };
+}

package/src/mcp/require-daemon-features.ts

@@ -4,10 +4,17 @@ import type { DaemonFeature } from '../protocol/daemon-features';
 // states it.
 const FEATURE_USES: Readonly<Record<DaemonFeature, string>> = {
   'agents.list': 'atc_agents_list',
+  'daemon.id': "the daemon's persisted identity",
   'events.more': "atc_events_read's more flag",
   'events.session': "atc_events_read's session filter",
+  'message.idempotency': "atc_session_message's idempotencyKey",
   'message.turn': "atc_message_get's turn and answeredWith",
   'message.wait': "atc_message_get's waitMs",
+  'session.locator': "a session's locator",
+  'spawn.idempotency': "atc_session_spawn's idempotencyKey",
+  'spawn.options': "atc_session_spawn's model and effort",
+  'spawn.target': "atc_session_spawn's target",
+  'request.principal': 'the target limits of a remote MCP client',
 };
 
 /**