Merge pull request #293 from nrslib/release/v0.18.2

Release v0.18.2

CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.18.2] - 2026-02-18
+
+### Added
+
+- Added `codex_cli_path` global config option and `TAKT_CODEX_CLI_PATH` environment variable to override the Codex CLI binary path used by the Codex SDK (#292)
+  - Supports strict validation: absolute path, file existence, executable permission, no control characters
+  - Priority: `TAKT_CODEX_CLI_PATH` env var > `codex_cli_path` in config.yaml > SDK vendored binary
+
 ## [0.18.1] - 2026-02-18
 
 ### Added

README.md

@@ -612,6 +612,11 @@ anthropic_api_key: sk-ant-...  # For Claude (Anthropic)
 # openai_api_key: sk-...       # For Codex (OpenAI)
 # opencode_api_key: ...        # For OpenCode
 
+# Codex CLI path override (optional)
+# Override the Codex CLI binary used by the Codex SDK (must be an absolute path to an executable file)
+# Can be overridden by TAKT_CODEX_CLI_PATH environment variable
+# codex_cli_path: /usr/local/bin/codex
+
 # Builtin piece filtering (optional)
 # builtin_pieces_enabled: true           # Set false to disable all builtins
 # disabled_builtins: [magi, passthrough] # Disable specific builtin pieces

docs/CHANGELOG.ja.md

@@ -6,6 +6,14 @@
 
 フォーマットは [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) に基づいています。
 
+## [0.18.2] - 2026-02-18
+
+### Added
+
+- グローバル設定に `codex_cli_path` オプションと `TAKT_CODEX_CLI_PATH` 環境変数を追加 — Codex SDK が使用する CLI バイナリのパスを上書き可能に (#292)
+  - 厳密なバリデーション付き: 絶対パス、ファイル存在確認、実行権限、制御文字の禁止
+  - 優先順位: `TAKT_CODEX_CLI_PATH` 環境変数 > config.yaml の `codex_cli_path` > SDK 同梱バイナリ
+
 ## [0.18.1] - 2026-02-18
 
 ### Added

docs/README.ja.md

@@ -612,6 +612,11 @@ anthropic_api_key: sk-ant-...  # Claude (Anthropic) を使う場合
 # openai_api_key: sk-...       # Codex (OpenAI) を使う場合
 # opencode_api_key: ...        # OpenCode を使う場合
 
+# Codex CLI パスの上書き（オプション）
+# Codex SDK が使用する CLI バイナリを上書き（実行可能ファイルの絶対パスを指定）
+# 環境変数 TAKT_CODEX_CLI_PATH で上書き可能
+# codex_cli_path: /usr/local/bin/codex
+
 # ビルトインピースのフィルタリング（オプション）
 # builtin_pieces_enabled: true           # false でビルトイン全体を無効化
 # disabled_builtins: [magi, passthrough] # 特定のビルトインピースを無効化

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "takt",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "takt",
-      "version": "0.18.1",
+      "version": "0.18.2",
       "license": "MIT",
       "dependencies": {
         "@anthropic-ai/claude-agent-sdk": "^0.2.37",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "takt",
-  "version": "0.18.1",
+  "version": "0.18.2",
   "description": "TAKT: TAKT Agent Koordination Topology - AI Agent Piece Orchestration",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/__tests__/codex-structured-output.test.ts

@@ -15,10 +15,14 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 let mockEvents: Array<Record<string, unknown>> = [];
 let lastThreadOptions: Record<string, unknown> | undefined;
+let lastCodexConstructorOptions: Record<string, unknown> | undefined;
 
 vi.mock('@openai/codex-sdk', () => {
   return {
     Codex: class MockCodex {
+      constructor(options?: Record<string, unknown>) {
+        lastCodexConstructorOptions = options;
+      }
       async startThread(options?: Record<string, unknown>) {
         lastThreadOptions = options;
         return {
@@ -47,6 +51,7 @@ describe('CodexClient — structuredOutput 抽出', () => {
     vi.clearAllMocks();
     mockEvents = [];
     lastThreadOptions = undefined;
+    lastCodexConstructorOptions = undefined;
   });
 
   it('outputSchema 指定時に agent_message の JSON テキストを structuredOutput として返す', async () => {
@@ -169,4 +174,21 @@ describe('CodexClient — structuredOutput 抽出', () => {
       networkAccessEnabled: true,
     });
   });
+
+  it('codexPathOverride が Codex constructor options に反映される', async () => {
+    mockEvents = [
+      { type: 'thread.started', thread_id: 'thread-1' },
+      { type: 'turn.completed', usage: { input_tokens: 0, cached_input_tokens: 0, output_tokens: 0 } },
+    ];
+
+    const client = new CodexClient();
+    await client.call('coder', 'prompt', {
+      cwd: '/tmp',
+      codexPathOverride: '/opt/codex/bin/codex',
+    });
+
+    expect(lastCodexConstructorOptions).toMatchObject({
+      codexPathOverride: '/opt/codex/bin/codex',
+    });
+  });
 });

src/__tests__/globalConfig-resolvers.test.ts

@@ -10,7 +10,7 @@
  */
 
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
-import { mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs';
+import { mkdirSync, rmSync, writeFileSync, readFileSync, chmodSync } from 'node:fs';
 import { join } from 'node:path';
 import { tmpdir } from 'node:os';
 import { randomUUID } from 'node:crypto';
@@ -22,6 +22,20 @@ const testDir = join(tmpdir(), `takt-api-key-test-${testId}`);
 const taktDir = join(testDir, '.takt');
 const configPath = join(taktDir, 'config.yaml');
 
+function createExecutableFile(filename: string): string {
+  const filePath = join(testDir, filename);
+  writeFileSync(filePath, '#!/bin/sh\necho codex\n', 'utf-8');
+  chmodSync(filePath, 0o755);
+  return filePath;
+}
+
+function createNonExecutableFile(filename: string): string {
+  const filePath = join(testDir, filename);
+  writeFileSync(filePath, '#!/bin/sh\necho codex\n', 'utf-8');
+  chmodSync(filePath, 0o644);
+  return filePath;
+}
+
 vi.mock('../infra/config/paths.js', async (importOriginal) => {
   const original = await importOriginal() as Record<string, unknown>;
   return {
@@ -32,7 +46,7 @@ vi.mock('../infra/config/paths.js', async (importOriginal) => {
 });
 
 // Import after mocking
-const { loadGlobalConfig, saveGlobalConfig, resolveAnthropicApiKey, resolveOpenaiApiKey, resolveOpencodeApiKey, invalidateGlobalConfigCache } = await import('../infra/config/global/globalConfig.js');
+const { loadGlobalConfig, saveGlobalConfig, resolveAnthropicApiKey, resolveOpenaiApiKey, resolveCodexCliPath, resolveOpencodeApiKey, invalidateGlobalConfigCache } = await import('../infra/config/global/globalConfig.js');
 
 describe('GlobalConfigSchema API key fields', () => {
   it('should accept config without API keys', () => {
@@ -281,6 +295,117 @@ describe('resolveOpenaiApiKey', () => {
   });
 });
 
+describe('resolveCodexCliPath', () => {
+  const originalEnv = process.env['TAKT_CODEX_CLI_PATH'];
+
+  beforeEach(() => {
+    invalidateGlobalConfigCache();
+    mkdirSync(taktDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (originalEnv !== undefined) {
+      process.env['TAKT_CODEX_CLI_PATH'] = originalEnv;
+    } else {
+      delete process.env['TAKT_CODEX_CLI_PATH'];
+    }
+    rmSync(testDir, { recursive: true, force: true });
+  });
+
+  it('should return env var path when set', () => {
+    const envCodexPath = createExecutableFile('env-codex');
+    const configCodexPath = createExecutableFile('config-codex');
+    process.env['TAKT_CODEX_CLI_PATH'] = envCodexPath;
+    const yaml = [
+      'language: en',
+      'default_piece: default',
+      'log_level: info',
+      'provider: codex',
+      `codex_cli_path: ${configCodexPath}`,
+    ].join('\n');
+    writeFileSync(configPath, yaml, 'utf-8');
+
+    const path = resolveCodexCliPath();
+    expect(path).toBe(envCodexPath);
+  });
+
+  it('should fall back to config path when env var is not set', () => {
+    delete process.env['TAKT_CODEX_CLI_PATH'];
+    const configCodexPath = createExecutableFile('config-codex');
+    const yaml = [
+      'language: en',
+      'default_piece: default',
+      'log_level: info',
+      'provider: codex',
+      `codex_cli_path: ${configCodexPath}`,
+    ].join('\n');
+    writeFileSync(configPath, yaml, 'utf-8');
+
+    const path = resolveCodexCliPath();
+    expect(path).toBe(configCodexPath);
+  });
+
+  it('should return undefined when neither env var nor config is set', () => {
+    delete process.env['TAKT_CODEX_CLI_PATH'];
+    const yaml = [
+      'language: en',
+      'default_piece: default',
+      'log_level: info',
+      'provider: codex',
+    ].join('\n');
+    writeFileSync(configPath, yaml, 'utf-8');
+
+    const path = resolveCodexCliPath();
+    expect(path).toBeUndefined();
+  });
+
+  it('should throw when env path is empty', () => {
+    process.env['TAKT_CODEX_CLI_PATH'] = '';
+    expect(() => resolveCodexCliPath()).toThrow(/must not be empty/i);
+  });
+
+  it('should throw when env path does not exist', () => {
+    process.env['TAKT_CODEX_CLI_PATH'] = join(testDir, 'missing-codex');
+    expect(() => resolveCodexCliPath()).toThrow(/does not exist/i);
+  });
+
+  it('should throw when env path points to a directory', () => {
+    const dirPath = join(testDir, 'codex-dir');
+    mkdirSync(dirPath, { recursive: true });
+    process.env['TAKT_CODEX_CLI_PATH'] = dirPath;
+    expect(() => resolveCodexCliPath()).toThrow(/executable file/i);
+  });
+
+  it('should throw when env path points to a non-executable file', () => {
+    process.env['TAKT_CODEX_CLI_PATH'] = createNonExecutableFile('non-executable-codex');
+    expect(() => resolveCodexCliPath()).toThrow(/not executable/i);
+  });
+
+  it('should throw when env path is relative', () => {
+    process.env['TAKT_CODEX_CLI_PATH'] = 'bin/codex';
+    expect(() => resolveCodexCliPath()).toThrow(/absolute path/i);
+  });
+
+  it('should throw when env path contains control characters', () => {
+    process.env['TAKT_CODEX_CLI_PATH'] = '/tmp/codex\nbad';
+    expect(() => resolveCodexCliPath()).toThrow(/control characters/i);
+  });
+
+  it('should throw when config path is invalid', () => {
+    delete process.env['TAKT_CODEX_CLI_PATH'];
+    const yaml = [
+      'language: en',
+      'default_piece: default',
+      'log_level: info',
+      'provider: codex',
+      `codex_cli_path: ${join(testDir, 'missing-codex-from-config')}`,
+    ].join('\n');
+    writeFileSync(configPath, yaml, 'utf-8');
+
+    expect(() => resolveCodexCliPath()).toThrow(/does not exist/i);
+  });
+});
+
 describe('resolveOpencodeApiKey', () => {
   const originalEnv = process.env['TAKT_OPENCODE_API_KEY'];
 

src/__tests__/provider-structured-output.test.ts

@@ -56,6 +56,7 @@ vi.mock('../infra/opencode/index.js', () => ({
 vi.mock('../infra/config/index.js', () => ({
   resolveAnthropicApiKey: vi.fn(() => undefined),
   resolveOpenaiApiKey: vi.fn(() => undefined),
+  resolveCodexCliPath: vi.fn(() => '/opt/codex/bin/codex'),
   resolveOpencodeApiKey: vi.fn(() => undefined),
 }));
 
@@ -148,6 +149,7 @@ describe('CodexProvider — structured output', () => {
 
     const opts = mockCallCodex.mock.calls[0]?.[2];
     expect(opts).toHaveProperty('outputSchema', SCHEMA);
+    expect(opts).toHaveProperty('codexPathOverride', '/opt/codex/bin/codex');
     expect(result.structuredOutput).toEqual({ step: 2 });
   });
 

src/core/models/global-config.ts

@@ -77,6 +77,8 @@ export interface GlobalConfig {
   anthropicApiKey?: string;
   /** OpenAI API key for Codex SDK (overridden by TAKT_OPENAI_API_KEY env var) */
   openaiApiKey?: string;
+  /** External Codex CLI path for Codex SDK override (overridden by TAKT_CODEX_CLI_PATH env var) */
+  codexCliPath?: string;
   /** OpenCode API key for OpenCode SDK (overridden by TAKT_OPENCODE_API_KEY env var) */
   opencodeApiKey?: string;
   /** Pipeline execution settings */

src/core/models/schemas.ts

@@ -429,6 +429,8 @@ export const GlobalConfigSchema = z.object({
   anthropic_api_key: z.string().optional(),
   /** OpenAI API key for Codex SDK (overridden by TAKT_OPENAI_API_KEY env var) */
   openai_api_key: z.string().optional(),
+  /** External Codex CLI path for Codex SDK override (overridden by TAKT_CODEX_CLI_PATH env var) */
+  codex_cli_path: z.string().optional(),
   /** OpenCode API key for OpenCode SDK (overridden by TAKT_OPENCODE_API_KEY env var) */
   opencode_api_key: z.string().optional(),
   /** Pipeline execution settings */

src/infra/codex/client.ts

@@ -104,7 +104,11 @@ export class CodexClient {
       : prompt;
 
     for (let attempt = 1; attempt <= CODEX_RETRY_MAX_ATTEMPTS; attempt++) {
-      const codex = new Codex(options.openaiApiKey ? { apiKey: options.openaiApiKey } : undefined);
+      const codexClientOptions = {
+        ...(options.openaiApiKey ? { apiKey: options.openaiApiKey } : {}),
+        ...(options.codexPathOverride ? { codexPathOverride: options.codexPathOverride } : {}),
+      };
+      const codex = new Codex(Object.keys(codexClientOptions).length > 0 ? codexClientOptions : undefined);
       const thread = threadId
         ? await codex.resumeThread(threadId, threadOptions)
         : await codex.startThread(threadOptions);

src/infra/codex/types.ts

@@ -33,6 +33,8 @@ export interface CodexCallOptions {
   onStream?: StreamCallback;
   /** OpenAI API key (bypasses CLI auth) */
   openaiApiKey?: string;
+  /** Override path to external Codex CLI binary (bypasses SDK vendored binary) */
+  codexPathOverride?: string;
   /** JSON Schema for structured output */
   outputSchema?: Record<string, unknown>;
 }

src/infra/config/global/globalConfig.ts

@@ -5,7 +5,8 @@
  * GlobalConfigManager encapsulates the config cache as a singleton.
  */
 
-import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { readFileSync, existsSync, writeFileSync, statSync, accessSync, constants } from 'node:fs';
+import { isAbsolute } from 'node:path';
 import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
 import { GlobalConfigSchema } from '../../../core/models/index.js';
 import type { GlobalConfig, DebugConfig, Language } from '../../../core/models/index.js';
@@ -18,6 +19,42 @@ import { parseProviderModel } from '../../../shared/utils/providerModel.js';
 /** Claude-specific model aliases that are not valid for other providers */
 const CLAUDE_MODEL_ALIASES = new Set(['opus', 'sonnet', 'haiku']);
 
+function hasControlCharacters(value: string): boolean {
+  for (let index = 0; index < value.length; index++) {
+    const code = value.charCodeAt(index);
+    if (code < 32 || code === 127) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function validateCodexCliPath(pathValue: string, sourceName: 'TAKT_CODEX_CLI_PATH' | 'codex_cli_path'): string {
+  const trimmed = pathValue.trim();
+  if (trimmed.length === 0) {
+    throw new Error(`Configuration error: ${sourceName} must not be empty.`);
+  }
+  if (hasControlCharacters(trimmed)) {
+    throw new Error(`Configuration error: ${sourceName} contains control characters.`);
+  }
+  if (!isAbsolute(trimmed)) {
+    throw new Error(`Configuration error: ${sourceName} must be an absolute path: ${trimmed}`);
+  }
+  if (!existsSync(trimmed)) {
+    throw new Error(`Configuration error: ${sourceName} path does not exist: ${trimmed}`);
+  }
+  const stats = statSync(trimmed);
+  if (!stats.isFile()) {
+    throw new Error(`Configuration error: ${sourceName} must point to an executable file: ${trimmed}`);
+  }
+  try {
+    accessSync(trimmed, constants.X_OK);
+  } catch {
+    throw new Error(`Configuration error: ${sourceName} file is not executable: ${trimmed}`);
+  }
+  return trimmed;
+}
+
 /** Validate that provider and model are compatible */
 function validateProviderModelCompatibility(provider: string | undefined, model: string | undefined): void {
   if (!provider) return;
@@ -144,6 +181,7 @@ export class GlobalConfigManager {
       enableBuiltinPieces: parsed.enable_builtin_pieces,
       anthropicApiKey: parsed.anthropic_api_key,
       openaiApiKey: parsed.openai_api_key,
+      codexCliPath: parsed.codex_cli_path,
       opencodeApiKey: parsed.opencode_api_key,
       pipeline: parsed.pipeline ? {
         defaultBranchPrefix: parsed.pipeline.default_branch_prefix,
@@ -219,6 +257,9 @@ export class GlobalConfigManager {
     if (config.openaiApiKey) {
       raw.openai_api_key = config.openaiApiKey;
     }
+    if (config.codexCliPath) {
+      raw.codex_cli_path = config.codexCliPath;
+    }
     if (config.opencodeApiKey) {
       raw.opencode_api_key = config.opencodeApiKey;
     }
@@ -379,6 +420,28 @@ export function resolveOpenaiApiKey(): string | undefined {
   }
 }
 
+/**
+ * Resolve the Codex CLI path override.
+ * Priority: TAKT_CODEX_CLI_PATH env var > config.yaml > undefined (SDK vendored binary fallback)
+ */
+export function resolveCodexCliPath(): string | undefined {
+  const envPath = process.env['TAKT_CODEX_CLI_PATH'];
+  if (envPath !== undefined) {
+    return validateCodexCliPath(envPath, 'TAKT_CODEX_CLI_PATH');
+  }
+
+  let config: GlobalConfig;
+  try {
+    config = loadGlobalConfig();
+  } catch {
+    return undefined;
+  }
+  if (config.codexCliPath === undefined) {
+    return undefined;
+  }
+  return validateCodexCliPath(config.codexCliPath, 'codex_cli_path');
+}
+
 /**
  * Resolve the OpenCode API key.
  * Priority: TAKT_OPENCODE_API_KEY env var > config.yaml > undefined

src/infra/config/global/index.ts

@@ -14,6 +14,7 @@ export {
   setProvider,
   resolveAnthropicApiKey,
   resolveOpenaiApiKey,
+  resolveCodexCliPath,
   resolveOpencodeApiKey,
   loadProjectDebugConfig,
   getEffectiveDebugConfig,

src/infra/providers/codex.ts

@@ -4,7 +4,7 @@
 
 import { execFileSync } from 'node:child_process';
 import { callCodex, callCodexCustom, type CodexCallOptions } from '../codex/index.js';
-import { resolveOpenaiApiKey } from '../config/index.js';
+import { resolveOpenaiApiKey, resolveCodexCliPath } from '../config/index.js';
 import type { AgentResponse } from '../../core/models/index.js';
 import type { AgentSetup, Provider, ProviderAgent, ProviderCallOptions } from './types.js';
 
@@ -34,6 +34,7 @@ function toCodexOptions(options: ProviderCallOptions): CodexCallOptions {
     networkAccess: options.providerOptions?.codex?.networkAccess,
     onStream: options.onStream,
     openaiApiKey: options.openaiApiKey ?? resolveOpenaiApiKey(),
+    codexPathOverride: resolveCodexCliPath(),
     outputSchema: options.outputSchema,
   };
 }