@axplusb/kepler 2.0.7 → 2.3.0

package/KEPLER-README.md

@@ -1,222 +1,237 @@
 # @axplusb/kepler
 
-AI coding agent that plans, builds, tests, and ships. 30.7% on SWE-bench Lite.
+Kepler is an AI coding agent for terminal-first software work. It can inspect a
+repo, plan changes, run tools, ask for human approval, resume prior sessions, and
+keep local project context in `.kepler/`.
 
 ## Install
 
 ```bash
-npm install -g @axplusb/kepler
+npm install -g @axplusb/kepler@latest
 ```
 
-## Quick Start
+Run without global install:
 
 ```bash
-kepler login                        # Sign in via browser (GitHub/Google)
-kepler                              # Start interactive REPL
-kepler "fix the auth bug"           # Run a single instruction
+npx @axplusb/kepler@latest
 ```
 
-## Commands
+Update an existing global install:
 
-```
-kepler                    Start interactive REPL
-kepler "instruction"      Run a single instruction and exit
-kepler login              Sign in via browser
-kepler dashboard          Open Kepler Pulse analytics dashboard
-kepler sessions           List recent local sessions
-kepler stats              Aggregate session stats (tokens, cost, tools)
-kepler history            Recent prompt history
-kepler skills list        List discovered project and global skills
-kepler skills view NAME   View a skill procedure or bundled resource
-kepler skills install SRC Install skills from a directory or Git repository
-kepler skills update NAME Update a locked installed skill
-kepler skills remove NAME Remove an installed skill
-kepler version            Show version
+```bash
+npm update -g @axplusb/kepler
+kepler version
 ```
 
-## Agent Skills
+Requires Node.js 18 or newer.
 
-Kepler supports portable `SKILL.md` bundles and Claude-compatible skill
-directories. Skill metadata is included in the cached agent context; full
-instructions and references are loaded only when the agent calls
-`skill_view`.
-
-Discovery precedence:
+## Quick Start
 
-1. `<project>/.kepler/skills`
-2. `<project>/.claude/skills`
-3. `~/.kepler/skills`
-4. `~/.claude/skills`
+```bash
+kepler login
+kepler
+kepler "fix the failing auth test"
+```
 
-Install a local bundle or a repository containing one or more skills:
+Common startup commands:
 
 ```bash
-kepler skills install ./my-skill
-kepler skills install github:owner/skills-repository
-kepler skills install https://github.com/owner/skills.git
-kepler skills install ./team-skills --project
+kepler                    Start interactive REPL
+kepler "instruction"      Run a single instruction and exit
+kepler login              Sign in through the browser
+kepler dashboard          Open Kepler Pulse analytics dashboard
+kepler sessions           List recent local sessions
+kepler stats              Aggregate local session stats
+kepler history            Show recent prompt history
+kepler version            Show installed version
 ```
 
-Global installations are recorded in `~/.kepler/skills.lock.json`. Project
-installations use `<project>/.kepler/skills.lock.json`. Kepler copies skill
-files as data, rejects symlinks, and does not execute bundled scripts during
-installation.
+## What's New In 2.2.0
+
+- Resume sessions with summary-only, summary plus last 10 turns, or summary plus
+  last 20 turns.
+- Resume summaries are checkpointed in the selected session transcript, so future
+  resumes summarize only new uncovered history.
+- Approval prompts now use one consistent layout across shell, sensitive reads,
+  destructive actions, and backend/framework HITL approvals.
+- Reject/stop is a single action. Use re-plan with note when you want to steer
+  the agent.
+- Approval logs redact secrets before writing to `.kepler/approvals.log`.
+- Long shell commands wrap instead of being truncated.
+- Long-running shell commands return an observed output tail instead of hanging
+  silently.
 
 ## REPL Commands
 
-```
-/help                   Show available commands
-/stats                  Session metrics (tokens, cost, tools)
-/cost                   Detailed cost breakdown by model
+```text
+/help                   Show commands and command groups
+/status                 Session status and loaded project context
+/plan                   Show project plan and task files
+/tasks                  List or add project tasks
+/stats                  Session metrics
 /history                Conversation history
-/clear                  Clear conversation history
+/history approvals      Recent approval decisions
+/resume                 Resume a previous local session
+/clear                  Clear in-memory conversation history
 /explore <query>        Spawn read-only codebase explorer
 /review <query>         Spawn code review agent
 /architect <query>      Spawn architecture planning agent
 /safety                 Show safety guardrail status
 /revoke                 Revoke auto-approvals
+/settings               Show effective settings and policy sources
 /exit                   Exit the REPL
 ```
 
