Agents Skill: Working with Subagents

This skill covers the full gobby-agents MCP server — spawning agents, managing their lifecycle, configuring agent definitions, and inter-agent communication.

Server Clarity

All agent tools live on gobby-agents, NOT gobby-sessions.

gobby-sessions — session lifecycle (CRUD, handoffs)
gobby-agents — spawning, lifecycle, definitions, messaging, commands

Session IDs can be passed as #N, N, full UUID, or UUID prefix throughout.

1. Spawning & Lifecycle

spawn_agent(prompt, ...)

Spawn a subagent to execute a task.

| Parameter | Required | Description | |-----------|----------|-------------| | prompt | yes | The task/instruction for the agent | | agent | no | Named agent definition to use (e.g. "default", "claude-cli-sonnet") | | task_id | no | Gobby task ID to associate with this run | | isolation | no | "none" (current dir), "worktree" (git worktree), "clone" (shallow clone) | | branch_name | no | Branch name for worktree/clone isolation | | base_branch | no | Base branch to create from | | clone_id / worktree_id | no | Reuse an existing clone or worktree | | workflow | no | Workflow to attach to the agent session | | mode | no | Workflow mode (e.g. "plan", "execute") | | initial_step | no | Starting step for the workflow | | provider | no | LLM provider override | | model | no | Model override | | timeout | no | Timeout in seconds | | max_turns | no | Maximum agentic turns | | sandbox | no | Enable sandboxing | | sandbox_mode | no | Sandbox mode string | | sandbox_allow_network | no | Allow network in sandbox | | sandbox_extra_paths | no | Extra paths to mount in sandbox | | parent_session_id | no | Override parent session (defaults to current) | | project_path | no | Override project path |

can_spawn_agent(parent_session_id)

Check if spawning is allowed from a session. Returns whether the depth limit or other restrictions would block a spawn.

evaluate_spawn(...)

Dry-run a spawn — validates agent definition, workflow, isolation, and runtime without actually executing. Accepts the same key parameters as spawn_agent (agent, workflow, task_id, isolation, mode, provider, branch_name, base_branch, parent_session_id, project_path).

wait_for_agent(run_id, timeout?, poll_interval?)

Block until an agent reaches a terminal status (success, error, timeout, cancelled) or the wait timeout expires.

| Parameter | Required | Description | |-----------|----------|-------------| | run_id | yes | The agent run ID to wait on | | timeout | no | Max wait time in seconds | | poll_interval | no | Polling interval in seconds |

stop_agent(run_id)

Mark a running agent as cancelled in the DB. Does not kill the process — use kill_agent for that.

kill_agent(run_id?, session_id?, signal?, force?, debug?)

Kill a running agent's process and close its terminal.

| Parameter | Required | Description | |-----------|----------|-------------| | run_id | no | Parent kills child by run ID | | session_id | no | Self-termination by session ID | | signal | no | Signal to send (default: SIGTERM) | | force | no | Force kill if graceful fails | | debug | no | Enable debug output |

Use run_id when a parent wants to kill a child. Use session_id for self-termination.

2. Querying Agents

list_agents(parent_session_id, status?, limit?)

List agent runs for a session (DB records). Filter by status and limit results.

list_running_agents(parent_session_id?, mode?)

List agents with active in-memory processes. Unlike list_agents, this only shows agents that are currently running, not historical records.

get_running_agent(run_id)

Get the in-memory process state for a specific running agent.

get_agent_result(run_id)

Get the result of a completed agent run (output, status, timing).

running_agent_stats()

Get aggregate statistics about all running agents (counts, resource usage).

unregister_agent(run_id)

Remove an agent from the in-memory running registry. Internal use — prefer stop_agent or kill_agent.

3. Agent Definitions

Agent definitions are named configurations stored in the DB that control how agents are spawned (CLI type, model, allowed tools, workflows, etc.).

list_agent_definitions(enabled?, project_id?)

List definitions, optionally filtered by enabled status or project scope.

get_agent_definition(name)

Get the full definition body for a named agent.

create_agent_definition(name, definition)

Create a new agent definition. The definition object is validated against AgentDefinitionBody before insertion.

toggle_agent_definition(name, enabled)

Enable or disable a definition by name.

delete_agent_definition(name, force?)

Soft-delete a definition. Template-sourced agents are protected unless force=True.

update_agent_rules(name, add?, remove?)

Add or remove rules from an agent definition's workflows.rules list.

update_agent_variables(name, set_vars?, remove?)

Set or remove variables from an agent definition's workflows.variables dict.

4. Messaging (P2P)

Peer-to-peer messaging between any two sessions in the same project.

send_message(from_session, to_session, content, priority?)

Send a message. When sending to a parent session, auto-writes to agent_runs.result.

| Parameter | Required | Description | |-----------|----------|-------------| | from_session | yes | Sender session ID | | to_session | yes | Recipient session ID | | content | yes | Message content | | priority | no | Priority level |

deliver_pending_messages(session_id)

Fetch all undelivered messages for a session and mark them as delivered. Call this often as an inbox check — especially before starting long-running work.

5. Commands (Parent-to-Child)

Structured task delegation from an ancestor session to a descendant. Only one active command per target at a time.

send_command(from_session, to_session, command_text, ...)

Issue a command to a descendant agent. Validates ancestry. Rejects if the target already has an active command.

| Parameter | Required | Description | |-----------|----------|-------------| | from_session | yes | Commanding (ancestor) session | | to_session | yes | Target (descendant) session | | command_text | yes | The command instruction | | allowed_tools | no | Restrict which tools the agent can use | | allowed_mcp_tools | no | Restrict which MCP tools the agent can use | | exit_condition | no | Condition for the agent to auto-complete |

activate_command(session_id, command_id)

Accept a pending command — marks it as running and sets session variables (command_id, command_text, allowed_tools, exit_condition).

complete_command(session_id, command_id, result)

Complete a command — marks it done, clears session variables, and sends the result back to the commanding session.

Dos and Don'ts

DO use #N shorthand for session IDs (e.g. #5).
DO call deliver_pending_messages before starting long-running work.
DO use evaluate_spawn to dry-run before spawning complex agents.
DO use can_spawn_agent to check depth limits before spawning.
DO use kill_agent (not bash tools or /quit) to terminate agents.
DON'T use unregister_agent directly — prefer stop_agent or kill_agent.
DON'T poll constantly — use hooks and event-driven patterns where possible.
DON'T send commands to non-descendant sessions — ancestry is validated.