angel

Structured advisor + conditional smarts.

Angel is available only when the active executor model matches a configured executor/advisor pair. By default it auto-injects advice on every 3rd tool error and gates dangerous shell commands once.

Config

~/.pi/agent/settings.json:

{
  "angel": {
    "pairs": [
      {
        "executor": "zai/glm-5.1",
        "advisor": "openai-codex/gpt-5.5"
      },
      {
        "executor": "openai-codex/gpt-5.5",
        "advisor": "zai/glm-5.1"
      }
    ],
    "maxCallsPerTask": 4,
    "enabled": true,
    "autoOnErrors": 3,
    "policyGate": "block"
  }
}

Pair fields:

• executor: active model required for Angel availability. Matches provider/model or bare model id.
• advisor: model Angel calls for advice. Prefer provider/model.

If current model is not listed as an executor, the angel tool is removed from active tools. /angel also refuses with an unavailable-model error.

Behavior

• Builds fresh AngelContextPacket from current session: user request, system prompt, context usage, recent conversation (last 200 messages), touched files (up to 50, 30k chars each), recent tool errors, missing/truncated-source labels.
• Calls configured advisor model for active executor.
• Requires structured JSON-backed AngelAdvice.
• Persists advice via angel-advice entries.
• Injects advice into the agent loop on every autoOnErrors-th tool error.
• Gates dangerous bash once per exact command; retrying the same command proceeds.
• Keeps semantic guidance in advisoryOnly.

Policy Gates

No popups. When policyGate is block (default):

1. Executor attempts dangerous bash (rm -rf, sudo, git push, publish, recursive chmod/chown, dd, mkfs, curl|sh, fork bomb)
2. Angel blocks that exact command once
3. Angel consults the advisor and returns advice in the block reason
4. Executor may retry the same command if still correct

This adds conditional smarts without turning Angel into a permanent permission wall.

Tool

angel({
  question: "What should I validate before editing auth?",
  context: "Extra context not already visible"
})

Commands

• /angel <question>: manual advisor consult. Opens full advice in editor.
• /angel-policy: show latest enforceable policy in editor.

Settings

| Setting | Type | Default | Notes | |---|---|---:|---| | pairs | { executor, advisor }[] | [] | Required for availability | | maxCallsPerTask | number | 4 | Session call budget | | enabled | boolean | true | Disables tool/gates if false | | autoOnErrors | number | 3 | Auto-consult every Nth failed tool result | | policyGate | off\|block | block | Gate dangerous bash commands once |

Difference from devil

• devil: adversarial stress-test of an idea. User-initiated.
• angel: execution advisor tied to configured executor/advisor pairs, fresh max-context packet, auto-injected advice, dangerous-command gate. Suggests devil only when confidence is low and a concrete decision remains.

Demo