# `/subagents` commands

[Documentation index](../README.md)

`/subagents` is the human-facing root-supervisor command namespace.

It is separate from the structured model-facing `subagent` API.

Commands require a root supervisor with UI.

## Usage

```text
/subagents agents
/subagents overrides
/subagents placement [tab|split]
/subagents stop
```

## `/subagents agents`

Shows the current agent-definition roster and its declared policy metadata.

In TUI mode, Pi Herd appends one themed transcript overview.

In other UI modes, it uses the equivalent deterministic plain-text projection.

The human overview can show:

- name and description;
- configured model and thinking;
- declared tool policy represented by definition metadata (not a complete
  runtime capability probe);
- named skills;
- declared direct delegation;
- overridden/custom state;
- override/custom source path when relevant.

Bundled implementation paths are intentionally hidden from the human overview.

Structured `subagent list` keeps exact deterministic metadata, including exact
source and skill paths when available.

`/subagents agents` does not probe runtime tool availability.

## `/subagents overrides`

Opens a nested UI for extension-backed definitions.

Per selected agent:

```text
set model
reset model
set reasoning
reset reasoning
back
```

Model selection refreshes Pi's registry and stores the canonical provider/model
token.

When Pi provides an explicit scoped-model list, that scope is used. Otherwise
available models are offered.

Reasoning options use the effective model's supported levels when resolvable,
or Pi Herd's validated vocabulary when not.

The command edits only the selected top-level `model` or `thinking` line in the
global Markdown override. It preserves unrelated frontmatter and the complete
body.

A new overlay uses the default global agents directory and an encoded filename.

Reset removes only the chosen saved field and never deletes the override file.

Changes apply to future starts and non-live historical-session resumes, not
already-running workers, live reusable resumes, or the root supervisor.

Standalone global definitions are not managed by this menu because they have no
bundled default to restore.

## `/subagents placement`

Query:

```text
/subagents placement
```

Set:

```text
/subagents placement tab
/subagents placement split
```

The query reports the effective value plus its current settings scope.

See [Configuration](configuration.md).

## `/subagents stop`

Destructive root-only emergency control.

It aborts the current root turn and attempts to close the exactly proven owned
worker tree.

It reports discarded active work or durable pending results when present.

Cleanup uses existing exact ownership proofs and proceeds conservatively across
independent failures.

Use ordinary `subagent close` for normal targeted model-driven control.

## See also

- [`subagent` API](subagent.md)
- [Configuration](configuration.md)
- [Status widget](status-widget.md)