@hienlh/ppm 0.23.22 → 0.23.24

package/src/providers/claude-agent-sdk.ts

@@ -7,7 +7,7 @@ import {
   getSessionInfo as sdkGetSessionInfo,
   getSessionMessages,
 } from "@anthropic-ai/claude-agent-sdk";
-import { allowedToolsFor, buildModelQueryOptions, buildSystemPromptOption, buildToolHooks, CLAUDE_DB_TOOLS, CLAUDE_TAB_TOOLS, dbToolsMcpServers, designMcpServers, fileWriteTarget, preToolUseDecision, READ_ONLY_TOOLS, shellHookCall, tabToolsMcpServers, withSessionTokenMasked } from "./claude-agent-sdk-query-options.ts";
+import { allowedToolsFor, buildModelQueryOptions, CLAUDE_SETTING_SOURCES, buildSystemPromptOption, buildToolHooks, CLAUDE_DB_TOOLS, CLAUDE_TAB_TOOLS, dbToolsMcpServers, designMcpServers, fileWriteTarget, preToolUseDecision, READ_ONLY_TOOLS, shellHookCall, tabToolsMcpServers, withSessionTokenMasked } from "./claude-agent-sdk-query-options.ts";
 import { localServerBaseUrl } from "../services/server-listen-address.ts";
 import { TAB_TOOLS_MCP_PATH, tabToolsMcpAccessFor } from "../services/tab-tools-mcp/tab-tools-mcp-tokens.ts";
 import { DB_TOOLS_MCP_PATH, dbToolsMcpAccessFor } from "../services/db-ai-tools/db-ai-tools-tokens.ts";
@@ -19,6 +19,10 @@ import { captureBaseline } from "../services/session-file-baselines/session-file
 import { observeFile } from "../services/session-file-baselines/session-file-history.ts";
 import { beginShellCommand, endShellCommand, noteFileToolWrite } from "../services/session-file-baselines/shell-change-tracker.ts";
 import { WarmSpares, spawnFingerprint } from "./claude-warm-spare.ts";
+import { APPROVAL_WAKE, ApprovalQueue } from "./claude-approval-queue.ts";
+import { EFFORT_ENV_VAR, effortStatusFromCli, estimateEffortStatus, userSettingsFile, type EffortSettingsQuery } from "./claude-effort-status.ts";
+import type { EffortStatus } from "../shared/effort-status.ts";
+import { withTimeout } from "../services/mcp-oauth/mcp-control-query.ts";
 import { CLAUDE_DESIGN_CHECK_TOOL } from "../services/design/mcp/design-mcp-tool.ts";
 import { designToolDecision } from "../services/design/design-tool-policy.ts";
 import { CLAUDE_MODELS } from "../types/claude-models.ts";
@@ -62,6 +66,8 @@ const usageLog = createLogger("usage");
 const mcpControlLog = createLogger("mcp-control");
 
 const CLAUDE_PROJECTS_DIR = resolve(homedir(), ".claude/projects");
+/** A running CLI answers `get_settings` in a few ms; this only bounds one that never does. */
+const EFFORT_READ_TIMEOUT_MS = 5_000;
 
 /**
  * Resolve the Claude CLI the SDK should spawn.
@@ -221,6 +227,14 @@ interface StreamingSession {
   lastUserContent: string;
   /** Latest user message images — updated on follow-ups for accurate retry */
   lastUserImages?: Array<{ data: string; mediaType: string }>;
+  /**
+   * A user message has been pushed whose turn has not finished.
+   *
+   * A crash retry may only re-send a prompt while this is true. Without it the retry re-sent
+   * whatever content it could find into a session that was simply idle, and an instruction the
+   * user gave hours earlier ran a second time as a real turn.
+   */
+  awaitingReply?: boolean;
   /** The sign-in this subprocess was started with — see `SubprocessCredential`. */
   credential: SubprocessCredential;
 }
