chati-dev 4.2.0 → 4.2.2

package/framework/hooks/mode-governance.js

@@ -41,12 +41,25 @@ const STATE_TO_GOVERNANCE_MODE = {
 
 function getCurrentMode(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
-  if (!existsSync(sessionPath)) return 'planning'; // Default to most restrictive
+  // No session = no enforcement yet (orchestrator will set mode on first run).
+  // Defaulting to planning here would deadlock fresh installs (planning blocks
+  // session.yaml writes, so the orchestrator could never bootstrap).
+  if (!existsSync(sessionPath)) return 'build';
 
   const raw = readFileSync(sessionPath, 'utf-8');
-  const match = raw.match(/^\s*mode:\s*(.+)$/m);
-  const state = match ? match[1].trim().replace(/^["']|["']$/g, '') : 'discover';
-  return STATE_TO_GOVERNANCE_MODE[state] || 'planning';
+  // Prefer explicit mode field; fall back to project.state mapping.
+  const modeMatch = raw.match(/^\s*mode:\s*(.+)$/m);
+  if (modeMatch) {
+    const mode = modeMatch[1].trim().replace(/^["']|["']$/g, '');
+    if (MODE_SCOPES[mode]) return mode;
+  }
+  const stateMatch = raw.match(/^\s+state:\s*(.+)$/m);
+  if (stateMatch) {
+    const state = stateMatch[1].trim().replace(/^["']|["']$/g, '');
+    return STATE_TO_GOVERNANCE_MODE[state] || 'build';
+  }
+  // Session exists but no mode/state field — be permissive.
+  return 'build';
 }
 
 function isPathAllowed(filePath, projectDir, mode) {
@@ -74,31 +87,59 @@ async function main() {
     const filePath = toolInput.file_path || toolInput.path || '';
 
     if (!filePath) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
     const mode = getCurrentMode(projectDir);
 
     if (isPathAllowed(filePath, projectDir, mode)) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
     } else {
       const scope = MODE_SCOPES[mode];
-      process.stdout.write(JSON.stringify({
-        decision: 'block',
-        reason: `[Article XI] ${scope.description}. Cannot write to "${filePath}" in ${mode} mode.`,
-      }));
+      process.stdout.write(JSON.stringify(denyOutput(
+        `[Article XI] ${scope.description}. Cannot write to "${filePath}" in ${mode} mode.`
+      )));
     }
   } catch (err) {
     process.stderr.write(`[chati-hook-error] mode-governance: ${err?.message || 'unknown'}\n`);
-    process.stdout.write(JSON.stringify({ decision: 'block', reason: 'Hook error — fail-closed for safety' }));
+    // Hook errors are fail-OPEN: a broken hook should not block the user.
+    // Security-critical denials are handled by explicit logic above.
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput() {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+}
+
+function denyOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
 export { getCurrentMode, isPathAllowed, MODE_SCOPES, STATE_TO_GOVERNANCE_MODE };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/model-governance.js

@@ -80,24 +80,34 @@ async function main() {
       const assignment = AGENT_MODELS[agent];
       const expected = assignment.model || assignment;
       const provider = assignment.provider || 'claude';
-      // Advisory note — appended to context
+      // Advisory context injection via canonical UserPromptSubmit schema.
       process.stdout.write(JSON.stringify({
-        result: 'allow',
-        prefix: `<!-- [Article XVI] Agent "${agent}" assigned model: ${expected} (provider: ${provider}) -->`,
+        hookSpecificOutput: {
+          hookEventName: 'UserPromptSubmit',
+          additionalContext: `[Article XVI] Agent "${agent}" assigned model: ${expected} (provider: ${provider})`,
+        },
       }));
     } else {
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write('{}');
     }
   } catch (err) {
     process.stderr.write(`[chati] model-governance: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    process.stdout.write('{}');
   }
 }
 
 export { AGENT_MODELS, UPGRADE_CONDITIONS, getCurrentAgent };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/framework/hooks/prism-engine.js

@@ -65,8 +65,8 @@ async function main() {
     const session = readSessionState(projectDir);
 
     if (!session) {
-      // No active session — don't inject anything
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      // No active session — don't inject anything (empty output = allow)
+      process.stdout.write('{}');
       return;
     }
 
@@ -163,13 +163,19 @@ async function main() {
       '</chati-context>',
     ].filter(Boolean).join('\n');
 
+    // UserPromptSubmit context injection schema:
+    // hookSpecificOutput.additionalContext is the canonical field for
+    // injecting text into Claude's view of the current prompt.
     process.stdout.write(JSON.stringify({
-      result: 'allow',
-      prefix: contextBlock,
+      hookSpecificOutput: {
+        hookEventName: 'UserPromptSubmit',
+        additionalContext: contextBlock,
+      },
     }));
   } catch (err) {
     process.stderr.write(`[chati] prism-engine: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    // Silent allow on error — empty object = no injection, no block.
+    process.stdout.write('{}');
   }
 }
 
@@ -201,8 +207,16 @@ function detectFrustration(prompt) {
 
 export { readSessionState, detectFrustration };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/read-protection.js

@@ -93,24 +93,52 @@ async function main() {
     const result = isSensitivePath(filePath, cwd);
 
     if (result.sensitive) {
-      process.stdout.write(JSON.stringify({
-        decision: 'block',
-        reason: `[Article IV] ${result.reason}. Use environment variables or secure vaults instead of reading sensitive files directly.`,
-      }));
+      process.stdout.write(JSON.stringify(denyOutput(
+        `[Article IV] ${result.reason}. Use environment variables or secure vaults instead of reading sensitive files directly.`
+      )));
       return;
     }
 
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
     process.stderr.write(`[chati-hook-error] read-protection: ${err?.message || 'unknown'}\n`);
-    process.stdout.write(JSON.stringify({ decision: 'block', reason: 'Hook error — fail-closed for safety' }));
+    // Fail-open: a broken hook should not prevent reads. Real protection
+    // patterns are explicit above and run before this catch.
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput() {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+}
+
+function denyOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
 export { isSensitivePath, SENSITIVE_PATTERNS, ALLOWED_EXCEPTIONS };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/session-digest.js

@@ -115,7 +115,9 @@ async function main() {
         process.stderr.write(`[chati] session-digest daily-append: ${err.message}\n`);
       }
 
-      // Auto memory consolidation: trigger when memories accumulate
+      // Auto memory consolidation: trigger when memories accumulate.
+      // CRITICAL: must be fully async (detached spawn) — PreCompact runs on the
+      // hot path and execSync would add up to 10s of latency to every compact.
       try {
         const memBase = join(projectDir, '.chati', 'memories');
         if (existsSync(memBase)) {
@@ -132,16 +134,19 @@ async function main() {
           // Consolidate when > 100 entries (50% of 200 cap)
           if (totalEntries > 100) {
             process.stderr.write(`[chati] auto-dream: ${totalEntries} entries, triggering consolidation\n`);
-            // Fire-and-forget: consolidation runs in background
-            // Import would fail in hook context, so we spawn a child process
-            const { execSync } = await import('child_process');
+            // Fire-and-forget detached spawn — returns immediately, child outlives parent.
+            const { spawn } = await import('child_process');
             try {
-              execSync(`node -e "import('./packages/chati-dev/src/memory/dream.js').then(m => m.runDreamConsolidation('${projectDir.replace(/'/g, "\\'")}'))"`, {
+              const child = spawn('node', [
+                '-e',
+                `import('./packages/chati-dev/src/memory/dream.js').then(m => m.runDreamConsolidation(${JSON.stringify(projectDir)}))`,
+              ], {
                 cwd: projectDir,
-                timeout: 10000,
+                detached: true,
                 stdio: 'ignore',
               });
-            } catch { /* expected: consolidation may timeout or fail */ }
+              child.unref();
+            } catch { /* expected: spawn may fail in restricted env */ }
           }
         }
       } catch (err) {
@@ -149,8 +154,9 @@ async function main() {
       }
     }
 
-    // Session telemetry ping (moved from license-guard to reduce per-prompt overhead)
-    // 5-minute throttle with phase/agent change detection
+    // Session telemetry ping (owned by session-digest, was moved here from license-guard).
+    // 5-minute throttle with phase/agent change detection.
+    // Pings.yaml format: '/path/to/project': '<ISO8601>|<phase>|<agent>'
     try {
       const homedir = process.env.HOME || '';
       const pingsPath = join(homedir, '.chati-dev', 'pings.yaml');
@@ -163,15 +169,17 @@ async function main() {
 
         if (licenseKey && digest) {
           let shouldPing = false;
-          const now = Date.now();
+          const nowIso = new Date().toISOString();
           const currentState = `${digest.mode}|${digest.currentAgent}`;
 
           if (existsSync(pingsPath)) {
             const pingsRaw = readFileSync(pingsPath, 'utf-8');
-            const entryMatch = pingsRaw.match(new RegExp(`${projectDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}.*?'([^']+)'`));
+            const escaped = projectDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const entryMatch = pingsRaw.match(new RegExp(`^${escaped}:\\s*'([^']+)'`, 'm'));
             if (entryMatch) {
               const [ts, phase, agent] = entryMatch[1].split('|');
-              const elapsed = now - parseInt(ts);
+              const lastTime = new Date(ts).getTime();
+              const elapsed = isNaN(lastTime) ? Infinity : Date.now() - lastTime;
               const stateChanged = `${phase}|${agent}` !== currentState;
               shouldPing = elapsed > 300000 || stateChanged; // 5 min or state change
             } else {
@@ -182,16 +190,24 @@ async function main() {
           }
 
           if (shouldPing) {
-            // Update ping timestamp
+            // Update ping entry — preserve other projects in the file.
             mkdirSync(join(homedir, '.chati-dev'), { recursive: true });
-            writeFileSync(pingsPath, `'${projectDir}': '${now}|${currentState}'\n`, 'utf-8');
+            const newEntry = `${projectDir}: '${nowIso}|${currentState}'\n`;
+            let content = existsSync(pingsPath) ? readFileSync(pingsPath, 'utf-8') : '';
+            const escaped = projectDir.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            if (new RegExp(`^${escaped}:`, 'm').test(content)) {
+              content = content.replace(new RegExp(`^${escaped}:.*$`, 'm'), newEntry.trim());
+            } else {
+              content += newEntry;
+            }
+            writeFileSync(pingsPath, content, 'utf-8');
 
             // Fire-and-forget telemetry (3s timeout, never blocks)
             try {
               const body = JSON.stringify({
                 license_key: licenseKey,
                 project_name: digest.currentAgent || 'unknown',
-                events: [{ type: 'session_active', timestamp: new Date().toISOString(), properties: { pipeline_phase: digest.mode, current_agent: digest.currentAgent } }],
+                events: [{ type: 'session_active', timestamp: nowIso, properties: { pipeline_phase: digest.mode, current_agent: digest.currentAgent } }],
               });
               fetch('https://chati.dev/api/telemetry', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body, signal: AbortSignal.timeout(3000) }).catch(() => {});
             } catch { /* expected: network may be unavailable */ }
@@ -202,15 +218,24 @@ async function main() {
       process.stderr.write(`[chati] session-digest telemetry-ping: ${err.message}\n`);
     }
 
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    // PreCompact is observational only — empty output is the canonical "no-op".
+    process.stdout.write('{}');
   } catch (err) {
     process.stderr.write(`[chati] session-digest: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    process.stdout.write('{}');
   }
 }
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/style-guard.js

@@ -97,7 +97,7 @@ async function main() {
     // Skip exempt paths
     const filePath = toolInput.file_path || '';
     if (isExemptPath(filePath, projectDir)) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
@@ -112,24 +112,44 @@ async function main() {
     }
 
     if (result.violations.length > 0) {
-      // Block all style violations — agent must rewrite
-      process.stdout.write(JSON.stringify({
-        decision: 'block',
-        reason: `[Style Guard] ${result.violations.join(' ')} Rewrite without em-dashes and emojis.`,
-      }));
+      // Advisory: surface as reason but allow. Style is a soft preference,
+      // not a security boundary — hard-blocking blocks legitimate markdown.
+      process.stdout.write(JSON.stringify(allowOutput(
+        `[Style Guard] ${result.violations.join(' ')} Consider rewriting without em-dashes and emojis (Article V).`
+      )));
       return;
     }
 
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
     process.stderr.write(`[chati] style-guard: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput(reason) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+  if (reason) out.hookSpecificOutput.permissionDecisionReason = reason;
+  return out;
+}
+
 export { checkStyle, checkBashStyle, isExemptPath, EM_DASH_PATTERN, EMOJI_PATTERN };
 
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/team-quality-gate.js

@@ -79,7 +79,7 @@ async function main() {
     // Quick exit: no team active → allow everything
     const teamId = process.env.CHATI_TEAM_ID;
     if (!teamId) {
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
@@ -87,14 +87,14 @@ async function main() {
     const currentAgent = process.env.CHATI_TEAM_MEMBER || detectAgentFromSession(projectDir);
     if (!currentAgent) {
       // Cannot determine agent → allow (fail-open for safety)
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
     // Get the file path being written
     const filePath = event.tool_input?.file_path || '';
     if (!filePath) {
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
@@ -103,7 +103,7 @@ async function main() {
 
     // Check shared paths first — always allowed
     if (SHARED_PATHS.some(sp => relativePath.startsWith(sp))) {
-      process.stdout.write(JSON.stringify({ result: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
@@ -112,24 +112,42 @@ async function main() {
       if (agent === currentAgent) continue;
       for (const scope of scopes) {
         if (relativePath.startsWith(scope) || (!scope.includes('/') && relativePath.endsWith(scope))) {
-          process.stdout.write(JSON.stringify({
-            result: 'block',
-            reason: `[Team Quality Gate] ${currentAgent} cannot write to ${relativePath} — this path belongs to ${agent}. Use the team mailbox to coordinate changes (Article XXI).`,
-          }));
+          process.stdout.write(JSON.stringify(denyOutput(
+            `[Team Quality Gate] ${currentAgent} cannot write to ${relativePath} — this path belongs to ${agent}. Use the team mailbox to coordinate changes (Article XXI).`
+          )));
           return;
         }
       }
     }
 
     // Path not owned by anyone specific → allow
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
     // Fail-open: hook errors should not block execution
     process.stderr.write(`[chati] team-quality-gate: ${err.message}\n`);
-    process.stdout.write(JSON.stringify({ result: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput() {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+}
+
+function denyOutput(reason) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
 function detectAgentFromSession(projectDir) {
   const sessionPath = join(projectDir, '.chati', 'session.yaml');
   if (!existsSync(sessionPath)) return null;
@@ -138,8 +156,16 @@ function detectAgentFromSession(projectDir) {
   return match ? match[1].trim().replace(/^["']|["']$/g, '') : null;
 }
 
-// Only run main when executed directly
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }

package/framework/hooks/undercover-guard.js

@@ -173,14 +173,14 @@ async function main() {
 
     // Check if undercover mode is enabled
     if (!isUndercoverEnabled(projectDir)) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
     // Skip framework-internal files
     const filePath = toolInput.file_path || '';
     if (isExemptPath(filePath, projectDir)) {
-      process.stdout.write(JSON.stringify({ decision: 'allow' }));
+      process.stdout.write(JSON.stringify(allowOutput()));
       return;
     }
 
@@ -196,25 +196,44 @@ async function main() {
 
     if (scan.found) {
       const terms = scan.matches.map(m => `"${m.term}" → "${m.replacement}"`).join(', ');
-      process.stdout.write(JSON.stringify({
-        decision: 'allow',  // Advisory — don't block, just warn
-        reason: `[Undercover] Internal references detected in output: ${terms}. Please sanitize before shipping to production. Replace internal terms with their generic equivalents.`,
-      }));
+      // Advisory only — surface findings as reason, allow operation.
+      process.stdout.write(JSON.stringify(allowOutput(
+        `[Undercover] Internal references detected: ${terms}. Sanitize before shipping. Replace internal terms with their generic equivalents.`
+      )));
       return;
     }
 
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   } catch (err) {
     process.stderr.write(`[chati-hook-error] undercover-guard: ${err?.message || 'unknown'}\n`);
     // Fail-open: undercover is advisory, not security-critical
-    process.stdout.write(JSON.stringify({ decision: 'allow' }));
+    process.stdout.write(JSON.stringify(allowOutput()));
   }
 }
 
+function allowOutput(reason) {
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'allow',
+    },
+  };
+  if (reason) out.hookSpecificOutput.permissionDecisionReason = reason;
+  return out;
+}
+
 export { scanForInternals, scanBashForInternals, isExemptPath, isUndercoverEnabled, UNDERCOVER_RULES };
 
-// Only run main when executed directly (not imported by tests)
+// Only run main when executed directly (not imported by tests).
+// realpathSync resolves symlinks on both sides — important on macOS where
+// /tmp is a symlink to /private/tmp. Without realpath the comparison fails
+// silently and main() never runs.
 import { fileURLToPath } from 'url';
-if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  main();
+import { realpathSync } from 'fs';
+if (process.argv[1]) {
+  try {
+    if (realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+      main();
+    }
+  } catch { /* path resolution failed — not invoked as a script */ }
 }