@heretyc/subagent-mcp

Spawn a sub-agent session. CONTRACT: `prompt` states objective + output format + tools/sources + boundaries; the server auto-upserts \

Return live in-memory MCP session state. `session_start_time` is the MCP server process boot time because smcp-activate runs as a separate hook process and cannot update this server

Get an agent

Terminate a live agent/session (status `processing`, `stalled`, or turn-finished but still interactive) by immediately force-killing its managed driver. A finished agent is force-killed automatically after 6 minutes of no `send_message`/`poll_agent` activity; call `kill_agent` sooner to free resources immediately. No-op for already-terminal closed agents.

Answer a parked permission request for an agent. One-time only; does not create session-wide approvals. If request_id is omitted, answers the agent

Enqueue a user message for an open interactive agent session. Observe output with poll_agent or wait.

List all agents with token-efficient core metrics (status, `alive`, `idle_seconds`). `stalled` is ALIVE-but-quiet, NOT dead (full status semantics on poll_agent). Use `poll_agent` for per-agent stream items, hints, and final output.

Blocks until one or more sub-agents reach a reportable state (turn-finished, errored, stopped, or zombie_killed), returning exit code when known + local-time timestamp; or returns the live-job list after a 15-minute timeout. This is how you learn an agent finished — do NOT poll-loop. A `finished` agent with null exit_code is still alive and accepts `send_message`; `send_message`/`poll_agent` activity keeps it alive, and 6 minutes idle auto-kills it. A `stalled` agent is still ALIVE and does NOT end the wait. `verbose: true` adds each finished agent

Test-only yolo wait pending-permission fixture.

Toggle or query per-project ORCHESTRATION MODE. `enabled`: true = ON, false = OFF for THIS session only, omit = query. SOLE CHANNEL holds in BOTH states: subagent-mcp is the only sanctioned way to launch sub-agents; toggling OFF does not lift that. WHAT: when ON act as a delegate-ONLY orchestrator; delegate every step, inline-by-right does not exist, a non-delegable atomic step needs a one-time user-approved exception via the structured-question tool. Default is OFF each session; setup writes no orchestration state. enabled:true explicitly turns ON or re-enables mid-session; enabled:false is a session-keyed 2h-TTL opt-out, HONORED even after the 15% latch or metering fail-safe forces ON. PERSISTENCE: a permitted disable applies only to THIS keyed session; after the 2h backstop the current session may latch/fail-safe ON, while each new keyed session returns to default OFF. Keyless or undetectable metering remains fail-safe ON; a hookless host may use only the one-time non-persisted conversational opt-out. DISABLE: never on your own initiative; you may PROPOSE OFF on task-fit mismatch, but only EXPLICIT user permission may set enabled:false. Per-turn injection fires only in CLI hosts that load the bundled hook; desktop hosts toggle the marker but inject nothing.

Set or query per-project MODEL SELECTION MODE, which gates launch_agent

Write a handoff for this working directory so the NEXT session can resume cleanly. UNLOCKS only at >=20% context utilization with readable metering (voluntary from 20%; a fresh write becomes MANDATORY at >=80%); below 20%, or if context size is undetectable, this tool returns an affirmative unavailable error (never silent). BEFORE calling, ask the user 10 clarifying questions via the structured-question tool to build a /goal prompt for the next session. content <=4000 chars; use overflow (<=8000 more chars) for anything beyond that, referenced by full path inside content. A successful fresh write creates a prepared handoff record; it does NOT mandate an immediate new session -- keep working. On success, relay the tool

Read the saved handoff for this working directory (if any). Call this first; after reading any saved handoff, confirm the user

Delete the saved handoff for this working directory, including any overflow file. The voluntary write/read/clear cycle reopens at each successor session

List, read, or update subagent-mcp configuration by canonical key. `action=list` enumerates settings; `action=get` requires `key`; `action=set` requires `key` and, for settable keys, string `value`. Secrets are always redacted. Machine-global and mode-owned settings are read-only here: edit the reported global file as a human or use `orchestration-mode`/`model-selection-mode`. Provider and .env writes are validated, backed up, and atomic; responses report `restart_required`.

Launches local Claude and Codex sub-agent sessions and can route configured tasks to direct Claude Messages or OpenAI-compatible API providers.