@@ -283,6 +297,8 @@ export class ClaudeAgentSdkProvider implements AIProvider {
    * and this is the only place that knows what made it do so.
    */
   private teardownReasons = new Map<string, string>();
+  /** The `--effort` each session's CLI was started with, to set beside what it reports sending. */
+  private startedEffort = new Map<string, string | null>();
   /** The API's last rate-limit status per account and limit, so only a change is logged. */
   private rateLimitStatus = new Map<string, string>();
   /** CLIs started for chats that do not exist yet — see `prewarm`. */
@@ -738,6 +754,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       }
     }
     this.forkSources.delete(sessionId);
+    this.startedEffort.delete(sessionId);
 
     // Best-effort: delete JSONL from ~/.claude/projects/
     try {
@@ -829,6 +846,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     // Track latest message for retry paths (fixes stale firstMsg bug)
     ss.lastUserContent = modelInput;
     ss.lastUserImages = opts?.images;
+    ss.awaitingReply = true;
     log.debug(`pushMessage: session=${sessionId} priority=${opts?.priority ?? 'next'}`);
   }
 
@@ -933,7 +951,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       ...(p.forkSession && { forkSession: true }),
       cwd: p.cwd,
       systemPrompt: p.systemPrompt,
-      settingSources: ["user", "project"],
+      settingSources: [...CLAUDE_SETTING_SOURCES],
       env: p.env,
       settings: { permissions: { allow: [], deny: [] } },
       allowedTools: p.allowedTools,
@@ -1177,12 +1195,8 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     const dbToolsMcp = opts?.designSession ? undefined : opts?.dbToolsMcp;
     const allowedTools = allowedToolsFor({ isBypass, agentTeams: providerConfig.agent_teams, designPolicy, designCheckTool });
 
