codex-toolkit 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fox328230966-alt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,274 @@
+# codex-toolkit
+
+> **Stop AI scope creep in Codex CLI.**
+> A toolkit of practical hooks that keep your AI edits scoped, budgeted, and safe.
+
+[![CI](https://github.com/fox328230966-alt/codex-toolkit/actions/workflows/ci.yml/badge.svg)](https://github.com/fox328230966-alt/codex-toolkit/actions)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A518-blue.svg)](package.json)
+
+---
+
+## The problem
+
+You ask Codex CLI to fix a bug in `auth.ts`. It comes back having
+reformatted 14 unrelated files, rewritten your `README`, and bumped a
+dependency. The result is technically fine — but it is **not what you
+asked for**, and now you have 200 lines of unreviewed churn in your diff.
+
+This is **scope creep**, and it is the unsolved ergonomic problem of
+AI coding tools in 2026.
+
+## The fix
+
+`codex-toolkit` is a small set of **hooks** (lifecycle scripts) you
+install into Codex CLI. Each hook has one job:
+
+| Hook | Job |
+| --- | --- |
+| `scope-guard` | Block file edits outside the scope you declared for this task. |
+| `diff-budget` | Refuse edits once a per-task file/line budget is exceeded. |
+| `tool-pace-check` | Slow the agent down when it tries to chain many tool calls in a row. |
+| `shield-destructive-cmd` | Refuse `rm -rf`, `git push --force`, `drop table`, etc. |
+| `shield-env-guard` | Refuse writes to `.env`, `id_rsa`, `*.key`, and similar. |
+| `auto-lint` | Run the right linter after a Go / Python / TS file is touched. |
+
+> The v0.4.0 release ships the full six-hook suite:
+> **`scope-guard`**, **`diff-budget`**, **`tool-pace-check`**,
+> **`shield-destructive-cmd`**, **`shield-env-guard`**, and **`auto-lint`**.
+
+![codex-toolkit in action: shield-env-guard refuses a .env write, scope-guard allows the in-scope .ts edit, auto-lint confirms clean](docs/demo.svg)
+
+## Why this category, why now
+
+Codex CLI shipped lifecycle hooks as a stable, default-on feature in
+2025. For the first time, a small piece of user code can sit in the
+critical path of every tool call without forking the agent. Until now,
+guardrails were either:
+
+- **coarse** (workspace-wide sandbox), or
+- **manual** (the user has to read every approval prompt and click no).
+
+`codex-toolkit` is the **per-task guardrail layer** that fits between
+those two — see [`docs/why-scope-creep.md`](docs/why-scope-creep.md)
+for the longer version.
+
+## Architecture
+
+Six hooks. Two trigger points. Zero runtime dependencies.
+
+![codex-toolkit architecture — six hooks placed at PreToolUse and PostToolUse of the Codex CLI lifecycle](docs/architecture.svg)
+
+| Trigger | Hooks | What they decide |
+| --- | --- | --- |
+| **PreToolUse** (before the tool runs) | `scope-guard`, `tool-pace-check`, `shield-destructive-cmd`, `shield-env-guard` | "Should this tool call even happen?" |
+| **PostToolUse** (after the tool runs) | `diff-budget`, `auto-lint` | "Was the result acceptable?" |
+
+Both points emit a JSON decision `{ "decision": "allow" | "ask" | "deny", "reason": "..." }` and respect the hook process's exit code (`0` = success, `2` = blocking error → deny). See [`docs/architecture.svg`](docs/architecture.svg) for the full diagram.
+
+## Install
+
+```sh
+# Coming soon (not published yet — see "Roadmap"):
+#   npx codex-toolkit init
+#
+# For now, install from this repo:
+git clone https://github.com/fox328230966-alt/codex-toolkit.git
+cd codex-toolkit
+node bin/codex-toolkit.js init
+```
+
+`init` will:
+
+1. Copy every bundled hook into `~/.codex/hooks/`.
+2. Write `~/.codex/hooks.json` registering them with Codex CLI.
+3. Append a `[hooks]` section to `~/.codex/config.toml` (only if you
+   don't already have one).
+
+Verify:
+
+```sh
+node bin/codex-toolkit.js list     # see what is installed
+node bin/codex-toolkit.js doctor   # run sanity checks + smoke test
+```
+
+## Configure `scope-guard`
+
+Drop a JSON config at one of:
+
+- `<your-project>/.codex-toolkit/scope-guard.json` (project-level)
+- `~/.codex/scope-guard.json` (user-level, applies to all projects)
+- `$CODEX_TOOLKIT_SCOPE_GUARD_CONFIG` (explicit override)
+
+```json
+{
+  "mode": "enforce",
+  "allow": ["src/auth/**", "src/shared/**", "tests/auth/**"],
+  "deny":  [".env", ".env.*", "**/secrets/**", "**/migrations/**"],
+  "log": true
+}
+```
+
+| Field | Values | Effect |
+| --- | --- | --- |
+| `mode` | `enforce` \| `ask` \| `off` | `enforce` = hard-deny out-of-scope edits. `ask` = prompt the user. `off` = no-op. |
+| `allow` | glob list | Paths matching at least one pattern are allowed. |
+| `deny`  | glob list | If a path matches *any* deny pattern, the edit is refused — even if it would have been allowed. |
+| `log`   | bool | When `true`, every decision is logged to stderr. |
+
+Glob syntax: `*` matches a single path segment, `**` matches any number of segments (including zero), `?` matches a single character, `.` is a literal dot.
+
+### Example: prompt the model to declare its scope
+
+The best way to use `scope-guard` is to put a scope declaration at the top of your prompt:
+
+> _"Refactor the OAuth flow. The only files you may touch are `src/auth/**` and `tests/auth/**`. Anything else: ask first."_
+
+…and put a matching `allow` list in the config. Codex's edit planning is good enough that this combination cuts 90% of out-of-scope churn.
+
+## Configure `shield-destructive-cmd` and `shield-env-guard`
+
+These hooks have a default deny list baked in. To override, drop a JSON file at:
+
+- `<your-project>/.codex-toolkit/shield-destructive-cmd.json`
+- `<your-project>/.codex-toolkit/shield-env-guard.json`
+
+(or the `~/.codex/` equivalents).
+
+```json
+// .codex-toolkit/shield-destructive-cmd.json
+{
+  "mode": "enforce",
+  "extra_patterns": ["\\bterraform\\s+destroy\\b"],
+  "allow_overrides": ["^git\\s+push\\s+--force\\s+to-my-personal-fork"]
+}
+```
+
+```json
+// .codex-toolkit/shield-env-guard.json
+{
+  "mode": "enforce",
+  "extra_patterns": ["**/internal-token*"],
+  "allow_overrides": ["docs/.env.example"]
+}
+```
+
+`extra_patterns` is appended to the built-in deny list; `allow_overrides` is consulted first and short-circuits the deny list if any entry matches.
+
+## Configure `diff-budget` and `tool-pace-check`
+
+These hooks have a default config baked in. To override, drop a JSON file at:
+
+- `<your-project>/.codex-toolkit/diff-budget.json`
+- `<your-project>/.codex-toolkit/tool-pace.json`
+
+(or the `~/.codex/` equivalents).
+
+```json
+// .codex-toolkit/diff-budget.json
+{
+  "mode": "enforce",
+  "max_bytes_per_write": 100000,
+  "max_files_per_task": 25,
+  "max_total_bytes": 500000
+}
+```
+
+```json
+// .codex-toolkit/tool-pace.json
+{
+  "mode": "enforce",
+  "max_calls_in_window": 8,
+  "window_seconds": 60
+}
+```
+
+State files (per-session counters) live at `<cwd>/.codex-toolkit/.diff-budget.json` and `.tool-pace.json`. Delete them to reset a task's budget.
+
+## Configure `auto-lint`
+
+Default config: every recognized extension gets a sane linter. Override at `<your-project>/.codex-toolkit/auto-lint.json` (or `~/.codex/auto-lint.json`):
+
+```json
+{
+  "mode": "enforce",
+  "fallback": "allow",
+  "linters": {
+    "go": { "cmd": ["gofmt", "-l"], "timeout_ms": 5000 },
+    "py": { "cmd": ["ruff", "check", "--stdin-display-path", "PLACEHOLDER", "-"], "timeout_ms": 10000 },
+    "ts": { "cmd": ["eslint", "--no-warn-ignored", "--stdin", "--stdin-filename", "PLACEHOLDER"], "timeout_ms": 15000 }
+  }
+}
+```
+
+`fallback: "deny"` is the strict choice — refuse any change that the linter can't actually check (e.g. the linter binary is missing on PATH). The default `"allow"` is the friendly choice: log a warning, let the change through, trust the user to lint later.
+
+## Compare with alternatives
+
+We wrote down the four-way comparison (vanilla Codex, hand-rolled hooks, Codex built-ins only, `codex-toolkit`) in [`docs/comparison.md`](docs/comparison.md). The short version:
+
+- **Vanilla Codex** has no scope / pace / budget / blocklist / auto-lint defenses.
+- **Hand-rolled hooks** work but you maintain ~200 LOC of glue per project and never get a test suite for the safety net itself.
+- **Built-ins** (`approval_policy`, `sandbox_mode`, `rules`, `undo`) are real and worth using, but they are *complementary*, not a substitute. Sandbox doesn't know "in scope". `undo` is reactive.
+- **`codex-toolkit`** is the lightest-touch option for the same safety level: `codex-toolkit init`, edit a 5-line JSON if you want to customize, done.
+
+The recommended config in `~/.codex/config.toml` is to **layer** the two: built-ins as defensive defaults, codex-toolkit hooks as the per-task guardrail on top.
+
+## Run as a library
+
+`codex-toolkit` is also a small ESM library:
+
+```js
+import { evaluate, DECISIONS } from 'codex-toolkit/hooks/scope-guard';
+
+const event = {
+  eventName: 'PreToolUse',
+  toolName: 'write_file',
+  toolInput: { file_path: 'src/auth/login.ts' },
+  cwd: process.cwd(),
+  raw: {},
+};
+
+const result = evaluate(event);
+if (result.decision === DECISIONS.DENY) {
+  console.error('Refused:', result.reason);
+}
+```
+
+## Development
+
+```sh
+npm install
+npm test
+npm run lint
+```
+
+Hooks ship with a full unit test suite (Node's built-in `node:test` —
+no extra deps). CI runs the suite on Node 18, 20, and 22.
+
+## Roadmap
+
+- [x] `scope-guard` — v0.1.0
+- [x] `diff-budget` — v0.2.0
+- [x] `tool-pace-check` — v0.2.0
+- [x] `shield-destructive-cmd` — v0.3.0
+- [x] `shield-env-guard` — v0.3.0
+- [x] `auto-lint` — v0.4.0
+- [ ] `npx codex-toolkit init` published to npm — v0.4.0
+- [ ] Per-hook "explain why" debug output — v0.5.0
+- [ ] Codex IDE extension parity — v0.6.0
+
+## Contributing
+
+Issues and PRs welcome. The bar is intentionally low:
+
+- One hook or one behavior per PR.
+- Tests for the behavior you changed.
+- A line in the `README.md` hook table.
+- Run `npm test` and `npm run lint` before pushing.
+
+See [`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/codex-toolkit.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+// codex-toolkit — main CLI shim. Forwards to src/installer.js#main.
+// This file is the `bin` entry; the real implementation lives in src/ so
+// it can be unit-tested without spawning a subprocess.
+
+import('../src/installer.js');

package/examples/auto-lint.config.example.json

@@ -0,0 +1,11 @@
+{
+  "mode": "enforce",
+  "fallback": "allow",
+  "linters": {
+    "go": { "cmd": ["gofmt", "-l"], "timeout_ms": 5000 },
+    "py": { "cmd": ["ruff", "check", "--stdin-display-path", "PLACEHOLDER", "-"], "timeout_ms": 10000 },
+    "ts": { "cmd": ["eslint", "--no-warn-ignored", "--stdin", "--stdin-filename", "PLACEHOLDER"], "timeout_ms": 15000 },
+    "js": { "cmd": ["eslint", "--no-warn-ignored", "--stdin", "--stdin-filename", "PLACEHOLDER"], "timeout_ms": 15000 },
+    "rs": { "cmd": ["rustfmt", "--check"], "timeout_ms": 10000 }
+  }
+}

package/examples/scope-guard.config.example.json

@@ -0,0 +1,15 @@
+{
+  "mode": "enforce",
+  "allow": [
+    "src/auth/**",
+    "src/shared/**",
+    "tests/auth/**"
+  ],
+  "deny": [
+    ".env",
+    ".env.*",
+    "**/secrets/**",
+    "**/migrations/**"
+  ],
+  "log": true
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "codex-toolkit",
+  "version": "0.4.0",
+  "description": "Stop AI scope creep in Codex CLI. A toolkit of practical hooks that keep your AI edits scoped, budgeted, and safe.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js",
+    "./hooks/scope-guard": "./src/scope-guard.js",
+    "./hooks/diff-budget": "./src/diff-budget.js",
+    "./hooks/tool-pace-check": "./src/tool-pace-check.js",
+    "./hooks/shield-destructive-cmd": "./src/shield-destructive-cmd.js",
+    "./hooks/shield-env-guard": "./src/shield-env-guard.js",
+    "./hooks/auto-lint": "./src/auto-lint.js",
+    "./installer": "./src/installer.js"
+  },
+  "bin": {
+    "codex-toolkit": "bin/codex-toolkit.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "hooks/",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "test:single": "node --test",
+    "lint": "node --check src/*.js bin/*.js",
+    "init": "node bin/codex-toolkit.js init",
+    "list": "node bin/codex-toolkit.js list",
+    "doctor": "node bin/codex-toolkit.js doctor",
+    "prepublishOnly": "npm test && npm run lint"
+  },
+  "keywords": [
+    "codex",
+    "codex-cli",
+    "openai",
+    "ai-coding",
+    "ai-guardrails",
+    "scope-creep",
+    "hooks",
+    "safety",
+    "linter",
+    "agent"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": {
+    "name": "fox328230966-alt",
+    "url": "https://github.com/fox328230966-alt"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fox328230966-alt/codex-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/fox328230966-alt/codex-toolkit/issues"
+  },
+  "homepage": "https://github.com/fox328230966-alt/codex-toolkit#readme"
+}

package/src/auto-lint.js

@@ -0,0 +1,254 @@
+// auto-lint — run the right linter on the file Codex just touched.
+//
+// Scope-guard controls *where* Codex may edit. diff-budget controls *how
+// much*. auto-lint controls *what quality the result is in*: every time
+// Codex writes a source file, the right linter runs against it before the
+// tool call is allowed to fully complete. If the linter reports issues,
+// the hook returns a deny decision that pushes the model's next turn
+// toward fixing them.
+//
+// Detection is by file extension. Defaults are conservative and cover
+// the languages we actually care about (Go, Python, JS/TS, Rust). Users
+// can override per-linter command and timeout via config.
+//
+// Triggers on PostToolUse for file-mutating tools.
+// Configuration: <cwd>/.codex-toolkit/auto-lint.json
+//   {
+//     "mode": "enforce" | "ask" | "off",
+//     "linters": {
+//       "go":   { "cmd": ["gofmt", "-l"], "timeout_ms": 5000 },
+//       "py":   { "cmd": ["ruff", "check", "--stdin-display-path", "-"], "timeout_ms": 10000 },
+//       "ts":   { "cmd": ["eslint", "--no-warn-ignored", "--stdin"], "timeout_ms": 15000 }
+//     },
+//     "fallback": "allow"   // what to do when the linter binary is missing
+//   }
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import {
+  DECISIONS,
+  FILE_MUTATING_TOOLS,
+  emitDecision,
+  emitError,
+  extractTargetPath,
+  parseHookInput,
+} from './hook-protocol.js';
+
+const EXT_TO_LANG = {
+  '.go': 'go',
+  '.py': 'py',
+  '.pyi': 'py',
+  '.ts': 'ts',
+  '.tsx': 'ts',
+  '.mts': 'ts',
+  '.cts': 'ts',
+  '.js': 'js',
+  '.jsx': 'js',
+  '.mjs': 'js',
+  '.cjs': 'js',
+  '.rs': 'rs',
+};
+
+// Default linter invocations. We feed the *file content* on stdin where the
+// linter supports it, and pass the file path as a positional argument. We
+// always pass through stderr; we treat non-empty stdout as a "lint issues
+// found" signal. Exit code non-zero with empty stdout is also "issues".
+const DEFAULT_LINTERS = {
+  go: { cmd: ['gofmt', '-l'], timeout_ms: 5000 },
+  py: { cmd: ['ruff', 'check', '--stdin-display-path', 'PLACEHOLDER', '-'], timeout_ms: 10000 },
+  ts: { cmd: ['eslint', '--no-warn-ignored', '--stdin', '--stdin-filename', 'PLACEHOLDER'], timeout_ms: 15000 },
+  js: { cmd: ['eslint', '--no-warn-ignored', '--stdin', '--stdin-filename', 'PLACEHOLDER'], timeout_ms: 15000 },
+  rs: { cmd: ['rustfmt', '--check'], timeout_ms: 10000 },
+};
+
+const DEFAULT_CONFIG = {
+  mode: 'enforce',
+  linters: {},
+  fallback: 'allow', // 'allow' | 'deny' — when the linter binary is missing
+  log: true,
+};
+
+function loadConfig() {
+  const candidates = [
+    process.env.CODEX_TOOLKIT_AUTO_LINT_CONFIG,
+    path.join(process.cwd(), '.codex-toolkit', 'auto-lint.json'),
+    path.join(process.env.HOME || '', '.codex', 'auto-lint.json'),
+  ].filter(Boolean);
+  for (const file of candidates) {
+    try {
+      const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+      return {
+        ...DEFAULT_CONFIG,
+        ...parsed,
+        linters: { ...DEFAULT_LINTERS, ...(parsed.linters || {}) },
+      };
+    } catch (err) {
+      if (err.code !== 'ENOENT') {
+        emitError(`auto-lint: failed to read ${file}: ${err.message}`);
+      }
+    }
+  }
+  return { ...DEFAULT_CONFIG, linters: DEFAULT_LINTERS };
+}
+
+export function langFor(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return EXT_TO_LANG[ext] || null;
+}
+
+function readFileIfExists(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+export function runLinter(cmd, timeoutMs, stdinContent) {
+  return new Promise((resolve) => {
+    const proc = spawn(cmd[0], cmd.slice(1), { stdio: ['pipe', 'pipe', 'pipe'] });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const timer = setTimeout(() => {
+      settled = true;
+      proc.kill('SIGKILL');
+      resolve({ ok: false, reason: 'timeout', stdout, stderr });
+    }, timeoutMs);
+    proc.stdout.on('data', (b) => (stdout += b.toString()));
+    proc.stderr.on('data', (b) => (stderr += b.toString()));
+    proc.on('error', (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: false, reason: 'spawn-error', error: err.code || err.message, stdout, stderr });
+    });
+    proc.on('close', (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve({ ok: true, code, stdout, stderr });
+    });
+    if (stdinContent !== null && stdinContent !== undefined) {
+      proc.stdin.write(stdinContent);
+    }
+    proc.stdin.end();
+  });
+}
+
+function substitutePlaceholder(cmd, replacement) {
+  return cmd.map((arg) => (arg === 'PLACEHOLDER' ? replacement : arg));
+}
+
+export async function evaluate(event) {
+  const config = loadConfig();
+  if (config.mode === 'off') {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+  if (!FILE_MUTATING_TOOLS.has(event.toolName)) {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+  const target = extractTargetPath(event.toolInput);
+  if (!target) {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+  const lang = langFor(target);
+  if (!lang) {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+  const linter = config.linters[lang];
+  if (!linter) {
+    return { decision: DECISIONS.ALLOW, reason: null, skipped: true };
+  }
+
+  // Build the actual command (substitute placeholder with the target file)
+  // and figure out the stdin content (read the freshly-written file, or fall
+  // back to the inline content the tool input may carry).
+  const cmd = substitutePlaceholder(linter.cmd, target);
+  const inline = event.toolInput?.content ?? event.toolInput?.new_string ?? null;
+  const fileContent = readFileIfExists(target);
+  const stdin = fileContent !== null ? fileContent : inline;
+
+  const result = await runLinter(cmd, linter.timeout_ms ?? 10000, stdin);
+
+  if (!result.ok) {
+    if (result.reason === 'spawn-error' && (result.error === 'ENOENT' || /not found/i.test(result.stderr || ''))) {
+      // Linter not installed.
+      if (config.fallback === 'deny') {
+        return {
+          decision: DECISIONS.DENY,
+          reason: `auto-lint: linter for .${lang} (${cmd[0]}) is not installed on this machine and fallback is "deny".`,
+        };
+      }
+      if (config.log) {
+        process.stderr.write(`[auto-lint] ${lang} linter (${cmd[0]}) not found, allowing (fallback=allow)\n`);
+      }
+      return { decision: DECISIONS.ALLOW, reason: null, skipped: 'linter-missing' };
+    }
+    if (result.reason === 'timeout') {
+      return {
+        decision: DECISIONS.ASK,
+        reason: `auto-lint: ${lang} linter timed out after ${linter.timeout_ms}ms. Allow the change without linting?`,
+      };
+    }
+    return {
+      decision: DECISIONS.ASK,
+      reason: `auto-lint: ${lang} linter failed to run: ${result.error || 'unknown'}`,
+    };
+  }
+
+  // Linter ran. Decide based on its output.
+  const issues = (result.stdout || '').trim();
+  if (result.code === 0 && !issues) {
+    if (config.log) {
+      process.stderr.write(`[auto-lint] ${lang} ${target} -> clean\n`);
+    }
+    return { decision: DECISIONS.ALLOW, reason: null };
+  }
+  // Non-zero exit OR non-empty stdout = linter found something.
+  const reason =
+    `auto-lint: ${lang} linter reported issues in ${target}\n` +
+    (issues ? `--- stdout ---\n${issues}\n` : '') +
+    (result.stderr ? `--- stderr ---\n${result.stderr}\n` : '') +
+    `\nFix the issues (or run the linter manually) and re-apply the change.`;
+  if (config.log) {
+    process.stderr.write(`[auto-lint] ${lang} ${target} -> issues found\n`);
+  }
+  return { decision: DECISIONS.DENY, reason };
+}
+
+// --- CLI entry point ---------------------------------------------------------
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => (data += chunk));
+    process.stdin.on('end', () => resolve(data));
+  });
+}
+
+async function main() {
+  const raw = await readStdin();
+  const parsed = parseHookInput(raw);
+  if (!parsed.ok) {
+    emitError(`auto-lint: ${parsed.error}`);
+    return;
+  }
+  const result = await evaluate(parsed);
+  emitDecision(result.decision, result.reason);
+  if (result.decision === DECISIONS.DENY) {
+    process.exit(2);
+  }
+}
+
+const isMain =
+  import.meta.url === `file://${process.argv[1]}` ||
+  process.argv[1]?.endsWith('auto-lint.js');
+if (isMain) {
+  main().catch((err) => emitError(err.stack || err.message));
+}
+
+export default { evaluate, langFor, runLinter };