@kontourai/flow-agents 0.1.1

package/scripts/flow-kit.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../build/src/cli/flow-kit.js").then(({ main }) => process.exit(main()));

package/scripts/generate-context-map.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import("../build/src/tools/generate-context-map.js").then(({ main }) => process.exit(main(process.argv.slice(2))));

package/scripts/git-status.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Spawn hook: git status + worktree context for parallel safety
+
+if ! git rev-parse --is-inside-work-tree &>/dev/null; then
+  echo "📁 Not a git repository — skipping git context"
+  exit 0
+fi
+
+# Basic status
+echo "=== Git Status ==="
+git status --short
+
+# Branch/worktree context
+echo ""
+echo "=== Branch ==="
+git branch --show-current
+
+# Detect if we're in a worktree (not the main working tree)
+TOPLEVEL=$(git rev-parse --show-toplevel)
+COMMON=$(git rev-parse --git-common-dir)
+GIT_DIR=$(git rev-parse --git-dir)
+
+if [ "$GIT_DIR" != "$COMMON" ]; then
+  echo "⚠️  Running inside a git worktree: $TOPLEVEL"
+  echo "   Main repo: $(cd "$COMMON/.." && pwd)"
+fi
+
+# List active worktrees for conflict awareness
+WORKTREE_COUNT=$(git worktree list | wc -l | tr -d ' ')
+if [ "$WORKTREE_COUNT" -gt 1 ]; then
+  echo ""
+  echo "=== Active Worktrees ($WORKTREE_COUNT) ==="
+  git worktree list
+  echo ""
+  echo "⚠️  Multiple worktrees active — check .flow-agents/ for in-progress tasks before modifying shared files"
+fi
+
+# List existing TODOs for awareness
+TODO_DIR=".flow-agents"
+if [ -d "$TODO_DIR" ]; then
+  TODO_COUNT=$(find "$TODO_DIR" -name "*.md" 2>/dev/null | wc -l | tr -d ' ')
+  if [ "$TODO_COUNT" -gt 0 ]; then
+    echo ""
+    echo "=== Active TODOs ($TODO_COUNT) ==="
+    while IFS= read -r f; do
+      [ -f "$f" ] && echo "  - $(basename "$f" .md): $(head -1 "$f")"
+    done < <(find "$TODO_DIR" -mindepth 2 -maxdepth 2 -name "*.md" 2>/dev/null | sort)
+  fi
+fi

