angel({
  question: "Which explanation fits the failing integration test?",
  context: "The failure occurs only against the staging endpoint."
});

{
  "angel": {
    "pairs": [
      {
        "executor": "openai-codex/gpt-5.6-sol",
        "advisor": "openai-codex/gpt-6-astra"
      }
    ],
    "thinkingLevel": "max",
    "subagentExtensions": ["web"],
    "enabled": true
  }
}

# angel

Investigative advisor for Pi.

Angel runs a configured advisor model as a tool-using child agent.
It receives a focused assignment, can inspect the pinned parent session on demand, can inspect the project and use loaded extension tools, and returns evidence-backed advice to the executor.
The persistent child session is the complete investigation record.

## Tool

`angel` asks for deep reasoning and independent investigation.
Use it for difficult diagnosis, competing explanations, architectural trade-offs, contradictory evidence, or consequential uncertainty.
Ask a concrete question; Angel can retrieve relevant parent evidence when needed.

```javascript
angel({
  question: "Which explanation fits the failing integration test?",
  context: "The failure occurs only against the staging endpoint."
});
```

`context` is optional and should contain only information that makes the assignment more precise.
The tool returns ordinary Markdown advice.
Angel advises; user instructions and primary evidence remain authoritative.

## Automatic recovery

Angel treats automatic recovery as deterministic stalled-operation detection.
The first eligible operation failure is remembered without consulting.
If the same tool call with canonically identical structured arguments fails again in a later executor turn, Angel starts one consultation before the executor's next model call.
A matching success or a new task clears the remembered failure.

Pi built-ins whose normal recovery is local discovery or retry are excluded: `read`, `edit`, `write`, `grep`, `find`, and `ls`.
This decision uses Pi's tool provenance, so an extension override with the same name remains an opaque non-built-in tool.
Built-in process tools, extension tools, SDK tools, and unknown tools share the generic repeated-operation rule; Angel contains no knowledge of unrelated extensions.
Sibling results from the triggering batch are investigated together.
Explicit cancellations, unmappable calls, and failures inside Angel do not trigger it.
There is no consultation quota or every-Nth-error cadence.

## Command

- `/angel <question>` runs a human-directed consultation without starting an executor turn afterward.
- `/angel cancel` cancels an active consultation without disabling Angel.
- `/angel on` enables Angel for the current session.
- `/angel off` disables the tool and automatic recovery for the current session.

In RPC mode, use `/angel cancel` because Pi 0.85 does not route the generic idle-session `abort` request to extension command work.

## Child agent

Each consultation creates a persistent child session linked to the parent session.
The child loads normal project context and skills, but no extensions by default.
`angel.subagentExtensions` can load all configured extensions or an explicit whitelist of sibling pi-ext extension names.
Its active tools include `read`, `ls`, `find`, and `grep`, plus tools from whitelisted extensions such as `web`.
`bash`, `edit`, `write`, and recursive `angel` access are disabled.
The child runtime owns its active tool set after initialization.
Active parent tools are not child requirements: on-demand and SDK tools such as IntelliJ remain parent-local and do not block consultation.

Angel is read-only: it cannot modify the user's project or perform implementation work.

The parent transcript is not copied into the child.
The assignment identifies the parent session and pins its current leaf.
A read-only `parent_session` tool provides metadata-first listing, narrow search, and exact entry retrieval from that stable snapshot.
It excludes `!!` Bash entries and custom-message bodies because Pi 0.85 cannot reapply the parent's final runtime context-filter chain safely.
This keeps unrelated history out of every advisor request while preserving on-demand access to ordinary conversation and tool evidence.

The child records only the assignment, retrieved evidence, and the advisor's actual model and tool work.
The parent displays attribution metadata but does not add child usage to the parent tool result, avoiding aggregate double counting.

## Settings

All settings live in the `angel` block of Pi `settings.json`.
Angel has no flags or environment variables.

Precedence: trusted project `.pi/settings.json`, then user `~/.pi/agent/settings.json`, then built-in defaults.
When both blocks are objects they deep-merge with project keys winning; arrays such as `pairs` replace rather than merge.
Project settings are read only when Pi trusts the project.

```json
{
  "angel": {
    "pairs": [
      {
        "executor": "openai-codex/gpt-5.6-sol",
        "advisor": "openai-codex/gpt-6-astra"
      }
    ],
    "thinkingLevel": "max",
    "subagentExtensions": ["web"],
    "enabled": true
  }
}
```

- `pairs` maps an active executor to its advisor.
  Model references may be `provider/model`; a bare advisor id uses the executor provider.
- `thinkingLevel` is requested independently for the advisor and visibly clamped by Pi if unsupported.
  Default: `max`.
- `subagentExtensions` accepts `"all"`, `"none"`, or a static array of sibling pi-ext extension names.
  The default is `"none"`; an empty array is equivalent.
  Unknown names fail consultation startup.
- `enabled` controls the initial session state.
  Default: `true`.

The merged block is validated as a whole.
An invalid block shows a warning naming the source, never falls back to a lower source, and leaves Angel unconfigured for the session.

Angel is available only when the active executor matches a pair, the advisor model is registered, and advisor authentication is available.

## UI

When available, Angel publishes semantic `model-route:angel` state for `model-info` to render as `󰧑 <advisor>:<thinking>`.
Without `model-info`, it publishes the full advisor id and thinking level as an `angel` status fallback.

Final advice is shown prominently as Markdown.
Model, effective thinking level, origin, runtime, token use, cost when known, and child-session identity are subdued metadata.
The complete investigation remains in the child session and is inspected through Pi's normal session browser.

Tool progress uses native streaming updates.
Collapsed tool output stays compact and shows the configured expansion shortcut.
Expanded output shows the full assignment, provisional draft text, and complete metadata.
Human-directed consultations use a cancellable live view in TUI mode and emit plain text in print mode.
Session replacement and tree navigation cancel stale investigations before they can deliver into another parent context.

See [SPEC.md](SPEC.md) for the binding behavior and acceptance criteria.

## Debug

Opt in through [debug logging](../DEBUG.md).
Safe records: `session.start`, `session.shutdown`, consultation span outcomes (`success`, `cancelled`, `failed`), and `consultation.skip` reasons (`disabled`, `unconfigured`).