-## Keyboard
+Keyboard:
 
-```
-Esc                     Cancel current execution
+```text
+Esc                     Stop current execution or close a prompt
 Space                   Pause / resume execution
 Ctrl+C                  Exit
 ```
 
-## Configuration
+## Resume Behavior
 
-Settings are managed via the web dashboard at [codekepler.ai/dashboard/settings](https://codekepler.ai/dashboard/settings) and synced to the CLI automatically.
+`/resume` reads local JSONL transcripts from `~/.kepler/projects/**`. The
+selected session is the source of truth.
 
-- **API Key**: Add your OpenRouter/Anthropic/OpenAI key in Settings
-- **Model**: Choose your preferred model (40+ supported)
-- **Gateway**: Select provider (OpenRouter, Anthropic, OpenAI, Bedrock, Google AI, etc.)
-- **Config directory**: `~/.kepler/`
+For large sessions, Kepler shows mode choices:
 
-## Models
+```text
+full transcript
+summary only
+summary + last 10 turns
+summary + last 20 turns
+```
 
-Works with 13 providers and 40+ models:
+The session picker still shows the raw full transcript estimate, for example
+`593k ctx`. If a summary checkpoint exists, it also shows a status such as
+`summarized 82%`. That means earlier reconstructed messages are already covered
+by a stored `resume_summary` marker. Summary and tail modes reuse that marker and
+only summarize uncovered messages when needed.
 
-| Provider | Models |
-|----------|--------|
-| DeepSeek | V4 Flash, V4 Pro, R1 |
-| Anthropic | Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 |
-| Google | Gemini 2.5 Pro, Flash |
-| OpenAI | GPT-4.1, O3, Codex |
-| Meta | Llama 4 Maverick, Scout |
-| Mistral | Devstral, Codestral |
-| xAI | Grok 3 |
-| Qwen | Qwen3 Coder |
-| + | AWS Bedrock, Azure OpenAI, Databricks, Moonshot, Custom |
+The agent receives:
 
-Platform default included free. Bring your own API key for unlimited.
+1. resume metadata
+2. the original user request
+3. the checkpointed or freshly generated summary
+4. the retained recent tail for summary-plus-tail modes
 
-## SWE-bench
+## Approvals And HITL
 
-| Model | Score | Cost |
-|-------|-------|------|
-| DeepSeek V4 Flash + stagnation | 47.3% (142/300) | $0.046/instance |
-| DeepSeek V4 Flash | 39.7% (119/300) | $0.046/instance |
-| DeepSeek V4 Flash (baseline) | 30.7% (92/300) | $0.03/instance |
-| DeepSeek V4 Pro | 50% (14/28 sample) | $0.48/instance |
+Kepler auto-approves low-risk reads and safe shell inspection commands. It asks
+for confirmation for sensitive reads, mutating shell commands, destructive
+actions, network actions, and framework-level HITL requests.
 
-### Running SWE-bench
+Prompt actions:
 
-Benchmarks run on an Azure VM (`swebench-eval-vm`, D8s_v3) with a local backend + CLI.
+```text
+Enter / y      approve once
+t              always allow this tool type, when available
+s              trust this pattern for the session, when policy allows it
+a              trust this pattern for the project, when policy allows it
+r              re-plan with a note for the agent
+n / Esc        stop without running
+?              show why approval is required
+```
 
-**Setup (one-time):**
+Sensitive reads include files such as `.env`, `*.pem`, and `secrets/**`.
 
-```bash
-# Deploy backend + CLI + harness to VM
-./benchmark/vm-setup.sh
-```
+Approval decisions are logged locally in `.kepler/approvals.log`. Secret-like
+values in commands, nested args, query strings, authorization headers, and
+rejection notes are redacted before the log is written.
 
-**Run benchmark:**
+## Project Context
 
-```bash
-# SSH into VM
-ssh azureuser@20.9.77.9
-
-# Start backend
-source ~/.tarang-benchmark.env
-cd ~/tarang-backend
-source ~/backend-env/bin/activate
-uvicorn app.main:app --port 8000 &
-
-# Run all 300 instances (3 parallel workers, skip already-done)
-source ~/swebench-env/bin/activate
-cd ~/tarang-npm
-python3 benchmark/swe-bench/harness.py \
-    --dataset lite \
-    --model deepseek/deepseek-v4-flash \
-    --parallel 3 \
-    --skip-done \
-    --timeout 600
+Kepler uses a project-local `.kepler/` folder for hand-editable context:
+
+```text
+.kepler/
+  KEPLER.md          Project operating brief
+  settings.json      Project settings and policy
+  hooks.json         Tool/user hook configuration
+  hitl.md            Approval guidance
+  tasks/
+    backlog.md
+    active.md
+    blocked.md
+    done.md
 ```
 
-**Flags:**
+Use `/plan` and `/tasks` in the REPL to inspect and update task files.
+
+## Skills
 
-| Flag | Description |
-|------|-------------|
-| `--dataset lite\|verified\|full` | SWE-bench split (default: lite, 300 instances) |
-| `--model <id>` | OpenRouter model ID |
-| `--parallel <n>` | Number of parallel workers (default: 1) |
-| `--skip-done` | Skip instances already in the output file |
-| `--timeout <s>` | Per-instance timeout in seconds (default: 600) |
-| `--limit <n>` | Only run first N instances |
-| `--instance <id>` | Run a single instance by ID |
-| `--gen-only` | Generate patches only (skip test evaluation) |
-| `--output <path>` | Custom output file path |
+Kepler supports portable `SKILL.md` bundles and Claude-compatible skill
+directories. Skill metadata is included in cached context; full instructions and
+references are loaded only when needed.
+
+Discovery precedence:
 
-**Results** are saved incrementally to `benchmark/results/<model>_<dataset>.json` — no data loss on kill.
+1. `<project>/.kepler/skills`
+2. `<project>/.claude/skills`
+3. `~/.kepler/skills`
+4. `~/.claude/skills`
 
-**Convenience scripts on VM:**
+Install skills:
 
 ```bash
-# Watchdog (auto-restarts on crash)
-tmux new-session -d -s bench "bash /tmp/start-parallel.sh"
+kepler skills install ./my-skill
+kepler skills install github:owner/skills-repository
+kepler skills install https://github.com/owner/skills.git
+kepler skills install ./team-skills --project
+```
+
+## Configuration
 
-# Check progress
-tmux capture-pane -t bench -p | tail -20
+Settings are managed in the web dashboard and synced to the CLI:
 
-# Or use the pre-built start script
-./start-benchmark.sh deepseek/deepseek-v4-flash
+https://codekepler.ai/dashboard/settings
+
+Common local paths:
+
+```text
+~/.kepler/                         Global CLI state
+~/.kepler/projects/**              Local JSONL transcripts
+~/.kepler/history.jsonl            Prompt history
+<project>/.kepler/                 Project context and policy
+<project>/.kepler/approvals.log    Project approval audit log
 ```
 
-## Terminal-Bench
+Provider API keys can be configured in the dashboard or through environment
+variables such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, and
+`OPENROUTER_API_KEY`.
 
-Use the benchmark-only adapter under `benchmark/terminal-bench/` when you want to
-evaluate Kepler in Terminal-Bench without touching the production CLI.
+## Troubleshooting
 
-It runs with:
+Check installed package:
 
-- a separate backend venv
-- a separate backend port (`8001` by default)
-- a custom `--agent-import-path kepler_agent:KeplerAgent`
-- per-trial workspace isolation so memory does not leak across tasks
+```bash
+npm list -g @axplusb/kepler --depth=0
+kepler version
+```
 
-Reusable entrypoints:
+Use a clean one-off run:
 
 ```bash
-benchmark/terminal-bench/setup-kepler-backend.sh
-benchmark/terminal-bench/run-kepler-backend.sh
-benchmark/terminal-bench/run-kepler-benchmark.sh --task-id hello-world
+npx @axplusb/kepler@latest --version
 ```
 
-Environment variables that can be overridden in another machine or CI setup:
+If npm cache permissions are broken, use a temporary cache:
 
-`BACKEND_DIR`, `FRAMEWORK_DIR`, `VENV_DIR`, `TB_VENV`, `TARANG_NPM_DIR`,
-`ENV_FILE`, `BACKEND_URL`, `PORT`, `MODEL`, `DATASET`, `CONCURRENCY`.
+```bash
+env NPM_CONFIG_CACHE=/private/tmp/kepler-npm-cache npm pack --dry-run
+```
 
-Create a local `.tarang-tbench.env` with the benchmark credentials and backend
-auth token, then point `ENV_FILE` at it if needed.
+If a resume session shows a large context number, check whether the row also
+shows `summarized`. The large number is the full transcript estimate; summary and
+tail modes usually send much less.
 
 ## Links
 
-- Website: [codekepler.ai](https://codekepler.ai)
-- Company: [axplusb.tech](https://axplusb.tech)
+- Website: https://codekepler.ai
+- Company: https://axplusb.tech
+- Repository: https://github.com/raviakasapu/codekepler-npm
 
 ## License
 

package/README.md

@@ -1,96 +1,68 @@
 # @axplusb/kepler
 
-AI coding agent that plans, builds, tests, and ships. 30.7% on SWE-bench Lite.
+Kepler is an AI coding agent for terminal-first software work. It can inspect a
+repo, plan changes, run tools, ask for human approval, resume prior sessions, and
+keep local project context in `.kepler/`.
+
+The npm package uses [KEPLER-README.md](./KEPLER-README.md) as the published
+README. Keep that file as the canonical npm-facing documentation.
 
 ## Install
 
 ```bash
-npm install -g @axplusb/kepler
+npm install -g @axplusb/kepler@latest
 ```
 
-## Quick Start
+Run without global install:
 
 ```bash
-kepler login                        # Sign in via browser (GitHub/Google)
-kepler                              # Start interactive REPL
-kepler "fix the auth bug"           # Run a single instruction
+npx @axplusb/kepler@latest
 ```
 
-## Commands
+## Quick Start
 
+```bash
+kepler login
+kepler
+kepler "fix the failing auth test"
 ```
+
+## Common Commands
+
+```text
 kepler                    Start interactive REPL
 kepler "instruction"      Run a single instruction and exit
-kepler login              Sign in via browser
+kepler login              Sign in through the browser
 kepler dashboard          Open Kepler Pulse analytics dashboard
 kepler sessions           List recent local sessions
-kepler stats              Aggregate session stats (tokens, cost, tools)
-kepler history            Recent prompt history
-kepler version            Show version
+kepler stats              Aggregate local session stats
+kepler history            Show recent prompt history
+kepler version            Show installed version
 ```
 
-## REPL Commands
+## 2.2.0 Highlights
 
-```
-/help                   Show available commands
-/stats                  Session metrics (tokens, cost, tools)
-/cost                   Detailed cost breakdown by model
-/history                Conversation history
-/clear                  Clear conversation history
-/explore <query>        Spawn read-only codebase explorer
-/review <query>         Spawn code review agent
-/architect <query>      Spawn architecture planning agent
-/safety                 Show safety guardrail status
-/revoke                 Revoke auto-approvals
-/exit                   Exit the REPL
-```
+- Checkpointed `/resume` summaries with summary-only and summary-plus-tail modes.
+- One approval prompt model for shell, sensitive reads, destructive actions, and
+  backend/framework HITL.
+- Redacted local approval logs.
+- Wrapped full shell command display.
+- Long-running shell command tail capture.
 
-## Keyboard
+## Development
 
+```bash
+npm test
+env NPM_CONFIG_CACHE=/private/tmp/kepler-npm-cache npm pack --dry-run
 ```
-Esc                     Cancel current execution
-Space                   Pause / resume execution
-Ctrl+C                  Exit
-```
-
-## Configuration
-
-Settings are managed via the web dashboard at [codekepler.ai/dashboard/settings](https://codekepler.ai/dashboard/settings) and synced to the CLI automatically.
-
-- **API Key**: Add your OpenRouter/Anthropic/OpenAI key in Settings
-- **Model**: Choose your preferred model (40+ supported)
-- **Gateway**: Select provider (OpenRouter, Anthropic, OpenAI, Bedrock, Google AI, etc.)
-- **Config directory**: `~/.kepler/`
-
-## Models
-
-Works with 13 providers and 40+ models:
-
-| Provider | Models |
-|----------|--------|
-| DeepSeek | V4 Flash, V4 Pro, R1 |
-| Anthropic | Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 |
-| Google | Gemini 2.5 Pro, Flash |
-| OpenAI | GPT-4.1, O3, Codex |
-| Meta | Llama 4 Maverick, Scout |
-| Mistral | Devstral, Codestral |
-| xAI | Grok 3 |
-| Qwen | Qwen3 Coder |
-| + | AWS Bedrock, Azure OpenAI, Databricks, Moonshot, Custom |
-
-Platform default included free. Bring your own API key for unlimited.
-
-## SWE-bench
 
-| Model | Score | Cost |
-|-------|-------|------|
-| DeepSeek V4 Flash | 30.7% (92/300) | $0.03/fix |
-| DeepSeek V4 Pro | 50% (14/28 sample) | $0.48/fix |
+See [RELEASE.md](./RELEASE.md) for the merge, PR, and npm publish checklist.
 
 ## Links
 
-- Website: [codekepler.ai](https://codekepler.ai)
-- Company: [axplusb.tech](https://axplusb.tech)
+- Website: https://codekepler.ai
+- Company: https://axplusb.tech
+- Repository: https://github.com/raviakasapu/codekepler-npm
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axplusb/kepler",
-  "version": "2.0.7",
+  "version": "2.3.0",
   "description": "Kepler — AI coding agent with operating brief, preflight planning, and sub-agents. SWE-bench Lite evaluated.",
   "type": "module",
   "bin": {
@@ -14,7 +14,7 @@
   "readme": "KEPLER-README.md",
   "scripts": {
     "start": "node src/terminal/main.mjs",
-    "test": "node test/test-sse-client.mjs && node test/test-tool-executor.mjs && node test/test-project-artifacts.mjs && node test/test-skills.mjs && node test/test-callback.mjs && node test/test-formatter.mjs && node test/test-terminal-rendering.mjs && node test/test-slash-commands.mjs && node test/test-approval.mjs && node test/test-session-manager.mjs && node test/test-safety.mjs && node test/test-jsonl-writer.mjs && node test/test-analytics.mjs && node test/test-stagnation.mjs"
+    "test": "KEPLER_HOME=/tmp/kepler-test-home node test/test-sse-client.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-tool-executor.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-project-artifacts.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-work-scope.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-skills.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-callback.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-rate-limit-display.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-preflight.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-formatter.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-terminal-rendering.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-slash-commands.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-approval.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-approval-log.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-kepler-contract.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-session-manager.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-safety.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-jsonl-writer.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-analytics.mjs && KEPLER_HOME=/tmp/kepler-test-home node test/test-stagnation.mjs"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/config/cli-args.mjs

@@ -103,6 +103,19 @@ export function parseArgs(args) {
                 result.freeswim = true; // headless implies skip permissions
                 break;
 
+            case '--cache-report':
+                // PRD-071 §1.5 — write a machine-readable cache summary to
+                // <path> at end of run. Consumed by benchmark/cache-check.sh.
+                result.cacheReport = args[++i];
+                break;
+
+            case '--local':
+                // Force LocalAgent path (bypass backend). Meant for benchmarks
+                // that need to exercise the CLI's own LLM code — cache_control
+                // wiring, prompt-cache stats, etc.
+                result.local = true;
+                break;
+
             case '--freeswim-open-waters':
             case '--freeswim':
             case '--yes':
@@ -161,6 +174,7 @@ Options:
   --resume, -r [sessionId]   Resume last session (or specific session)
   --continue                 Alias for --resume
   --headless                 Non-interactive mode: auto-approve, JSONL output
+  --cache-report <file>      Write prompt-cache summary JSON to <file> (headless only)
   --freeswim-open-waters     Skip all approval prompts (no boundaries)
   --freeswim                 Alias for --freeswim-open-waters
   --yes                      Alias for --freeswim-open-waters

package/src/config/hook-runner.mjs

@@ -0,0 +1,100 @@
+import { execFile } from 'node:child_process';
+import * as path from 'node:path';
+import { loadKeplerSettings } from './settings-loader.mjs';
+
+function asArray(value) {
+  if (!value) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+function matchesHook(hook, toolName) {
+  const matcher = hook.matcher || hook.toolName || hook.tool;
+  if (!matcher) return true;
+  try {
+    return new RegExp(matcher).test(toolName);
+  } catch {
+    return matcher === toolName;
+  }
+}
+
+function runCommand(command, { cwd, env, timeoutMs, input }) {
+  return new Promise((resolve) => {
+    const child = execFile('/bin/sh', ['-lc', command], {
+      cwd,
+      env,
+      timeout: timeoutMs,
+      windowsHide: true,
+    }, (error, stdout, stderr) => {
+      let parsed = null;
+      try { parsed = stdout.trim() ? JSON.parse(stdout.trim()) : null; }
+      catch { parsed = stdout.trim() ? { output: stdout.trim() } : null; }
+      resolve({
+        ok: !error,
+        code: error?.code ?? 0,
+        signal: error?.signal || null,
+        stdout,
+        stderr,
+        parsed,
+        error,
+      });
+    });
+    if (input) child.stdin?.end(JSON.stringify(input));
+  });
+}
+
+export class HookRunner {
+  constructor({ cwd = process.cwd(), settings = null, sessionId = null } = {}) {
+    this.cwd = cwd;
+    this.sessionId = sessionId;
+    this.settings = settings || loadKeplerSettings({ cwd }).settings;
+  }
+
+  reload() {
+    this.settings = loadKeplerSettings({ cwd: this.cwd }).settings;
+  }
+
+  hooksFor(event) {
+    return asArray(this.settings?.hooks?.[event]);
+  }
+
+  async run(event, payload = {}) {
+    const results = [];
+    for (const hook of this.hooksFor(event)) {
+      const toolName = payload.toolName || payload.tool || '';
+      if ((event === 'PreToolUse' || event === 'PostToolUse') && !matchesHook(hook, toolName)) continue;
+      const timeoutSeconds = hook.timeout ?? this.settings?.hooks?.timeout ?? 5;
+      const input = {
+        event,
+        tool_name: toolName,
+        tool_input: payload.input || payload.args || {},
+        tool_result: payload.result || null,
+        project_dir: this.cwd,
+        session_id: this.sessionId || '',
+      };
+      const env = {
+        ...process.env,
+        ...(this.settings?.env || {}),
+        KEPLER_TOOL_NAME: toolName,
+        KEPLER_TOOL_INPUT_FILE_PATH: input.tool_input.file_path || input.tool_input.path || '',
+        KEPLER_PROJECT_DIR: this.cwd,
+        KEPLER_SESSION_ID: this.sessionId || '',
+        KEPLER_TURN_ID: payload.turnId || '',
+      };
+      const result = await runCommand(hook.command, {
+        cwd: path.resolve(this.cwd),
+        env,
+        timeoutMs: timeoutSeconds * 1000,
+        input,
+      });
+      results.push({ hook, ...result });
+      if (result.code === 2 || result.parsed?.block === true || result.parsed?.decision === 'deny') {
+        return {
+          blocked: true,
+          message: result.parsed?.message || result.stderr?.trim() || `Blocked by hook: ${hook.command}`,
+          results,
+        };
+      }
+    }
+    return { blocked: false, results };
+  }
+}