paqad-ai 1.44.0 → 1.44.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # paqad-ai
 
+## 1.44.1
+
+### Patch Changes
+
+- 91e4798: Fix the Claude Stop hook so it respects the paqad enable/disable flag and can no longer wedge a session in an infinite loop.
+
+  - **Respects ON/OFF from the real project root.** `verification-completion.mjs` now resolves the project root via `CLAUDE_PROJECT_DIR` / `PAQAD_PROJECT_ROOT` (cwd fallback) like the sibling Stop hooks, instead of raw `process.cwd()`. A project set to `paqad_enable=false` is honored even when the host launched the hook from a subdirectory (previously the disable flag was missed and the OFF project was still blocked).
+  - **Bites once, never loops.** Every blocking Stop hook now reads Claude's `stop_hook_active`: the gate still blocks (exit 2) on the first stop so the model gets a turn to fix it, but once it is already inside a Stop-hook continuation it steps aside (surfaces the summary, exits 0). An unresolvable verdict can no longer drive an infinite Stop loop. The git/CI backstop remains the hard, non-bypassable layer.
+
 ## 1.44.0
 
 ### Minor Changes

package/dist/cli/index.js

@@ -26122,7 +26122,7 @@ init_cancelled_error();
 init_events();
 
 // src/index.ts
-var VERSION = "1.44.0";
+var VERSION = "1.44.1";
 
 // src/cli/commands/audit.ts
 init_esm_shims();

package/dist/index.js

