The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix: port Windows hook safety fixes (#1719)
Affaan Mustafaf442bac8c9f3
diff --git a/scripts/hooks/mcp-health-check.js b/scripts/hooks/mcp-health-check.jsindex 76da6b5db..3e763d05f 100644--- a/scripts/hooks/mcp-health-check.js+++ b/scripts/hooks/mcp-health-check.js@@ -306,126 +306,175 @@ function probeCommandServer(serverName, config) {...(config.env && typeof config.env === 'object' && !Array.isArray(config.env) ? config.env : {})};- let stderr = '';let done = false;- let timer = null;function finish(result) {if (done) return;done = true;- if (timer) {- clearTimeout(timer);- timer = null;- }resolve(result);}- // On Windows, commands like 'npx' are actually 'npx.cmd' batch files that- // require shell expansion to resolve. However, absolute paths (e.g.- // 'C:\Program Files\nodejs\node.exe') must NOT use shell mode because- // cmd.exe misparses paths containing spaces. Only enable shell for- // non-absolute commands that need PATH resolution.- //- // Security: validate the command for shell metacharacters before enabling- // shell mode. cmd.exe treats &, |, <, >, ^, %, !, (, ), ;, and whitespace- // as operators/separators. A crafted command value from an MCP config file- // could otherwise inject arbitrary shell commands.+ // On Windows, commands like 'npx' are commonly exposed as npx.cmd.+ // Probe bare PATH commands through platform-extension fallbacks, but keep+ // absolute/relative path commands as a single candidate so their existing+ // ENOENT failure semantics stay intact.+ const commandIsString = typeof command === 'string' && command.length > 0;+ const isPathLike = commandIsString && (+ path.isAbsolute(command)+ || command.includes('/')+ || command.includes('\\')+ );+ const candidates = process.platform === 'win32'+ && commandIsString+ && !path.extname(command)+ && !isPathLike+ ? [command, `${command}.cmd`, `${command}.exe`, `${command}.bat`]+ : [command];++ // cmd.exe treats these as operators, grouping syntax, expansion markers,+ // separators, or argument boundaries. Do not route such command strings+ // through shell mode.const UNSAFE_SHELL_CHARS = /[&|<>^%!()\s;]/;- const needsShell =- process.platform === 'win32' &&- typeof command === 'string' &&- !path.isAbsolute(command) &&- !UNSAFE_SHELL_CHARS.test(command);- let child;- try {- child = spawn(command, args, {- env: mergedEnv,- cwd: process.cwd(),- stdio: ['pipe', 'ignore', 'pipe'],- shell: needsShell- });- } catch (error) {- finish({- ok: false,- statusCode: null,- reason: error.message- });- return;- }- child.stderr.on('data', chunk => {- if (stderr.length < 4000) {- const remaining = 4000 - stderr.length;- stderr += String(chunk).slice(0, remaining);+ function attempt(idx) {+ const tryCommand = candidates[idx];+ const isLast = idx + 1 >= candidates.length;+ let stderr = '';+ let attemptDone = false;+ let timer = null;++ function retryNext() {+ if (attemptDone) return;+ attemptDone = true;+ if (timer) {+ clearTimeout(timer);+ timer = null;+ }+ attempt(idx + 1);}- });- child.on('error', error => {- finish({- ok: false,- statusCode: null,- reason: error.message- });- });+ function attemptFinish(result) {+ if (attemptDone) return;+ attemptDone = true;+ if (timer) {+ clearTimeout(timer);+ timer = null;+ }+ finish(result);+ }- child.on('exit', (code, signal) => {- finish({- ok: false,- statusCode: code,- reason: stderr.trim() || `process exited before handshake (${signal || code || 'unknown'})`- });- });+ // Node 18.20+/20.12+ refuse to spawn .cmd/.bat directly on Windows+ // after the CVE-2024-27980 mitigation. Only those extension candidates+ // go through cmd.exe, after the command string is shell-character clean.+ const useShell = process.platform === 'win32'+ && typeof tryCommand === 'string'+ && /\.(cmd|bat)$/i.test(tryCommand)+ && !UNSAFE_SHELL_CHARS.test(tryCommand);- timer = setTimeout(() => {- // A fast-crashing stdio server can finish before the timer callback runs- // on a loaded machine. Check the process state again before classifying it- // as healthy on timeout.- if (child.exitCode !== null || child.signalCode !== null) {- finish({+ let child;+ try {+ child = spawn(tryCommand, args, {+ env: mergedEnv,+ cwd: process.cwd(),+ stdio: ['pipe', 'ignore', 'pipe'],+ shell: useShell+ });+ } catch (error) {+ if ((error.code === 'ENOENT' || error.code === 'EINVAL') && !isLast) {+ retryNext();+ return;+ }+ attemptFinish({ok: false,- statusCode: child.exitCode,- reason: stderr.trim() || `process exited before handshake (${child.signalCode || child.exitCode || 'unknown'})`+ statusCode: null,+ reason: error.message});return;}- try {- if (needsShell && child.pid && process.platform === 'win32') {- // When spawned via shell on Windows, child is cmd.exe. kill() only- // terminates the shell and leaves the real server process orphaned.- // taskkill /T kills the entire process tree rooted at cmd.exe.- const killResult = spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], { stdio: 'ignore' });- if (killResult.error || (typeof killResult.status === 'number' && killResult.status !== 0)) {- // taskkill not on PATH, permission denied, or already exited.- // Best-effort fallback: signal the cmd.exe shell directly. The- // child tree may still leak if it already detached, but this at- // least kills the shell we spawned.- try { child.kill('SIGKILL'); } catch { /* ignore */ }- }- } else {- child.kill('SIGTERM');- setTimeout(() => {- try {- child.kill('SIGKILL');- } catch {- // ignore- }- }, 200).unref?.();+ child.stderr.on('data', chunk => {+ if (stderr.length < 4000) {+ const remaining = 4000 - stderr.length;+ stderr += String(chunk).slice(0, remaining);}- } catch {- // ignore- }+ });- finish({- ok: true,- statusCode: null,- reason: `${serverName} accepted a new stdio process`+ child.on('error', error => {+ if ((error.code === 'ENOENT' || error.code === 'EINVAL') && !isLast) {+ retryNext();+ return;+ }+ attemptFinish({+ ok: false,+ statusCode: null,+ reason: error.message+ });+ });++ child.on('exit', (code, signal) => {+ attemptFinish({+ ok: false,+ statusCode: code,+ reason: stderr.trim() || `process exited before handshake (${signal || code || 'unknown'})`+ });});- }, timeoutMs);- if (typeof timer.unref === 'function') {- timer.unref();+ timer = setTimeout(() => {+ // A fast-crashing stdio server can finish before the timer callback runs+ // on a loaded machine. Check the process state again before classifying it+ // as healthy on timeout.+ if (child.exitCode !== null || child.signalCode !== null) {+ attemptFinish({+ ok: false,+ statusCode: child.exitCode,+ reason: stderr.trim() || `process exited before handshake (${child.signalCode || child.exitCode || 'unknown'})`+ });+ return;+ }++ try {+ if (useShell && child.pid && process.platform === 'win32') {+ // When spawned via shell on Windows, child is cmd.exe. kill() only+ // terminates the shell and leaves the real server process orphaned.+ // taskkill /T kills the entire process tree rooted at cmd.exe.+ const killResult = spawnSync('taskkill', ['/PID', String(child.pid), '/T', '/F'], {+ stdio: 'ignore',+ windowsHide: true+ });+ if (killResult.error || (typeof killResult.status === 'number' && killResult.status !== 0)) {+ // taskkill not on PATH, permission denied, or already exited.+ // Best-effort fallback: signal the cmd.exe shell directly. The+ // child tree may still leak if it already detached, but this at+ // least kills the shell we spawned.+ try { child.kill('SIGKILL'); } catch { /* ignore */ }+ }+ } else {+ child.kill('SIGTERM');+ setTimeout(() => {+ try {+ child.kill('SIGKILL');+ } catch {+ // ignore+ }+ }, 200).unref?.();+ }+ } catch {+ // ignore+ }++ attemptFinish({+ ok: true,+ statusCode: null,+ reason: `${serverName} accepted a new stdio process`+ });+ }, timeoutMs);++ if (typeof timer.unref === 'function') {+ timer.unref();+ }}++ attempt(0);});}diff --git a/scripts/hooks/post-edit-format.js b/scripts/hooks/post-edit-format.jsindex d6486866b..26a79f939 100644--- a/scripts/hooks/post-edit-format.js+++ b/scripts/hooks/post-edit-format.js@@ -21,7 +21,7 @@ const { execFileSync, spawnSync } = require('child_process');const path = require('path');// Shell metacharacters that cmd.exe interprets as command separators/operators-const UNSAFE_PATH_CHARS = /[&|<>^%!]/;+const UNSAFE_PATH_CHARS = /[&|<>^%!;`()$]/;const { findProjectRoot, detectFormatter, resolveFormatterBin } = require('../lib/resolve-formatter');diff --git a/tests/hooks/hooks.test.js b/tests/hooks/hooks.test.jsindex 0142a876b..9f2767d75 100644--- a/tests/hooks/hooks.test.js+++ b/tests/hooks/hooks.test.js@@ -2732,6 +2732,68 @@ async function runTests() {passed++;else failed++;+ if (+ await asyncTest('blocks Windows shell metacharacters before shell:true formatter execution', async () => {+ const hookPath = path.join(scriptsDir, 'post-edit-format.js');+ const resolverPath = path.join(scriptsDir, '..', 'lib', 'resolve-formatter.js');+ const childProcess = require('child_process');+ const originalPlatform = Object.getOwnPropertyDescriptor(process, 'platform');+ const originalSpawnSync = childProcess.spawnSync;+ const originalExecFileSync = childProcess.execFileSync;+ const resolvedResolverPath = require.resolve(resolverPath);+ const resolvedHookPath = require.resolve(hookPath);+ const originalResolverCache = require.cache[resolvedResolverPath];+ const originalHookCache = require.cache[resolvedHookPath];+ const blockedPaths = ['semicolon;test.js', 'backtick`test.js', 'subshell$(test).js', 'group(test).js'];++ try {+ Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });++ let spawnCalls = [];+ childProcess.spawnSync = (...args) => {+ spawnCalls.push(args);+ return { status: 0, stderr: Buffer.from('') };+ };+ childProcess.execFileSync = () => {+ throw new Error('execFileSync should not run for Windows .cmd formatter shims');+ };++ require.cache[resolvedResolverPath] = {+ id: resolvedResolverPath,+ filename: resolvedResolverPath,+ loaded: true,+ exports: {+ findProjectRoot: () => process.cwd(),+ detectFormatter: () => 'prettier',+ resolveFormatterBin: () => ({ bin: 'formatter.cmd', prefix: [] })+ }+ };+ delete require.cache[resolvedHookPath];++ const { run } = require(hookPath);++ for (const filePath of blockedPaths) {+ spawnCalls = [];+ const stdinJson = JSON.stringify({ tool_input: { file_path: filePath } });+ assert.strictEqual(run(stdinJson), stdinJson, 'Should pass through original stdin JSON');+ assert.strictEqual(spawnCalls.length, 0, `Should reject ${filePath} before spawnSync`);+ }+ } finally {+ if (originalPlatform) {+ Object.defineProperty(process, 'platform', originalPlatform);+ }+ childProcess.spawnSync = originalSpawnSync;+ childProcess.execFileSync = originalExecFileSync;+ if (originalResolverCache) require.cache[resolvedResolverPath] = originalResolverCache;+ else delete require.cache[resolvedResolverPath];+ if (originalHookCache) require.cache[resolvedHookPath] = originalHookCache;+ else delete require.cache[resolvedHookPath];+ }+ })+ )+ passed++;+ else failed++;+if (await asyncTest('matches .tsx extension for formatting', async () => {const stdinJson = JSON.stringify({ tool_input: { file_path: '/nonexistent/component.tsx' } });diff --git a/tests/hooks/mcp-health-check.test.js b/tests/hooks/mcp-health-check.test.jsindex 958221c1e..02145adef 100644--- a/tests/hooks/mcp-health-check.test.js+++ b/tests/hooks/mcp-health-check.test.js@@ -952,6 +952,65 @@ async function runTests() {}})) passed++; else failed++;+ // Windows-only: child_process.spawn cannot resolve .cmd/.bat shims for+ // bare PATH commands without an extension, and Node 18.20+/20.12+ refuse+ // to spawn .cmd targets without `shell: true` (CVE-2024-27980). The probe+ // must retry bare command names with platform extensions and route .cmd/.bat+ // through the shell, otherwise tools like `npx` are misclassified as+ // unhealthy on first use. Path-like commands keep single-candidate ENOENT+ // semantics.+ if (process.platform === 'win32') {+ if (await asyncTest('windows: probes bare PATH commands via .cmd fallback', async () => {+ const tempDir = createTempDir();+ const binDir = path.join(tempDir, 'bin');+ const configPath = path.join(tempDir, 'claude.json');+ const statePath = path.join(tempDir, 'mcp-health.json');++ fs.mkdirSync(binDir, { recursive: true });+ fs.writeFileSync(+ path.join(binDir, 'winfallback.cmd'),+ ['@echo off', 'node -e "setInterval(()=>{},1000)"', ''].join('\r\n')+ );++ try {+ writeConfig(configPath, {+ mcpServers: {+ winfallback: {+ command: 'winfallback',+ args: []+ }+ }+ });++ const input = { tool_name: 'mcp__winfallback__list', tool_input: {} };+ const result = runHook(input, {+ CLAUDE_HOOK_EVENT_NAME: 'PreToolUse',+ ECC_MCP_CONFIG_PATH: configPath,+ ECC_MCP_HEALTH_STATE_PATH: statePath,+ ECC_MCP_HEALTH_TIMEOUT_MS: '500',+ PATH: `${binDir}${path.delimiter}${process.env.PATH || ''}`+ });++ assert.strictEqual(+ result.code,+ 0,+ `Expected bare command to be probed via .cmd fallback: ${hookFailureDetails(result, statePath)}`+ );++ const state = readState(statePath);+ assert.strictEqual(+ state.servers.winfallback.status,+ 'healthy',+ 'Expected bare command to be marked healthy via .cmd fallback'+ );+ } finally {+ cleanupTempDir(tempDir);+ }+ })) passed++; else failed++;+ } else {+ console.log(' - skipped: windows: probes bare PATH commands via .cmd fallback (non-Windows)');+ }+if (await asyncTest('probes command servers using non-absolute commands (e.g. npx) via PATH resolution', async () => {const tempDir = createTempDir();const configPath = path.join(tempDir, 'claude.json');@@ -962,10 +1021,8 @@ async function runTests() {// Create a server script that stays alivefs.writeFileSync(serverScript, "setInterval(() => {}, 1000);\n");- // Use 'node' (non-absolute) as the command to exercise PATH-based resolution.- // On Windows, shell execution is especially relevant for commands exposed via- // batch wrappers such as 'npx.cmd'; using 'node' here simulates that class of- // non-absolute command without depending on npx being available in the environment.+ // Use 'node' (non-absolute) as the command to exercise PATH-based+ // resolution without depending on npx being available in the environment.writeConfig(configPath, {mcpServers: {shelltest: {@@ -983,10 +1040,10 @@ async function runTests() {ECC_MCP_HEALTH_TIMEOUT_MS: '100'});- assert.strictEqual(result.code, 0, `Expected non-absolute command to resolve via shell, got ${result.code}`);+ assert.strictEqual(result.code, 0, `Expected non-absolute command to resolve via PATH, got ${result.code}`);const state = readState(statePath);- assert.strictEqual(state.servers.shelltest.status, 'healthy', 'Expected shell-resolved server to be marked healthy');+ assert.strictEqual(state.servers.shelltest.status, 'healthy', 'Expected PATH-resolved server to be marked healthy');} finally {cleanupTempDir(tempDir);}