spawn_agent
Spawns a relay agent terminal pre-configured with role, capabilities, and auth token, for task delegation to fresh sub-agents.
Instructions
Open a new Claude Code terminal pre-configured as a relay agent (macOS only).
When to use: orchestrators delegating work to a fresh sub-agent. The new terminal arrives in a known role + capability set with RELAY_AGENT_NAME/ROLE/CAPABILITIES already in env, and the SessionStart hook auto-registers it before the LLM's first turn. Linux/Windows drivers exist for headless smoke tests but do not open a UI window.
Behavior: pre-registers the new agent server-side (so its token is minted before the child process starts and reaches it via env), opens an iTerm2 or Terminal.app window via AppleScript, and runs the configured shell command in that window. Optional initial_message is queued in the new agent's mailbox and surfaces on its first get_messages. brief_file_path (v2.1.4) threads a durable on-disk task brief into the KICKSTART prompt, preferred over initial_message for non-trivial scopes because file-on-disk does not read as prompt-injection the way an inbox message can.
Returns: { success: true, name, role, capabilities, platform, driver, agent_token, auth_note, has_initial_message, brief_file_path, note }. agent_token is shown ONCE — already written to the per-instance file vault at <instanceDir>/agents/<name>.token (v2.6.1). The spawned terminal's launcher reads the vault before exec'ing claude (macOS / Linux), and the stdio MCP server transport's resolveToken falls back to RELAY_AGENT_TOKEN env or the per-instance vault when RELAY_AGENT_NAME is set, so the child authenticates from its first tool call regardless of platform. HTTP clients must always present an explicit token via args.agent_token or X-Agent-Token header — the daemon's own env (RELAY_AGENT_TOKEN, RELAY_AGENT_NAME) and the per-instance vault are stdio-only credentials and are never used to authenticate HTTP callers (R3 transport gate).
Errors: SPAWN_NOT_SUPPORTED (non-macOS host without an explicit driver), AUTH_FAILED, INVALID_INPUT, RATE_LIMITED.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cli | No | Which agent CLI to launch for the new terminal: a registered agent-CLI profile id — 'claude' (default) or 'codex'. Codex launches via bin/codex-relay (POSIX; macOS + Linux). See `relay cli-profiles`. | claude |
| cwd | No | Absolute path working directory for the new terminal. Defaults to user's home. | |
| name | Yes | Name for the new agent — [A-Za-z0-9_.-]+, max 64 chars | |
| role | Yes | Role of the new agent — [A-Za-z0-9_.-]+, max 64 chars | |
| agent_token | No | Your agent token (from register_agent response). Optional here — also resolvable from RELAY_AGENT_TOKEN env or X-Agent-Token header. | |
| capabilities | No | Capabilities of the new agent | |
| brief_file_path | No | v2.1.4 (I10): absolute path to a task-brief file the spawned agent should read FIRST. The relay validates that the file exists at spawn time, is readable, and is <=10KB. When set, the default KICKSTART prompt appends a sentence telling the agent to read this file as the canonical source for its task scope — trust-anchored fix for respawned-agent context loss (inbox messages are not durable). macOS only for v2.1.4; Linux/Windows drivers ignore (no KICKSTART on those platforms yet). | |
| initial_message | No | Optional message to queue for the new agent before it spawns. It will see this on session start. |