Budget Gatekeeper

Budget Gatekeeper

Provides runtime budget enforcement patterns for conductor workflows, tracking model tier allocation, delegation count, and estimated token cost to prevent runaway sessions.

Copilot CLI Native Metrics

Under copilot CLI, use native commands for budget telemetry instead of manual estimation:

• /context — real-time token usage and visualisation.
• /usage — session-wide model cost and invocation metrics.

Hooks still emit artifacts/sessions/hooks/*.jsonl for post-session analytics. CLI metrics supplement, do not replace, the JSONL stream.

Description

This skill teaches the conductor and delegating agents how to monitor and enforce session budgets in real time. Inspired by Athena's BudgetGatekeeper pattern, it adapts the concept to our multi-agent orchestration model — where the "cost" is distributed across 16 specialized agents using a 3-tier model allocation.

Unlike our existing token-thresholds.json (which enforces file-level token limits at validation time), this skill provides runtime session-level enforcement during active conductor workflows.

When to Use

This skill is relevant when:

• Conductor is orchestrating a multi-phase workflow with 3+ phases
• Multiple premium-tier agents are being invoked in sequence
• A workflow involves parallel subagent tracks (ULTRADEEP complexity)
• Session has been running for an extended period (15+ minutes)
• User requests cost-aware execution ("keep this lean", "minimize API usage")

When NOT to Use

• Do not use for single-turn questions or instant-complexity tasks that complete in one delegation.
• Do not use for static file-level token enforcement — that is handled by token-thresholds.json and scripts/token-report.ps1.

Entry Points

Trigger Phrases

• "budget check", "cost estimate", "token usage"
• "keep this lean", "minimize cost", "efficient execution"
• "how many delegations", "session cost"

Context Patterns

• Multi-phase workflows with 5+ phases
• Repeated reviewer → implementer iteration loops
• Three or more premium-tier agent invocations in one session
• Extended sessions exceeding 30 minutes

Core Knowledge

Budget Tracking Model

The conductor tracks four budget dimensions across a workflow session:

Model Tier Cost Weights

Each delegation carries a cost weight based on the target agent's model tier. Weights are approximate ratios based on current per-token pricing.

Annual Plan Multiplier Mode

If the workspace is still on annual-plan multipliers, override the weights with the policy multipliers (e.g., Opus 27x, Sonnet 6x) and treat premium invocations as budget-exception-only.

AI Credits Mode (Default)

Under usage-based billing, cost is driven by token volume and per-model pricing. The tier weights are directional only; apply stricter controls on context size and effort before escalating tiers.

Budget State Tracking

The conductor maintains a budget state block in its internal tracking, updated after every delegation:

## Budget Status
- **Delegations:** {used}/{limit} ({percentage}%)
- **Premium Calls:** {used}/{limit}
- **Est. Tokens:** ~{used}K / {limit}K
- **Session Time:** {elapsed} min / {limit} min
- **Effort Profile:** {High: N, Medium: N, Low: N}
- **Zone:** 🟢 Green | 🟡 Yellow (soft limit) | 🔴 Red (hard limit)

Effort-Weighted Token Estimates

Thinking effort affects token consumption within the same pricing tier. Use these weights for budget estimation:

When tracking estimated session tokens, multiply the base estimate by the effort weight:

• A Medium-effort delegation to implementer: ~25K tokens × 1.0 = ~25K
• A High-effort delegation to security: ~25K tokens × 1.5 = ~37.5K
• A Low-effort delegation to docs: ~25K tokens × 0.7 = ~17.5K

Yellow Zone Cost Saving via Effort Reduction

When approaching budget limits, reduce effort before switching model tiers:

1. Switch Execution-Medium agents to Execution-Low (save ~30% thinking tokens)
2. Use premium tier only for explicit security review requests
3. Reserve High effort for security and adversarial reviews only

Enforcement Patterns

Green Zone (0-79% of any limit)

Normal operation. No special actions needed.

Yellow Zone (80-99% of any limit — Soft Limit)

⚠️ **Budget Warning**: {dimension} at {percentage}% ({used}/{limit}).
Recommendations:
1. Consolidate remaining phases where possible
2. Consider switching premium agents to execution-tier alternatives:
   - researcher → implementer (if just gathering file contents)
   - planner → conductor (if plan adjustments are minor)
3. Create a handoff artifact if approaching token limit

Red Zone (100%+ of any limit — Hard Limit)

🛑 **Budget Limit Reached**: {dimension} at {used}/{limit}.
**MANDATORY PAUSE POINT**

Options:
a) **Checkpoint & Continue** — Save current progress to `artifacts/sessions/`, start fresh session
b) **Override** — User explicitly approves additional budget: "I acknowledge the budget override for {N} additional {delegations/calls}."
c) **Abort** — Stop workflow, preserve artifacts

Awaiting your decision before proceeding.

Premium-Tier Conservation Strategies

When approaching premium-tier limits, apply these substitution patterns:

Circuit Breaker Pattern

For destructive or high-risk operations, the conductor activates a circuit breaker independent of budget limits:

Ruin-Risk Detection

Trigger the circuit breaker when the workflow involves:

• File deletions affecting 5+ files or entire directories
• Security policy changes (auth, encryption, access control)
• Production environment modifications (deployment configs, infrastructure)
• PII or credential handling (schema changes, migration scripts)
• Irreversible operations (database migrations, external API calls with side effects)

Circuit Breaker Ceremony

⚠️ **CIRCUIT BREAKER ACTIVATED**

**Detected:** {ruin category} with estimated risk level: {LOW | MEDIUM | HIGH}
**Trigger:** {specific operation that triggered the breaker}
**Impact:** {what could go wrong if this proceeds without review}

**Required:** To proceed, you must:
1. Review the specific changes listed above
2. Confirm with: "I acknowledge the risk and approve proceeding with {operation}."

Any other response or no response = abort this operation.

Integration with Token Thresholds

This skill complements (does not replace) the existing static enforcement:

Session Handoff on Budget Exhaustion

When the conductor needs to hand off to a fresh session due to budget constraints:

## Session Handoff Artifact

**Save to:** `artifacts/sessions/{date}-{feature-slug}-handoff.md`

### Progress Summary
- **Original objective:** {user's request}
- **Completed phases:** {list with status}
- **Current phase:** {in-progress work}
- **Pending phases:** {remaining work}

### Context for Next Session
- **Key decisions made:** {list}
- **Open questions:** {list}
- **Artifacts created:** {paths}
- **Budget consumed:** {delegations, premium calls, est. tokens}

### Next Steps
1. {immediate next action}
2. {subsequent actions}

### Files Modified
{list of changed files with brief descriptions}

Examples

Example 1: Budget Check Mid-Workflow

## Budget Status
- **Delegations:** 12/20 (60%)
- **Premium Calls:** 1/3 (security review)
- **Est. Tokens:** ~280K / 500K
- **Session Time:** 18 min / 30 min
- **Zone:** 🟢 Green

All limits within normal range. Proceeding with Phase 4.

Example 2: Yellow Zone Warning

## Budget Status
- **Delegations:** 17/20 (85%)
- **Premium Calls:** 2/3 (67%)
- **Est. Tokens:** ~410K / 500K
- **Session Time:** 22 min / 30 min
- **Zone:** 🟡 Yellow

⚠️ **Budget Warning**: Delegations at 85% (17/20) and premium calls at 67% (2/3).
Recommendations:
1. Consolidate remaining 2 phases into a single implementer delegation
2. Use the `quick-review` prompt instead of full reviewer for the final phase
3. Skip optional documentation update — flag as follow-up task

Example 3: Circuit Breaker Activation

⚠️ **CIRCUIT BREAKER ACTIVATED**

**Detected:** Database migration affecting production schema
**Trigger:** Phase 3 implementation includes `ALTER TABLE users DROP COLUMN legacy_id`
**Impact:** Irreversible column deletion; any code referencing `legacy_id` will fail

**Required:** To proceed, you must:
1. Confirm no code references `legacy_id` (grep results show 0 matches)
2. Confirm with: "I acknowledge the risk and approve proceeding with schema migration."

Any other response = abort this operation.

References

• Token Thresholds: token-thresholds.json — static per-file limits
• Token Report Script: scripts/token-report.ps1 — validate token budgets
• Conductor Instructions: instructions/workflows/conductor.instructions.md — workflow rules and pause expectations
• Conductor Agent: .github/agents/conductor.agent.md — runtime orchestration entry point
• Model Selection: instructions/global/03_model-selection.instructions.md — tier definitions
• Conductor Lifecycle: .github/skills/conductor-lifecycle/SKILL.md — phase management
• Delegation Routing: .github/skills/delegation-routing/SKILL.md — agent selection
• Inspiration: Athena-Public BudgetGatekeeper pattern (MIT License)