start-vibing-stacks 2.28.0 → 2.29.0

package/dist/migrate.js

@@ -233,40 +233,56 @@ function applyOne(item, opts) {
     copyFileSync(item.source, item.target);
     return { applied: true };
 }
+// Keyed by event; each event carries one or more independent blocks. PreToolUse
+// runs two: the multi-instance collision guard AND the plan-gate nudge. Each
+// block is checked/appended individually so backfill is precise per-script.
 const REQUIRED_HOOK_BLOCKS = {
-    SessionStart: {
-        hooks: [
-            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.ts"', timeout: 10 },
-        ],
-    },
-    UserPromptSubmit: {
-        matcher: '',
-        hooks: [
-            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/user-prompt-submit.ts"', timeout: 10 },
-        ],
-    },
-    PreToolUse: {
-        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
-        hooks: [
-            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-use.ts"', timeout: 5 },
-        ],
-    },
-    PostToolUse: {
-        matcher: 'Edit|Write|MultiEdit|NotebookEdit',
-        hooks: [
-            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use.ts"', timeout: 5 },
-        ],
-    },
-    Stop: {
-        hooks: [
-            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validator.ts"', timeout: 30 },
-        ],
-    },
-    SessionEnd: {
-        hooks: [
-            { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validator.ts"', timeout: 10 },
-        ],
-    },
+    SessionStart: [
+        {
+            hooks: [
+                { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/session-start.ts"', timeout: 10 },
+            ],
+        },
+    ],
+    UserPromptSubmit: [
+        {
+            matcher: '',
+            hooks: [
+                { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/user-prompt-submit.ts"', timeout: 10 },
+            ],
+        },
+    ],
+    PreToolUse: [
+        {
+            matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+            hooks: [
+                { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-use.ts"', timeout: 5 },
+                { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/plan-gate.ts"', timeout: 5 },
+            ],
+        },
+    ],
+    PostToolUse: [
+        {
+            matcher: 'Edit|Write|MultiEdit|NotebookEdit',
+            hooks: [
+                { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/post-tool-use.ts"', timeout: 5 },
+            ],
+        },
+    ],
+    Stop: [
+        {
+            hooks: [
+                { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validator.ts"', timeout: 30 },
+            ],
+        },
+    ],
+    SessionEnd: [
+        {
+            hooks: [
+                { type: 'command', command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/stop-validator.ts"', timeout: 10 },
+            ],
+        },
+    ],
 };
 function commandSubstring(cmd) {
     const m = cmd.match(/\.claude\/hooks\/([A-Za-z0-9._-]+\.(?:ts|sh|js|mjs))/);
@@ -291,18 +307,40 @@ export function patchSettings(projectDir, dryRun) {
         }
     }
     settings.hooks = settings.hooks || {};
-    for (const [event, requiredBlock] of Object.entries(REQUIRED_HOOK_BLOCKS)) {
-        const existingBlocks = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
-        const requiredScript = commandSubstring(requiredBlock.hooks[0].command);
-        const alreadyHas = existingBlocks.some(b => (b.hooks || []).some(h => commandSubstring(h.command).includes(requiredScript)));
-        if (alreadyHas) {
-            report.alreadyPresent.push(event);
-            continue;
+    for (const [event, requiredBlocks] of Object.entries(REQUIRED_HOOK_BLOCKS)) {
+        let existingBlocks = Array.isArray(settings.hooks[event]) ? settings.hooks[event] : [];
+        let mutated = false;
+        // Check at the SCRIPT (hook) level, not the block level: an install may
+        // already have pre-tool-use.ts but be missing the newer plan-gate.ts in the
+        // same PreToolUse matcher — a block-level check would wrongly skip it.
+        for (const requiredBlock of requiredBlocks) {
+            for (const requiredHook of requiredBlock.hooks) {
+                const requiredScript = commandSubstring(requiredHook.command);
+                const alreadyHas = existingBlocks.some(b => (b.hooks || []).some(h => commandSubstring(h.command).includes(requiredScript)));
+                const label = `${event}:${requiredScript}`;
+                if (alreadyHas) {
+                    report.alreadyPresent.push(label);
+                    continue;
+                }
+                if (!dryRun) {
+                    const sameMatcher = existingBlocks.find(b => (b.matcher ?? '') === (requiredBlock.matcher ?? ''));
+                    if (sameMatcher) {
+                        sameMatcher.hooks = [...(sameMatcher.hooks || []), requiredHook];
+                    }
+                    else {
+                        existingBlocks = [
+                            ...existingBlocks,
+                            { matcher: requiredBlock.matcher, hooks: [requiredHook] },
+                        ];
+                    }
+                    mutated = true;
+                }
+                report.added.push(label);
+            }
         }
-        if (!dryRun) {
-            settings.hooks[event] = [...existingBlocks, requiredBlock];
+        if (!dryRun && mutated) {
+            settings.hooks[event] = existingBlocks;
         }
-        report.added.push(event);
     }
     // High-reasoning defaults (v2.28.0). Only set when MISSING so we never clobber
     // a user's explicit choice. `ultracode` is intentionally never written here:

package/dist/setup.js

@@ -287,6 +287,11 @@ export async function setupProject(projectDir, config, options = {}) {
                                 command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/pre-tool-use.ts"',
                                 timeout: 5,
                             },
+                            {
+                                type: 'command',
+                                command: 'npx tsx "$CLAUDE_PROJECT_DIR/.claude/hooks/plan-gate.ts"',
+                                timeout: 5,
+                            },
                         ],
                     },
                 ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.28.0",
+  "version": "2.29.0",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/hooks/_state.ts

@@ -1,9 +1,9 @@
-// @sv-version: 1.1.0
+// @sv-version: 1.2.0
 /**
  * Multi-Instance Coordination — Shared State Library
  *
  * Used by session-start.ts, user-prompt-submit.ts, pre-tool-use.ts,
- * post-tool-use.ts, stop-validator.ts and peers.ts.
+ * post-tool-use.ts, stop-validator.ts, plan-gate.ts and peers.ts.
  *
  * Layout (project-local, gitignored):
  *   .claude/state/
@@ -23,6 +23,10 @@
  * FILES_TOUCHED_CAP 50→200 (large sessions were dropping early edits, which then
  * showed up as orphaned dirty files a peer could not attribute); path
  * normalization in extractTargetFiles is now repo-root-stable.
+ *
+ * v1.2.0: added optional `planGateNotifiedAt` to SessionRecord — a one-shot
+ * marker so plan-gate.ts nudges the user toward `/effort ultracode` only once
+ * per session when a change crosses the distinct-file threshold.
  */
 
 import {
@@ -63,6 +67,8 @@ export interface SessionRecord {
   lastSeenAt: string;
   lastActivity: string;
   filesTouched: string[];
+  /** ISO timestamp set once when plan-gate fired its high-reasoning nudge. */
+  planGateNotifiedAt?: string;
 }
 
 export interface FileTouch {

package/stacks/_shared/hooks/plan-gate.ts

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// @sv-version: 1.0.0
+/**
+ * PreToolUse Hook — Plan Gate (high-reasoning nudge)
+ *
+ * Wired with matcher `Edit|Write|MultiEdit|NotebookEdit`, alongside pre-tool-use.ts.
+ * When a SINGLE session is about to touch MORE THAN the threshold (default 4)
+ * DISTINCT files, it fires ONCE per session: returns `permissionDecision: "ask"`
+ * so Claude Code prompts the USER, recommending they cancel, run `/effort` and
+ * select `ultracode`, then confirm a short plan before the large change proceeds.
+ *
+ * WHY ONLY A RECOMMENDATION (hard limitation, confirmed in the hooks docs):
+ *   "Command hooks communicate through stdout, stderr, and exit codes only. They
+ *    cannot trigger `/` commands or tool calls."
+ *   Effort level (`ultracode`) is also read-only metadata to hooks and is not
+ *   persistable in settings.json. So switching to ultracode is necessarily a user
+ *   keystroke — this hook just makes the moment impossible to miss. The
+ *   `permissions.defaultMode: "plan"` setting handles the "plan first" half.
+ *
+ * Distinct-file count = union(session.filesTouched, files this Edit will touch).
+ * The one-shot marker (`SessionRecord.planGateNotifiedAt`) prevents re-prompting on
+ * every subsequent edit in the same large task.
+ *
+ * Config (env):
+ *   PLAN_GATE_DISABLED=1        — turn the gate off entirely
+ *   PLAN_GATE_THRESHOLD=<n>     — fire when distinct files exceed <n> (default 4)
+ *
+ * Hook input:
+ *   { session_id, tool_name, tool_input, hook_event_name, ... }
+ *
+ * Output schema (JSON):
+ *   { continue: true, hookSpecificOutput?: { hookEventName, permissionDecision, permissionDecisionReason } }
+ *
+ * Fail-open: any error → approve silently. A nudge must NEVER break editing.
+ */
+
+import {
+  extractTargetFiles,
+  getProjectDir,
+  getStateDir,
+  nowIso,
+  readSession,
+  readStdinJson,
+  writeSession,
+} from './_state.js';
+
+const DEFAULT_THRESHOLD = 4;
+
+function approve(): void {
+  console.log(JSON.stringify({ continue: true }));
+}
+
+function parseThreshold(raw: string | undefined): number {
+  if (!raw) return DEFAULT_THRESHOLD;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 1 ? n : DEFAULT_THRESHOLD;
+}
+
+async function main(): Promise<void> {
+  if (process.env['PLAN_GATE_DISABLED'] === '1') {
+    approve();
+    return;
+  }
+
+  const input = await readStdinJson(1500);
+  const sessionId: string | undefined = input.session_id || input.sessionId;
+  const toolName: string = input.tool_name || input.toolName || '';
+  const toolInput: any = input.tool_input || input.toolInput || {};
+
+  if (!/^(Edit|Write|MultiEdit|NotebookEdit)$/.test(toolName)) {
+    approve();
+    return;
+  }
+
+  // Without a session we can neither count distinct files reliably nor record the
+  // one-shot marker — stay out of the way.
+  if (!sessionId) {
+    approve();
+    return;
+  }
+
+  const projectDir = getProjectDir();
+  const stateDir = getStateDir(projectDir);
+  const session = readSession(stateDir, sessionId);
+
+  // session-start.ts hasn't registered yet (or state is unavailable): do nothing.
+  if (!session) {
+    approve();
+    return;
+  }
+
+  // Already nudged this session — never nag again.
+  if (session.planGateNotifiedAt) {
+    approve();
+    return;
+  }
+
+  const threshold = parseThreshold(process.env['PLAN_GATE_THRESHOLD']);
+  const distinct = new Set(session.filesTouched || []);
+  for (const f of extractTargetFiles(toolName, toolInput, projectDir)) distinct.add(f);
+
+  if (distinct.size <= threshold) {
+    approve();
+    return;
+  }
+
+  // Fire once: set the marker BEFORE returning so it never re-prompts regardless
+  // of whether the user approves or cancels this particular edit.
+  try {
+    writeSession(stateDir, { ...session, planGateNotifiedAt: nowIso() });
+  } catch {}
+
+  const reason =
+    `This task is now touching ${distinct.size} distinct files (> ${threshold}). ` +
+    `For a change this size, consider switching to maximum reasoning before continuing:\n` +
+    `  1. Press ESC to cancel this edit.\n` +
+    `  2. Run /effort and select "ultracode".\n` +
+    `  3. Ask Claude for a short plan, confirm it, then implement.\n\n` +
+    `Hooks cannot run /effort for you (effort is read-only to hooks), so this is a ` +
+    `one-time nudge per session. Approve to continue WITHOUT switching.`;
+
+  console.log(
+    JSON.stringify({
+      continue: true,
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'ask',
+        permissionDecisionReason: reason,
+      },
+    })
+  );
+}
+
+main().catch(() => {
+  // A high-reasoning nudge must never block Claude on its own bug.
+  console.log(JSON.stringify({ continue: true }));
+  process.exit(0);
+});