feat(tools): add key_usage tool reporting API-key usage levels

Adds an agent-callable `key_usage` tool that reports current usage for
configured API keys so the agent can pick a key with headroom, warn before
hitting a rate limit, and diagnose exhausted-key failures.

Per key it reports: provider, active/exhausted status (with last error +
when it was exhausted), remaining rate-limit headroom and reset timestamp per
window (5-hour, weekly, and monthly where the provider exposes it), and
whether the figures are live or served from cache (with the cache's
last-fetched-from-source time). Supports anthropic and opencode-go keys
(live with cache fallback for anthropic; live scrape for opencode-go).
Optional `key_id` reports one key; omitted reports all.

Hard permission gate `perm_key_usage` (default off): when disabled the tool
is completely removed from the toolset/context. Registered in both the
parent permission-gated path and the child whitelist path, advertised in the
system prompt (TOOL_DESCRIPTIONS), grantable to subagents via the summon
enum, and exposed as a frontend tool-permission checkbox.

To report data freshness, claude.ts gains `getAccountUsageWithSource` +
`ClaudeUsageResult` (live vs cache + cachedAt from usage_cache.cached_at);
the existing `getAccountUsage` now delegates to it, preserving behavior.

Tests: core key-usage tool suite (windows, %-conversion, freshness, exhausted
status, unsupported/unavailable, filtering) + agent-manager perm-gate test.

1 files changed, 30 insertions, 0 deletions

diff --git a/packages/api/tests/agent-manager.test.ts b/packages/api/tests/agent-manager.test.ts
index dbbcc65..788106e 100644
--- a/packages/api/tests/agent-manager.test.ts
+++ b/packages/api/tests/agent-manager.test.ts
@@ -472,6 +472,14 @@ vi.mock("@dispatch/core", () => ({
 			execute: async () => "mock",
 		};
 	},
+	createKeyUsageTool(_callbacks: unknown) {
+		return {
+			name: "key_usage",
+			description: "key usage",
+			parameters: { _type: "z.ZodObject", shape: {} },
+			execute: async () => "mock",
+		};
+	},
 	createSearchCodeTool(_wd: string) {
 		return {
 			name: "search_code",
@@ -1568,6 +1576,28 @@ describe("AgentManager", () => {
 		});
 	});
 
+	describe("key_usage permission gate", () => {
+		// The key_usage tool is conditionally useful, so it must be COMPLETELY
+		// absent from the toolset (and thus the model's context) unless
+		// perm_key_usage is explicitly allowed.
+		async function toolsForPerms(tabId: string, perms: Record<string, string>): Promise<string[]> {
+			for (const [k, v] of Object.entries(perms)) setFakeSetting(k, v);
+			const manager = new AgentManager();
+			await manager.processMessage(tabId, "go");
+			return constructedAgents.at(-1)?.toolNames ?? [];
+		}
+
+		it("registers key_usage when perm_key_usage is allowed", async () => {
+			const tools = await toolsForPerms("tab-key-usage-on", { perm_key_usage: "allow" });
+			expect(tools).toContain("key_usage");
+		});
+
+		it("omits key_usage when perm_key_usage is not allowed", async () => {
+			const tools = await toolsForPerms("tab-key-usage-off", {});
+			expect(tools).not.toContain("key_usage");
+		});
+	});
+
 	// Regression: granted tab-messaging tools must also be ADVERTISED in the
 	// agent's system prompt. The tools were registered in the API tool payload
 	// but `buildSystemPrompt` filtered its "You have access to the following