@hienlh/ppm 0.23.22 → 0.23.23

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.
@@ -283,6 +289,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 +746,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       }
     }
     this.forkSources.delete(sessionId);
+    this.startedEffort.delete(sessionId);
 
     // Best-effort: delete JSONL from ~/.claude/projects/
     try {
@@ -933,7 +942,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 +1186,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 +1198,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,6 +1464,8 @@ 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.
@@ -1610,7 +1616,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 +1651,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.
@@ -2430,9 +2439,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." };
@@ -2533,7 +2540,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 +2585,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";

package/src/server/ws/chat-effort-status.ts

@@ -0,0 +1,73 @@
+/**
+ * The effort a chat's turns really run at, kept beside the pick.
+ *
+ * PPM starts the CLI with the picked `--effort`, but `CLAUDE_CODE_EFFORT_LEVEL` (in the
+ * environment or a settings file's `env`), a `maxEffortLevel` cap, an organization limit and the
+ * model itself all outrank it there. So the session's CLI is asked at the start of every turn —
+ * a settings file edited since the last one shows up there too — and its answer goes to the
+ * clients. Before any turn has asked, what the settings files say stands in.
+ */
+import { effortInEffect, effortSettingPlace, type EffortStatus } from "../../shared/effort-status.ts";
+
+export interface EffortStatusSession {
+  providerId: string;
+  projectPath?: string;
+  /** The CLI's last answer for this session. */
+  effortStatus?: EffortStatus;
+}
+
+export interface EffortStatusProvider {
+  readEffortStatus?(sessionId: string): Promise<EffortStatus | null>;
+  estimateEffortStatus?(projectPath: string | undefined, model?: string): EffortStatus;
+}
+
+/** What a greeting carries: the CLI's answer, else the settings files; null for a provider nothing overrides. */
+export function sessionEffortStatus(
+  provider: EffortStatusProvider | undefined,
+  session: EffortStatusSession,
+  model: string | undefined,
+): EffortStatus | null {
+  return session.effortStatus ?? provider?.estimateEffortStatus?.(session.projectPath, model) ?? null;
+}
+
+/** The session log's line for a turn whose effort is not the one it was started with. */
+export function effortOverrideLogLine(status: EffortStatus): string | null {
+  const { observed } = status;
+  if (!observed?.requested) return null;
+  const { level, reason } = effortInEffect(observed.requested, status);
+  if (!reason) return null;
+  const by = reason === "env" && status.env
+    ? `CLAUDE_CODE_EFFORT_LEVEL=${status.env.value} in ${effortSettingPlace(status.env)}`
+    : reason === "cap" && status.cap
+      ? `maxEffortLevel ${status.cap.value} in ${effortSettingPlace(status.cap)}`
+      : `what ${observed.model ?? "the model"} allows`;
+  return `Effort ${observed.requested} was picked; Claude Code sends ${level ?? "no effort"} (${by})`;
+}
+
+/**
+ * Ask the session's CLI at a turn's start, and tell the clients when its answer changed. Never
+ * rejects: it runs unawaited beside the turn, where a rejection would reach the server's
+ * fatal-error handler for what is only a label.
+ */
+export async function refreshEffortStatus(p: {
+  sessionId: string;
+  session: EffortStatusSession;
+  provider: EffortStatusProvider | undefined;
+  /** False once the session's entry was replaced while the CLI was answering. */
+  isCurrent: () => boolean;
+  broadcast: (event: unknown) => void;
+  log: (line: string) => void;
+}): Promise<void> {
+  try {
+    const status = await p.provider?.readEffortStatus?.(p.sessionId);
+    if (!status || !p.isCurrent()) return;
+    const before = p.session.effortStatus;
+    p.session.effortStatus = status;
+    if (before && JSON.stringify(before) === JSON.stringify(status)) return;
+    p.broadcast({ type: "effort_status", status });
+    const line = effortOverrideLogLine(status);
+    if (line) p.log(line);
+  } catch {
+    // The status stays as it was; the next turn asks again.
+  }
+}