1 +#
Angel: investigative advisor specification 5 +This specification records the agreed redesign of Angel.
6 +It defines the required result, not an implementation plan or a description of the current code.
7 +It is the binding contract for the authorized implementation.
9 +**Angel provides deep reasoning and independent investigation to improve the executor's next decision.**
10 +Advice quality and verified recovery take priority over cost or consultation frequency.
11 +Angel is an advisor, not a permission system, command firewall, or implementation worker.
13 +##
Consultation lifecycle 15 +Each consultation runs a capable, tool-using Pi agent in a new persistent child session linked to the originating parent session.
16 +The advisor investigates until it can provide useful advice or identify what prevents a supported conclusion.
17 +The parent receives the final advice, not the advisor's intermediate investigation.
19 +A consultation has three possible origins:
21 +- Executor: the model invokes the `angel` tool with a question or decision to investigate.
22 +- Human: the user invokes `/angel <question>` directly.
23 +- Error: Angel automatically investigates a completed executor tool batch containing a failed tool result.
25 +All origins share the same investigation engine and advice presentation.
26 +Their instructions and delivery behavior differ as specified below.
30 +Automatic consultation is a deterministic stalled-recovery mechanism, not a response to every failed tool result.
31 +The first eligible operation failure is remembered without consulting.
32 +If the same opaque operation fails again in a later completed executor turn before the task boundary changes, Angel starts one consultation before the executor's next model call.
33 +A matching successful operation clears the remembered failure and makes a later failure a new incident.
34 +After one consultation, the same operation does not trigger again until it succeeds or the task boundary changes.
36 +Operation identity is the tool name plus a cryptographic hash of canonically ordered structured arguments.
37 +Arguments are matched exactly after canonical ordering; Angel does not normalize tool-specific fields, inspect command text, classify error prose, or persist argument values.
38 +A result whose originating structured call cannot be mapped reliably is not eligible for automatic consultation.
39 +Duplicate failures for one operation in the same completed turn count as one attempt, not stalled recovery.
41 +Tool provenance comes from Pi's active tool metadata.
42 +Known low-signal Pi built-ins `read`, `edit`, `write`, `grep`, `find`, and `ls` are excluded from automatic consultation because their ordinary recovery is local discovery or retry.
43 +This exclusion applies only when Pi identifies the actual registration as built-in; an extension override with the same name remains an opaque non-built-in tool.
44 +Built-in process tools such as `bash` and `powershell`, extension tools, SDK tools, future unknown tools, and tools with unavailable provenance use the same generic repeated-operation rule.
45 +Angel must not contain names or domain assumptions for unrelated extensions.
46 +The `angel` tool itself is always excluded to prevent recursion.
48 +A triggering batch produces one consultation with all completed sibling results available, including successes and first-time failures.
49 +There is no every-Nth-error counter or session-wide error-review budget.
50 +Explicit cancellation is not a failure candidate.
51 +Remembered state is session-local and is cleared on new human input, session replacement, tree navigation, reload, or `/angel on|off`.
52 +It is intentionally not restored from transcripts because stale recovery state is worse than a missed automatic consultation.
54 +Error-origin instructions require Angel to diagnose the repeated failure, examine the intervening evidence, and recommend a concrete recovery step with validation.
55 +Errors produced inside Angel's child session must never recursively launch another Angel consultation.
56 +A failed explicit `angel` consultation must not trigger automatic Angel recovery either.
57 +Difficult one-off failures remain available to executor-origin or human-origin consultation.
61 +The `angel` tool is available at the executor's discretion when Angel is enabled and its advisor configuration is usable.
62 +Calling it does not require separate human permission.
63 +Its purpose includes difficult diagnosis, architectural trade-offs, competing explanations, contradictory evidence, and consequential decisions.
64 +It is not restricted to errors or explicit human requests.
66 +Executor-origin instructions require Angel to answer the supplied question, investigate alternatives, and challenge unsupported assumptions.
67 +The executor waits for the tool result and then continues normally.
71 +`/angel <question>` starts the advisor directly, without asking the executor to formulate or relay the request.
72 +Human-origin instructions prioritize the user's explicit focus while retaining the shared advisor role and applicable instructions.
73 +The final advice is displayed and made available in the parent's context.
74 +It does not automatically start or restart an executor turn.
75 +Invocation while the executor is busy must respect a safe consultation boundary rather than racing shared workspace activity.
77 +`/angel on|off` remains a session-local control over the tool and automatic consultations.
78 +`/angel cancel` cancels an active consultation without changing that control state; this is the non-TUI cancellation route when the host does not propagate idle-command aborts.
79 +Its effective state must be reported accurately.
81 +##
Advisor instructions and tool contract 83 +Instructions have three distinct homes:
85 +1. The `angel` tool's `description` explains its capabilities, useful invocation situations, inputs, and output.
86 +2. Its `promptGuidelines` instruct the executor and participate in Pi's system-prompt Guidelines while the tool is active.
87 +3. The advisor's own instructions define investigative behavior, workspace boundaries, and origin-specific focus.
89 +The tool description must communicate this contract clearly:
91 +> Consult Angel for deep reasoning and independent investigation: difficult diagnosis, competing explanations, architectural trade-offs, contradictory evidence, or a second opinion before committing to an approach.
92 +> Angel receives the focused assignment, loads project instructions, and can inspect the pinned parent session, project, and research evidence on demand.
93 +> Provide the question or decision you need resolved, including any competing hypotheses.
94 +> Returns evidence-backed advice, not implementation or permission.
96 +Exact wording may improve without changing that contract.
97 +The tool's schema and descriptions must make supplying a focused question straightforward.
98 +Any optional extra context sharpens the assignment rather than requiring the executor to rebuild a context packet.
100 +Executor guidance must establish that:
102 +- Angel should be called when independent investigation can materially improve the next decision, not merely for generic reassurance.
103 +- A concrete question, uncertainty, or competing hypothesis is more useful than a vague request for review.
104 +- Parent history need not be copied into tool arguments because Angel can retrieve relevant entries on demand.
105 +- Advice must be evaluated against evidence and user instructions, not treated as an authority override.
107 +Advisor guidance must require evidence gathering where needed, a distinction between observations and hypotheses, and explicit acknowledgment of unresolved uncertainty.
108 +Angel must not invent certainty, a diagnosis, or a need for changes merely to produce an answer.
110 +##
Tools, extensions, and workspace access 112 +Angel has access to `read`, `ls`, `find`, `grep`, `bash`, and `edit`.
113 +It also receives the parent's configured Pi extension capabilities, including tools such as `web` and their applicable guidance.
114 +It must not accidentally lose extension tools through a built-in-only tool allowlist.
115 +Skills and project instructions remain discoverable through normal Pi resource loading.
117 +Angel may inspect the whole project, read logs and history, research external documentation, and run relevant diagnostics and tests.
118 +There is no special restriction to files previously touched by the executor.
119 +Nested model operations must use the active model registry so extension-registered providers continue to work.
121 +Instructions prohibit modifying the user's working files or performing the executor's implementation work.
122 +Experiments that require edits may use Angel's own temporary experimental directory.
123 +Existing project automation rules, permissions, trust decisions, secret protections, and authorization requirements still apply.
125 +**The workspace boundary is instruction-based, not enforced isolation.**
126 +Bash can mutate files; disabling an edit tool or filtering command strings would not make this a security boundary.
127 +Temporary experimental artifacts are not a second logging system and are not to be deleted indiscriminately.
129 +Child-session extension loading must prevent recursive Angel consultation and unintended parent-UI or parent-session side effects.
130 +Unsupported interactive-only capabilities must be handled explicitly rather than hanging the advisor or pretending they succeeded.
134 +Angel starts with a focused assignment rather than a copied parent transcript:
136 +- Advisor and origin-specific instructions.
137 +- Normal project context, skills, and available tool definitions loaded for the child.
138 +- The triggering question and any concise caller-supplied context.
139 +- The parent session ID and the parent leaf pinned at the consultation boundary.
140 +- Stable, read-only access to parent evidence through the `parent_session` tool.
142 +The parent transcript and parent system prompt are not copied into the child.
143 +The child loads applicable project instructions itself, avoiding duplicated instructions and repeated transmission of unrelated parent history.
145 +`parent_session` operates on a snapshot pinned to the originating leaf.
146 +Its default context view is compaction-aware; its branch view permits deliberate retrieval of older active-branch history.
147 +It supports metadata-first overview and listing, narrow text search, and exact entry retrieval.
148 +The advisor should inspect metadata or search narrowly before requesting entry content.
149 +Retrieved messages are historical evidence, not instructions to continue the executor's actions.
150 +The advisor must not locate or read the parent JSONL directly.
152 +Triggering tool-call IDs and sibling-result references must resolve through the snapshot.
153 +Older history, compaction and branch summaries, complete needed tool results, and project files remain retrievable on demand.
154 +Ordinary Pi tool-output truncation applies and must be disclosed rather than presented as complete output.
155 +Known exclusions such as `!!` Bash messages must not be exposed by the retrieval tool.
156 +Custom-message bodies are also excluded because Pi 0.85 cannot safely reapply the parent's final runtime context-filter chain inside a normal extension.
158 +**Full access does not mean preloading every file and every historical token.**
159 +Remove the automatic first-50-touched-files packet and fixed message, file, error, and system-prompt character slicing.
160 +Use on-demand investigation rather than silent truncation or eager transcript duplication.
162 +##
Model, thinking, and limits 164 +Keep the currently configured Astra advisor model and executor/advisor pairing behavior.
165 +Configure advisor thinking independently from the executor in `pi/agent/settings.json`.
166 +The agreed target is `max` when supported by Astra.
167 +Any capability-based adjustment must be visible; it must not silently inherit a lower executor thinking level.
169 +There are no Angel-specific consultation quotas, cost budgets, investigation-turn caps, file-count limits, or arbitrary character limits.
170 +Physical model context windows, provider limits, ordinary tool output management, and cancellation still exist.
171 +These constraints must not be disguised as unlimited capacity or silently disable future consultations.
173 +##
Advice and executor context 175 +The advisor returns ordinary text, normally Markdown, rather than a required JSON object.
176 +The answer should explain what is happening, what to do next and why, how to verify it, and what remains unknown where those elements are useful.
177 +Evidence references and concrete observations belong in the advice.
178 +Obvious cases may have short answers; difficult cases may require substantial explanation.
179 +There are no mandatory sections, array lengths, confidence percentages, or policy fields.
181 +Only the completed advice is delivered to the executor, once per consultation.
182 +UI metadata, progress updates, investigative tool output, and the child transcript are not injected into the executor's conversation.
183 +A concise failure or cancellation report is distinct from completed advice and must never masquerade as a successful answer.
185 +##
Sessions, history, and accounting 187 +The child session is the investigation record.
188 +Its normal Pi history records advisor messages, investigative tool calls and results, the final advice, and usage.
189 +There is no separate Angel log file, custom log viewer, or `/angel log` command.
190 +Users inspect investigations through existing Pi session discovery and browsing.
192 +The parent-child relationship and the individual consultation must remain identifiable after reload or resume.
193 +The child must be distinguishable as an Angel consultation and associated with its origin and originating parent branch.
194 +The parent's displayed metadata identifies the child session.
196 +Usage attributable to Angel includes the work performed during that consultation, including nested model work where reported.
197 +Parent history is charged only when retrieved into the child and subsequently processed; unrelated parent messages are not copied or charged.
198 +Parent attribution and child-session usage must be traceable without counting one consultation twice in aggregate accounting.
199 +Parent linkage alone must not be assumed to provide this accounting automatically.
200 +Unavailable pricing or usage must be identified as unavailable rather than fabricated as zero.
204 +The presentation hierarchy is:
206 +1. Final advice, prominently displayed as readable Markdown.
207 +2. Subdued metadata: advisor model, thinking level, origin, runtime, tokens, cost where available, and child-session identity.
208 +3. Investigation history, available through normal session browsing rather than displayed in the parent transcript.
210 +Tool, command, and error origins share the advice component, not necessarily the same Pi delivery API.
211 +The final advice appears once in the normal parent view.
212 +No permanent availability footer, policy badges, numeric confidence badges, or duplicate advice messages are required.
214 +###
Native tool behavior 216 +The `angel` tool follows Pi's default tool standards.
217 +Its collapsed widget contains only compact invocation/progress/status information and bounded metadata or summaries.
218 +Full bodies and investigation output must not be placed in collapsed `renderResult` output.
219 +Expansion respects `app.tools.expand`, using `keyHint("app.tools.expand", "to expand")` where a hint is needed.
221 +To keep complete advice front and center without violating compact tool behavior, a tool-origin consultation displays its advice in a separate persistent UI-only transcript entry.
222 +The executor receives the advice through the actual tool result, not a duplicate custom message.
223 +Command and error origins may use rendered custom messages with advice in `content` and UI metadata in `details`.
224 +UI-only records must not leak into the executor's model context.
226 +###
Streaming and completion 228 +Consultations provide live progress and streamed answer text using supported Pi interfaces.
229 +Tool invocations use native tool updates; command and error origins may use a temporary widget.
230 +Investigative output remains in the child session, with at most compact activity information in the parent's live presentation.
232 +Streamed text is provisional until the advisor finishes, because an assistant text stream may precede further tool calls rather than constitute the final answer.
233 +Temporary presentation is removed when persistent final advice or an explicit failure/cancellation state is displayed.
234 +Intermediate text must not be persisted or injected as completed advice.
236 +Cancellation stops the child investigation and its abort-aware operations.
237 +Session switching, reload, and shutdown must prevent stale results or UI updates from being delivered into a different parent context.
238 +Child history already recorded remains available for inspection.
239 +The extension must remain usable across Windows, macOS, and Linux, with supported non-TUI behavior rather than a dependency on terminal-only components.
241 +##
Removed behavior and non-goals 243 +The redesign removes:
245 +- Dangerous-Bash regex detection and one-time command blocking.
246 +- Exact-command retry exemptions and policy-gate state.
247 +- `enforceablePolicy`, confidence scoring, and policy enforcement claims.
248 +- Mandatory JSON advice parsing and fallback schemas.
249 +- `maxCallsPerTask` and silent exhaustion behavior.
250 +- Error cadence counters and fixed context-packet slicing.
251 +- Separate investigation logs, custom log navigation, and `/angel log`.
253 +New heuristic danger filters, universal pre-action approval, multi-advisor debate, and semantic error classifiers are outside this specification.
254 +More sophisticated automatic triggers require separate evidence and agreement.
256 +##
Acceptance criteria 258 +Implementation is complete only when focused tests establish the following behavior:
260 +- A first eligible operation failure is remembered without consulting, and the same canonical operation failing in a later turn causes one investigation with all current sibling results before the next executor model call.
261 +- Canonical argument matching is key-order independent, while changed arguments identify a different operation.
262 +- Matching success, new human input, disable/enable control, session replacement, reload, and tree navigation clear remembered failure state.
263 +- Known low-signal built-ins are excluded by verified built-in provenance, while non-built-in and unknown tools receive generic opaque handling without extension-specific names.
264 +- Duplicate same-operation failures in one turn, successful batches, cancellations, unmappable calls, and errors inside Angel do not trigger consultations.
265 +- Further distinct stalled operations remain eligible after more than four consultations in one session.
266 +- Executor tool invocation and direct human invocation use their respective instructions and delivery semantics.
267 +- Human invocation does not start an otherwise idle executor.
268 +- The configured Astra advisor uses the independently selected supported thinking level.
269 +- Core tools, extension tools such as `web`, skill discovery, and project instructions are available to the child.
270 +- The initial child context does not contain the parent transcript or a duplicate parent system prompt.
271 +- `parent_session` provides metadata-first, pinned, read-only retrieval of compaction and branch summaries, recent results, exact entries, and older active-branch evidence.
272 +- Ordinary Markdown advice works without JSON, policy fields, or confidence scores.
273 +- The executor receives completed advice exactly once, without UI metadata or investigation transcripts.
274 +- Human presentation prioritizes advice, supports live updates, follows compact tool standards, and does not duplicate the final answer.
275 +- Each consultation remains discoverable as a parent-linked child session after reload, with attributable usage and no parent-history double counting.
276 +- Cancellation, provider failures, reload, and session replacement leave explicit and accurate state without stale delivery.
277 +- The removed command gate no longer intercepts Bash commands.
279 +Quality validation uses representative failure episodes to compare the existing Angel, the redesigned Angel, and an executor without Angel.
280 +Judge verified recovery, repeated failed approaches, unsupported recommendations, and incorrect advice followed by the executor.
281 +Longer answers, higher confidence, and more tool calls are not success metrics.
282 +Live evaluations are separate from deterministic regression tests; their results must not be claimed without running them.
284 +##
Evidence informing the design 286 +These sources motivate the design but do not replace the binding requirements above:
288 +- [Anthropic advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool): transcript-informed advice returned to an executor.
289 +- [Claude Code subagents](https://code.claude.com/docs/en/sub-agents): separate agent contexts with tools and focused assignments.
290 +- [Codex subagents](https://developers.openai.com/codex/multi-agent): independent investigative work with results returned to the parent.
291 +- [Effective context engineering](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents): just-in-time retrieval and context management rather than indiscriminate preloading.
292 +- [CRITIC](https://arxiv.org/abs/2305.11738) and [the critical survey of self-correction](https://arxiv.org/abs/2406.01297): external evidence matters more than ungrounded self-critique; these studies do not establish current-model performance for Angel.
294 +The installed Pi `docs/extensions.md`, `docs/sdk.md`, `docs/tui.md`, and `docs/session-format.md`, together with the message and entry renderer examples, establish the relevant SDK surfaces.
295 +Exact runtime wiring, cost aggregation, cancellation, streaming, and restoration must be verified against the installed SDK during implementation rather than assumed from documentation alone.