Add a budget-aware escalation guard

[bmdhodl]

PR Draft

Title

Add a budget-aware escalation guard for advisor-style model routing

Summary

• add BudgetAwareEscalation, EscalationSignal, and EscalationRequired so apps can keep a cheaper default model and escalate only hard turns to a stronger model
• support four v1 signals: token count, confidence, tool-call depth, and a custom rule
• keep the SDK boundary intact: AgentGuard decides when to escalate; the app still owns the actual provider call

Scope

• core guard implementation in sdk/agentguard/escalation.py
• public exports and guard-module compatibility re-exports
• tests for signal matching, next-call arming, exports, DX, smoke, and example execution
• one guide and one local-only example
• README / examples / changelog / roadmap / generated PyPI README sync
• proof artifacts under proof/budget-aware-escalation/

Non-goals

• no dashboard work
• no provider-specific routing adapter
• no hidden network behavior
• no new runtime dependencies
• no attempt to auto-switch OpenAI or Anthropic patchers under the hood

Proof

• python -m ruff check sdk/agentguard/guards.py sdk/agentguard/escalation.py sdk/agentguard/__init__.py sdk/tests/test_guards.py sdk/tests/test_exports.py sdk/tests/test_dx.py sdk/tests/test_smoke.py sdk/tests/test_example_starters.py sdk/tests/test_architecture.py examples/budget_aware_escalation.py scripts/generate_pypi_readme.py
• python -m pytest sdk/tests -v --cov=agentguard --cov-report=term-missing --cov-fail-under=80
• python scripts/sdk_release_guard.py
• python scripts/sdk_preflight.py
• python -m bandit -r sdk/agentguard -s B101,B110,B112,B311 -q
• python scripts/generate_pypi_readme.py --write
• PYTHONPATH=sdk python examples/budget_aware_escalation.py

Saved artifacts

• proof/budget-aware-escalation/example-output.txt
• proof/budget-aware-escalation/budget_aware_escalation_traces.jsonl
• proof/budget-aware-escalation/source-notes.md
• proof/budget-aware-escalation/blog-draft.md

[Copilot]

Pull request overview

Adds a new “advisor-style” escalation guard to the AgentGuard SDK so applications can run a cheaper default model and selectively route hard turns to a stronger model, while keeping provider invocation logic in the app (not inside the SDK).

Changes:

• Introduces BudgetAwareEscalation, EscalationSignal, and EscalationRequired (new core module + public exports).
• Adds coverage across guards/exports/DX/smoke/example-starters, plus a runnable local-only example.
• Updates docs and release-facing artifacts (README, PyPI README sync, changelog, roadmap, proof outputs).

Reviewed changes

Copilot reviewed 25 out of 26 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
sdk/agentguard/escalation.py	New escalation guard implementation and signal primitives.
sdk/agentguard/guards.py	Re-exports escalation symbols via agentguard.guards.
sdk/agentguard/init.py	Adds escalation types to public top-level API and __all__.
sdk/tests/test_guards.py	Adds unit tests for escalation signals/behavior and updates guard tests.
sdk/tests/test_exports.py	Ensures new guard/signal/exception are exported and in __all__.
sdk/tests/test_dx.py	Adds repr/docstring DX checks for the new guard.
sdk/tests/test_smoke.py	Extends smoke imports to include new public exports.
sdk/tests/test_example_starters.py	Executes the new example in CI-style test coverage.
sdk/tests/test_architecture.py	Updates allowed-module lists to include escalation.py and new guard.
examples/budget_aware_escalation.py	New local-only example demonstrating escalation decision + tracing.
examples/README.md	Documents the new example and how to run it.
docs/guards/budget-aware-escalation.md	New guide page describing semantics, signals, and boundary.
README.md	Adds guard to table and includes a brief usage snippet + guide link.
sdk/PYPI_README.md	Adds guard to PyPI README table and usage snippet + GitHub link.
scripts/generate_pypi_readme.py	Marks the new guard doc path as unreleased for link rewriting.
CHANGELOG.md	Notes the new feature under Unreleased.
ops/03-ROADMAP_NOW_NEXT_LATER.md	Marks budget-aware escalation guard as done.
PR_DRAFT.md	Updates draft PR metadata to match this feature.
MORNING_REPORT.md	Updates report narrative/validation summary for this feature.
AGENTS.md	Updates module map and public API surface documentation.
proof/budget-aware-escalation/verification.txt	Captures validation commands/results for the PR.
proof/budget-aware-escalation/source-notes.md	Documents primary-source rationale for advisor framing.
proof/budget-aware-escalation/blog-draft.md	Draft copy describing the feature.
proof/budget-aware-escalation/report.txt	Captured CLI report output for the example trace.
proof/budget-aware-escalation/example-output.txt	Captured console output from running the example.
proof/budget-aware-escalation/budget_aware_escalation_traces.jsonl	Captured trace output from running the example.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2393ea2dc1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".