@khalilgharbaoui/opencode-claude-code-plugin 0.29.1 → 0.30.0

package/README.md

@@ -324,6 +324,24 @@ That beats whatever effort the call arrived with. It has to, because opencode re
 
 An agent that declares nothing keeps the inherited effort, so this changes nothing until a file asks for it. An unrecognised level is refused and the inherited one kept, since the CLI rejects a level it does not know. Compaction is exempt: its summary always gets the full budget.
 
+### The prompt cache an agent writes
+
+The third thing a turn costs is the prompt cache it writes, and the same file can state that too:
+
+```yaml
+cacheTtl: 5m
+```
+
+Or once, for every subagent that declares nothing, as `defaultSubagentCacheTtl` in the provider options. Values are `5m` and `1h`; anything else warns and leaves the CLI alone. It applies to headless spawns only: `/compact` and the experimental interactive transport keep the CLI's own default.
+
+Claude Code's automatic default is a 1-hour cache on a subscription, and a 1-hour cache write is billed above a 5-minute one. That trade pays off for a long-lived main session, which re-reads the cache it wrote. It does not pay off for a fan-out of short workers: each one writes an hour-long cache, finishes, and never reads it again, and all of it comes out of the same weekly limit. Declaring `cacheTtl: 5m` on the workers while the main session keeps the default is the point of the knob.
+
+**It is unset by default**, for the same reason `defaultSubagentModel` is: an upgrade must not quietly change how anybody's turns are cached.
+
+One piece of Claude Code trivia is worth stating plainly, because it is the opposite of what the names suggest. The CLI has a per-agent `experimental.cacheTtl` and a `CLAUDE_CODE_SUBAGENT_PROMPT_CACHE_TTL`, and **neither of them does anything to this plugin.** Both apply only to subagents the CLI runs itself, through its own `Task` tool, which this plugin disallows by default so that opencode runs the subagent instead. An opencode subagent arrives here as its own `doStream` and its own `claude --print` process, and the CLI counts that as a main conversation. So the knob that reaches every process this plugin spawns is the main-conversation one, `CLAUDE_CODE_PROMPT_CACHE_TTL`, which is what `cacheTtl` sets. Measured on CLI 2.1.280 by reading `usage.cache_creation` back off a real turn: the main variable moved the writes to `ephemeral_5m_input_tokens`; the subagent variable left them at 1 hour.
+
+Like model and effort, the TTL is part of the Claude session key, so changing it respawns rather than sharing a process. Compaction is exempt.
+
 To force an **account** rather than a model, pin the full string. This only applies if you declared [`accounts`](#multiple-claude-code-accounts) in the first place; with the default single-account setup there is nothing to pin. Both halves are needed, because the provider selects the account's config dir and the `@account` marker is what the model was registered under for that provider:
 
 ```yaml
@@ -434,6 +452,7 @@ reaches the CLI, so there is nothing there to fall back from.
 | `skipPermissions` | boolean | `true` | Pass `--dangerously-skip-permissions` to `claude`. It is still passed when `proxyTools` is set: proxied calls go through opencode's permission system regardless, but unproxied CLI built-ins do not. The one case where the flag is dropped is `permissionMode: "plan"`, because the CLI lets the skip flag override plan mode outright. See [Plan mode](#plan-mode). |
 | `permissionMode` | `acceptEdits` \| `auto` \| `bypassPermissions` \| `default` \| `dontAsk` \| `plan` | – | Forwarded to headless `claude --permission-mode`. `"plan"` also suppresses `--dangerously-skip-permissions` (see the row above). Not version-gated, so check that your installed CLI accepts the value. The [interactive transport](#interactive-transport-experimental) does not forward it. |
 | `permissionPreset` | `"read-only"` | – | A named permission posture, so you set one option instead of combining five and getting one wrong. Opt-in: unset is exactly today's behaviour. `"read-only"` replaces `skipPermissions`, `permissionMode`, `controlRequestBehavior` and `controlRequestToolBehaviors`, and filters the write and command tools out of `proxyTools`. See [Read-only mode](#read-only-mode). |
+| `defaultSubagentCacheTtl` | string | – | Prompt cache TTL (`5m` or `1h`) for plugin-discovered `mode: subagent` agents whose own definition states no `cacheTtl`. Reaches the CLI as `CLAUDE_CODE_PROMPT_CACHE_TTL`. Unset means the CLI keeps choosing, which is 1 hour on a subscription. An unrecognised value warns and changes nothing. See [The prompt cache an agent writes](#the-prompt-cache-an-agent-writes). |
 | `defaultSubagentModel` | string | – | Model that plugin-discovered `mode: subagent` agents run on when their own definition pins nothing. The caller's account is kept; only the model name changes. An agent's own `forceModel` wins over it, and an unknown id is refused rather than spawned. Unset means no implicit override at all. See [Subagents: your account, their model](#subagents-your-account-their-model). |
 | `fallbackModels` | string[] | – | Ordered models to try when the one a turn would run on is refused. The default for agents that declare no `fallbackModels` of their own; a per-agent list **replaces** this one rather than extending it. Always the same account, never a different one. Only two things arm it: the CLI refusing the model (`model_not_found`) and a usage limit on an account with no other account to offer. Each model is tried at most once per turn and an exhausted chain surfaces the original error. Unset means no chain at all. See [Fallback model chain](#fallback-model-chain). |
 | `proxyTools` | string[] | `["Bash", "Edit", "Write", "WebFetch", "Task"]` | Claude built-in tools to route through opencode's executor + permission UI. Opt-in extras: `"Question"`, `"Compress"`. See [Selective tool proxy](#selective-tool-proxy). |
@@ -766,6 +785,9 @@ sqlite3 ~/.local/share/opencode/opencode.db \
 
 - A small per-call latency hop through `127.0.0.1:<random>/mcp`.
 - Batched-edit ergonomics: with `Edit` proxied, Claude can no longer use `MultiEdit`, so a refactor that would have been one tool call becomes N single `Edit` calls.
+- **One extra Claude Code API call per `claude` process**, and it is a `ToolSearch`. A proxied tool reaches the model as an MCP tool, and Claude Code 2.1.280 defers MCP tools behind its own `ToolSearch` tool, so before the first proxied call of a session the model spends one request finding the tool. Claude's built-in `Bash` is never deferred, so an unproxied tool goes straight to the call.
+
+  Measured on 2.1.280 with `claude-haiku-4-5`, three runs a side, one `echo` command: 3 CLI API calls with `Bash` proxied against 2 with the CLI running it, and roughly twice the cache reads. It is paid **once per process, not once per call**: the same task with two sequential commands measured 4 calls against 3, with a single `ToolSearch` either way. It is also not a function of how many tools you have, since a run with `strictMcpConfig: true` and 28 tools still spent it. Setting `ENABLE_TOOL_SEARCH=0` does remove it, and costs far more than it saves (all ~164 tool definitions then sit in every prompt, which measured 2.5 to 4 times the total cost and tripped a compaction), so that is not a fix and the plugin does not do it. `ToolSearch` is one of Claude's internal tools, so you never see the call, only the cost. Full numbers: `docs/agents-history.md` under `#g166`.
 
 ### How a proxied call ends
 
@@ -863,6 +885,14 @@ It carries the startup-diagnostics fields (plugin version, opencode version, `cl
 - every pending proxy call, with the tool, the call id, how long it has waited, and its deadline,
 - each proxy server's URL with one unauthenticated `initialize` posted to it: `401, good` is the patched behaviour, and anything else is flagged unsafe with the fix (restart every opencode window, since a window opened before 0.13.2 keeps serving an open port). See [Proxy endpoint security](#proxy-endpoint-security).
 
+When Claude Code refused an entry in an `--mcp-config` it was handed, an **MCP config entries Claude Code skipped** section names each one with the CLI's own category and sentence. That section only appears when there is something in it. It matters because a skipped server is absent from the CLI's server list entirely rather than listed as broken, so the model silently does not have those tools; if the skipped name is `opencode_proxy` the report says so plainly, because then it is the plugin's own server and every proxied tool call in the session fails. The same thing is a warning in your terminal when it happens.
+
+```text
+/claude-code-doctor usage
+```
+
+adds a **Plan usage** section: the CLI's own answer to `/cost`, which is the subscription-or-API-key line, how much of the 5-hour and 7-day windows is used, when each resets, and what has been contributing to them. It is measured free (`num_turns: 0`, `$0`, no API call: the CLI answers it locally), so it costs no tokens and nothing is billed. It is opt-in anyway because reading it starts a short-lived `claude` process, which runs your `SessionStart` hooks and takes a few seconds. Without the argument the section says so and the report stays instant. A CLI that cannot answer leaves one line saying why and the rest of the report is unaffected.
+
 The `permissionPreset` row reads `provider: preset` for every registered provider, `none` where none is set, so two accounts configured with different postures are not collapsed into one answer. When a preset is in force, a **Permission preset overrides** block under the table lists the options it replaced, in the same words the log uses. A name the plugin does not recognise is reported as `readonly (unknown, nothing applied)` rather than shown as if it took effect: a typo'd safety option runs at full permissions, and the report is where you find that out. See [Read-only mode](#read-only-mode).
 
 Nothing secret goes in it: not the proxy bearer token, not the value of `ANTHROPIC_API_KEY`, not the system prompt, not a pending call's arguments. A `claude-code-doctor` command you defined yourself is never overwritten. The name has no space in it because opencode reads everything after the first space as the command's arguments. The whole exchange is kept out of any transcript replayed to the CLI, like a `/btw` pair.
@@ -1205,6 +1235,7 @@ The plugin respects the standard Claude Code thinking env vars. If you set them
 | Env var | Effect |
 |---|---|
 | `CLAUDE_CODE_EFFORT_LEVEL=<level>` | Session effort override. Passes through when no effort was requested; a variant or an agent's `reasoningEffort` replaces it for that spawn. |
+| `CLAUDE_CODE_PROMPT_CACHE_TTL=5m\|1h` | Prompt cache TTL for the whole machine. Passes through when no agent asked; an agent's `cacheTtl` or `defaultSubagentCacheTtl` replaces it for that spawn. |
 | `CLAUDE_CODE_DISABLE_THINKING=1` | Disable thinking entirely. |
 | `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1` | Disable adaptive thinking only. |
 | `CLAUDE_CODE_SHOW_THINKING_SUMMARIES=0` | Suppress summaries (the plugin sets this to `1` by default when unset). |

package/dist/index.d.ts

@@ -498,6 +498,14 @@ interface ClaudeCodeProviderSettings {
      * caller's model exactly as opencode intends. See `src/agent-models.ts`.
      */
     defaultSubagentModel?: string;
+    /**
+     * Prompt cache TTL (`"5m"` or `"1h"`) for subagents whose own definition
+     * states no `cacheTtl`. Unset (the default) means the plugin sets nothing
+     * and the CLI keeps choosing, which is 1 hour on a subscription. Setting
+     * `"5m"` is the cheaper trade for short-lived workers that never re-read
+     * the cache they wrote. See `resolveAgentCacheTtl` in `src/agent-models.ts`.
+     */
+    defaultSubagentCacheTtl?: string;
     /**
      * Models to try, in order, when the model a turn would have run on is
      * refused. The default for every agent that declares no `fallbackModels` of
@@ -939,6 +947,17 @@ interface ClaudeStreamMessage {
         name?: string;
         status?: string;
     }>;
+    /**
+     * `--mcp-config` entries the CLI refused to load. Omitted entirely when
+     * there are none, and an affected server is absent from `mcp_servers` too,
+     * which is why it needs its own field: a skipped server is invisible in the
+     * list. See `parseMcpServerErrors` in `cli-events.ts`.
+     */
+    mcp_server_errors?: Array<{
+        name?: string;
+        type?: string;
+        message?: string;
+    }>;
     compact_metadata?: Record<string, unknown>;
     compactMetadata?: Record<string, unknown>;
     rate_limit_info?: Record<string, unknown>;
@@ -1259,6 +1278,12 @@ type AgentRecord = {
     forceModel?: string;
     /** Thinking budget this agent wants, whatever the caller's picker says. */
     reasoningEffort?: string;
+    /**
+     * Prompt cache TTL for this agent's own `claude` process, `5m` or `1h`.
+     * See `resolveAgentCacheTtl` for why this is a main-conversation setting
+     * and not the CLI's per-agent `experimental.cacheTtl`.
+     */
+    cacheTtl?: string;
     /**
      * Models to try, in order, when the one this agent would have run is
      * refused. Same account throughout; see `src/model-fallback.ts`.

package/dist/index.js

@@ -405,6 +405,17 @@ function titleizeAccount(account) {
   return normalizeAccountName(account).split("-").filter(Boolean).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
 }
 
+// src/types.ts
+var READ_ONLY_PERMISSION_MODE = "read-only";
+var DEFAULT_PROXY_TOOL_NAMES = [
+  "Bash",
+  "Edit",
+  "Write",
+  "WebFetch",
+  "Task"
+];
+var PROXY_MCP_SERVER_NAME = "opencode_proxy";
+
 // src/cli-events.ts
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -529,6 +540,35 @@ function reportRateLimitEvent(msg) {
   log[report.level](report.message, data);
   return report.transcript;
 }
+var MCP_SERVER_ERROR_TYPES = {
+  unknown_type: "its `type` is not one Claude Code knows",
+  url_missing_type: "it has a `url` but no `type`",
+  invalid_config: "its configuration did not validate",
+  reserved_name: "its name is reserved"
+};
+function parseMcpServerErrors(msg) {
+  const raw = msg.mcp_server_errors;
+  if (!Array.isArray(raw)) return [];
+  const errors = [];
+  for (const entry of raw) {
+    if (!isRecord(entry)) continue;
+    errors.push({
+      name: str(entry.name) ?? "unknown",
+      type: str(entry.type) ?? "unknown",
+      message: str(entry.message) ?? ""
+    });
+  }
+  return errors;
+}
+function describeMcpServerError(error) {
+  const why = MCP_SERVER_ERROR_TYPES[error.type];
+  const reason = why ? ` because ${why}` : "";
+  const detail = error.message ? ` Claude Code said: ${error.message}` : "";
+  if (error.name === PROXY_MCP_SERVER_NAME) {
+    return `Claude Code skipped the plugin's own MCP server "${error.name}" (${error.type})${reason}, so every proxied tool call this session will fail. This is a plugin bug or a corrupted scratch config rather than something in your own MCP settings: report it with this line.${detail}`;
+  }
+  return `Claude Code skipped MCP server "${error.name}" (${error.type})${reason}, so its tools are not available to the model this session. Fix the entry in your MCP config.${detail}`;
+}
 var API_KEY_SOURCES = /* @__PURE__ */ new Set([
   "ANTHROPIC_API_KEY",
   "apiKeyHelper",
@@ -554,7 +594,8 @@ function parseSystemInit(msg) {
     model: str(raw.model),
     cliVersion: str(raw.claude_code_version),
     toolCount: Array.isArray(raw.tools) ? raw.tools.length : 0,
-    mcpServers: servers
+    mcpServers: servers,
+    mcpServerErrors: parseMcpServerErrors(msg)
   };
 }
 function apiKeySourceWarning(apiKeySource, ignoreAnthropicApiKey) {
@@ -564,6 +605,11 @@ function apiKeySourceWarning(apiKeySource, ignoreAnthropicApiKey) {
 }
 var warnedApiKeySources = /* @__PURE__ */ new Set();
 var warnedMcpFailures = /* @__PURE__ */ new Set();
+var warnedMcpSkips = /* @__PURE__ */ new Set();
+var lastMcpServerErrors = /* @__PURE__ */ new Map();
+function snapshotMcpServerErrors() {
+  return [...lastMcpServerErrors.values()];
+}
 function reportSystemInit(msg, options = {}) {
   const info = parseSystemInit(msg);
   if (!info) return;
@@ -573,8 +619,20 @@ function reportSystemInit(msg, options = {}) {
     model: info.model ?? null,
     cliVersion: info.cliVersion ?? null,
     tools: info.toolCount,
-    mcpServers: info.mcpServers
+    mcpServers: info.mcpServers,
+    mcpServerErrors: info.mcpServerErrors
   });
+  for (const error of info.mcpServerErrors) {
+    lastMcpServerErrors.set(error.name, error);
+    const key2 = `${error.name}:${error.type}`;
+    const message = describeMcpServerError(error);
+    if (warnedMcpSkips.has(key2)) {
+      log.debug(message, { server: error.name, type: error.type });
+      continue;
+    }
+    warnedMcpSkips.add(key2);
+    log.warn(message, { server: error.name, type: error.type });
+  }
   for (const server2 of info.mcpServers) {
     if (server2.status === "connected") continue;
     const key2 = `${server2.name}:${server2.status}`;
@@ -786,12 +844,13 @@ function unwrapToolOutput(part) {
   }
 }
 function unwrapOpencodeQuestionResult(value, question) {
-  if (!value.startsWith(OPENCODE_QUESTION_RESULT_PREFIX) || !value.endsWith(OPENCODE_QUESTION_RESULT_SUFFIX)) {
+  const sentence = value.trim();
+  if (!sentence.startsWith(OPENCODE_QUESTION_RESULT_PREFIX) || !sentence.endsWith(OPENCODE_QUESTION_RESULT_SUFFIX)) {
     return value;
   }
-  const body = value.slice(
+  const body = sentence.slice(
     OPENCODE_QUESTION_RESULT_PREFIX.length,
-    value.length - OPENCODE_QUESTION_RESULT_SUFFIX.length
+    sentence.length - OPENCODE_QUESTION_RESULT_SUFFIX.length
   );
   if (!body.startsWith('"') || !body.endsWith('"')) return value;
   let answer;
@@ -1420,7 +1479,7 @@ function isExpectedCleanupError(message) {
   return message.includes("timed out after") && message.includes("waiting for opencode to resolve") || message.includes("rejecting as orphaned") || message.includes("was orphaned by a new user turn") || message.includes("stream was aborted") || message.includes(SERVER_CLOSED_MESSAGE);
 }
 var PROTOCOL_VERSION = "2024-11-05";
-var SERVER_NAME = "opencode_proxy";
+var SERVER_NAME = PROXY_MCP_SERVER_NAME;
 var PROXY_TOOL_PREFIX = `mcp__${SERVER_NAME}__`;
 var PROXY_DEFAULT_TIMEOUT_MS = 10 * 60 * 1e3;
 var PROXY_NO_DEADLINE_MS = 0;
@@ -2706,16 +2765,6 @@ function clearCompression(sessionKey2) {
   compressions.delete(sessionKey2);
 }
 
-// src/types.ts
-var READ_ONLY_PERMISSION_MODE = "read-only";
-var DEFAULT_PROXY_TOOL_NAMES = [
-  "Bash",
-  "Edit",
-  "Write",
-  "WebFetch",
-  "Task"
-];
-
 // src/permission-presets.ts
 var READ_ONLY_DISALLOWED_CLI_TOOLS = [
   "Bash",
@@ -3082,6 +3131,9 @@ function claudeSpawnEnv(opts) {
   if (opts?.effort) {
     env.CLAUDE_CODE_EFFORT_LEVEL = cliEffortLevel(opts.effort);
   }
+  if (opts?.promptCacheTtl) {
+    env.CLAUDE_CODE_PROMPT_CACHE_TTL = opts.promptCacheTtl;
+  }
   if (opts?.ignoreAnthropicApiKey) {
     delete env.ANTHROPIC_API_KEY;
     delete env.ANTHROPIC_AUTH_TOKEN;
@@ -3367,19 +3419,20 @@ function invalidateOtherEffortSessions(baseKey, effort) {
     clearCompression(key);
   }
 }
-function spawnClaudeProcess(cliPath, cliArgs, cwd, sessionKey2, proxyServer, mcpHash, systemPromptFile, ignoreAnthropicApiKey, effort) {
+function spawnClaudeProcess(cliPath, cliArgs, cwd, sessionKey2, proxyServer, mcpHash, systemPromptFile, ignoreAnthropicApiKey, effort, promptCacheTtl) {
   evictIfNeeded();
   log.info("spawning new claude process", {
     cliPath,
     cliArgs,
     cwd,
     sessionKey: sessionKey2,
-    effort
+    effort,
+    promptCacheTtl
   });
   const proc = spawn(cliPath, cliArgs, {
     cwd,
     stdio: ["pipe", "pipe", "pipe"],
-    env: claudeSpawnEnv({ ignoreAnthropicApiKey, effort }),
+    env: claudeSpawnEnv({ ignoreAnthropicApiKey, effort, promptCacheTtl }),
     shell: process.platform === "win32"
   });
   const lineEmitter = new EventEmitter3();
@@ -3390,6 +3443,7 @@ function spawnClaudeProcess(cliPath, cliArgs, cwd, sessionKey2, proxyServer, mcp
     mcpHash,
     systemPromptFile,
     effort,
+    promptCacheTtl,
     startedAt: Date.now(),
     cliPath,
     cliArgs: [...cliArgs],
@@ -3496,7 +3550,8 @@ function respawnActiveProcess(sessionKey2, cliPath, cliArgs, cwd, ignoreAnthropi
     old.mcpHash,
     old.systemPromptFile,
     ignoreAnthropicApiKey,
-    old.effort
+    old.effort,
+    old.promptCacheTtl
   );
   replacement.pendingProxyCompletions = old.pendingProxyCompletions;
   delete old.pendingProxyCompletions;
@@ -3911,8 +3966,90 @@ async function handleBtwCommand(client, input, options = {}) {
   }
 }
 
-// src/startup-diagnostics.ts
+// src/plan-usage.ts
 import { execFile as execFile2 } from "child_process";
+var PLAN_USAGE_ARGUMENTS = /* @__PURE__ */ new Set(["usage", "cost", "stats", "limits"]);
+function wantsPlanUsage(argument) {
+  return PLAN_USAGE_ARGUMENTS.has(argument.trim().toLowerCase());
+}
+var PLAN_USAGE_MAX_CHARS = 4e3;
+function truncate(text) {
+  return text.length <= PLAN_USAGE_MAX_CHARS ? text : `${text.slice(0, PLAN_USAGE_MAX_CHARS)}
+[truncated]`;
+}
+function parsePlanUsage(stdout) {
+  const trimmed = stdout.trim();
+  if (!trimmed) return { status: "failed", error: "the CLI printed nothing" };
+  const candidates = trimmed.split("\n").reverse();
+  for (const line of candidates) {
+    const start = line.indexOf("{");
+    if (start === -1) continue;
+    let parsed;
+    try {
+      parsed = JSON.parse(line.slice(start));
+    } catch {
+      continue;
+    }
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) continue;
+    const record = parsed;
+    if (record.type !== void 0 && record.type !== "result") continue;
+    const text = typeof record.result === "string" ? record.result.trim() : "";
+    if (record.is_error === true) {
+      return { status: "failed", error: text || "the CLI reported an error" };
+    }
+    if (!text) continue;
+    return {
+      status: "ok",
+      text: truncate(text),
+      costUsd: typeof record.total_cost_usd === "number" ? record.total_cost_usd : 0,
+      numTurns: typeof record.num_turns === "number" ? record.num_turns : 0
+    };
+  }
+  return { status: "failed", error: "no result object in the CLI's reply" };
+}
+function runCli(cliPath, args, timeoutMs, env) {
+  return new Promise((resolve6, reject) => {
+    execFile2(
+      cliPath,
+      args,
+      // `killSignal` so a CLI wedged on a hook is actually gone, and a generous
+      // buffer because the reply is prose of unbounded length.
+      { timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: 4 * 1024 * 1024, env },
+      (error, stdout) => {
+        if (stdout && stdout.trim()) return resolve6(stdout);
+        if (error) return reject(error);
+        resolve6(stdout ?? "");
+      }
+    );
+  });
+}
+async function fetchPlanUsage(cliPath, options = {}) {
+  const timeoutMs = options.timeoutMs ?? 2e4;
+  const run = options.runImpl ?? runCli;
+  try {
+    const env = claudeSpawnEnv({ ignoreAnthropicApiKey: options.ignoreAnthropicApiKey });
+    const stdout = await run(
+      cliPath,
+      ["-p", "/cost", "--output-format", "json"],
+      timeoutMs,
+      env
+    );
+    const usage = parsePlanUsage(stdout);
+    if (usage.status === "ok") {
+      log.info("read claude plan usage", { costUsd: usage.costUsd, numTurns: usage.numTurns });
+    } else if (usage.status === "failed") {
+      log.debug("could not read claude plan usage", { error: usage.error });
+    }
+    return usage;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    log.debug("could not read claude plan usage", { error: message });
+    return { status: "failed", error: message };
+  }
+}
+
+// src/startup-diagnostics.ts
+import { execFile as execFile3 } from "child_process";
 import * as fs4 from "fs";
 import * as path5 from "path";
 import { promisify as promisify2 } from "util";
@@ -4447,7 +4584,7 @@ function pickOpencodeVersion(input) {
   if (typeof direct === "string" && direct.length > 0) return direct;
   return void 0;
 }
-var execFileAsync2 = promisify2(execFile2);
+var execFileAsync2 = promisify2(execFile3);
 var opencodeVersionProbe;
 function detectOpencodeVersion(execPath = process.execPath) {
   if (opencodeVersionProbe) return opencodeVersionProbe;
@@ -4557,7 +4694,7 @@ function logStartupDiagnostics(providers, opencodeVersion) {
 
 // src/doctor.ts
 var DOCTOR_COMMAND = "claude-code-doctor";
-var DOCTOR_COMMAND_DESCRIPTION = "Report what the Claude Code plugin sees: versions, cwd, live processes, pending proxy calls";
+var DOCTOR_COMMAND_DESCRIPTION = "Report what the Claude Code plugin sees: versions, cwd, live processes, pending proxy calls. Add `usage` for plan windows";
 var DOCTOR_MARKER = "\u258C **claude-code doctor**";
 function isRecord3(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -4687,6 +4824,36 @@ function formatDoctorReport(report) {
       lines.push(`| ${server2.url} | ${describeAuth(server2.auth)} |`);
     }
   }
+  if (report.mcpServerErrors.length > 0) {
+    lines.push("");
+    lines.push("**MCP config entries Claude Code skipped**");
+    lines.push("");
+    lines.push("| server | category | Claude Code said |");
+    lines.push("|---|---|---|");
+    for (const error of report.mcpServerErrors) {
+      lines.push(`| ${error.name} | \`${error.type}\` | ${error.message || "no detail"} |`);
+    }
+    lines.push("");
+    lines.push("A skipped server is missing from the model's tools with no other sign of it.");
+  }
+  lines.push("");
+  lines.push("**Plan usage**");
+  lines.push("");
+  switch (report.planUsage.status) {
+    case "ok":
+      lines.push("```text");
+      lines.push(report.planUsage.text);
+      lines.push("```");
+      break;
+    case "failed":
+      lines.push(`Could not read it from the CLI: ${report.planUsage.error}`);
+      break;
+    case "not-requested":
+      lines.push(
+        "Not checked. Run `/claude-code-doctor usage` for the account's plan windows and reset times, straight from the CLI. It costs no tokens, but it does start a `claude` process, so it runs your `SessionStart` hooks and takes a few seconds."
+      );
+      break;
+  }
   const stderr = report.processes.filter((proc) => proc.lastStderr);
   if (stderr.length > 0) {
     lines.push("");
@@ -4746,6 +4913,9 @@ async function gatherDoctorReport(options) {
       auth: await checkProxyAuth(proc.proxyUrl, options.fetchImpl ?? fetch)
     });
   }
+  const planUsage = wantsPlanUsage(options.argument ?? "") ? await (options.planUsageImpl ?? fetchPlanUsage)(cliPath, {
+    ignoreAnthropicApiKey: options.ignoreAnthropicApiKey
+  }) : { status: "not-requested" };
   return {
     plugin: base.plugin,
     opencode: base.opencode,
@@ -4762,7 +4932,9 @@ async function gatherDoctorReport(options) {
     anthropicApiKeyInEnv: base.anthropicApiKeyInEnv,
     processes,
     pendingCalls: snapshotPendingProxyCalls(),
-    proxyServers
+    proxyServers,
+    mcpServerErrors: snapshotMcpServerErrors(),
+    planUsage
   };
 }
 async function buildDoctorReport(options) {
@@ -4774,7 +4946,9 @@ async function buildDoctorReport(options) {
       cwd: report.cwd,
       processes: report.processes.length,
       pendingCalls: report.pendingCalls.length,
-      proxyServers: report.proxyServers.map((server2) => server2.auth.status)
+      proxyServers: report.proxyServers.map((server2) => server2.auth.status),
+      mcpServerErrors: report.mcpServerErrors.length,
+      planUsage: report.planUsage.status
     });
     return formatDoctorReport(report);
   } catch (error) {
@@ -5107,6 +5281,7 @@ function parseModelId(modelId) {
 
 // src/agent-models.ts
 var AGENT_DIR_NAMES = ["agents", "agent"];
+var PROMPT_CACHE_TTLS = ["5m", "1h"];
 var REASONING_EFFORTS = [
   "minimal",
   "low",
@@ -5117,6 +5292,7 @@ var REASONING_EFFORTS = [
 ];
 var registry = {};
 var defaultSubagentModel;
+var defaultSubagentCacheTtl;
 var providerFallbackModels = [];
 function setAgentRegistry(records) {
   registry = records;
@@ -5130,6 +5306,9 @@ function setDefaultSubagentModel(model) {
 function getDefaultSubagentModel() {
   return defaultSubagentModel;
 }
+function setDefaultSubagentCacheTtl(ttl) {
+  defaultSubagentCacheTtl = ttl?.trim() || void 0;
+}
 function setProviderFallbackModels(models) {
   providerFallbackModels = models ?? [];
 }
@@ -5194,6 +5373,25 @@ function resolveAgentEffort(agent, inherited, overrides) {
   }
   return declared;
 }
+function resolveAgentCacheTtl(agent, overrides) {
+  if (!agent) return void 0;
+  const record = (overrides?.records ?? registry)[agent];
+  if (!record) return void 0;
+  const fallback = overrides ? overrides.defaultSubagentCacheTtl : defaultSubagentCacheTtl;
+  const declared = record.cacheTtl?.trim();
+  const wanted = declared || (record.mode === "subagent" ? fallback?.trim() : void 0);
+  if (!wanted) return void 0;
+  if (!PROMPT_CACHE_TTLS.includes(wanted)) {
+    log.warn("agent prompt cache ttl refused: unknown value", {
+      agent,
+      wanted,
+      allowed: PROMPT_CACHE_TTLS.join(", ")
+    });
+    return void 0;
+  }
+  log.debug("agent prompt cache ttl", { agent, ttl: wanted });
+  return wanted;
+}
 function parseAgentFrontmatter(text) {
   const record = {};
   if (!text.startsWith("---")) return record;
@@ -5225,6 +5423,7 @@ function parseAgentFrontmatter(text) {
     else if (key === "model") record.model = value;
     else if (key === "forceModel") record.forceModel = value;
     else if (key === "reasoningEffort") record.reasoningEffort = value;
+    else if (key === "cacheTtl") record.cacheTtl = value;
   }
   return record;
 }
@@ -9353,9 +9552,15 @@ var ClaudeCodeLanguageModel = class {
       this.getOpencodeAgent(options),
       this.getReasoningEffort(options.providerOptions)
     );
+    const promptCacheTtl = compactionMode ? void 0 : resolveAgentCacheTtl(this.getOpencodeAgent(options));
+    const context = [
+      this.config.provider,
+      this.getOpencodeAgent(options) ?? null
+    ];
+    if (promptCacheTtl) context.push(promptCacheTtl);
     const baseKey = sessionKey(
       cwd,
-      `${effectiveModelId}::${scope}::${affinity}::context=${JSON.stringify([this.config.provider, this.getOpencodeAgent(options) ?? null])}`
+      `${effectiveModelId}::${scope}::${affinity}::context=${JSON.stringify(context)}`
     );
     const sk = compactionMode ? sessionKey(cwd, `${effectiveModelId}::compaction::${affinity}`) : effortSessionKey(baseKey, reasoningEffort);
     const toUsage2 = this.toUsage.bind(this);
@@ -9383,7 +9588,11 @@ var ClaudeCodeLanguageModel = class {
       const doctorOptions = {
         cliPath,
         interactive: !!useInteractive,
-        turnStats: this.config.turnStats === true
+        turnStats: this.config.turnStats === true,
+        ignoreAnthropicApiKey: this.config.ignoreAnthropicApiKey === true,
+        // `/claude-code-doctor usage` opts into the CLI's own plan-usage
+        // report; anything else here is ignored, as it always has been.
+        argument: doctor.rest
       };
       const stream2 = new ReadableStream({
         async start(controller) {
@@ -9943,7 +10152,8 @@ var ClaudeCodeLanguageModel = class {
                 spawnMcpHash,
                 spawnSystemPromptFile,
                 self.config.ignoreAnthropicApiKey,
-                reasoningEffort
+                reasoningEffort,
+                promptCacheTtl
               );
               state.proc = ap.proc;
               state.lineEmitter = ap.lineEmitter;
@@ -11351,6 +11561,10 @@ async function buildAgentRegistry(config) {
   setDefaultSubagentModel(
     typeof configured === "string" ? configured : void 0
   );
+  const configuredTtl = options?.defaultSubagentCacheTtl;
+  setDefaultSubagentCacheTtl(
+    typeof configuredTtl === "string" ? configuredTtl : void 0
+  );
   setProviderFallbackModels(parseFallbackModelList(options?.fallbackModels));
   const records = await readAgentMarkdownRecords(
     agentDirectories(
@@ -11372,6 +11586,7 @@ async function buildAgentRegistry(config) {
       model: pick("model") ?? records[name]?.model,
       forceModel: pick("forceModel") ?? records[name]?.forceModel,
       reasoningEffort: pick("reasoningEffort") ?? records[name]?.reasoningEffort,
+      cacheTtl: pick("cacheTtl") ?? records[name]?.cacheTtl,
       fallbackModels: declaredChain.length ? declaredChain : records[name]?.fallbackModels
     };
   }