package/scripts/hooks/claude-hook-adapter.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+/**
+ * Claude Code hook adapter for canonical Flow Agents hooks.
+ *
+ * Canonical hook scripts use the Kiro convention: exit 0 passes, exit 2 blocks,
+ * and stderr/stdout carries human-readable guidance. Claude Code expects JSON
+ * hook responses, so this wrapper translates policy blocks while failing open
+ * for hook runtime errors.
+ */
+
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    let truncated = false;
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        const remaining = MAX_STDIN - raw.length;
+        raw += chunk.substring(0, remaining);
+        if (chunk.length > remaining) truncated = true;
+      } else {
+        truncated = true;
+      }
+    });
+    process.stdin.on('end', () => resolve({ raw, truncated }));
+    process.stdin.on('error', () => resolve({ raw, truncated }));
+  });
+}
+
+function parseEvent(raw, fallback) {
+  try {
+    return JSON.parse(raw || '{}').hook_event_name || fallback || '';
+  } catch {
+    return fallback || '';
+  }
+}
+
+function messageFrom(result) {
+  const stderr = String(result.stderr || '').trim();
+  const stdout = String(result.stdout || '').trim();
+  return stderr || stdout || 'Blocked by Flow Agents hook policy.';
+}
+
+function guidanceFromStdout(rawInput, stdout) {
+  const text = String(stdout || '');
+  if (!text.trim()) return '';
+  const guidance = text.startsWith(rawInput) ? text.slice(rawInput.length) : text;
+  return guidance.trim();
+}
+
+function successOutput(event, additionalContext = '') {
+  const context = String(additionalContext || '').trim();
+  if (event === 'SessionStart') {
+    return {
+      continue: true,
+      suppressOutput: !context,
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: context || 'Flow Agents hooks are active for this Claude Code session.',
+      },
+    };
+  }
+  if (event === 'PostToolUse' && context) {
+    return {
+      continue: true,
+      suppressOutput: false,
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: context,
+      },
+    };
+  }
+  if (event === 'UserPromptSubmit' && context) {
+    return {
+      continue: true,
+      suppressOutput: false,
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: context,
+      },
+    };
+  }
+  return { continue: true, suppressOutput: true };
+}
+
+function blockedOutput(event, reason) {
+  if (event === 'PreToolUse') {
+    return {
+      continue: false,
+      stopReason: reason,
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    };
+  }
+  if (event === 'PostToolUse') {
+    return {
+      continue: false,
+      stopReason: reason,
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: reason,
+      },
+    };
+  }
+  if (event === 'Stop') {
+    return {
+      decision: 'block',
+      reason,
+      continue: false,
+      stopReason: reason,
+    };
+  }
+  return {
+    decision: 'block',
+    reason,
+    continue: false,
+    stopReason: reason,
+  };
+}
+
+async function main() {
+  const [, , eventArg = 'unknown', hookId, relScriptPath, profilesCsv] = process.argv;
+  const { raw, truncated } = await readStdinRaw();
+  const event = parseEvent(raw, eventArg);
+
+  if (!hookId || !relScriptPath) {
+    process.stdout.write(`${JSON.stringify(successOutput(event))}\n`);
+    return;
+  }
+
+  const runHookPath = path.resolve(__dirname, 'run-hook.js');
+  const result = spawnSync(process.execPath, [runHookPath, hookId, relScriptPath, profilesCsv || ''], {
+    input: raw,
+    encoding: 'utf8',
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      SA_HOOK_INPUT_TRUNCATED: truncated ? '1' : '0',
+      SA_HOOK_INPUT_MAX_BYTES: String(MAX_STDIN),
+      FLOW_AGENTS_HOOK_RUNTIME: 'claude-code',
+    },
+    timeout: Number(process.env.FLOW_AGENTS_CLAUDE_HOOK_TIMEOUT_MS || 30000),
+  });
+
+  if (result.status === 2) {
+    process.stdout.write(`${JSON.stringify(blockedOutput(event, messageFrom(result)))}\n`);
+    return;
+  }
+
+  if (result.error || result.signal || result.status === null) {
+    const detail = result.error ? result.error.message : result.signal ? `signal ${result.signal}` : 'missing exit status';
+    process.stderr.write(`[ClaudeHook] ${hookId} failed open: ${detail}\n`);
+    process.stdout.write(`${JSON.stringify(successOutput(event))}\n`);
+    return;
+  }
+
+  if (result.stderr) process.stderr.write(result.stderr);
+  process.stdout.write(`${JSON.stringify(successOutput(event, guidanceFromStdout(raw, result.stdout)))}\n`);
+}
+
+main().catch(err => {
+  process.stderr.write(`[ClaudeHook] adapter error: ${err.message}\n`);
+  process.exit(0);
+});

