feat: optional per-invocation MCP tool call cap

[dmartinol]

Summary

Adds MAX_TOOL_CALLS_PER_INVOCATION (default 0 = disabled) so operators can cap how many MCP tools may start in one ADK agent run. When the limit is exceeded, UsageTrackingPlugin.before_tool_callback short-circuits (ADK error dict); the tool is not executed and after_tool_callback does not run, so blocked calls are not persisted as usage tool_calls.

Motivation

• HTTP rate limiting (Redis) bounds incoming A2A requests per principal.
• Metering records completed work for billing/analytics.
• This layer bounds depth of a single run (model–tool loops), addressing a different abuse pattern than request rate limits.

Implementation

• Settings.max_tool_calls_per_invocation with env MAX_TOOL_CALLS_PER_INVOCATION.
• Per-invocation counter in UsageTrackingPlugin (invocation_id from ToolContext), guarded by asyncio.Lock.
• after_run_callback drops counters for the finished invocation to avoid unbounded memory growth.
• Log line on block includes call count, limit, and attempted tool= for clarity.

Limitations (documented)

Counters are in-memory per process — not shared across Cloud Run instances, Podman replicas, or multi-worker processes. docs/metering.md describes mitigations and a future Redis/DB direction for shared caps.

Testing

• make lint and make test pass.
• New tests in tests/test_usage_plugin.py: disabled limit (0), block after N starts, after_run_callback resets budget.

Documentation and deploy wiring

• docs/metering.md (per-invocation tool budget, diagram, comparison to rate limits, multi-instance caveat).
• docs/rate-limiting.md (three-layer table).
• docs/configuration.md (usage table; also lists existing metering env vars in the table).
• .env.example, CLAUDE.md, deploy/cloudrun/service.yaml, deploy/podman/lightspeed-agent-configmap.yaml.

Made with Cursor