@redue/cli 0.1.0-alpha.10 → 0.1.0-alpha.11

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # Changelog
 
+## 0.1.0-alpha.11 — 2026-10-18
+
+Bench numbers below are from one 800-file project on macOS arm64, Node 22.13.0.
+Released alpha.10 and this build ran back to back on the same machine.
+
+- Faster status decisions for the direct TypeScript recipe on macOS and Linux.
+  The observer checks the compiler's recorded filesystem questions in-process
+  instead of starting a probe that rebuilds the whole program. A full probe runs
+  only when that check fails, the plan or toolchain changes, or observation was
+  interrupted. While idle it no longer starts any probe process.
+  - warm `status --sync`: 741 → 194 ms (+683 → +154 ms over cached `status`)
+  - `status --sync` after an unrelated edit: 619 → 219 ms
+  - `status --sync` after a relevant edit: 1472 → 321 ms. It answers STALE without
+    a full probe when the edited inputs already differ from the receipt.
+  - probe processes started in 20 s idle: 4 → 0
+- Cheaper `redue run` on macOS and Linux. The compiler records its own inputs
+  while it runs, so REDUE no longer probes before and after the compile. After
+  a relevant edit, the run builds the new certificate from that recording instead
+  of running a full probe. Output and exit code are those of plain `tsc`.
+  - repeat run: 4143 → 2752 ms, overhead over plain `tsc` 72% → 16%
+  - run right after a relevant edit: 3990 → 2802 ms, overhead 65% → 18%
+- The direct TypeScript recipe accepts inert Node settings. Before, any non-empty
+  `NODE_*` setting other than `NODE_ENV` kept a check from becoming CURRENT.
+  Now accepted: `NODE_EXTRA_CA_CERTS`, `NODE_PATH`, and `NODE_OPTIONS` made only of
+  `--max-old-space-size`, `--max-semi-space-size`, `--use-openssl-ca`,
+  `--use-bundled-ca`, `--use-system-ca` and `--dns-result-order`. A run under one
+  value is not reused under another. See [Node settings](docs/user/direct-typescript.md#node-settings).
+- `redue agent setup claude --apply` adds a Claude Code hook to
+  `.claude/settings.local.json`. When the agent reruns a configured typecheck
+  that is CURRENT and PASS, the hook blocks it and names the passing run. When
+  the check is not CURRENT, it rewrites the command to `redue run CHECK`, so the
+  result is recorded and the next identical command can be skipped. Prefix a
+  command with `REDUE_FORCE=1` to always run it. On the bench: a skip decision
+  takes about 155 ms; a forced command adds 39 ms. Tested live with Claude Code
+  2.1.302 (`claude -p`). See [the hook](docs/user/agents.md#claude-code-typecheck-hook).
+- Unstable-run and observation-gap reasons now name the failed check or operation.
+- macOS counts each input event once, which removes an intermittent UNVERIFIED
+  after an edit.
+
+Known limits:
+
+- Two bench targets are still missed: warm sync adds 154 ms over cached status
+  (target < 100 ms), and `redue run` adds 16–18% over plain `tsc` (target < 10%).
+- An edit that changes imports, configuration or lib files still costs one full
+  probe, at the end of the next run.
+- Windows keeps the earlier probe-based path, except the STALE shortcut. Yarn
+  and pnpm recipes still probe on each decision. The bench was not run on Linux.
+- The Claude hook covers the Bash tool only, from the project root. It allows the
+  rewritten command without a permission prompt. It judges its own environment,
+  not variables the Bash tool adds from your shell profile.
+- To upgrade, stop observers, install into the same prefix, and keep config, state
+  and receipts. Rerun `redue agent setup claude --apply` to add the hook.
+
 ## 0.1.0-alpha.10 — 2026-10-10
 
 - Combine guarded caller-discovery reuse and cheaper non-reusable recording on

package/README.md

@@ -37,7 +37,7 @@ it; relevant source edits make it stale. [Run the reproducible demo](docs/contri
 
 ## Install the alpha
 
-The opt-in pilot uses **0.1.0-alpha.10**. Follow the
+The opt-in pilot uses **0.1.0-alpha.11**. Follow the
 [fixed-version pilot guide](docs/user/pilot.md) for supported projects, setup,
 updates and voluntary feedback. No external usage results are claimed yet.
 

package/bin/redue.mjs

@@ -9,12 +9,10 @@ import path from 'node:path';
 import {createHash} from 'node:crypto';
 import {spawn,spawnSync} from 'node:child_process';
 import {createRequire} from 'node:module';
-import {fileURLToPath} from 'node:url';
-import {discoverNodeProject} from '../src/node-onboarding.mjs';
+import {fileURLToPath,pathToFileURL} from 'node:url';
 import {processAlive} from '../src/process-liveness.mjs';
 import {samePath,withinPath,realObservedPath} from '../src/path-identity.mjs';
 import {discoverConfig,projectState,canonicalConfig} from '../src/project-location.mjs';
-import {agentCommand} from '../src/agent-integration.mjs';
 import {findExecutable} from '../src/executable-lookup.mjs';
 import {readCachedStatus} from '../src/cached-state.mjs';
 import {assertOwnedStatePlacement} from '../src/owned-state.mjs';
@@ -46,6 +44,12 @@ No checks run in the background. Direct commands outside redue create no receipt
 
 function error(message){console.error(`redue: ${message}`);process.exit(2);}
 const args=process.argv.slice(2);
+if(args.length===3&&args[0]==='agent'&&args[1]==='hook'&&args[2]==='claude'){
+  // Runs before config discovery: the hook must exit 0 on every failure,
+  // because Claude Code treats exit 2 as a block.
+  const {runClaudeHook}=await import('../src/claude-hook.mjs');
+  await runClaudeHook(fileURLToPath(import.meta.url));process.exit(0);
+}
 if(args.length===1&&args[0]==='--version'){console.log(version);process.exit(0);}
 if(args.includes('--help')||args.includes('-h')||!args.length){console.log(help);process.exit(0);}
 let configFile=null,stateOverride=null;
@@ -62,8 +66,12 @@ try{configFile??=command==='init'||stateOverride&&['stop','remove-state'].includ
 catch(e){error(e.message);}
 if(fs.existsSync(path.dirname(configFile)))configFile=canonicalConfig(configFile);
 if(command==='agent'){
+  // Loaded on demand: onboarding and agent setup are not on the run/status path.
+  const {agentCommand}=await import('../src/agent-integration.mjs');
   try{await agentCommand(args,{configFile,stateOverride,entry:fileURLToPath(import.meta.url)});}
   catch(e){error(e.message);}
+  // Exiting with piped output still queued truncates it (8 KB on macOS).
+  await new Promise(resolve=>process.stdout.write('',resolve));
   process.exit(0);
 }
 if(!['init','start','stop','status','detail','explain','run','remove-state'].includes(command))
@@ -88,6 +96,7 @@ if(short&&(command!=='status'||json||sync))error('--short is a cached status opt
 if(dryRun&&command!=='init')error('--dry-run is for init');
 
 if(command==='init'){
+  const {discoverNodeProject}=await import('../src/node-onboarding.mjs');
   let discovery;try{discovery=discoverNodeProject(process.cwd(),{recipe:recipeSelection});}
   catch(e){error(e.message);}
   if(workspaceSelection||checkSelection){
@@ -322,7 +331,13 @@ if(command==='status'&&!sync){
 const details=command==='detail'||command==='explain';
 const internal=command==='remove-state'?'uninstall':
   details?'sync':command==='status'&&sync?'sync':command;
-if(command==='run'){
+// On macOS and Linux the engine runs in this process, which saves a Node startup
+// on every run; its own handlers receive SIGINT and SIGTERM. Windows keeps a
+// child engine because cancellation reaches it over IPC.
+if(command==='run'&&process.platform!=='win32'){
+  process.argv=[process.argv[0],engine,runtimeFile,internal,check,...(!json?['--human']:[])];
+  await import(pathToFileURL(engine).href);
+}else if(command==='run'){
   const child=spawn(process.execPath,[engine,runtimeFile,internal,check,...(!json?['--human']:[])],
     {stdio:['inherit','inherit','inherit','ipc'],env:process.env});
   const forward=signal=>{if(child.exitCode!==null)return;
@@ -337,19 +352,20 @@ if(command==='run'){
   process.off('SIGINT',interrupt);process.off('SIGTERM',terminate);
   if(outcome.error)error(outcome.error.message);
   process.exit(outcome.status??(outcome.signal?128+os.constants.signals[outcome.signal]:1));
+}else{
+  mark('client.engine_submit');
+  const result=spawnSync(process.execPath,[engine,runtimeFile,internal,...(check?[check]:[])],
+    {stdio:['inherit','pipe','inherit'],
+      encoding:'utf8',env:traceEnvironment()});
+  mark('client.engine_complete',{exit:result.status,signal:result.signal});
+  if(result.error)error(result.error.message);
+  if(result.stdout){
+    if(['status','detail','explain'].includes(command)){
+      let value;try{value=JSON.parse(result.stdout);}catch{error('status response could not be read; applicability is unknown');}
+      if(details&&check)value={...value,checks:value.checks.filter(row=>row.name===check)};
+      if(json)console.log(JSON.stringify(value));
+      else console.log(details?renderExplain(value,check):renderStatus(value,{short}));
+    }else printLifecycle(result.stdout,command,json);
+  }
+  process.exit(result.status??1);
 }
-mark('client.engine_submit');
-const result=spawnSync(process.execPath,[engine,runtimeFile,internal,...(check?[check]:[])],
-  {stdio:['inherit','pipe','inherit'],
-    encoding:'utf8',env:traceEnvironment()});
-mark('client.engine_complete',{exit:result.status,signal:result.signal});
-if(result.error)error(result.error.message);
-if(result.stdout){
-  if(['status','detail','explain'].includes(command)){
-    let value;try{value=JSON.parse(result.stdout);}catch{error('status response could not be read; applicability is unknown');}
-    if(details&&check)value={...value,checks:value.checks.filter(row=>row.name===check)};
-    if(json)console.log(JSON.stringify(value));
-    else console.log(details?renderExplain(value,check):renderStatus(value,{short}));
-  }else printLifecycle(result.stdout,command,json);
-}
-process.exit(result.status??1);

package/docs/user/agents.md

@@ -71,6 +71,51 @@ setup requires `--apply`. `--dry-run` never writes. Installing REDUE or running
 `init` does not connect an agent automatically. Setup does not start an observer
 or execute verification. Use `redue start` when you want observation.
 
+## Claude Code typecheck hook
+
+`redue agent setup claude --apply` also adds a PreToolUse hook to
+`.claude/settings.local.json`. The hook needs a local REDUE install, so it is
+per-developer; keep that file out of commits. Other settings in the file are kept,
+but the file is rewritten as 2-space JSON. `.claude/settings.json` is not touched.
+`redue agent remove claude --apply` removes only the entry REDUE added.
+
+The hook skips an exact rerun of a configured typecheck: a check with
+`kind: "typecheck"` or named `typecheck`. It matches these commands, run from the
+project root:
+
+- `redue run CHECK`
+- `npm run SCRIPT`, when the check has an npm script
+- `npx tsc --noEmit`, for the direct-TypeScript recipe
+- the check's `command`, when it has no `@` tokens
+
+Each form may end with `2>&1` and then one `| tail -n N`, `| head -n N`,
+`| tail -N` or `| head -N`. Nothing else matches. Each form has its own `if`
+rule, so other Bash commands never start the hook.
+
+On a match, the hook runs `redue status --sync --json` with a 2-second timeout.
+It blocks the command only when the check is CURRENT, PASS and
+`reuse_eligible: true`. The message names the check and the receipt's run ID. Every
+other result allows the command: STALE, UNVERIFIED, FAILED, a timeout, an error, or
+a missing `redue`. A command that starts with `REDUE_FORCE=1` always runs.
+
+When the check is not CURRENT but the observer answered for it, the hook rewrites
+the command to `redue run CHECK` and allows it, keeping any `2>&1` and
+`| tail`/`| head` suffix. It adds `--config FILE` when the config is not
+`redue.config.json`. The run is recorded, so the next identical command can be
+skipped. Without a healthy answer (timeout, error, no observer) the command runs
+as typed. Claude Code still applies deny and ask rules to the rewritten command.
+
+Limits:
+
+- The hook judges its own environment, which Claude Code passes to it. The Bash
+  tool can add variables from your shell profile. The hook cannot see those.
+- Commands run from a subdirectory, or combined with `&&`, `;` or other pipes,
+  are not matched.
+- Only the Bash tool is covered, not PowerShell.
+- Run setup again after you rename a check or script.
+- The rewrite is allowed without a permission prompt, even where the original
+  command would have prompted.
+
 ## Update an existing connection
 
 Installing a newer package does **not** rewrite project instructions. From the
@@ -138,7 +183,8 @@ request; it does not synchronize or run these probes.
 config resolution, cached observer health, a bounded read-only control-access probe,
 managed-file integrity, detected host
 version, and loading guidance. `behavior_verified: false` is deliberate: intact
-files do not prove the agent followed them. No hooks are installed. Doctor neither
+files do not prove the agent followed them. For Claude, doctor reports whether the
+typecheck hook is installed. Doctor neither
 executes checks nor starts observers, reconciles inputs, or installs a host.
 
 Doctor separates missing/unreadable state, a missing or refused endpoint, an

package/docs/user/direct-typescript.md

@@ -94,3 +94,21 @@ explicit request for `npm run typecheck` is not satisfied by this different comm
 The injected `NODE_USE_ENV_PROXY=1` setting is admitted only on Node 22.13.0,
 where it is inert; it remains strictly tracked. Other Node versions with this
 setting need review and stay unqualified. REDUE does not alter the setting.
+
+## Node settings
+
+Since alpha.11 the direct recipe accepts these `NODE_*` settings:
+
+- `NODE_OPTIONS`, when every token is one of `--max-old-space-size=<n>`,
+  `--max-semi-space-size=<n>`, `--use-openssl-ca`, `--use-bundled-ca`,
+  `--use-system-ca` or `--dns-result-order=ipv4first|ipv6first|verbatim`.
+  Any other flag, quotes, backslashes or tabs are refused.
+- `NODE_EXTRA_CA_CERTS`.
+- `NODE_PATH`.
+
+`NODE_ENV` set to `production`, `test` or empty was already accepted. Every other non-empty
+`NODE_*` setting withholds applicability. The values are part of the recorded
+execution context: a run under one value is not reusable under another. A
+`--require` in `NODE_OPTIONS` still runs inside REDUE's own process before REDUE
+refuses it. The npm, pnpm and Yarn recipes still refuse `NODE_OPTIONS` and
+`NODE_PATH`.

package/docs/user/pilot.md

@@ -1,4 +1,4 @@
-# Opt-in development pilot: alpha.10
+# Opt-in development pilot: alpha.11
 
 Use one fixed build for several ordinary development sessions. The owner will
 invite two or three willing testers and approve their projects; nothing is
@@ -16,7 +16,8 @@ outside-root inputs are added by this pilot. Do not downgrade or change your
 project to fit; record an unsupported setup as feedback.
 
 Development-mode source-map support, Node preloads/inspectors/compile-cache
-overrides and `TS_ETW_MODULE_PATH` are unsupported. The injected
+overrides and `TS_ETW_MODULE_PATH` are unsupported. A few inert Node settings
+are accepted; see [Node settings](direct-typescript.md#node-settings). The injected
 `NODE_USE_ENV_PROXY=1` context is reviewed only on Node **22.13.0**; leave the
 environment and security controls intact. See the [full recipe boundary](direct-typescript.md).
 
@@ -24,15 +25,17 @@ CLI/package mechanics are tested on macOS/APFS, native Linux and Windows/NTFS;
 Linux also needs Python 3 and [supported native storage](getting-started.md).
 Actual fresh-session behavior was tested with Codex **0.162.0 on macOS**, Node
 22.13.0 and the approved exact checkout/state/socket access. This is not general
-sandbox compatibility. Claude mechanics are tested; Claude behavior and cross-host
-handoff are **NOT RUN**. The recording shortcut is macOS/direct-recipe only.
+sandbox compatibility. Claude mechanics are tested, and the
+[Claude Code typecheck hook](agents.md#claude-code-typecheck-hook) was exercised in
+Claude Code 2.1.302 (`claude -p`). Broader Claude behavior and cross-host handoff
+are **NOT RUN**. The recording shortcut is macOS/direct-recipe only.
 
 ## Install and connect explicitly
 
 For a new default npm installation:
 
 ```sh
-npm install --global @redue/cli@0.1.0-alpha.10
+npm install --global @redue/cli@0.1.0-alpha.11
 redue --version
 cd my-project
 redue --config redue.config.json init --recipe typescript-direct --check typecheck --dry-run
@@ -86,7 +89,7 @@ using it; keep the same npm prefix, config and any explicit state selection.
 
 ```sh
 redue --config redue.config.json stop
-npm install --global @redue/cli@0.1.0-alpha.10
+npm install --global @redue/cli@0.1.0-alpha.11
 redue --config redue.config.json agent setup codex --dry-run
 redue --config redue.config.json agent setup codex --apply
 redue --config redue.config.json start

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@redue/cli",
   "private": false,
-  "version": "0.1.0-alpha.10",
+  "version": "0.1.0-alpha.11",
   "publishConfig": {
     "access": "public",
     "tag": "alpha"

package/src/agent-integration.mjs

@@ -11,12 +11,48 @@ import {readProject,projectState,canonicalConfig} from './project-location.mjs';
 import {readCachedStatus} from './cached-state.mjs';
 import {samePath,withinPath} from './path-identity.mjs';
 import {processAlive} from './process-liveness.mjs';
+import {hookCommand,hookForms} from './claude-hook.mjs';
 
 const policy=fs.readFileSync(new URL('./agent-policy.md',import.meta.url),'utf8');
 const hosts={codex:{instruction:'AGENTS.md',skill:'.agents/skills/redue-verification/SKILL.md'},
   claude:{instruction:'CLAUDE.md',skill:'.claude/skills/redue-verification/SKILL.md'}};
 const hash=s=>createHash('sha256').update(s).digest('hex');
 const marker=host=>`.redue/agents/${host}.json`;
+// The hook needs a local REDUE install, so it lives in per-developer settings.
+const settingsPath='.claude/settings.local.json';
+const sameJson=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+// One handler per exact command form; `if` keeps other Bash calls from starting Node.
+function hookFor(config){
+  const rules=[...new Set(hookForms(config).flatMap(row=>row.forms))].map(form=>`Bash(${form}*)`);
+  return rules.length?{matcher:'Bash',hooks:rules.map(rule=>({type:'command',if:rule,command:hookCommand,timeout:5}))}:null;
+}
+// REDUE's entry is recognized by its command, not by a committed record: the
+// local file differs between checkouts, and users may edit the entry.
+const ownedHook=entry=>Array.isArray(entry?.hooks)&&entry.hooks.length>0&&entry.hooks.every(h=>h?.command===hookCommand);
+function parseSettings(text){
+  if(text===null)return {};
+  let value;try{value=JSON.parse(text);}catch{throw Error(`${settingsPath} is not valid JSON; fix it before agent setup or removal`);}
+  if(!value||typeof value!=='object'||Array.isArray(value)||value.hooks!==undefined&&
+    (!value.hooks||typeof value.hooks!=='object'||Array.isArray(value.hooks)||
+      value.hooks.PreToolUse!==undefined&&!Array.isArray(value.hooks.PreToolUse)))
+    throw Error(`${settingsPath} has an unexpected shape; fix it before agent setup or removal`);
+  return value;
+}
+// Replace REDUE's entries with `next` (or remove them). Unchanged input returns
+// the same text, so idempotent setup does not rewrite the file.
+function settingsWith(text,next){
+  const value=parseSettings(text),old=value.hooks?.PreToolUse||[];
+  const at=old.findIndex(ownedHook),list=old.filter(entry=>!ownedHook(entry));
+  if(next)list.splice(at<0?list.length:at,0,next);
+  if(sameJson(list,old))return text;
+  if(list.length)value.hooks={...value.hooks,PreToolUse:list};
+  else if(value.hooks){delete value.hooks.PreToolUse;if(!Object.keys(value.hooks).length)delete value.hooks;}
+  return Object.keys(value).length?JSON.stringify(value,null,2)+'\n':null;
+}
+function hookInstalled(root){
+  try{return (parseSettings(read(root,settingsPath)).hooks?.PreToolUse||[]).some(ownedHook);}
+  catch{return false;}
+}
 function safeFile(root,relative){
   if(path.isAbsolute(relative)||relative.split(/[\\/]/).some(p=>p==='..'||p===''))throw Error('unsafe integration path');
   const file=path.resolve(root,relative);
@@ -88,6 +124,8 @@ function warnings(root,host,cwd){
   }
   if(host==='claude'&&read(root,'.claude/CLAUDE.md')!==null)
     throw Error('.claude/CLAUDE.md already exists; reconcile its project policy with root CLAUDE.md before setup');
+  if(host==='claude'&&spawnSync('git',['check-ignore','-q',settingsPath],{cwd:root,stdio:'ignore'}).status===1)
+    result.push(`${settingsPath} is not ignored by Git; the hook needs a local REDUE install, so keep it out of commits.`);
   let dir=path.resolve(cwd);
   while(withinPath(dir,root)&&!samePath(dir,root)){
     for(const name of ['AGENTS.md','AGENTS.override.md','CLAUDE.md','CLAUDE.local.md'])
@@ -137,36 +175,43 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
       if(value.state_access)console.log(`State access: ${value.state_access.status}${value.state_access.reason?' — '+value.state_access.reason:''}`);
       if(value.compatibility?.reason)console.log(`Observer compatibility: ${value.compatibility.reason}`);
       if(value.applicability?.requires_reassessment)console.log('Applicability: cached evidence needs reassessment; choose synchronization or execution deliberately.');
-      for(const row of value.hosts)console.log(`${row.host}: ${row.version||'host unavailable'}; integration ${row.integrity}; behavioral validation NOT VERIFIED by doctor${row.reason?' — '+row.reason:''}`);
-      console.log('Hooks: none installed by REDUE. Doctor does not start observers, execute checks, or prove agent behavior.');
+      for(const row of value.hosts)console.log(`${row.host}: ${row.version||'host unavailable'}; integration ${row.integrity}; hook ${row.hook}; behavioral validation NOT VERIFIED by doctor${row.reason?' — '+row.reason:''}`);
+      console.log('Doctor does not start observers, execute checks, or prove agent behavior.');
       for(const warning of value.warnings)console.log(`Review: ${warning}`);
     }return value;
   }
   if(stateOverride)throw Error('agent setup/removal uses the selected project config, not a committed machine-local --state-dir; use the generic path for custom state');
-  const {root,relative}=project(configFile),h=hosts[host],record=saved(root,host),health=inspect(root,host,record);
+  const {root,relative,config}=project(configFile),h=hosts[host],record=saved(root,host),health=inspect(root,host,record);
   if(health.integrity==='conflict')throw Error(health.reason);
   const changes=[],notes=action==='setup'?warnings(root,host,cwd):[];
+  let hook=null;
   if(action==='setup'){
     const before=read(root,h.instruction),skill=skillFor(relative),block=blockFor(host,relative);
     if(!record&&(before?.includes('<!-- REDUE:')||read(root,h.skill)!==null))
       throw Error('unowned REDUE instruction or skill already exists; inspect it before setup');
     const after=record?before.replace(record.block,block):(before||'')+block;
+    hook=host==='claude'?hookFor(config):null;
     const next={schema:1,host,config:relative,instruction:h.instruction,skill:h.skill,
       block,skillHash:hash(skill),instructionCreated:record?.instructionCreated??before===null};
     changes.push({path:h.skill,before:read(root,h.skill),after:skill},
-      {path:h.instruction,before,after},
-      {path:marker(host),before:read(root,marker(host)),after:JSON.stringify(next,null,2)+'\n'});
+      {path:h.instruction,before,after});
+    if(host==='claude'){const settings=read(root,settingsPath);
+      changes.push({path:settingsPath,before:settings,after:settingsWith(settings,hook),
+        content:hook?JSON.stringify(hook,null,2):'remove the REDUE PreToolUse hook (no typecheck check to match)'});}
+    changes.push({path:marker(host),before:read(root,marker(host)),after:JSON.stringify(next,null,2)+'\n'});
   }else if(record){
     const before=read(root,h.instruction),after=before.replace(record.block,'');
     changes.push({path:h.instruction,before,after:record.instructionCreated&&after===''?null:after},
-      {path:h.skill,before:read(root,h.skill),after:null},
-      {path:marker(host),before:read(root,marker(host)),after:null});
+      {path:h.skill,before:read(root,h.skill),after:null});
+    if(host==='claude'){const settings=read(root,settingsPath);
+      changes.push({path:settingsPath,before:settings,after:settingsWith(settings,null)});}
+    changes.push({path:marker(host),before:read(root,marker(host)),after:null});
   }
   const actual=changes.filter(c=>c.before!==c.after);
   const summary={schema:1,action,host,config:configFile,applied:false,
     changes:actual.map(c=>({path:c.path,operation:c.after===null?'remove':c.before===null?'create':'update',
-      ...(action==='setup'?{content:c.path===h.instruction?blockFor(host,relative):c.after}: {})})),
-    warnings:notes,hooks:'none',behavior_verified:false};
+      ...(action==='setup'?{content:c.path===h.instruction?blockFor(host,relative):c.content??c.after}: {})})),
+    warnings:notes,hooks:hook?`${settingsPath} PreToolUse`:'none',behavior_verified:false};
   if(!json){console.log(`${action} ${host}: ${configFile}`);
     for(const c of summary.changes)console.log(`  ${c.operation} ${c.path}${c.content?'\n'+c.content:''}`);
     if(!actual.length)console.log('Already in the requested state.');
@@ -186,7 +231,7 @@ export async function agentCommand(args,{configFile,stateOverride,entry,cwd=proc
 export async function doctor({configFile,stateOverride,entry,cwd,host}){
   const value={schema:1,command:{path:findExecutable('redue'),invoked:entry},project:{config:configFile},
     observation:null,control:null,state_access:null,observer_process:null,compatibility:null,
-    applicability:null,hosts:[],warnings:[],hooks:'none installed by REDUE',behavior_verified:false};
+    applicability:null,hosts:[],warnings:[],hooks:`claude only: PreToolUse typecheck hook in ${settingsPath}`,behavior_verified:false};
   let p;try{p=project(configFile);value.project.root=p.root;
     const state=stateOverride||projectState(p.root,configFile);value.project.state=state;
     const cached=readCachedStatus(state,p.config.checks);value.observation=cached.observation;
@@ -217,11 +262,12 @@ export async function doctor({configFile,stateOverride,entry,cwd,host}){
     if(executable){const launch=windowsLaunch([executable,'--version']);
       const out=spawnSync(launch.file,launch.args,{...launch.options,encoding:'utf8',timeout:2000,maxBuffer:4096,stdio:['ignore','pipe','pipe']});
       if(out.status===0)version=out.stdout.trim();}
-    let integration={installed:false,integrity:'unknown'};
-    if(p)try{integration=inspect(p.root,name,saved(p.root,name));
+    let integration={installed:false,integrity:'unknown'},hook=name==='claude'?'absent':'none';
+    if(p)try{const record=saved(p.root,name);integration=inspect(p.root,name,record);
+      if(name==='claude'&&hookInstalled(p.root))hook=value.command.path?'installed':'installed, but redue is not on PATH, so it never runs';
       value.warnings.push(...warnings(p.root,name,cwd));
     }catch(e){integration={installed:false,integrity:'conflict',reason:e.message};}
-    value.hosts.push({host:name,executable,version,...integration,behavior_verified:false,
+    value.hosts.push({host:name,executable,version,...integration,hook,behavior_verified:false,
       loading:name==='codex'?'AGENTS.md at session start; .agents/skills; overrides and size limits apply':
         'CLAUDE.md at session start; .claude/skills; managed/user policies and exclusions apply'});
   }

package/src/claude-hook.mjs

@@ -0,0 +1,115 @@
+// Claude Code PreToolUse hook: skip an exact typecheck rerun when REDUE reports
+// CURRENT/PASS with reuse_eligible on the current inputs. When the check is not
+// CURRENT, the command becomes `redue run <check>` so the run is recorded. Every
+// other outcome, including errors and timeouts, allows the command unchanged.
+// Never exit 2: Claude Code treats exit 2 as a block.
+import fs from 'node:fs';
+import path from 'node:path';
+import {spawn} from 'node:child_process';
+
+export const hookCommand='redue agent hook claude';
+const safe=/^[A-Za-z0-9_./:=,+-]+$/;
+const typecheck=check=>check?.kind==='typecheck'||check?.name==='typecheck';
+
+// Exact commands that rerun each configured typecheck. Names that would need
+// shell quoting get no form, so the hook never fires for them.
+export function hookForms(config){
+  const rows=[];
+  for(const check of config?.checks||[]){
+    if(!typecheck(check)||typeof check.name!=='string'||!safe.test(check.name))continue;
+    const forms=[`redue run ${check.name}`];
+    // Other forms run from the project root, so they match only a root check.
+    if(check.cwd!==undefined&&check.cwd!=='.'){rows.push({check:check.name,forms});continue;}
+    if(config.packageManager==='npm'&&typeof check.script==='string'&&safe.test(check.script))
+      forms.push(`npm run ${check.script}`);
+    if(check.qualification==='npm-typescript-direct-v1')forms.push('npx tsc --noEmit');
+    if(Array.isArray(check.command)&&check.command.length&&
+      check.command.every(v=>typeof v==='string'&&safe.test(v)&&!v.startsWith('@')))
+      forms.push(check.command.join(' '));
+    rows.push({check:check.name,forms:[...new Set(forms)]});
+  }
+  return rows;
+}
+
+// Accept only an optional trailing `2>&1`, then an optional `| tail|head -n N`
+// or `-N`. Newlines separate commands, so they never match.
+function split(command){
+  if(typeof command!=='string'||/[\r\n]/.test(command))return null;
+  const [,base,suffix]=command.trim().replace(/[ \t]+/g,' ')
+    .match(/^(.*?)((?: 2>&1)?(?: \| (?:tail|head) (?:-n \d+|-\d+))?)$/);
+  return {base,suffix};
+}
+export function matchCheck(command,config){
+  const parts=split(command);
+  return parts&&hookForms(config).find(row=>row.forms.includes(parts.base))?.check||null;
+}
+// The same check through REDUE, keeping the output suffix; null if it already is.
+export function recordedCommand(command,name,configFile='redue.config.json'){
+  const parts=split(command);
+  if(!parts||!safe.test(name)||!safe.test(configFile))return null;
+  const run=`redue ${configFile==='redue.config.json'?'':`--config ${configFile} `}run ${name}`;
+  return parts.base===run||parts.base===`redue run ${name}`?null:run+parts.suffix;
+}
+
+export function verdict(status,name){
+  const row=status?.schema===1&&status.observation?.healthy===true&&Array.isArray(status.checks)?
+    status.checks.find(item=>item?.name===name):null;
+  const runId=row?.invocation?.runId;
+  if(!row||row.freshness!=='CURRENT'||row.result!=='PASS'||row.reuse_eligible!==true||
+    typeof runId!=='string'||!/^[0-9a-f-]{36}$/.test(runId))return null;
+  return `REDUE: check ${JSON.stringify(name)} passed on these exact inputs (run ${runId}); `+
+    'rerun skipped. To run it anyway, prefix the command with REDUE_FORCE=1.';
+}
+
+function synchronizedStatus(entry,config,root,timeout){
+  return new Promise(resolve=>{
+    let child,out='',done=false;
+    const finish=value=>{if(done)return;done=true;clearTimeout(timer);
+      if(child?.pid&&child.exitCode===null)try{process.platform==='win32'?child.kill('SIGKILL'):process.kill(-child.pid,'SIGKILL');}catch{}
+      resolve(value);};
+    const timer=setTimeout(()=>finish(null),timeout);
+    // Its own process group on POSIX, so a timeout also ends the engine it starts.
+    try{child=spawn(process.execPath,[entry,'--config',config,'status','--sync','--json'],
+      {cwd:root,stdio:['ignore','pipe','ignore'],env:process.env,windowsHide:true,detached:process.platform!=='win32'});}
+    catch{return finish(null);}
+    child.on('error',()=>finish(null));
+    child.stdout.on('data',chunk=>{out+=chunk;if(out.length>4*1024*1024)finish(null);});
+    child.on('close',code=>{if(code!==0)return finish(null);
+      try{finish(JSON.parse(out));}catch{finish(null);}});
+  });
+}
+
+// Returns the hook's stdout object, or null to allow the command.
+export async function claudeHook(input,{entry,timeout=2000}){
+  if(input?.tool_name!=='Bash')return null;
+  const command=input.tool_input?.command,root=input.cwd;
+  if(typeof command!=='string'||/^\s*REDUE_FORCE=1(?:\s|$)/.test(command))return null;
+  if(typeof root!=='string'||!path.isAbsolute(root))return null;
+  const record=JSON.parse(fs.readFileSync(path.join(root,'.redue','agents','claude.json'),'utf8'));
+  if(record?.schema!==1||record.host!=='claude'||typeof record.config!=='string'||
+    !/^[^/\\]+\.json$/.test(record.config))return null;
+  const config=path.join(root,record.config);
+  const name=matchCheck(command,JSON.parse(fs.readFileSync(config,'utf8')));
+  if(!name)return null;
+  const status=await synchronizedStatus(entry,config,root,timeout),reason=verdict(status,name);
+  if(reason)return {hookSpecificOutput:{hookEventName:'PreToolUse',
+    permissionDecision:'deny',permissionDecisionReason:reason}};
+  // Rewrite only on a healthy answer for this check: without an observer,
+  // `redue run` cannot record, so the command stays as Claude sent it.
+  const rewritten=status?.schema===1&&status.observation?.healthy===true&&Array.isArray(status.checks)&&
+    status.checks.some(item=>item?.name===name)?recordedCommand(command,name,record.config):null;
+  // updatedInput replaces the whole tool input. Deny and ask rules still apply
+  // to the rewritten command; "allow" skips only the prompt.
+  return rewritten?{hookSpecificOutput:{hookEventName:'PreToolUse',permissionDecision:'allow',
+    permissionDecisionReason:`REDUE: check ${JSON.stringify(name)} is not CURRENT; running it through redue run so the result is recorded.`,
+    updatedInput:{...input.tool_input,command:rewritten}}}:null;
+}
+
+export async function runClaudeHook(entry){
+  try{
+    let text='';process.stdin.setEncoding('utf8');
+    for await(const chunk of process.stdin){text+=chunk;if(text.length>1024*1024)return;}
+    const output=await claudeHook(JSON.parse(text),{entry});
+    if(output)await new Promise(resolve=>process.stdout.write(JSON.stringify(output)+'\n',resolve));
+  }catch{}
+}