@cartanova/qgrid-cli 2.10.2 → 2.10.3

package/bundle/src/utils/providers/anthropic/anthropic-dispatcher.ts

@@ -1,14 +1,6 @@
 /**
- * AnthropicDispatcher
- *
- * OpenAIDispatcher와 달리, worker pool을 두는 대신 요청별 fresh spawn
- * 토큰은 인메모리(MAP)으로 관리하고 smooth weighted round-robin 으로 고른다
- *
- * - 모든 요청은 fresh `--session-id` 로 실행
- * - 멀티턴 문맥은 클라이언트가 매 호출 보내는 full history 를 평탄화해 전달한다.
- * - 발급한 session-id 를 GenerateResult.threadCoord(threadId=session-id, workerId=tokenId,
- *   epoch=0)로 올려, 상위(issueConvContext)가 클라에 회송할 좌표를 만든다. 다음 turn 이 좌표를
- *   회송해도 Anthropic 라우팅에는 쓰지 않는다.
+ * 요청마다 새 Claude 프로세스에 전체 대화 이력을 전달한다.
+ * 반환한 threadCoord는 다음 요청의 세션 재사용이나 토큰 선택에 쓰지 않는다.
  */
 
 import { getLogger } from "@logtape/logtape";
@@ -26,19 +18,14 @@ import {
 import { serializeAndValidateDispatchSchema } from "../common/schema-validation";
 import { SmoothWeightedRoundRobin } from "../common/smooth-weighted-round-robin";
 import { assertSupportedOneMillionSuffix, canonicalAnthropicModel } from "./anthropic-constants";
-import {
-  invalidateAnthropicQuotaUsage,
-  readAnthropicQuotaUsage,
-  type AnthropicQuotaUsageResult,
-} from "./anthropic-quota";
+import { invalidateAnthropicQuotaUsage, readAnthropicQuotaUsage } from "./anthropic-quota";
+import { assertAnthropicThinkingRuntime, resolveAnthropicThinking } from "./anthropic-thinking";
 import { makeAnthropicWorkerId, runClaudeSession } from "./claude-session";
 
 const logger = getLogger(["qgrid", "anthropic-dispatcher"]);
 
-// 1M context 정상 생성은 실측상 100s+까지 간다. 240s는 완충 장치일 뿐,
-// 거부+거대 system 재생성 지연을 완전히 해결하는 값은 아니다.
+// 1M context 생성은 100초 이상 걸릴 수 있다.
 const DEFAULT_TIMEOUT_MS = 240_000;
-// access token 만료 임박 임계 — 기존 standalone 경로(qgrid.dispatcher.ts)와 동일(60s).
 const REFRESH_SAFETY_MS = 60_000;
 
 interface PooledToken {
@@ -49,30 +36,15 @@ interface PooledToken {
   weight: number;
 }
 
-function quotaThresholdExceededMessage(
-  provider: string,
-  tokens: Array<{ tokenName: string; threshold: number }>,
-): string {
-  const details = tokens
-    .map((token) => `${token.tokenName} (threshold ${token.threshold}%)`)
-    .join(", ");
-  return details.length > 0
-    ? `All ${provider} tokens exceeded quota threshold: ${details}`
-    : `All ${provider} tokens exceeded quota threshold`;
-}
-
 export class AnthropicDispatcher implements ProviderDispatcher {
-  // tokenId → 풀 항목. start()/token 이벤트로 채움
-  private tokenPool = new Map<number, PooledToken>();
-  private readonly weightedSelector = new SmoothWeightedRoundRobin();
+  tokenPool = new Map<number, PooledToken>();
+  readonly weightedSelector = new SmoothWeightedRoundRobin();
+  inFlight = 0;
 
   async start(): Promise<void> {
-    // OpenAIDispatcher.start() 와 동일하게 DB 에서 기존 anthropic 토큰을 self-bootstrap 한다.
-    // (서버 재시작 시 NOTIFY 가 안 오므로 부트스트랩이 없으면 풀이 빈 채로 남는다.)
-    // 이후 변경분은 token-subscriber 가 onTokenAdded/Updated/Removed 로 전달한다.
-    // findActiveByProvider 가 active=true + provider 필터를 DB 에서 처리 → inactive 는 애초에 안 온다.
+    // NOTIFY는 기존 토큰을 재전송하지 않으므로 시작 시 DB에서 읽는다.
     const tokens = await TokenModel.findActiveByProvider("A", "anthropic");
-    for (const t of tokens) {
+    tokens.forEach((t) => {
       this.tokenPool.set(t.id, {
         id: t.id,
         name: t.name,
@@ -82,37 +54,17 @@ export class AnthropicDispatcher implements ProviderDispatcher {
       });
       this.weightedSelector.setToken(t.id, t.weight);
       logger.info(`worker spawned: ${t.name}`);
-    }
+    });
   }
 
   async stop(): Promise<void> {
     const tokenIds = [...this.tokenPool.keys()];
-    for (const id of tokenIds) this.weightedSelector.removeToken(id);
+    tokenIds.forEach((id) => this.weightedSelector.removeToken(id));
     this.tokenPool.clear();
     this.weightedSelector.resetScores();
   }
 
-  // 현재 풀의 토큰 수(startup 로그/health 용).
-  get tokenCount(): number {
-    return this.tokenPool.size;
-  }
-
-  // 지금 실행 중인 Claude Code 프로세스 수 — fresh-spawn 이라 이게 곧 동시 요청 수다.
-  private inFlightCount = 0;
-  get inFlight(): number {
-    return this.inFlightCount;
-  }
-
-  // Monit 표시용 — 풀에 있는 토큰 이름 스냅샷 (이름순 정렬)
-  get tokenNames(): string[] {
-    return [...this.tokenPool.values()].map((token) => token.name).toSorted();
-  }
-
-  // DB active anthropic 토큰 목록으로 풀을 재동기화한다(periodic reconcile/재연결용).
-  // LISTEN/NOTIFY 가 끊긴 동안 유실된 추가/삭제/비활성화를 DB 기준으로 다시 맞춘다.
-  // 이벤트 핸들러를 재사용해 풀 갱신이 일관되게 적용되도록 한다:
-  //  - DB 에 없는데 풀에 있는 토큰 → onTokenRemoved
-  //  - DB 에 있는 토큰 → 신규면 onTokenAdded, 기존이면 onTokenUpdated
+  // LISTEN/NOTIFY 연결이 끊긴 동안 놓친 변경을 DB 기준으로 맞춘다.
   replaceTokens(
     rows: Array<{
       id: number;
@@ -123,21 +75,20 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     }>,
   ): void {
     const next = new Set(rows.map((r) => r.id));
-    // onTokenRemoved 가 tokenPool 을 delete 하므로 순회 중 수정을 피하려 키를 먼저 스냅샷한다.
+    // 삭제할 키는 순회 전에 스냅샷한다.
     const currentIds = Array.from(this.tokenPool.keys());
-    for (const id of currentIds) {
+    currentIds.forEach((id) => {
       if (!next.has(id)) this.onTokenRemoved(id);
-    }
-    for (const r of rows) {
+    });
+    rows.forEach((r) => {
       if (this.tokenPool.has(r.id)) {
         this.onTokenUpdated(r.id, r.name, r.credentials, r.quotaThreshold, r.weight);
       } else {
         this.onTokenAdded(r.id, r.name, r.credentials, r.quotaThreshold, r.weight);
       }
-    }
+    });
   }
 
-  // token events (token-subscriber 가 호출)
   onTokenAdded(
     id: number,
     name: string,
@@ -167,7 +118,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
 
   // 지정 요청은 해당 토큰만 quota 판정하고 weighted 상태를 건드리지 않는다.
   // 미지정 요청만 quota 통과 후보로 smooth weighted round-robin 을 진행한다.
-  private async selectToken(model: string, preferredTokenId?: number): Promise<PooledToken | null> {
+  async selectToken(model: string, preferredTokenId?: number): Promise<PooledToken | null> {
     const preferred =
       preferredTokenId === undefined ? undefined : this.tokenPool.get(preferredTokenId);
     if (preferredTokenId !== undefined && !preferred) {
@@ -185,8 +136,13 @@ export class AnthropicDispatcher implements ProviderDispatcher {
         overThresholdTokens,
         reason: "all_exceeded",
       });
+      const details = overThresholdTokens
+        .map((token) => `${token.tokenName} (threshold ${token.threshold}%)`)
+        .join(", ");
       throw new QuotaThresholdExceededError(
-        quotaThresholdExceededMessage("anthropic", overThresholdTokens),
+        details
+          ? `All anthropic tokens exceeded quota threshold: ${details}`
+          : "All anthropic tokens exceeded quota threshold",
       );
     }
 
@@ -197,7 +153,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     return this.tokenPool.get(selectedId) ?? null;
   }
 
-  private async filterEligibleTokens(
+  async filterEligibleTokens(
     rows: PooledToken[],
     model: string,
   ): Promise<{
@@ -219,24 +175,35 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     );
 
     checks.forEach((check, index) => {
-      if (check.status === "rejected") {
-        const token = thresholded[index];
-        if (!token) return;
-        this.logQuotaLookupFailOpen(token, String(check.reason));
-        eligibleIds.add(token.id);
-        return;
-      }
-
-      const token = check.value.token;
-      const result = check.value.result;
+      const token = check.status === "rejected" ? thresholded[index] : check.value.token;
+      if (!token) return;
+      const result =
+        check.status === "fulfilled"
+          ? check.value.result
+          : { kind: "lookup_failed" as const, reason: String(check.reason) };
       if (result.kind === "lookup_failed") {
-        this.logQuotaLookupFailOpen(token, result.reason);
+        logger.warn("quota_threshold gate: lookup_fail_open", {
+          tokenId: token.id,
+          tokenName: token.name,
+          provider: "anthropic",
+          threshold: token.quotaThreshold,
+          reason: "lookup_fail_open",
+          lookupReason: result.reason,
+        });
         eligibleIds.add(token.id);
         return;
       }
 
       if (result.utilizationPct >= token.quotaThreshold) {
-        this.logQuotaOverThreshold(token, result);
+        logger.info("quota_threshold gate: over_threshold", {
+          tokenId: token.id,
+          tokenName: token.name,
+          provider: "anthropic",
+          threshold: token.quotaThreshold,
+          cachedUtilization: result.utilizationPct,
+          cacheAge: result.cacheAgeMs,
+          reason: "over_threshold",
+        });
         overThresholdTokens.push({ tokenName: token.name, threshold: token.quotaThreshold });
         return;
       }
@@ -247,39 +214,10 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     return { eligible: rows.filter((token) => eligibleIds.has(token.id)), overThresholdTokens };
   }
 
-  private hasQuotaThreshold(token: PooledToken): token is PooledToken & { quotaThreshold: number } {
+  hasQuotaThreshold(token: PooledToken): token is PooledToken & { quotaThreshold: number } {
     return token.quotaThreshold !== undefined && token.quotaThreshold !== null;
   }
 
-  private logQuotaOverThreshold(
-    token: PooledToken & { quotaThreshold: number },
-    result: Extract<AnthropicQuotaUsageResult, { kind: "ok" }>,
-  ): void {
-    logger.info("quota_threshold gate: over_threshold", {
-      tokenId: token.id,
-      tokenName: token.name,
-      provider: "anthropic",
-      threshold: token.quotaThreshold,
-      cachedUtilization: result.utilizationPct,
-      cacheAge: result.cacheAgeMs,
-      reason: "over_threshold",
-    });
-  }
-
-  private logQuotaLookupFailOpen(
-    token: PooledToken & { quotaThreshold: number },
-    reason: string,
-  ): void {
-    logger.warn("quota_threshold gate: lookup_fail_open", {
-      tokenId: token.id,
-      tokenName: token.name,
-      provider: "anthropic",
-      threshold: token.quotaThreshold,
-      reason: "lookup_fail_open",
-      lookupReason: reason,
-    });
-  }
-
   async generate(req: GenerateRequest): Promise<GenerateResult> {
     return this.run(req, () => {});
   }
@@ -294,38 +232,26 @@ export class AnthropicDispatcher implements ProviderDispatcher {
     }
   }
 
-  // generate/generateStream 공통 실행. onDelta 는 스트림이면 점진 방출, 비스트림이면 no-op.
-  private async run(...args: Parameters<AnthropicDispatcher["runInner"]>): Promise<GenerateResult> {
-    this.inFlightCount++;
-    try {
-      return await this.runInner(...args);
-    } finally {
-      this.inFlightCount--;
-    }
-  }
-
-  private async runInner(
+  async run(
     req: GenerateRequest,
     onDelta: (t: string) => void,
     opts?: { includePartialMessages?: boolean },
   ): Promise<GenerateResult> {
-    // 이미지 생성은 OpenAI 경로 전용. Anthropic 라우팅에 이미지 플래그가
-    // 도달하면 조용히 텍스트로 폴백하지 않고 명시적으로 거부한다.
-    if (req.imageGeneration) {
-      throw new Error("image generation is not supported on the Anthropic route");
-    }
-    // model 정규화를 dispatcher 진입점에서 한 번 한다: result.model / runClaudeSession 전부
-    // canonical(prefix 없는 cost 키) 을 쓰게 통일. 미지정이면 ANTHROPIC_DEFAULT_MODEL — qgrid.dispatcher
-    // 의 "sonnet" 별칭 우회 차단. 정규화 규칙은 fallback 경로와 공유(canonicalAnthropicModel).
-    assertSupportedOneMillionSuffix(req.model);
-    const model = canonicalAnthropicModel(req.model);
-    const jsonSchema = serializeAndValidateDispatchSchema(req.outputSchema, "anthropic");
+    this.inFlight++;
+    try {
+      if (req.imageGeneration) {
+        throw new Error("image generation is not supported on the Anthropic route");
+      }
+      assertSupportedOneMillionSuffix(req.model);
+      const model = canonicalAnthropicModel(req.model);
+      const thinking = resolveAnthropicThinking(model, req.thinking, req.effort);
+      assertAnthropicThinkingRuntime(thinking.extraBody);
+      const jsonSchema = serializeAndValidateDispatchSchema(req.outputSchema, "anthropic");
 
-    const token = await this.selectToken(model, req.preferredTokenId);
-    if (!token) throw new Error("No anthropic tokens available");
+      const token = await this.selectToken(model, req.preferredTokenId);
+      if (!token) throw new Error("No anthropic tokens available");
 
-    const exec = async (): Promise<GenerateResult> => {
-      // 만료 임박 토큰 preemptive refresh(기존 standalone 경로와 동일). 실패해도 진행.
+      // 만료 직전에 갱신하되 실패하면 기존 토큰으로 진행한다.
       let accessToken = token.credentials.accessToken;
       const expiresAt = getExpiresAt(token.credentials);
       if (
@@ -336,7 +262,6 @@ export class AnthropicDispatcher implements ProviderDispatcher {
         try {
           const { QgridFrame } = await import("../../../application/qgrid/qgrid.frame");
           // provider 를 반드시 채워야 refreshToken 내부 TokenModel.save 가 성공한다.
-          // refreshToken(TokenSubsetA) 는 id/provider/credentials/name 만 사용하므로 그 4개만 넘긴다.
           accessToken = await QgridFrame.refreshToken({
             id: token.id,
             provider: "anthropic",
@@ -357,6 +282,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
           system: req.systemPrompt,
           jsonSchema,
           effort: req.effort,
+          thinking: req.thinking,
           timeoutMs: req.timeoutMs ?? DEFAULT_TIMEOUT_MS,
           coldHistory: req.coldHistory,
           input: req.coldInput,
@@ -374,9 +300,7 @@ export class AnthropicDispatcher implements ProviderDispatcher {
         throw new Error(`quota exhausted (${token.name})`);
       }
       if (session.isError) {
-        // 진단(SON-495): isError 판정 사유(subtype/terminal_reason)를 메시지 앞에 드러낸다.
-        // 그동안 detail 이 session.text(완전한 JSON 본문)뿐이라 "schema 위반인지 / max retries 인지 /
-        // max turns 인지"를 구분할 수 없었다. text 는 진단에 필요한 만큼만 잘라 덧붙인다.
+        // 종료 사유를 먼저 표시하고 응답 본문은 진단에 필요한 만큼만 남긴다.
         const reason =
           session.subtype ?? session.terminalReason ?? (session.isError ? "is_error" : "unknown");
         const body = session.text
@@ -395,20 +319,18 @@ export class AnthropicDispatcher implements ProviderDispatcher {
         durationMs: session.durationMs,
         ttftMs: session.ttftMs,
         costUsd: session.costUsd,
-        // Claude Code 는 Fable refusal 을 Opus 로 자동 fallback 할 수 있다. 요청 모델을
-        // 그대로 serving model 로 기록하면 비용/감사 로그가 모두 틀어지므로 둘을 구분한다.
+        // Claude Code의 모델 fallback을 비용·감사 로그에 반영한다.
         model: session.servedModel ?? model,
         requestedModel: model,
         modelFallbacks: session.modelFallbacks,
-        // systemHash 는 상위 issueConvContext 가 채운다(여기선 비운다).
         threadCoord: {
           workerId: makeAnthropicWorkerId(token.id),
           threadId: session.sessionId,
           epoch: 0,
         },
       };
-    };
-
-    return exec();
+    } finally {
+      this.inFlight--;
+    }
   }
 }

package/bundle/src/utils/providers/anthropic/anthropic-thinking.test.ts

@@ -0,0 +1,36 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const version = vi.hoisted(() => vi.fn());
+vi.mock("node:child_process", () => ({ execFileSync: version }));
+
+describe("Anthropic native extra-body thinking modes", () => {
+  beforeEach(() => {
+    vi.resetModules();
+    version.mockReset();
+  });
+
+  it.each([
+    ["claude-haiku-5-5", "disabled"],
+    ["claude-sonnet-5-5", "between_tools"],
+  ])("%s only overrides thinking and ignores caller effort", async (model, type) => {
+    const { resolveAnthropicThinking, assertAnthropicThinkingRuntime } = await import("./anthropic-thinking");
+    version.mockReturnValue("2.1.295 (Claude Code)");
+    const policy = resolveAnthropicThinking(model, false, "max");
+    expect(policy.mode).toBe("disabled");
+    expect(policy.effort).toBe("low");
+    expect(JSON.parse(policy.extraBody!)).toEqual({thinking: {type}});
+    assertAnthropicThinkingRuntime(policy.extraBody);
+    assertAnthropicThinkingRuntime(policy.extraBody);
+    expect(version).toHaveBeenCalledTimes(1);
+    expect(resolveAnthropicThinking(model).extraBody).toBeUndefined();
+    expect(resolveAnthropicThinking(model, true).extraBody).toBeUndefined();
+  });
+
+  it.each(["2.1.294 (Claude Code)", "unrecognized"])("rejects unverified runtime %s without affecting other models", async (output) => {
+    const { assertAnthropicThinkingRuntime } = await import("./anthropic-thinking");
+    version.mockReturnValue(output);
+    expect(() => assertAnthropicThinkingRuntime(undefined)).not.toThrow();
+    expect(version).not.toHaveBeenCalled();
+    expect(() => assertAnthropicThinkingRuntime('{"thinking":{"type":"disabled"}}')).toThrow("2.1.295");
+  });
+});

package/bundle/src/utils/providers/anthropic/anthropic-thinking.ts

@@ -0,0 +1,84 @@
+import { execFileSync } from "node:child_process";
+
+import { resolveAnthropicEffort } from "../common/effort";
+import { ThinkingValidationError } from "../common/thinking";
+import {
+  ANTHROPIC_DEFAULT_EFFORT,
+  canonicalAnthropicModel,
+  usesAdaptiveThinking,
+} from "./anthropic-constants";
+
+const THINKING_OFF_MODELS = new Set([
+  "claude-haiku-4-5",
+  "claude-sonnet-4-5",
+  "claude-sonnet-4-6",
+  "claude-sonnet-5",
+  "claude-opus-4-5",
+  "claude-opus-4-6",
+  "claude-opus-4-7",
+  "claude-opus-4-8",
+  "claude-opus-5",
+  "claude-haiku-5-5",
+  "claude-sonnet-5-5",
+]);
+
+let extraBodyRuntimeSupported: boolean | undefined;
+
+/** These modes were verified through native extra-body delivery on Claude Code 2.1.295. */
+export function assertAnthropicThinkingRuntime(extraBody: string | undefined): void {
+  if (!extraBody) return;
+  if (extraBodyRuntimeSupported === undefined) {
+    try {
+      const version = execFileSync("claude", ["--version"], {
+        encoding: "utf8",
+        timeout: 5000,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { PATH: process.env.PATH, TMPDIR: process.env.TMPDIR },
+      }).match(/^(\d+)\.(\d+)\.(\d+)/);
+      const [major, minor, patch] = version?.slice(1).map(Number) ?? [];
+      extraBodyRuntimeSupported =
+        major !== undefined &&
+        minor !== undefined &&
+        patch !== undefined &&
+        (major > 2 || (major === 2 && (minor > 1 || (minor === 1 && patch >= 295))));
+    } catch {
+      extraBodyRuntimeSupported = false;
+    }
+  }
+  if (!extraBodyRuntimeSupported) {
+    throw new ThinkingValidationError(
+      "thinking:false for Haiku 5.5 and Sonnet 5.5 requires Claude Code 2.1.295 or later; runtime version could not be verified",
+    );
+  }
+}
+
+export function resolveAnthropicThinking(model: string, thinking?: boolean, effort?: string) {
+  const canonical = canonicalAnthropicModel(model);
+  if (thinking === false && !THINKING_OFF_MODELS.has(canonical)) {
+    const reason = usesAdaptiveThinking(canonical)
+      ? "this model requires thinking"
+      : "thinking-off support has not been verified for this model";
+    throw new ThinkingValidationError(
+      `thinking:false is not supported for anthropic/${canonical}: ${reason}`,
+    );
+  }
+  return {
+    // Never accept caller-provided extra body data or inherit it from the host environment.
+    extraBody:
+      thinking === false && (canonical === "claude-haiku-5-5" || canonical === "claude-sonnet-5-5")
+        ? JSON.stringify({
+            thinking: { type: canonical === "claude-sonnet-5-5" ? "between_tools" : "disabled" },
+          })
+        : undefined,
+    mode:
+      thinking === true
+        ? ("adaptive" as const)
+        : thinking === false || !usesAdaptiveThinking(canonical)
+          ? ("disabled" as const)
+          : undefined,
+    effort:
+      thinking === false
+        ? ANTHROPIC_DEFAULT_EFFORT
+        : (resolveAnthropicEffort(effort) ?? ANTHROPIC_DEFAULT_EFFORT),
+  };
+}

package/bundle/src/utils/providers/anthropic/claude-session.test.ts

@@ -1,6 +1,9 @@
+import * as childProcess from "node:child_process";
+import { EventEmitter } from "node:events";
 import { existsSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { PassThrough } from "node:stream";
 
-import { describe, expect, it } from "vitest";
+import { describe, expect, it, vi } from "vitest";
 
 import { ANTHROPIC_CONFIG_DIR_BASE, anthropicConfigDir } from "./anthropic-constants";
 import {
@@ -13,12 +16,17 @@ import {
   runClaudeSession,
   shouldPinStructuredRetries,
   structuredOutputRetriesEnv,
-  thinkingEnv,
   SYSTEM_PROMPT_ARGV_MAX_BYTES,
   withSessionLock,
 } from "./claude-session";
 import { buildStreamJsonInput } from "./stream-json-adapter";
 
+vi.mock("node:child_process", async (importOriginal) => ({
+  ...await importOriginal<typeof import("node:child_process")>(),
+  spawn: vi.fn(),
+  execFileSync: vi.fn(() => "2.1.295 (Claude Code)"),
+}));
+
 describe("makeAnthropicWorkerId (coord 매핑 P0-2)", () => {
   it("tokenId 기반 안정 합성", () => {
     expect(makeAnthropicWorkerId(7)).toBe(7);
@@ -74,6 +82,54 @@ describe("ensureConfigDir (R10 격리 seed self-healing)", () => {
   });
 });
 
+describe("runClaudeSession thinking and environment boundary", () => {
+  it.each([
+    {model: "claude-opus-4-8", thinking: undefined},
+    {model: "claude-opus-4-8", thinking: true},
+    {model: "claude-opus-4-8", thinking: false},
+    {model: "claude-haiku-5-5", thinking: false},
+    {model: "claude-sonnet-5-5", thinking: false},
+  ])("$model thinking=$thinking preserves isolation without competing env controls", async ({model, thinking}) => {
+    const tokenId = -990002;
+    const child = Object.assign(new EventEmitter(), {
+      stdout: new PassThrough(), stderr: new PassThrough(), stdin: new PassThrough(), kill: vi.fn(),
+    });
+    const spawn = vi.mocked(childProcess.spawn).mockImplementation(() => {
+      queueMicrotask(() => child.stdout.write(`${JSON.stringify({
+        type: "result", subtype: "success", result: "OK", is_error: false,
+        usage: {input_tokens: 1, output_tokens: 1},
+      })}\n`));
+      return child as unknown as ReturnType<typeof childProcess.spawn>;
+    });
+    vi.stubEnv("ANTHROPIC_API_KEY", "must-not-inherit");
+    vi.stubEnv("MAX_THINKING_TOKENS", "0");
+    vi.stubEnv("CLAUDE_CODE_EXTRA_BODY", '{"model":"must-not-inherit"}');
+    try {
+      const result = await runClaudeSession({
+        tokenId, token: "test-oauth", model, thinking, effort: "high", timeoutMs: 1000,
+        input: [{type: "text", text: "OK", text_elements: []}],
+      }, () => {});
+      expect(result.text).toBe("OK");
+      const [, args, options] = spawn.mock.calls[0]!;
+      expect(args).toContain("--thinking");
+      expect(args).toContain(thinking === true ? "adaptive" : "disabled");
+      expect(options?.env).toMatchObject({
+        CLAUDE_CODE_OAUTH_TOKEN: "test-oauth", CLAUDE_CONFIG_DIR: anthropicConfigDir(tokenId),
+        CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1", CLAUDE_CODE_DISABLE_CLAUDE_MDS: "1",
+        CLAUDE_CODE_DISABLE_BUNDLED_SKILLS: "1", CLAUDE_CODE_DISABLE_WORKFLOWS: "1",
+      });
+      for (const key of ["ANTHROPIC_API_KEY", "MAX_THINKING_TOKENS", "CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING"]) {
+        expect(options?.env).not.toHaveProperty(key);
+      }
+      const extraBody = options?.env?.CLAUDE_CODE_EXTRA_BODY;
+      if (model === "claude-opus-4-8") expect(extraBody).toBeUndefined();
+      else expect(JSON.parse(extraBody!)).toEqual({thinking: {type: model === "claude-sonnet-5-5" ? "between_tools" : "disabled"}});
+    } finally {
+      spawn.mockRestore(); vi.unstubAllEnvs(); rmSync(anthropicConfigDir(tokenId), {recursive: true, force: true});
+    }
+  });
+});
+
 describe("withSessionLock (per-session 락 P0-3)", () => {
   it("같은 session-id 의 동시 호출은 직렬화된다", async () => {
     const order: Array<string> = [];
@@ -134,19 +190,24 @@ describe("buildClaudeArgs (멀티턴/격리/structured)", () => {
     expect(oneMillionEnv(false)).toEqual({ CLAUDE_CODE_DISABLE_1M_CONTEXT: "1" });
   });
 
-  it("thinkingEnv: Fable 5/5.1/Opus 5 는 adaptive thinking 을 보존하고 나머지는 비활성화", () => {
-    expect(thinkingEnv("claude-fable-5-1")).toEqual({});
-    expect(thinkingEnv("anthropic/claude-fable-5-1")).toEqual({});
-    expect(thinkingEnv("claude-fable-5")).toEqual({});
-    expect(thinkingEnv("anthropic/claude-fable-5")).toEqual({});
-    expect(thinkingEnv("claude-opus-5")).toEqual({});
-    expect(thinkingEnv("anthropic/claude-opus-5")).toEqual({});
-    expect(thinkingEnv("claude-opus-4-8")).toEqual({
-      CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING: "1",
-      MAX_THINKING_TOKENS: "0",
-    });
+  it("thinking true enables a legacy default-off model and preserves effort", () => {
+    const args = buildClaudeArgs({model: "claude-opus-4-8", sessionId: "u", thinking: true, effort: "high"});
+    expect(args[args.indexOf("--thinking") + 1]).toBe("adaptive");
+    expect(args[args.indexOf("--effort") + 1]).toBe("high");
   });
 
+  it("thinking false disables a supported default-adaptive model and ignores effort", () => {
+    const args = buildClaudeArgs({model: "anthropic/claude-opus-5", sessionId: "u", thinking: false, effort: "max"});
+    expect(args[args.indexOf("--thinking") + 1]).toBe("disabled");
+    expect(args[args.indexOf("--effort") + 1]).toBe("low");
+  });
+
+  it.each(["claude-fable-5-1", "claude-fable-5", "claude-opus-5-5", "claude-opus-4-1", "unknown"])(
+    "thinking false rejects %s instead of silently changing its model or thinking mode", (model) => {
+      expect(() => buildClaudeArgs({model, sessionId: "u", thinking: false})).toThrow(`anthropic/${model}`);
+    },
+  );
+
   // SON-495: structured output retry 를 1 로 고정한다.
   it("structuredOutputRetriesEnv: 미설정/비정상 값은 1 로 기본 고정", () => {
     expect(structuredOutputRetriesEnv(undefined)).toEqual({ MAX_STRUCTURED_OUTPUT_RETRIES: "1" });