package/scripts/hooks/claude-telemetry-hook.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+/**
+ * Claude Code telemetry hook wrapper.
+ *
+ * Claude Code hooks send JSON on stdin and accept a permissive JSON response
+ * for lifecycle hooks. This wrapper adapts Claude hook events to the canonical
+ * Flow Agents telemetry script and stays fail-open so telemetry cannot block work.
+ */
+
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+const DEFAULT_FULL_REDACT = 'hook.raw_input,turn.prompt_text,tool.input,tool.output';
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        raw += chunk.slice(0, MAX_STDIN - raw.length);
+      }
+    });
+    process.stdin.on('end', () => resolve(raw));
+    process.stdin.on('error', () => resolve(raw));
+  });
+}
+
+function parseJson(raw) {
+  try {
+    return JSON.parse(raw || '{}');
+  } catch {
+    return {};
+  }
+}
+
+function canonicalEvent(cliEvent, payload) {
+  const event = cliEvent || payload.hook_event_name || 'unknown';
+  const mapping = {
+    SessionStart: 'agentSpawn',
+    UserPromptSubmit: 'userPromptSubmit',
+    PreToolUse: 'preToolUse',
+    PermissionRequest: 'permissionRequest',
+    PostToolUse: 'postToolUse',
+    PostToolUseFailure: 'postToolUse',
+    Stop: 'stop',
+    SessionEnd: 'stop',
+    SubagentStart: 'subagentStart',
+    SubagentStop: 'subagentStop',
+  };
+  return mapping[event] || event;
+}
+
+function claudeSuccessOutput(event) {
+  if (event === 'SessionStart') {
+    return {
+      continue: true,
+      suppressOutput: true,
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: 'Flow Agents telemetry hooks are active for this Claude Code session.',
+      },
+    };
+  }
+  if (event === 'UserPromptSubmit') {
+    return { continue: true, suppressOutput: true };
+  }
+  if (event === 'Stop' || event === 'SubagentStop' || event === 'SessionEnd') {
+    return { continue: true, suppressOutput: true };
+  }
+  return { continue: true, suppressOutput: true };
+}
+
+async function main() {
+  const [, , eventArg = 'unknown', agentName = 'dev'] = process.argv;
+  const raw = await readStdinRaw();
+  const payload = parseJson(raw);
+  const hookEvent = payload.hook_event_name || eventArg;
+  const telemetryScript = path.resolve(__dirname, '..', 'telemetry', 'telemetry.sh');
+
+  const result = spawnSync('bash', [telemetryScript, canonicalEvent(eventArg, payload), agentName], {
+    input: raw,
+    encoding: 'utf8',
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      FLOW_AGENTS_TELEMETRY_RUNTIME: 'claude-code',
+      FLOW_AGENTS_TELEMETRY_FOREGROUND: process.env.FLOW_AGENTS_CLAUDE_TELEMETRY_FOREGROUND || 'false',
+      TELEMETRY_CHANNELS: process.env.FLOW_AGENTS_CLAUDE_TELEMETRY_CHANNELS || 'full,analytics',
+      TELEMETRY_CHANNEL_FULL_REDACT: process.env.TELEMETRY_CHANNEL_FULL_REDACT || DEFAULT_FULL_REDACT,
+      TELEMETRY_CHANNEL_ANALYTICS_REDACT:
+        process.env.TELEMETRY_CHANNEL_ANALYTICS_REDACT ||
+        'tool.input,tool.output,turn.prompt_text,delegation.targets.query,context.cwd,hook.raw_input',
+      TELEMETRY_CHANNEL_FULL_ENDPOINT_URL: process.env.TELEMETRY_CHANNEL_FULL_ENDPOINT_URL || '',
+      TELEMETRY_USAGE_TRACKING: process.env.TELEMETRY_USAGE_TRACKING || 'true',
+    },
+    timeout: Number(process.env.FLOW_AGENTS_CLAUDE_TELEMETRY_TIMEOUT_MS || 30000),
+  });
+
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.error || result.signal || result.status === null) {
+    const detail = result.error ? result.error.message : result.signal ? `signal ${result.signal}` : 'missing exit status';
+    process.stderr.write(`[ClaudeTelemetryHook] failed open: ${detail}\n`);
+  }
+
+  process.stdout.write(`${JSON.stringify(claudeSuccessOutput(hookEvent))}\n`);
+}
+
+main().catch(err => {
+  process.stderr.write(`[ClaudeTelemetryHook] wrapper error: ${err.message}\n`);
+  process.exit(0);
+});

