Expand cycles-openclaw-budget-guard documentation with advanced features

[amavashev]

Summary

This PR significantly expands the documentation for the cycles-openclaw-budget-guard plugin with comprehensive coverage of advanced features, configuration options, and operational patterns. The updates reflect the full capabilities of the plugin beyond basic budget enforcement.

Key Changes

• Enhanced lifecycle hook descriptions: Updated the five OpenClaw lifecycle hooks table to clarify that both model and tool calls follow the reserve → commit → release protocol, with details on immediate model commitment and actual cost tracking via costEstimator callbacks.

• Chained model fallbacks: Documented support for ordered fallback chains (arrays) in modelFallbacks, allowing the plugin to select the cheapest affordable model when budget is low. Added modelBaseCosts configuration example.

• Tool access control: New section covering toolAllowlist and toolBlocklist with glob-style pattern matching (* wildcards) for fine-grained tool permission management.

• Graceful degradation strategies: Introduced composable low-budget strategies beyond model downgrading:

  • downgrade_model — use cheaper fallback models
  • reduce_max_tokens — append token limit guidance
  • disable_expensive_tools — block high-cost tools
  • limit_remaining_calls — cap remaining calls

• Dynamic cost estimation: Documented costEstimator callback for per-tool actual cost calculation based on execution duration and results, with fallback to estimates.

• Per-user and per-session scoping: Added section on userId and sessionId configuration for budget isolation, with runtime override via ctx.metadata.

• Reservation settings: Documented per-tool TTL and overage policy overrides (REJECT, ALLOW_IF_AVAILABLE, ALLOW_WITH_OVERDRAFT).

• Retry on denied reservations: Added configuration for automatic retry of denied tool reservations with configurable delay and max attempts.

• Budget transition alerts: Documented webhook and callback support for budget level changes (healthy → low → exhausted).

• Session analytics and cost breakdown: New section covering per-tool/model cost tracking, session summaries with timing and forecasts, and export via callback or webhook.

• End-user budget visibility: Documented automatic attachment of budget status to ctx.metadata["cycles-budget-guard-status"] for frontend UI display.

• Multi-currency support: Added configuration for per-tool and per-model currency overrides.

• Budget pools: Documented hierarchical budget scoping via parentBudgetId with pool balance visibility in hints and snapshots.

• Dry-run mode: New section on testing without a live Cycles server using in-memory simulation.

• Error handling: Documented structured error types (BudgetExhaustedError, ToolBudgetDeniedError) for programmatic error handling.

• Comprehensive configuration reference: Reorganized and expanded the configuration table into logical sections (core, thresholds, model, tool, prompts, reservations, strategies, retry, dry-run, scoping, transitions, analytics, pools) with 50+ documented fields.

• Updated verification section: Improved log output examples to match actual plugin output format.

• Removed phase 1 limitations: Removed outdated limitations section as the documentation now covers the full feature set.

Notable Implementation Details

• The prompt budget hint now includes forecast projections, pool balances, and token limit guidance when applicable.
• The plugin manages in-memory reservation maps to ensure proper settlement or release at agent_end.
• Blocklist takes precedence over allowlist in tool access control.
• Strategies are composable — multiple can be active simultaneously.
• Dry-run mode enables full plugin behavior testing without infrastructure dependencies.
• Budget snapshots are cached (default 5s TTL) to reduce Cycles server load.

https://claude.ai/code/session_01B9dEkb617462NNiRpgA96g