ap-spawn-agent

Spawn an Agent

When to use

The user wants a new, independent agent session doing bounded work in a directory — a worker to delegate to, a background task runner, or a fresh session for a subtask. Check agent_sessions_list first if there's any chance a matching session is already running; spawning a second one on the same cwd/task wastes a process.

MCP tool: agent_start

{
  "tool": "agent_start",
  "args": {
    "adapter": "claude-code",
    "model": "claude-sonnet-5",
    "cwd": "/Volumes/SSDExternalMacStudio/Code/products/agentik/agentik-studio",
    "prompt": "Add input validation to the signup form in apps/agentik/web/src/app/signup — reject empty email and password < 8 chars, add a unit test.",
    "label": "signup-validation",
    "mcpServers": [
      { "name": "agentproto", "transport": "http", "ref": "http://127.0.0.1:18790/mcp" }
    ],
    "access": { "profileRef": "default" },
    "orchestrator": false,
    "mode": "background",
    "effort": "medium",
    "permissionHold": false,
    "worktree": false,
    "wait": false,
    "idempotencyKey": "signup-validation-2026-09-01",
    "dedupe": true
  }
}

Only adapter, cwd, and prompt are typically required; the rest are tuning knobs. Use agent_sessions_list to see what's already running before you spawn:

{ "tool": "agent_sessions_list", "args": {} }

CLI

agentproto sessions start claude-code \
  --cwd /Volumes/SSDExternalMacStudio/Code/products/agentik/agentik-studio \
  --model claude-sonnet-5 \
  --prompt "Add input validation to the signup form..." \
  --label signup-validation \
  --attach false \
  --orchestrator false \
  --mcp-servers-json '[{"name":"agentproto","transport":"http","ref":"http://127.0.0.1:18790/mcp"}]' \
  --options-json '{"effort":"medium"}' \
  --access-profile default

HTTP

None. Spawning a session is MCP-tool/CLI-only — there is no daemon HTTP route for agent_start.

Gotchas

• hermes has no built-in file/shell tools. Unlike claude-code or claude-sdk, hermes ships with nothing but chat. If the task needs to read/write files or run commands, you MUST pass mcpServers:[{name:'agentproto',transport:'http',ref:'http://127.0.0.1:18790/mcp'}] at spawn time, or the agent can only talk, not act.
• cwd must be an absolute host path — a relative path fails the spawn outright.
• Give children authentic, bounded tasks. Sentinel prompts like "just repeat this token back to me" get refused by capable models as prompt injection — write a real task with a real goal and scope.
• Always set a distinct label so the session is identifiable later in agent_sessions_list / session_list — unlabeled sessions are hard to tell apart once several are running. When you list them back, narrow server-side (session_list {q:'<label>', excludeNoise:true, limit:10}) instead of reading every session on the daemon.
• dedupe + idempotencyKey: calling agent_start again with the same key + adapter + cwd within ~10 minutes returns the same session (deduped:true) instead of forking a second process — safe to retry a spawn call without fear of duplicates.