package/scripts/hooks/codex-hook-adapter.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * Codex hook adapter.
+ *
+ * The canonical hook scripts in this repo were originally written for Kiro:
+ * exit 0 passes through, exit 2 blocks, and stdout often echoes the hook input.
+ * Codex has a stricter event-specific JSON contract, so this adapter runs the
+ * canonical hook and translates its result into the Codex hook protocol.
+ */
+
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    let truncated = false;
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        const remaining = MAX_STDIN - raw.length;
+        raw += chunk.substring(0, remaining);
+        if (chunk.length > remaining) truncated = true;
+      } else {
+        truncated = true;
+      }
+    });
+    process.stdin.on('end', () => resolve({ raw, truncated }));
+    process.stdin.on('error', () => resolve({ raw, truncated }));
+  });
+}
+
+function eventName(raw) {
+  try {
+    return JSON.parse(raw).hook_event_name || '';
+  } catch {
+    return '';
+  }
+}
+
+function messageFrom(result) {
+  const stderr = String(result.stderr || '').trim();
+  const stdout = String(result.stdout || '').trim();
+  return stderr || stdout || 'Blocked by Flow Agents hook policy.';
+}
+
+function guidanceFromStdout(rawInput, stdout) {
+  const text = String(stdout || '');
+  if (!text.trim()) return '';
+  const guidance = text.startsWith(rawInput) ? text.slice(rawInput.length) : text;
+  return guidance.trim();
+}
+
+function successOutput(event, additionalContext = '') {
+  const context = String(additionalContext || '').trim();
+  if (event === 'SessionStart') {
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: context || 'Flow Agents Codex hooks are active for this workspace.',
+      },
+    };
+  }
+  if (event === 'PostToolUse' && context) {
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: context,
+      },
+    };
+  }
+  if (event === 'UserPromptSubmit' && context) {
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: context,
+      },
+    };
+  }
+  if (event === 'UserPromptSubmit' || event === 'Stop') {
+    return { continue: true };
+  }
+  return null;
+}
+
+function blockedOutput(event, reason) {
+  if (event === 'PreToolUse') {
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'deny',
+        permissionDecisionReason: reason,
+      },
+    };
+  }
+  if (event === 'PermissionRequest') {
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PermissionRequest',
+        decision: {
+          behavior: 'deny',
+          message: reason,
+        },
+      },
+    };
+  }
+  if (event === 'PostToolUse') {
+    return {
+      continue: false,
+      stopReason: reason,
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: reason,
+      },
+    };
+  }
+  return {
+    decision: 'block',
+    reason,
+  };
+}
+
+async function main() {
+  const [, , hookId, relScriptPath, profilesCsv] = process.argv;
+  const { raw, truncated } = await readStdinRaw();
+  const event = eventName(raw);
+
+  if (!hookId || !relScriptPath) {
+    const output = successOutput(event);
+    if (output) process.stdout.write(`${JSON.stringify(output)}\n`);
+    return;
+  }
+
+  const runHookPath = path.resolve(__dirname, 'run-hook.js');
+  const result = spawnSync(process.execPath, [runHookPath, hookId, relScriptPath, profilesCsv || ''], {
+    input: raw,
+    encoding: 'utf8',
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      SA_HOOK_INPUT_TRUNCATED: truncated ? '1' : '0',
+      SA_HOOK_INPUT_MAX_BYTES: String(MAX_STDIN),
+      FLOW_AGENTS_HOOK_RUNTIME: 'codex',
+    },
+    timeout: Number(process.env.FLOW_AGENTS_CODEX_HOOK_TIMEOUT_MS || 30000),
+  });
+
+  if (result.status === 2) {
+    process.stdout.write(`${JSON.stringify(blockedOutput(event, messageFrom(result)))}\n`);
+    return;
+  }
+
+  if (result.error || result.signal || result.status === null) {
+    const detail = result.error ? result.error.message : result.signal ? `signal ${result.signal}` : 'missing exit status';
+    const output = successOutput(event);
+    if (output) process.stdout.write(`${JSON.stringify(output)}\n`);
+    process.stderr.write(`[CodexHook] ${hookId} failed open: ${detail}\n`);
+    return;
+  }
+
+  if (result.stderr) process.stderr.write(result.stderr);
+  const output = successOutput(event, guidanceFromStdout(raw, result.stdout));
+  if (output) process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+main().catch(err => {
+  process.stderr.write(`[CodexHook] adapter error: ${err.message}\n`);
+  process.exit(0);
+});