@@ -22780,7 +22780,7 @@ var memoizedReport;
 function getEngineVersionReport() {
   if (memoizedReport === void 0) {
     memoizedReport = Object.freeze({
-      engineVersion: normalizeEngineVersion("1.44.0"),
+      engineVersion: normalizeEngineVersion("1.44.1"),
       minConsumerVersion: MIN_CONSUMER_VERSION,
       deprecatedAsOf: DEPRECATED_AS_OF
     });
@@ -39165,7 +39165,7 @@ function formatVerdictSummary(input2) {
 
 // src/verification/repository/run-repository-verification.ts
 function verifierVersion() {
-  return true ? "1.44.0" : "0.0.0-dev";
+  return true ? "1.44.1" : "0.0.0-dev";
 }
 function backstopGates() {
   return [
@@ -41899,7 +41899,7 @@ var WorkflowEngine = class {
 };
 
 // src/index.ts
-var VERSION = "1.44.0";
+var VERSION = "1.44.1";
 function getFrameworkName() {
   return "paqad-ai";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paqad-ai",
-  "version": "1.44.0",
+  "version": "1.44.1",
   "description": "Spec-driven development framework — AI agents that think before they type",
   "type": "module",
   "license": "MIT",

package/runtime/hooks/capability-gate.mjs

@@ -20,11 +20,13 @@
 // capability currently folded into the seam (rule-scripts); as F6 folds in
 // stages/decision-pause/delivery, this pre-check generalises per-capability.
 
-import { existsSync } from 'node:fs';
+import { existsSync, realpathSync } from 'node:fs';
 import { join } from 'node:path';
 import process from 'node:process';
+import { pathToFileURL } from 'node:url';
 
 import { isPaqadDisabled, readFlooredMode, resolveProjectRoot } from './lib/paqad-disabled.mjs';
+import { stopHookActiveFromStdin } from './lib/loop-guard.mjs';
 
 // Mirrors PATHS.RULE_SCRIPT_MAP — kept in sync by hand (runtime mjs has no dist).
 const RULE_SCRIPT_MAP_REL = 'docs/instructions/rules/rule-script-map.yml';
@@ -90,7 +92,7 @@ function parsePayload(input) {
   }
 }
 
-async function main(input) {
+export async function main(input, seam = SEAM) {
   try {
     const projectRoot = resolveProjectRoot();
     if (isPaqadDisabled(projectRoot)) return 0;
@@ -104,11 +106,24 @@ async function main(input) {
 
     const result = await runCapabilityGate({
       projectRoot,
-      seam: SEAM,
+      seam,
       payload: parsePayload(input),
     });
     if (result.block) {
       process.stderr.write(`${result.summary}\n`);
+      // Loop guard (fix #2) — the completion (Stop) seam is the only one the host
+      // re-runs after forcing a continuation. When Claude marks this Stop as a
+      // continuation of a prior block (`stop_hook_active`), the gate has already
+      // bitten once, so blocking again would loop on an unresolvable outcome:
+      // surface the summary (above) but exit non-blocking. The pre-mutation seam
+      // is a PreToolUse deny, not a Stop loop, so it always keeps its teeth. git/CI
+      // remain the hard, non-bypassable layer.
+      if (seam === 'completion' && stopHookActiveFromStdin(input)) {
+        process.stderr.write(
+          '[paqad] already surfaced this turn — not blocking again so the session can end (git/CI remains the hard gate).\n',
+        );
+        return 0;
+      }
       return 2;
     }
     if (result.summary) {
@@ -123,12 +138,30 @@ async function main(input) {
 }
 
 // Drain stdin (the host pipes the tool/Stop payload) then enforce. The payload is
-// parsed lazily inside main() and only the decision-pause self-arm reads it.
-let input = '';
-process.stdin.on('data', (chunk) => {
-  input += chunk;
-});
-process.stdin.on('end', () => {
-  main(input).then((code) => process.exit(code));
-});
-process.stdin.resume();
+// parsed lazily inside main() and only the decision-pause self-arm reads it. Guarded
+// so importing this module for tests runs nothing. The guard resolves the entry
+// path with realpathSync: the host invokes this hook through the symlinked install
+// (~/.paqad-ai/current → the package runtime), and macOS also aliases /tmp →
+// /private/tmp, so a raw argv[1] compare would MISS the match and silently no-op
+// the whole gate. Comparing realpaths is symlink-safe.
+if (isDirectEntry()) {
+  let input = '';
+  process.stdin.on('data', (chunk) => {
+    input += chunk;
+  });
+  process.stdin.on('end', () => {
+    main(input).then((code) => process.exit(code));
+  });
+  process.stdin.resume();
+}
+
+/** True when this module is the process entry point, symlink-safe (see above). */
+function isDirectEntry() {
+  const entry = process.argv[1];
+  if (!entry) return false;
+  try {
+    return import.meta.url === pathToFileURL(realpathSync(entry)).href;
+  } catch {
+    return false;
+  }
+}

package/runtime/hooks/lib/loop-guard.mjs

@@ -0,0 +1,32 @@
+// loop-guard.mjs — the Stop-hook loop breaker (fix #2).
+//
+// A blocking Stop hook (exit 2) makes the host re-prompt the model and run the
+// hook again. When the block is on a condition the model cannot resolve in-session
+// (a missing canonical doc, an unrecordable stage), that re-prompt loops forever.
+//
+// The host tells us when we are already inside such a continuation: Claude sets
+// `stop_hook_active: true` on the Stop payload once a prior Stop hook forced the
+// turn. Every blocking Stop hook reads this and, when set, degrades from a hard
+// block to an advisory — the gate still bites ONCE (surfacing the problem and
+// giving the model a turn to fix it), then steps aside so the session can end.
+// The non-bypassable teeth remain at the git/CI backstop, exactly as the hook
+// header comments already promise.
+//
+// Dependency-free and side-effect-free (importing runs nothing) so it is trivially
+// unit-testable and safe to load on every Stop.
+
+/**
+ * Best-effort `stop_hook_active` from the host Stop-hook stdin payload. True only
+ * when the host explicitly marks this Stop as a continuation of a prior Stop-hook
+ * block. Absent / non-JSON / malformed ⇒ false (treat as the first stop, so the
+ * gate keeps its teeth).
+ */
+export function stopHookActiveFromStdin(stdin) {
+  try {
+    const parsed = JSON.parse(stdin);
+    return parsed?.stop_hook_active === true;
+  } catch {
+    // Not JSON / no field — treat as the first stop.
+    return false;
+  }
+}

package/runtime/hooks/verification-completion.mjs

@@ -13,6 +13,8 @@
 import process from 'node:process';
 
 import { sessionIdFromStdin } from './lib/context-seam-emit.mjs';
+import { resolveProjectRoot } from './lib/paqad-disabled.mjs';
+import { stopHookActiveFromStdin } from './lib/loop-guard.mjs';
 import { runVerificationBackstop } from '../scripts/verify-backstop.mjs';
 
 // Read the Stop-hook JSON payload: the host (Claude) puts the session_id here, and
@@ -33,8 +35,16 @@ async function main() {
   const code = await runVerificationBackstop({
     origin: 'hook-completion',
     softFail: true,
-    projectRoot: process.cwd(),
+    // Fix #1 — resolve the project root the host is operating on (CLAUDE_PROJECT_DIR
+    // / PAQAD_PROJECT_ROOT, cwd fallback) via the shared helper, matching the sibling
+    // Stop hooks. Raw process.cwd() missed the disable flag stored in the project's
+    // .paqad/.config whenever the host launched the hook from a subdirectory, so an
+    // OFF project still got blocked.
+    projectRoot: resolveProjectRoot(),
     hostSessionId: sessionIdFromStdin(input),
+    // Fix #2 — pass Claude's `stop_hook_active` so a block downgrades to advisory
+    // once we are already inside a Stop-hook continuation loop (see loop-guard.mjs).
+    loopActive: stopHookActiveFromStdin(input),
   });
   process.exit(code);
 }

package/runtime/scripts/verify-backstop.mjs

@@ -50,6 +50,7 @@ export async function runVerificationBackstop({
   hostSessionId,
   stdout,
   stderr,
+  loopActive,
 }) {
   const out = stdout ?? process.stdout;
   const err = stderr ?? process.stderr;
@@ -84,8 +85,21 @@ export async function runVerificationBackstop({
     // Stop-hook contract: on a block (exit 2) the host surfaces only STDERR to
     // the model — STDOUT is transcript-only. Writing the verdict to stdout made
     // the block invisible ("No stderr output"). Mirror capability-gate.mjs so the
-    // failing verdict summary reaches the model. Exit code (2) is unchanged.
+    // failing verdict summary reaches the model.
     err.write(`${verdict.summary}\n`);
+    // Loop guard (fix #2) — when the host says we are already inside a Stop-hook
+    // continuation (`loopActive`, set only by the completion hook from Claude's
+    // `stop_hook_active`), the gate has already bitten once this turn. Blocking
+    // again would loop forever on an unresolvable verdict, so we step aside: the
+    // summary is surfaced (above) but the exit is a non-blocking 0. git/CI stay the
+    // hard, non-bypassable layer. Never reached by the git/CI backstop, which
+    // never sets loopActive.
+    if (loopActive) {
+      err.write(
+        '[paqad] already surfaced this turn — not blocking again so the session can end (git/CI remains the hard gate).\n',
+      );
+      return 0;
+    }
     return 2;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);