---
name: subagent-registry
description: Manage named subagent instances with persistent provider pinning and memory. Use when spawning, resuming, listing, or deleting subagents.
---

# Subagent Registry

Manage named subagent instances. Each agent gets a human-readable name, persistent memory, and pinned provider for KV cache continuity.

## Registry File

`<project>/.pi/subagents.json`:

```json
{
  "session": "<session-name>",
  "agents": [
    {
      "name": "<human-readable-name>",
      "id": "<agent-uuid>",
      "type": "<agent-type>",
      "provider": "<provider-config>",
      "status": "running|completed|error",
      "created": "<ISO-timestamp>"
    }
  ]
}
```

## Rules

1. **Always ask for a name** when spawning a new subagent. Never auto-generate. Ask: "What should I name this subagent?"
2. **One agent per name.** If name exists, ask for a different name.
3. **Store the agent ID** in the registry immediately after spawn.
4. **Use the same provider** when resuming — read from registry.
5. **Each named agent gets its own memory** directory via `memory: project` in agent frontmatter.
6. **No auto-cleanup.** Agents persist until explicitly deleted.
7. **Session-scoped.** Registry is per-project directory.

## Workflow: Spawn

1. User requests a subagent
2. **Ask for a name** if not provided: "What should I name this subagent?"
3. Call `Agent({ subagent_type, prompt, run_in_background: true, ... })`
4. Wait for completion notification with agent ID
5. Append to `.pi/subagents.json`:
   ```json
   {
     "name": "<user-given-name>",
     "id": "<agent-uuid>",
     "type": "<subagent_type>",
     "provider": "<provider-config-from-agent-frontmatter>",
     "status": "running",
     "created": "<ISO-timestamp>"
   }
   ```
6. Inform user: "Created subagent '<name>' (<id-short>) using <provider>"

## Workflow: Resume

1. User says "resume <name>" or "tell <name> to..."
2. Read `.pi/subagents.json`, find agent by name
3. If not found: "No subagent named '<name>'. Use /subagent-list to see available agents."
4. If found: `Agent({ subagent_type, resume: "<agent-id>", prompt: "<new-task>", run_in_background: true })`
5. Update status in registry to "running"
6. Inform user: "Resumed '<name>' (<id-short>) — <provider> cache warm"

## Workflow: List

Display all agents in a compact table:

```
Name              Type         Provider    Status    Created
----              ----         --------    ------    -------
coder-login       coder-pro    DeepInfra   ✓ done    20:00
coder-nav         coder-pro    DeepInfra   ↻ run     20:05
obsidian-edit     obsidian     StreamLake  ✓ done    19:30
```

Show: name, type, provider (from config), status, created time.

## Workflow: Delete

1. User says "delete <name>" or "kill <name>"
2. Read registry, find agent
3. If running: call `TaskStop` or steer to abort
4. Remove entry from registry
5. Inform user: "Deleted '<name>' (<id-short>)"

## Workflow: Delete Session

1. User says "delete session <name>" or "clear all subagents for <session>"
2. Find all agents where `session == <name>`
3. Abort any running agents
4. Remove all matching entries from registry
5. Inform user: "Deleted <N> subagents from session '<name>'"

## Provider Config Format

Store as string: `"only:<provider-slug>"`

Examples:
- `"only:DeepInfra"`
- `"only:Baidu"`
- `"only:StreamLake"`
- `"only:Moonshot AI"`

When resuming, parse and reconstruct the provider field:
```
"only:DeepInfra" → { "only": ["DeepInfra"] }
```

## Memory

Each named agent should have `memory: project` in its frontmatter. This gives it a persistent memory directory at `.pi/agent-memory/<agent-name>/` that survives across resume calls.

## Session Name

The `session` field in the registry should match the pi session name. If no session name is set, use the project directory name.

## Example Interaction

```
User: "Spawn a coder-pro to fix the login module"
LLM: "What should I name this subagent?"
User: "auth-login"
LLM: *spawns agent, gets ID 7efad0d8-5a78-415*
LLM: "Created subagent 'auth-login' (7efad0d8) using DeepInfra"

User: "What subagents do we have?"
LLM: *reads registry, displays table*
  auth-login    coder-pro  DeepInfra  ✓ done  20:00

User: "Resume auth-login and tell it to add password reset"
LLM: *reads registry, finds ID, resumes with same provider*
LLM: "Resumed 'auth-login' (7efad0d8) — DeepInfra cache warm"
```