-    /**
-     * Approval events to yield from the generator.
-     * PreToolUse hook pushes events here; the main loop yields them.
-     */
-    const approvalEvents: ChatEvent[] = [];
-    let approvalNotify: (() => void) | undefined;
+    /** Approval requests from canUseTool and the PreToolUse hook, handed out by the main loop. */
+    const approvals = new ApprovalQueue<ChatEvent>();
 
     /**
      * Helper: send approval request to FE and wait for response.
@@ -1193,8 +1207,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       const promise = new Promise<{ approved: boolean; data?: unknown }>((resolve) => {
         this.pendingApprovals.set(requestId, { resolve, sessionId });
       });
-      approvalEvents.push({ type: "approval_request", requestId, tool: toolName, input });
-      approvalNotify?.();
+      approvals.push({ type: "approval_request", requestId, tool: toolName, input });
       return promise;
     };
 
@@ -1460,12 +1473,32 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         providerConfig,
         stderr: stderrCallback,
       });
+      // Every retry below restarts the CLI with these same options.
+      this.startedEffort.set(sessionId, (queryOptions.effort as string | undefined) ?? null);
 
       // Crash retry: if subprocess exits with non-zero code before producing events,
       // clean up and retry once with a fresh query before surfacing the error.
       const MAX_CRASH_RETRIES = 1;
       let crashRetryCount = 0;
 
+      /**
+       * What the crashed subprocess was doing, read off its session entry before that entry is
+       * deleted. Undefined until a crash. `awaiting` false means no turn was in flight, and a
+       * retry must then push nothing at all: the session is only being rebuilt so the next real
+       * message has somewhere to go.
+       */
+      let crashed: { content: string; images?: Array<{ data: string; mediaType: string }>; awaiting: boolean } | undefined;
+
+      // Once the turn has produced output (top-level assistant text/tool_use), the user
+      // message + any tool_results are persisted to JSONL. Mid-turn retries must resume and
+      // continue — NOT re-push the original message, which restarts the turn and re-displays
+      // an already-answered AskUserQuestion.
+      //
+      // Declared outside `crashRetryLoop` on purpose: inside it, a crash re-entered the loop
+      // body and cleared the very flag that keeps the retry from re-sending the prompt. It is
+      // reset at the end of each turn instead.
+      let turnProgressed = false;
+
       crashRetryLoop: for (;;) {
       try {
       // Streaming input: create message channel and persistent query.
@@ -1479,11 +1512,6 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         session_id: sessionId,
       };
 
-      // Once the turn has produced output (top-level assistant text/tool_use), the user
-      // message + any tool_results are persisted to JSONL. Mid-turn retries must resume and
-      // continue — NOT re-push the original message, which restarts the turn and re-displays
-      // an already-answered AskUserQuestion. Persists across retryLoop iterations.
-      let turnProgressed = false;
 
       // Build a retry message for token-refresh / transient-error retries.
       // Pre-turn (nothing persisted yet): re-push the LATEST user content so the SDK has a
@@ -1494,8 +1522,10 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       // Also returns the raw content/images for re-populating the new streaming session.
       const buildRetryMsg = () => {
         const ss = this.streamingSessions.get(sessionId);
-        const content = ss?.lastUserContent ?? modelInput;
-        const images = ss?.lastUserImages;
+        // `crashed` is the only source once the entry is gone: `?? modelInput` would otherwise
+        // reach past every follow-up to the message that opened the stream, hours earlier.
+        const content = ss?.lastUserContent ?? crashed?.content ?? modelInput;
+        const images = ss?.lastUserImages ?? crashed?.images;
         const retryContent = turnProgressed ? "Continue from where you left off." : content;
         return {
           msg: {
@@ -1516,9 +1546,14 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         : undefined;
       const channel = spare ? undefined : createMessageChannel();
       const initialCtrl = spare?.controller ?? channel!.controller;
-      // On crash retry, use buildRetryMsg to get the latest user message (not the stale firstMsg)
+      // On crash retry, use buildRetryMsg to get the latest user message (not the stale firstMsg).
+      // A crash with no turn in flight pushes NOTHING: the subprocess is replaced so the next real
+      // message has somewhere to go, and re-sending a finished instruction runs it a second time.
       const initRetry = crashRetryCount > 0 ? buildRetryMsg() : null;
-      initialCtrl.push(initRetry?.msg ?? firstMsg);
+      const resendOnCrash = crashRetryCount > 0 && crashed?.awaiting === true;
+      if (crashRetryCount === 0) initialCtrl.push(firstMsg);
+      else if (resendOnCrash && initRetry) initialCtrl.push(initRetry.msg);
+      else log.info(`session=${sessionId} crash retry rebuilt the subprocess with no turn to resume — nothing re-sent`);
       const initContent = initRetry?.lastUserContent ?? modelInput;
       const initImages = initRetry?.lastUserImages ?? opts?.images;
 
@@ -1533,7 +1568,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       // The query's one start line: a warm CLI and the MCP servers belong to it.
       log.info(`query: session=${sessionId} isFirst=${isFirstMessage} fork=${shouldFork} cwd=${effectiveCwd} platform=${process.platform} accountMode=${!!account} permissionMode=${permissionMode} isBypass=${isBypass}`
         + ` cli=${spare ? `warm ageMs=${spare.ageMs}` : "cold"}${crashRetryCount > 0 ? ` crashRetry=${crashRetryCount}` : ""} mcp=${Object.keys(mcpServers).join(",") || "none"}`);
-      this.streamingSessions.set(sessionId, { meta, query: initialQuery, controller: initialCtrl, lastUserContent: initContent, lastUserImages: initImages, credential: queryCredential });
+      this.streamingSessions.set(sessionId, { meta, query: initialQuery, controller: initialCtrl, lastUserContent: initContent, lastUserImages: initImages, awaitingReply: crashRetryCount === 0 || resendOnCrash, credential: queryCredential });
       this.activeQueries.set(sessionId, initialQuery);
       let eventSource: AsyncIterable<any> = initialQuery;
       log.debug(`session=${sessionId} query() created, waiting for first SDK event...`);
@@ -1610,7 +1645,12 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       assistantContent = "";
       pendingToolCount = 0;
       let sdkEventCount = 0;
-      for await (const msg of eventSource) {
+      for await (const msg of approvals.alongside(eventSource)) {
+        // An approval goes out now: the CLI sends nothing more until it is answered.
+        if (msg === APPROVAL_WAKE) {
+          yield* approvals.drain();
+          continue;
+        }
         sdkEventCount++;
         hadAnyEvents = true;
         if (sdkEventCount === 1) {
@@ -1640,9 +1680,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         const parentId = (msg as any).parent_tool_use_id as string | undefined;
 
         // Yield any queued approval events
-        while (approvalEvents.length > 0) {
-          yield approvalEvents.shift()!;
-        }
+        yield* approvals.drain();
 
         // Log system events for debugging SDK lifecycle: the subtype only, never the message.
         // thinking_tokens and status=requesting arrive at token rate, so not even at DEBUG.
@@ -2395,6 +2433,12 @@ export class ClaudeAgentSdkProvider implements AIProvider {
             }
           }
 
+          // The turn is over: a crash from here on has nothing to resume, and must not re-send
+          // this instruction. `turnProgressed` goes with it, so the next turn starts clean.
+          const finished = this.streamingSessions.get(sessionId);
+          if (finished) finished.awaitingReply = false;
+          turnProgressed = false;
+
           // Streaming input: yield done for this turn, then continue for next turn
           yieldedDone = true;
           yield {
@@ -2430,9 +2474,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       }
 
       // Yield remaining approval events
-      while (approvalEvents.length > 0) {
-        yield approvalEvents.shift()!;
-      }
+      yield* approvals.drain();
 
       if (!hadAnyEvents) {
         yield { type: "error", message: "Claude did not respond. Check that 'claude' CLI works in your terminal." };
@@ -2444,10 +2486,17 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       const crashMsg = (crashErr as Error).message ?? String(crashErr);
       const stderrInfo = stderrBuffer.trim() ? ` stderr: ${stderrBuffer.trim().slice(-500)}` : "";
 
-      // Clean up crashed subprocess before retry or error
+      // Clean up crashed subprocess before retry or error. Read what the turn was doing FIRST:
+      // the retry below needs it, and deleting the entry is what used to send it back to the
+      // message that opened the stream.
       this.activeQueries.delete(sessionId);
       const ss = this.streamingSessions.get(sessionId);
-      if (ss) { ss.controller.done(); ss.query.close(); this.streamingSessions.delete(sessionId); }
+      if (ss) {
+        crashed = { content: ss.lastUserContent, images: ss.lastUserImages, awaiting: ss.awaitingReply === true };
+        ss.controller.done(); ss.query.close(); this.streamingSessions.delete(sessionId);
+      } else {
+        crashed = { content: modelInput, images: opts?.images, awaiting: false };
+      }
       log.debug(`session=${sessionId} streaming session ended`);
 
       // Each case below logs itself: a cancel or a closed socket is not a failure.
@@ -2533,7 +2582,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
         ...(needsNodeInterpreter(process.platform, cliExecutablePath) && { executable: "node" }),
         ...(cliExecutablePath && { pathToClaudeCodeExecutable: cliExecutablePath }),
         cwd,
-        settingSources: ["user", "project"],
+        settingSources: [...CLAUDE_SETTING_SOURCES],
         // No account: MCP OAuth tokens belong to the CLI's own credential store, the same
         // one an interactive `claude` writes, and no model call is ever made here.
         env: this.buildQueryEnv(cwd, null),
@@ -2578,6 +2627,39 @@ export class ClaudeAgentSdkProvider implements AIProvider {
     }
   }
 
+  /**
+   * The effort this session's CLI sends and what overrides the pick, asked of the CLI itself:
+   * `CLAUDE_CODE_EFFORT_LEVEL`, a settings cap, an organization limit and the model's own levels
+   * all count there, while the `--effort` PPM passed is only one input to it. Null when the
+   * session has no live subprocess or the CLI does not answer.
+   */
+  async readEffortStatus(sessionId: string): Promise<EffortStatus | null> {
+    const ss = this.streamingSessions.get(sessionId);
+    if (!ss) return null;
+    const cli = ss.query as unknown as EffortSettingsQuery;
+    try {
+      const [answer, init] = await Promise.all([
+        withTimeout(cli.getSettings(), EFFORT_READ_TIMEOUT_MS, "Claude did not report its settings"),
+        withTimeout(cli.initializationResult(), EFFORT_READ_TIMEOUT_MS, "Claude did not report its models").catch(() => undefined),
+      ]);
+      return effortStatusFromCli({
+        answer,
+        models: init?.models,
+        requested: this.startedEffort.get(sessionId),
+        processEnv: process.env[EFFORT_ENV_VAR],
+        userFile: userSettingsFile(process.env).shown,
+      });
+    } catch (e) {
+      log.debug(`session=${sessionId} effort status unavailable: ${(e as Error).message}`);
+      return null;
+    }
+  }
+
+  /** What the settings files say about effort for a chat in `projectPath` no CLI has answered for yet. */
+  estimateEffortStatus(projectPath: string | undefined, model?: string): EffortStatus {
+    return estimateEffortStatus({ projectPath, model, env: process.env });
+  }
+
   /** Abort and fully teardown the streaming session — user must resume to continue */
   abortQuery(sessionId: string, source = "unknown"): void {
     const ss = this.streamingSessions.get(sessionId);

package/src/providers/claude-approval-queue.ts

@@ -0,0 +1,75 @@
+/** What `alongside` yields instead of a message when only the queue has something to hand out. */
+export const APPROVAL_WAKE = Symbol("approval-wake");
+
+/**
+ * Approval requests raised from the CLI's callbacks (`canUseTool`, the PreToolUse hook), for the
+ * turn's loop over the CLI's messages to hand out.
+ *
+ * The CLI asks through a control request and then says nothing until it is answered, so a queue
+ * looked at only when the next message arrives can wait forever: an AskUserQuestion stayed behind
+ * a thinking spinner for 17 minutes, until the user cancelled. Whether the turn's last message
+ * landed before or after the callback ran decided it, which is why it looked intermittent.
+ */
+export class ApprovalQueue<E> {
+  private readonly queued: E[] = [];
+  private wake: (() => void) | undefined;
+
+  push(event: E): void {
+    this.queued.push(event);
+    this.wake?.();
+  }
+
+  *drain(): Generator<E> {
+    while (this.queued.length > 0) yield this.queued.shift()!;
+  }
+
+  /**
+   * `source`'s items, plus `APPROVAL_WAKE` whenever something is queued and `source` has nothing
+   * to give. The caller must drain the queue on a wake, or it is woken again at once.
+   */
+  async *alongside<T>(source: AsyncIterable<T>): AsyncGenerator<T | typeof APPROVAL_WAKE> {
+    const it = source[Symbol.asyncIterator]();
+    // Kept across wakes: a second next() would hand this item to a promise nobody reads.
+    let next: Promise<IteratorResult<T>> | undefined;
+    // Closed on an early exit, as `for await` closes it: not once it has ended or thrown.
+    let open = true;
+    try {
+      for (;;) {
+        if (this.queued.length > 0) {
+          yield APPROVAL_WAKE;
+          continue;
+        }
+        const pending = (next ??= it.next());
+        let got: IteratorResult<T> | typeof APPROVAL_WAKE;
+        try {
+          got = await new Promise<IteratorResult<T> | typeof APPROVAL_WAKE>((resolve, reject) => {
+            this.wake = () => resolve(APPROVAL_WAKE);
+            // next() may have run a callback that queued something before there was a wake to call.
+            if (this.queued.length > 0) this.wake();
+            pending.then(resolve, reject);
+          });
+        } catch (e) {
+          open = false;
+          throw e;
+        } finally {
+          this.wake = undefined;
+        }
+        if (got === APPROVAL_WAKE) continue;
+        next = undefined;
+        if (got.done) {
+          open = false;
+          return;
+        }
+        yield got.value;
+      }
+    } finally {
+      if (open && next) {
+        // Not awaited: an async generator's return() waits behind the next() still out, which
+        // the CLI answers only after the approval it is waiting on.
+        Promise.resolve().then(() => it.return?.()).catch(() => {});
+      } else if (open) {
+        await it.return?.();
+      }
+    }
+  }
+}

package/src/providers/claude-effort-status.ts

@@ -0,0 +1,211 @@
+/**
+ * What decides a Claude session's effort besides the pick, worked out from the same settings
+ * the CLI reads. The live answer comes from the running CLI (`readEffortStatus` in the
+ * provider); until a turn has started one, `estimateEffortStatus` reads the settings files
+ * the CLI would, which is enough for the common overrides and is replaced by the CLI's own
+ * answer as soon as there is one.
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import * as nodePath from "node:path";
+import { join } from "node:path";
+import {
+  effortEnvMeaning, effortRank, isEffortLevel,
+  type EffortLevel, type EffortSetting, type EffortSettingSource, type EffortStatus,
+} from "../shared/effort-status.ts";
+import { CLAUDE_SETTING_SOURCES, type ClaudeSettingSource } from "./claude-agent-sdk-query-options.ts";
+
+export const EFFORT_ENV_VAR = "CLAUDE_CODE_EFFORT_LEVEL";
+
+/** One entry of `get_settings`'s `sources`, which the CLI orders from lowest priority to highest. */
+export interface CliSettingsSource {
+  source: string;
+  settings: Record<string, unknown>;
+}
+
+/**
+ * The part of the `get_settings` answer read here. `getSettings()` is on the SDK's `Query`
+ * object but left out of `sdk.d.ts`, which is why this is typed here; a test asserts the SDK
+ * still has it, so an upgrade that renames it fails loudly instead of the status going quiet.
+ */
+export interface CliSettingsAnswer {
+  sources?: Array<CliSettingsSource | null>;
+  /** What the session sends after env overrides, caps and model downgrades. */
+  applied?: { model?: string; effort?: string | null };
+}
+
+/** A model as the CLI's `initialize` answer lists it. */
+export interface CliModelInfo {
+  value: string;
+  resolvedModel?: string;
+  supportedEffortLevels?: string[];
+}
+
+export interface EffortSettingsQuery {
+  getSettings(): Promise<CliSettingsAnswer>;
+  initializationResult(): Promise<{ models?: CliModelInfo[] }>;
+}
+
+type PathApi = Pick<typeof nodePath, "join" | "relative" | "isAbsolute" | "sep">;
+
+/**
+ * Where the CLI keeps its user settings; `~/` stands in for the home folder in what is shown.
+ * Decided with `relative` rather than a `${home}/` prefix, which never matches a Windows path.
+ */
+export function userSettingsFile(
+  env: Record<string, string | undefined>,
+  home = homedir(),
+  path: PathApi = nodePath,
+): { path: string; shown: string } {
+  const file = path.join(env.CLAUDE_CONFIG_DIR || path.join(home, ".claude"), "settings.json");
+  const rel = path.relative(home, file);
+  const inHome = rel !== "" && rel !== ".." && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
+  return { path: file, shown: inHome ? `~/${rel.split(path.sep).join("/")}` : file };
+}
+
+const FILE_OF: Partial<Record<EffortSettingSource, string>> = {
+  projectSettings: ".claude/settings.json",
+  localSettings: ".claude/settings.local.json",
+};
+
+function place(source: string, userFile: string): Pick<EffortSetting<unknown>, "source" | "file"> {
+  const known = source as EffortSettingSource;
+  const file = source === "userSettings" ? userFile : FILE_OF[known];
+  return { source: known, ...(file && { file }) };
+}
+
+/** `modelSettings` keys name a model the way its dated, `[1m]`, Bedrock and Vertex spellings all match. */
+function modelKey(model: string): string {
+  return model.toLowerCase()
+    .replace(/\[[^\]]*\]$/, "")
+    .replace(/@.*$/, "")
+    .replace(/-v\d+(?::\d+)?$/, "")
+    .replace(/^(?:[a-z-]+\.)?anthropic\./, "")
+    .replace(/-\d{8}$/, "");
+}
+
+/** A source's own cap for the model: a matching `modelSettings` entry replaces its `maxEffortLevel`. */
+function sourceCap(settings: Record<string, unknown>, model: string | undefined): unknown {
+  const perModel = settings.modelSettings;
+  if (model && perModel && typeof perModel === "object") {
+    const key = modelKey(model);
+    let lowest: EffortLevel | undefined;
+    for (const [name, entry] of Object.entries(perModel as Record<string, unknown>)) {
+      const level = (entry as { maxEffortLevel?: unknown } | null)?.maxEffortLevel;
+      if (modelKey(name) !== key || !isEffortLevel(level)) continue;
+      if (!lowest || effortRank(level) < effortRank(lowest)) lowest = level;
+    }
+    if (lowest) return lowest;
+  }
+  return settings.maxEffortLevel;
+}
+
+/**
+ * The overrides the settings and the environment hold: the `CLAUDE_CODE_EFFORT_LEVEL` that wins
+ * (the highest-priority settings file that sets it, else the environment, which every settings
+ * file outranks) and the lowest cap (across files the lowest wins, and "max" caps nothing).
+ */
+export function effortOverrides(p: {
+  sources: ReadonlyArray<CliSettingsSource | null | undefined>;
+  processEnv?: string;
+  model?: string;
+  userFile: string;
+}): Pick<EffortStatus, "env" | "cap"> {
+  const out: Pick<EffortStatus, "env" | "cap"> = {};
+  const sources = p.sources.filter((s): s is CliSettingsSource => !!s?.settings && typeof s.settings === "object");
+
+  let env: EffortSetting<string> | undefined;
+  for (let i = sources.length - 1; i >= 0 && !env; i--) {
+    const value = (sources[i]!.settings.env as Record<string, unknown> | undefined)?.[EFFORT_ENV_VAR];
+    if (typeof value === "string") env = { value, ...place(sources[i]!.source, p.userFile) };
+  }
+  env ??= p.processEnv !== undefined ? { value: p.processEnv, source: "environment" } : undefined;
+  // A value the CLI ignores overrides nothing — but it still hides a lower one, as it does there.
+  if (env && effortEnvMeaning(env.value)) out.env = env;
+
+  for (const s of sources) {
+    const level = sourceCap(s.settings, p.model);
+    if (!isEffortLevel(level) || level === "max") continue;
+    if (!out.cap || effortRank(level) < effortRank(out.cap.value)) out.cap = { value: level, ...place(s.source, p.userFile) };
+  }
+  return out;
+}
+
+function levels(values: unknown): EffortLevel[] {
+  return Array.isArray(values) ? values.filter(isEffortLevel) : [];
+}
+
+/** The model's levels, from the `initialize` answer; undefined when it lists no such model. */
+export function supportedLevels(models: CliModelInfo[] | undefined, model: string | undefined): EffortLevel[] | undefined {
+  if (!models || !model) return undefined;
+  const bare = (name: string) => name.toLowerCase().replace(/\[[^\]]*\]$/, "");
+  const hit = models.find((m) => [m.value, m.resolvedModel].some((name) => name && bare(name) === bare(model)));
+  return hit ? levels(hit.supportedEffortLevels) : undefined;
+}
+
+/** The running CLI's answer, as a status: its overrides plus what it said it sends. */
+export function effortStatusFromCli(p: {
+  answer: CliSettingsAnswer;
+  models?: CliModelInfo[];
+  requested: string | null | undefined;
+  processEnv?: string;
+  userFile: string;
+}): EffortStatus {
+  const model = typeof p.answer.applied?.model === "string" ? p.answer.applied.model : undefined;
+  const applied = p.answer.applied?.effort;
+  const supported = supportedLevels(p.models, model);
+  return {
+    ...effortOverrides({ sources: p.answer.sources ?? [], processEnv: p.processEnv, model, userFile: p.userFile }),
+    observed: {
+      requested: isEffortLevel(p.requested) ? p.requested : null,
+      applied: isEffortLevel(applied) ? applied : null,
+      ...(model && { model }),
+    },
+    ...(supported && { supported }),
+  };
+}
+
+/**
+ * The settings files a chat in `projectPath` reads, lowest priority first: those of the sources
+ * its CLI is started with, so the estimate never counts a file the chat does not load. A file
+ * that does not parse is skipped, as the CLI skips it.
+ */
+export function readSettingsFiles(
+  projectPath: string | undefined,
+  userPath: string,
+  sources: readonly ClaudeSettingSource[] = CLAUDE_SETTING_SOURCES,
+): CliSettingsSource[] {
+  const fileOf: Record<ClaudeSettingSource, [EffortSettingSource, string] | null> = {
+    user: ["userSettings", userPath],
+    project: projectPath ? ["projectSettings", join(projectPath, ".claude", "settings.json")] : null,
+    local: projectPath ? ["localSettings", join(projectPath, ".claude", "settings.local.json")] : null,
+  };
+  const files = sources.map((source) => fileOf[source]).filter((f): f is [EffortSettingSource, string] => !!f);
+  const out: CliSettingsSource[] = [];
+  for (const [source, file] of files) {
+    let settings: unknown;
+    try { settings = JSON.parse(readFileSync(file, "utf8")); } catch { continue; }
+    if (settings && typeof settings === "object" && !Array.isArray(settings)) out.push({ source, settings: settings as Record<string, unknown> });
+  }
+  return out;
+}
+
+/**
+ * The overrides a chat in `projectPath` will meet, from the files alone — for a session no CLI
+ * has answered for yet. Managed settings and organization limits are left to the CLI's answer.
+ */
+export function estimateEffortStatus(p: {
+  projectPath?: string;
+  model?: string;
+  env?: Record<string, string | undefined>;
+  home?: string;
+}): EffortStatus {
+  const env = p.env ?? process.env;
+  const user = userSettingsFile(env, p.home);
+  return effortOverrides({
+    sources: readSettingsFiles(p.projectPath, user.path),
+    processEnv: env[EFFORT_ENV_VAR],
+    model: p.model,
+    userFile: user.shown,
+  });
+}

package/src/server/routes/chat.ts

@@ -166,6 +166,23 @@ chatRoutes.get("/providers/:providerId/models", async (c) => {
   }
 });
 
+/**
+ * GET /chat/providers/:providerId/effort-status?model= — what overrides the effort picked for a
+ * new chat in this project (`CLAUDE_CODE_EFFORT_LEVEL`, a `maxEffortLevel` cap), from the settings
+ * files; a session's own socket carries the CLI's answer once a turn has run. `status` is null
+ * for a provider nothing overrides.
+ */
+chatRoutes.get("/providers/:providerId/effort-status", (c) => {
+  const provider = providerRegistry.get(c.req.param("providerId"));
+  if (!provider) return c.json(err(`Provider "${c.req.param("providerId")}" not found`), 404);
+  try {
+    const status = provider.estimateEffortStatus?.(c.get("projectPath"), c.req.query("model") || undefined) ?? null;
+    return c.json(ok({ status }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
 /** GET /chat/sessions — list chat sessions filtered by project from context */
 chatRoutes.get("/sessions", async (c) => {
   try {

package/src/server/routes/settings.ts

@@ -314,6 +314,22 @@ settingsRoutes.get("/ai/providers/:id/models", async (c) => {
   }
 });
 
+/**
+ * GET /settings/ai/providers/:id/effort-status — what overrides the default effort outside PPM for
+ * every project: the user settings and the environment PPM runs in. A project's own settings can
+ * add more, which the chat's picker reports. `status` is null for a provider nothing overrides.
+ */
+settingsRoutes.get("/ai/providers/:id/effort-status", (c) => {
+  const id = c.req.param("id");
+  const provider = providerRegistry.get(id);
+  if (!provider) return c.json(err(`Provider "${id}" not found`), 404);
+  try {
+    return c.json(ok({ status: provider.estimateEffortStatus?.(undefined, c.req.query("model") || undefined) ?? null }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
 // ── Keybindings ──────────────────────────────────────────────────────
 
 const KEYBINDINGS_KEY = "keybindings";