package/scripts/hooks/codex-telemetry-hook.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * Codex telemetry hook wrapper.
+ *
+ * Codex command hooks are stricter than Kiro hooks. This wrapper runs the
+ * canonical telemetry script with Codex-safe environment overrides, then emits
+ * a valid hook response for lifecycle events. Telemetry runs in the background
+ * by default so PostToolUse hooks do not stall the chat loop.
+ */
+
+'use strict';
+
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const MAX_STDIN = 1024 * 1024;
+const DEFAULT_FULL_REDACT = 'hook.raw_input,turn.prompt_text,tool.input,tool.output';
+
+function readStdinRaw() {
+  return new Promise(resolve => {
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', chunk => {
+      if (raw.length < MAX_STDIN) {
+        raw += chunk.slice(0, MAX_STDIN - raw.length);
+      }
+    });
+    process.stdin.on('end', () => resolve(raw));
+    process.stdin.on('error', () => resolve(raw));
+  });
+}
+
+function hookEventName(raw) {
+  try {
+    return JSON.parse(raw).hook_event_name || '';
+  } catch {
+    return '';
+  }
+}
+
+function codexSuccessOutput(event) {
+  if (event === 'SessionStart') {
+    return {
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'SessionStart',
+        additionalContext: 'Flow Agents telemetry hooks are active for this session.',
+      },
+    };
+  }
+  if (event === 'UserPromptSubmit' || event === 'Stop') {
+    return { continue: true };
+  }
+  return null;
+}
+
+async function main() {
+  const [, , eventType = 'unknown', agentName = 'dev'] = process.argv;
+  const raw = await readStdinRaw();
+  const event = hookEventName(raw);
+  const telemetryScript = path.resolve(__dirname, '..', 'telemetry', 'telemetry.sh');
+
+  const result = spawnSync('bash', [telemetryScript, eventType, agentName], {
+    input: raw,
+    encoding: 'utf8',
+    cwd: process.cwd(),
+    env: {
+      ...process.env,
+      FLOW_AGENTS_TELEMETRY_RUNTIME: 'codex',
+      FLOW_AGENTS_TELEMETRY_FOREGROUND: process.env.FLOW_AGENTS_CODEX_TELEMETRY_FOREGROUND || 'false',
+      TELEMETRY_CHANNELS: process.env.FLOW_AGENTS_CODEX_TELEMETRY_CHANNELS || 'full,analytics',
+      TELEMETRY_CHANNEL_FULL_REDACT: process.env.TELEMETRY_CHANNEL_FULL_REDACT || DEFAULT_FULL_REDACT,
+      TELEMETRY_CHANNEL_ANALYTICS_REDACT:
+        process.env.TELEMETRY_CHANNEL_ANALYTICS_REDACT ||
+        'tool.input,tool.output,turn.prompt_text,delegation.targets.query,context.cwd,hook.raw_input',
+      TELEMETRY_CHANNEL_FULL_ENDPOINT_URL: process.env.TELEMETRY_CHANNEL_FULL_ENDPOINT_URL || '',
+      TELEMETRY_USAGE_TRACKING: process.env.TELEMETRY_USAGE_TRACKING || 'true',
+    },
+    timeout: Number(process.env.FLOW_AGENTS_CODEX_TELEMETRY_TIMEOUT_MS || 30000),
+  });
+
+  if (result.stderr) process.stderr.write(result.stderr);
+  if (result.error || result.signal || result.status === null) {
+    const detail = result.error ? result.error.message : result.signal ? `signal ${result.signal}` : 'missing exit status';
+    process.stderr.write(`[CodexTelemetryHook] failed open: ${detail}\n`);
+  }
+
+  const output = codexSuccessOutput(event);
+  if (output) process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+main().catch(err => {
+  process.stderr.write(`[CodexTelemetryHook] wrapper error: ${err.message}\n`);
+  process.exit(0);
+});

package/scripts/hooks/config-protection.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * Config Protection Hook
+ *
+ * Blocks modifications to linter/formatter config files.
+ * Steers the agent to fix source code instead of weakening configs.
+ *
+ * Exit codes: 0 = allow, 2 = block
+ */
+
+'use strict';
+
+const path = require('path');
+
+const MAX_STDIN = 1024 * 1024;
+
+const PROTECTED_FILES = new Set([
+  '.eslintrc', '.eslintrc.js', '.eslintrc.cjs', '.eslintrc.json', '.eslintrc.yml', '.eslintrc.yaml',
+  'eslint.config.js', 'eslint.config.mjs', 'eslint.config.cjs', 'eslint.config.ts', 'eslint.config.mts', 'eslint.config.cts',
+  '.prettierrc', '.prettierrc.js', '.prettierrc.cjs', '.prettierrc.json', '.prettierrc.yml', '.prettierrc.yaml',
+  'prettier.config.js', 'prettier.config.cjs', 'prettier.config.mjs',
+  'biome.json', 'biome.jsonc',
+  '.ruff.toml', 'ruff.toml',
+  '.shellcheckrc', '.stylelintrc', '.stylelintrc.json', '.stylelintrc.yml',
+  '.markdownlint.json', '.markdownlint.yaml', '.markdownlintrc',
+]);
+
+function run(inputOrRaw, options = {}) {
+  if (options.truncated) {
+    return {
+      exitCode: 2,
+      stderr: `BLOCKED: Hook input exceeded ${options.maxStdin || MAX_STDIN} bytes. ` +
+        'Refusing to bypass config-protection on a truncated payload.',
+    };
+  }
+
+  let input;
+  try {
+    input = typeof inputOrRaw === 'string' ? JSON.parse(inputOrRaw) : inputOrRaw;
+  } catch { return { exitCode: 0 }; }
+
+  const filePath = input?.tool_input?.path || input?.tool_input?.file_path || '';
+  if (!filePath) return { exitCode: 0 };
+
+  const basename = path.basename(filePath);
+  if (PROTECTED_FILES.has(basename)) {
+    return {
+      exitCode: 2,
+      stderr: `BLOCKED: Modifying ${basename} is not allowed. ` +
+        'Fix the source code to satisfy linter/formatter rules instead of ' +
+        'weakening the config. If this is a legitimate config change, ' +
+        'disable the config-protection hook temporarily.',
+    };
+  }
+
+  return { exitCode: 0 };
+}
+
+module.exports = { run };
+
+// Stdin fallback for spawnSync execution
+if (require.main === module) {
+  let raw = '';
+  let truncated = /^(1|true|yes)$/i.test(String(process.env.SA_HOOK_INPUT_TRUNCATED || ''));
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (raw.length < MAX_STDIN) {
+      const remaining = MAX_STDIN - raw.length;
+      raw += chunk.substring(0, remaining);
+      if (chunk.length > remaining) truncated = true;
+    } else { truncated = true; }
+  });
+  process.stdin.on('end', () => {
+    const result = run(raw, { truncated, maxStdin: Number(process.env.SA_HOOK_INPUT_MAX_BYTES) || MAX_STDIN });
+    if (result.stderr) process.stderr.write(result.stderr + '\n');
+    if (result.exitCode === 2) process.exit(2);
+    process.stdout.write(raw);
+  });
+}