---
title: "Subagents"
description: "Create and manage session-backed child agents."
canonical_url: https://fx.sh/docs/capabilities/subagents
markdown_url: https://fx.sh/docs/capabilities/subagents.md
---

# Subagents

A subagent is a child fx session controlled by another agent. It uses the same workspace and runtime, with its own model, reasoning effort, permission mode, transcript, and lifecycle.

## Run modes

- A **one-off** child runs one prompt and finishes.
- A **persistent** child returns to idle after each turn and can receive more messages.

Persistent children remain resumable fx sessions. Parent and child messages are queued durably, so the child can work without copying its full transcript into the parent's context.

## ctrl+x manager

Press ctrl+x in an interactive session to open the manager. It can:

- show the child tree and current state
- create and open persistent children
- send follow-up instructions
- change name, model, effort, permission mode, and notifications
- attach, detach, or reparent an existing session
- resume, cancel, close, or reopen a child
- resolve child approval requests

Closing the manager does not stop persistent children.

## Agent tool

The model uses one `subagent` tool with six branches:

| Branch | Purpose |
| --- | --- |
| `create` | Create a one-off or persistent child. |
| `inspect` | Read selected state for a child ID. |
| `message` | Send a parent message or emit a child milestone. |
| `relationship` | Attach, detach, or reparent a session. |
| `configure` | Change model, effort, permissions, name, or notifications. |
| `lifecycle` | Resume, cancel, close, or reopen a child. |

Create a persistent child:

```json
{
  "command": {
    "create": {
      "name": "researcher",
      "mode": "persistent",
      "prompt": "Inspect the authentication flow and report risky edges.",
      "model": "<provider/model-id>",
      "effort": "high",
      "permission_mode": "ask"
    }
  }
}
```

Operations use durable identities, so a safe retry returns the original result instead of repeating the effect.

> **Children cannot elevate model-created authority**
>
> When the model creates a child without specifying a permission mode, the child inherits the caller's effective permission mode and cannot request broader authority. A human-created child in the ctrl+x manager can use the manager's explicit configuration and may default to `yolo`, so review that setting before starting it.

---

[Browse all fx documentation](https://fx.sh/llms.txt)