learnship 2.1.1 → 2.2.0

package/bin/install.js

@@ -67,6 +67,8 @@ const hasGlobal    = args.includes('--global') || args.includes('-g');
 const hasLocal     = args.includes('--local')  || args.includes('-l');
 const hasUninstall = args.includes('--uninstall') || args.includes('-u');
 const hasHelp      = args.includes('--help') || args.includes('-h');
+const targetIdx    = args.indexOf('--target');
+const targetOverride = targetIdx !== -1 && args[targetIdx + 1] ? path.resolve(args[targetIdx + 1]) : null;
 
 let selectedPlatforms = [];
 if (hasAll) {
@@ -111,6 +113,7 @@ const helpText = `
     ${cyan}-l, --local${reset}   Install to current project directory
 
   ${yellow}Options:${reset}
+    ${cyan}--target <dir>${reset}   Install to a custom directory instead of the platform default
     ${cyan}-u, --uninstall${reset}  Remove learnship files
     ${cyan}-h, --help${reset}       Show this help
 
@@ -533,6 +536,16 @@ function replacePaths(content, pathPrefix, platform) {
   } else if (platform === 'codex') {
     c = c.replace(/~\/\.codex\//g, pathPrefix);
   }
+  // Rewrite AskUserQuestion to platform-native interactive question tool name.
+  // Source files use AskUserQuestion (Claude Code syntax). Each platform has its own tool name.
+  // OpenCode is handled separately in convertToOpencode(). Claude keeps AskUserQuestion as-is.
+  if (platform === 'windsurf') {
+    c = c.replace(/\bAskUserQuestion\b/g, 'ask_user_question');
+  } else if (platform === 'gemini') {
+    c = c.replace(/\bAskUserQuestion\b/g, 'ask_user');
+  } else if (platform === 'codex') {
+    c = c.replace(/\bAskUserQuestion\b/g, 'request_user_input');
+  }
   // Replace @mention skill syntax — @mention dispatch is Windsurf-native only
   if (platform === 'claude') {
     c = c.replace(/@agentic-learning\b/g, '/agentic-learning');
@@ -1084,6 +1097,266 @@ function scanForLeakedPaths(targetDir, platform) {
   }
 }
 
+// ─── Hook installation ────────────────────────────────────────────────────
+
+/** List of learnship hook files managed by the installer */
+const LEARNSHIP_MANAGED_HOOKS = [
+  'learnship-statusline.js',
+  'learnship-context-monitor.js',
+  'learnship-prompt-guard.js',
+  'learnship-session-state.js',
+];
+
+/**
+ * Install Claude Code / Gemini native hooks into settings.json.
+ * Copies hook .js files to target/hooks/ and registers them in settings.json.
+ * Preserves existing non-learnship entries (read-modify-write).
+ */
+function installClaudeHooks(targetDir, isGlobal, platform) {
+  const hooksSrc = path.join(__dirname, '..', 'hooks');
+  const hooksDest = path.join(targetDir, 'hooks');
+  fs.mkdirSync(hooksDest, { recursive: true });
+
+  // Copy hook .js files (skip session-start bash script — replaced by learnship-session-state.js)
+  let copied = 0;
+  for (const file of LEARNSHIP_MANAGED_HOOKS) {
+    const src = path.join(hooksSrc, file);
+    if (fs.existsSync(src)) {
+      // Stamp version header
+      let content = fs.readFileSync(src, 'utf8');
+      content = content.replace(/learnship-hook-version:\s*[\d.]+/, `learnship-hook-version: ${pkg.version}`);
+      fs.writeFileSync(path.join(hooksDest, file), content);
+      copied++;
+    }
+  }
+
+  if (copied === 0) return 0;
+
+  // Write package.json for CJS require() support in hooks
+  const pkgJsonPath = path.join(targetDir, 'package.json');
+  if (!fs.existsSync(pkgJsonPath)) {
+    fs.writeFileSync(pkgJsonPath, '{"type":"commonjs"}\n');
+  }
+
+  // Build hook commands — use $CLAUDE_PROJECT_DIR for local installs
+  const dirName = getDirName(platform);
+  const localPrefix = '"$CLAUDE_PROJECT_DIR"/' + dirName;
+  const buildCmd = (file) => {
+    if (isGlobal) {
+      const resolved = path.resolve(targetDir).replace(/\\/g, '/');
+      return `node "${resolved}/hooks/${file}"`;
+    }
+    return `node ${localPrefix}/hooks/${file}`;
+  };
+
+  // Read-modify-write settings.json
+  const settingsPath = path.join(targetDir, 'settings.json');
+  const settings = readSettings(settingsPath);
+  if (!settings.hooks) settings.hooks = {};
+
+  // Gemini uses AfterTool/BeforeTool instead of PostToolUse/PreToolUse
+  const isGemini = platform === 'gemini';
+  const postToolEvent = isGemini ? 'AfterTool' : 'PostToolUse';
+  const preToolEvent = isGemini ? 'BeforeTool' : 'PreToolUse';
+
+  // --- SessionStart: learnship-session-state.js ---
+  if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+  const hasSessionHook = settings.hooks.SessionStart.some(entry =>
+    entry.hooks && entry.hooks.some(h => h.command && h.command.includes('learnship-session-state'))
+  );
+  if (!hasSessionHook && fs.existsSync(path.join(hooksDest, 'learnship-session-state.js'))) {
+    settings.hooks.SessionStart.push({
+      hooks: [{ type: 'command', command: buildCmd('learnship-session-state.js') }]
+    });
+  }
+
+  // --- PostToolUse: learnship-context-monitor.js ---
+  if (!settings.hooks[postToolEvent]) settings.hooks[postToolEvent] = [];
+  const hasContextHook = settings.hooks[postToolEvent].some(entry =>
+    entry.hooks && entry.hooks.some(h => h.command && h.command.includes('learnship-context-monitor'))
+  );
+  if (!hasContextHook && fs.existsSync(path.join(hooksDest, 'learnship-context-monitor.js'))) {
+    settings.hooks[postToolEvent].push({
+      matcher: 'Bash|Edit|Write|MultiEdit',
+      hooks: [{ type: 'command', command: buildCmd('learnship-context-monitor.js'), timeout: 10 }]
+    });
+  }
+
+  // --- PreToolUse: learnship-prompt-guard.js ---
+  if (!settings.hooks[preToolEvent]) settings.hooks[preToolEvent] = [];
+  const hasPromptGuard = settings.hooks[preToolEvent].some(entry =>
+    entry.hooks && entry.hooks.some(h => h.command && h.command.includes('learnship-prompt-guard'))
+  );
+  if (!hasPromptGuard && fs.existsSync(path.join(hooksDest, 'learnship-prompt-guard.js'))) {
+    settings.hooks[preToolEvent].push({
+      matcher: 'Write|Edit',
+      hooks: [{ type: 'command', command: buildCmd('learnship-prompt-guard.js'), timeout: 5 }]
+    });
+  }
+
+  // --- statusLine: learnship-statusline.js ---
+  if (!settings.statusLine && fs.existsSync(path.join(hooksDest, 'learnship-statusline.js'))) {
+    settings.statusLine = {
+      type: 'command',
+      command: buildCmd('learnship-statusline.js')
+    };
+  }
+
+  writeSettings(settingsPath, settings);
+  return copied;
+}
+
+/**
+ * Remove learnship hooks from settings.json and delete hook files.
+ */
+function uninstallClaudeHooks(targetDir) {
+  const settingsPath = path.join(targetDir, 'settings.json');
+  if (fs.existsSync(settingsPath)) {
+    try {
+      const settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+      let modified = false;
+
+      // Remove learnship entries from hook arrays
+      for (const event of ['SessionStart', 'PostToolUse', 'AfterTool', 'PreToolUse', 'BeforeTool']) {
+        if (Array.isArray(settings.hooks?.[event])) {
+          const before = settings.hooks[event].length;
+          settings.hooks[event] = settings.hooks[event].filter(entry =>
+            !entry.hooks || !entry.hooks.some(h => h.command && h.command.includes('learnship-'))
+          );
+          if (settings.hooks[event].length !== before) modified = true;
+          if (settings.hooks[event].length === 0) delete settings.hooks[event];
+        }
+      }
+
+      // Remove statusLine if it's ours
+      if (settings.statusLine?.command?.includes('learnship-')) {
+        delete settings.statusLine;
+        modified = true;
+      }
+
+      // Clean empty hooks object
+      if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+      if (modified) {
+        writeSettings(settingsPath, settings);
+        console.log(`  ${green}✓${reset} Removed learnship hooks from settings.json`);
+      }
+    } catch (e) { /* ignore parse errors */ }
+  }
+
+  // Remove hook files
+  const hooksDir = path.join(targetDir, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    let n = 0;
+    for (const file of LEARNSHIP_MANAGED_HOOKS) {
+      const fp = path.join(hooksDir, file);
+      if (fs.existsSync(fp)) { fs.unlinkSync(fp); n++; }
+    }
+    if (n > 0) console.log(`  ${green}✓${reset} Removed ${n} learnship hook files`);
+  }
+
+  // Remove package.json if it's our minimal one
+  const pkgJsonPath = path.join(targetDir, 'package.json');
+  if (fs.existsSync(pkgJsonPath)) {
+    try {
+      const content = fs.readFileSync(pkgJsonPath, 'utf8').trim();
+      if (content === '{"type":"commonjs"}') {
+        fs.unlinkSync(pkgJsonPath);
+      }
+    } catch (e) { /* ignore */ }
+  }
+}
+
+// ─── File manifest ────────────────────────────────────────────────────────
+
+const crypto = require('crypto');
+
+function fileHash(filePath) {
+  const content = fs.readFileSync(filePath);
+  return crypto.createHash('sha256').update(content).digest('hex');
+}
+
+/**
+ * Generate install manifest with SHA-256 hashes for all installed files.
+ */
+function generateManifest(targetDir) {
+  const manifest = {
+    version: pkg.version,
+    timestamp: new Date().toISOString(),
+    files: {}
+  };
+
+  function scanDir(dir, prefix) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const full = path.join(dir, entry.name);
+      const rel = prefix ? prefix + '/' + entry.name : entry.name;
+      if (entry.isDirectory()) {
+        scanDir(full, rel);
+      } else {
+        manifest.files[rel] = fileHash(full);
+      }
+    }
+  }
+
+  // Scan learnship/ payload
+  const learnshipDir = path.join(targetDir, 'learnship');
+  if (fs.existsSync(learnshipDir)) scanDir(learnshipDir, 'learnship');
+
+  // Scan hooks/
+  const hooksDir = path.join(targetDir, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    for (const file of fs.readdirSync(hooksDir)) {
+      if (file.startsWith('learnship-')) {
+        manifest.files['hooks/' + file] = fileHash(path.join(hooksDir, file));
+      }
+    }
+  }
+
+  fs.writeFileSync(path.join(targetDir, 'learnship-file-manifest.json'), JSON.stringify(manifest, null, 2));
+  return manifest;
+}
+
+/**
+ * Detect user-modified files by comparing against install manifest.
+ * Backs up modified files to learnship-local-patches/.
+ */
+function saveLocalPatches(targetDir) {
+  const manifestPath = path.join(targetDir, 'learnship-file-manifest.json');
+  if (!fs.existsSync(manifestPath)) return [];
+
+  let manifest;
+  try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8')); } catch { return []; }
+
+  const patchesDir = path.join(targetDir, 'learnship-local-patches');
+  const modified = [];
+
+  for (const [relPath, originalHash] of Object.entries(manifest.files || {})) {
+    const fullPath = path.join(targetDir, relPath);
+    if (!fs.existsSync(fullPath)) continue;
+    const currentHash = fileHash(fullPath);
+    if (currentHash !== originalHash) {
+      const backupPath = path.join(patchesDir, relPath);
+      fs.mkdirSync(path.dirname(backupPath), { recursive: true });
+      fs.copyFileSync(fullPath, backupPath);
+      modified.push(relPath);
+    }
+  }
+
+  if (modified.length > 0) {
+    const meta = {
+      backed_up_at: new Date().toISOString(),
+      from_version: manifest.version,
+      files: modified
+    };
+    fs.writeFileSync(path.join(patchesDir, 'backup-meta.json'), JSON.stringify(meta, null, 2));
+    console.log(`\n  ${yellow}i${reset}  Found ${modified.length} locally modified learnship file(s) — backed up to learnship-local-patches/`);
+    for (const f of modified.slice(0, 5)) console.log(`     ${dim}${f}${reset}`);
+    if (modified.length > 5) console.log(`     ${dim}... and ${modified.length - 5} more${reset}`);
+  }
+  return modified;
+}
+
 // ─── Main install function ─────────────────────────────────────────────────
 function install(platform, isGlobal) {
   // Cursor installs via the marketplace plugin, not this CLI.
@@ -1100,7 +1373,7 @@ function install(platform, isGlobal) {
   }
 
   const src = path.join(__dirname, '..');
-  const targetDir = isGlobal ? getGlobalDir(platform) : path.join(process.cwd(), getDirName(platform));
+  const targetDir = targetOverride || (isGlobal ? getGlobalDir(platform) : path.join(process.cwd(), getDirName(platform)));
   const pathPrefix = `${targetDir.replace(/\\/g, '/')}/learnship/`;
   const label = getPlatformLabel(platform);
   const locationLabel = targetDir.replace(os.homedir(), '~');
@@ -1109,6 +1382,9 @@ function install(platform, isGlobal) {
 
   fs.mkdirSync(targetDir, { recursive: true });
 
+  // Save locally modified files before overwriting
+  saveLocalPatches(targetDir);
+
   const learnshipSrc = path.join(src, 'learnship');
   const commandsSrc  = path.join(src, 'commands', 'learnship');
   const agentsSrc    = path.join(src, 'agents');
@@ -1200,6 +1476,9 @@ function install(platform, isGlobal) {
     } else {
       failures.push('skills/');
     }
+    // Install native Claude Code hooks (settings.json + hook files)
+    const hCount = installClaudeHooks(targetDir, isGlobal, 'claude');
+    if (hCount > 0) console.log(`  ${green}✓${reset} Installed ${hCount} hooks + settings.json (statusline, context monitor, prompt guard, session state)`);
   } else if (platform === 'opencode') {
     const count = installOpencodeCommands(commandsSrc, targetDir, pathPrefix);
     console.log(`  ${green}✓${reset} Installed ${count} commands to command/ (flat)`);
@@ -1222,6 +1501,9 @@ function install(platform, isGlobal) {
       writeSettings(settingsPath, settings);
       console.log(`  ${green}✓${reset} Enabled experimental.enableAgents in settings.json`);
     }
+    // Install native Gemini hooks (settings.json + hook files)
+    const hCount = installClaudeHooks(targetDir, isGlobal, 'gemini');
+    if (hCount > 0) console.log(`  ${green}✓${reset} Installed ${hCount} hooks + settings.json (statusline, context monitor, prompt guard, session state)`);
   } else if (platform === 'codex') {
     const count = installCodexSkills(commandsSrc, targetDir, pathPrefix);
     console.log(`  ${green}✓${reset} Installed ${count} skills to skills/`);
@@ -1237,7 +1519,11 @@ function install(platform, isGlobal) {
   // 4. Scan for leaked .claude paths
   scanForLeakedPaths(targetDir, platform);
 
-  // 5. Post-install tips
+  // 5. Generate file manifest for upgrade safety
+  generateManifest(targetDir);
+  console.log(`  ${green}✓${reset} Generated learnship-file-manifest.json`);
+
+  // 6. Post-install tips
   const firstCmd = platform === 'windsurf' ? '/ls' :
                    platform === 'claude'   ? '/learnship:ls' :
                    platform === 'opencode' ? '/learnship-ls' :
@@ -1251,7 +1537,7 @@ function install(platform, isGlobal) {
 
 // ─── Uninstall function ────────────────────────────────────────────────────
 function uninstall(platform, isGlobal) {
-  const targetDir = isGlobal ? getGlobalDir(platform) : path.join(process.cwd(), getDirName(platform));
+  const targetDir = targetOverride || (isGlobal ? getGlobalDir(platform) : path.join(process.cwd(), getDirName(platform)));
   const label = getPlatformLabel(platform);
   const locationLabel = targetDir.replace(os.homedir(), '~');
   console.log(`\n  Uninstalling learnship from ${cyan}${label}${reset} at ${cyan}${locationLabel}${reset}\n`);
@@ -1374,6 +1660,18 @@ function uninstall(platform, isGlobal) {
     if (n > 0) { removed++; console.log(`  ${green}✓${reset} Removed ${n} learnship agent files`); }
   }
 
+  // 4. Remove hooks and settings.json entries (Claude Code / Gemini)
+  if (platform === 'claude' || platform === 'gemini') {
+    uninstallClaudeHooks(targetDir);
+    removed++;
+  }
+
+  // 5. Remove file manifest and local patches
+  const manifestPath = path.join(targetDir, 'learnship-file-manifest.json');
+  if (fs.existsSync(manifestPath)) { fs.unlinkSync(manifestPath); removed++; console.log(`  ${green}✓${reset} Removed learnship-file-manifest.json`); }
+  const patchesDir = path.join(targetDir, 'learnship-local-patches');
+  if (fs.existsSync(patchesDir)) { fs.rmSync(patchesDir, { recursive: true }); removed++; console.log(`  ${green}✓${reset} Removed learnship-local-patches/`); }
+
   if (removed === 0) console.log(`  ${yellow}⚠${reset} No learnship files found.`);
   else console.log(`\n  ${green}Done!${reset} learnship uninstalled from ${label}. Your other files and settings were preserved.`);
 }
@@ -1455,6 +1753,10 @@ if (process.env.LEARNSHIP_TEST_MODE) {
     rewriteNewProject,
     rewriteAgentsMd,
     installClaudeSkills,
+    installClaudeHooks,
+    uninstallClaudeHooks,
+    generateManifest,
+    saveLocalPatches,
     toHomePrefix,
     LEARNSHIP_CODEX_MARKER,
     CODEX_AGENT_SANDBOX,

package/commands/learnship/diagnose-issues.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Bash
   - Write
   - Task
+  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/discuss-phase.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Bash
   - Write
   - Task
+  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/ideate.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Bash
   - Write
   - Task
+  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/list-phase-assumptions.md

@@ -5,6 +5,7 @@ argument-hint: "[N]"
 allowed-tools:
   - Read
   - Bash
+  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/quick.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Bash
   - Write
   - Task
+  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/research-phase.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Bash
   - Write
   - Task
+  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/secure-phase.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Bash
   - Write
   - Task
+  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/validate-phase.md

@@ -6,6 +6,8 @@ allowed-tools:
   - Read
   - Bash
   - Write
+  - Task
+  - AskUserQuestion
 ---
 
 <execution_context>

package/commands/learnship/verify-work.md

@@ -7,6 +7,7 @@ allowed-tools:
   - Bash
   - Write
   - Task
+  - AskUserQuestion
 ---
 
 <execution_context>

package/cursor-rules/learnship.mdc

@@ -47,7 +47,7 @@ When the user runs `/new-project`, execute these **9 mandatory steps in order**.
 
 2. **Research decision = always ask the user.** After PROJECT.md is confirmed, ask: "Do you want me to research the domain ecosystem first?" and WAIT for the user's reply. You are FORBIDDEN from deciding this yourself — even if the tech stack is defined in PROJECT.md, the domain seems trivial, or the user gave detailed answers. Never say "no research needed" or "skipping research" on your own.
 
-3. **Research = 5 separate files.** If the user chooses research, create exactly 5 files in `.planning/research/`: `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`, `SUMMARY.md`. Do NOT write a single monolithic research file. Run the `node -e` verification command from the workflow — it must print `RESEARCH VERIFIED OK` before proceeding.
+3. **Research = WRITE 5 FILES TO DISK.** "Research" means creating files on the filesystem, not thinking or browsing. If the user chooses research, write exactly 5 files to `.planning/research/`: `STACK.md`, `FEATURES.md`, `ARCHITECTURE.md`, `PITFALLS.md`, `SUMMARY.md`. Do NOT do web searches or domain analysis and then say "I have enough research data" without writing the files — that is a workflow failure. Run the `node -e` verification command — it must print `RESEARCH VERIFIED OK` before proceeding to requirements.
 
 4. **After Step 7 (roadmap approved):** Do NOT display the done banner or suggest next steps. Generate AGENTS.md (Step 8) first.
 
@@ -141,13 +141,23 @@ Available actions: `adapt`, `animate`, `arrange`, `audit`, `bolder`, `clarify`,
 
 ## Parallel Execution
 
-Cursor supports real parallel subagents. During `/new-project` setup (Group D), ask:
+Cursor supports real parallel subagents. During `/new-project` Step 2 configuration, one of the questions asks about parallel execution:
 
-"Do you want to enable parallel subagent execution?"
 - **No** (recommended default) — Plans execute sequentially, one at a time. Safer, easier to follow.
 - **Yes** — Each independent plan in a wave gets its own dedicated subagent with a fresh context budget. Faster, but uses more tokens.
 
-Set `"parallelization": true|false` in `.planning/config.json` based on the user's choice.
+Set `"parallelization": { "enabled": true|false }` in `.planning/config.json` based on the user's choice.
+
+## Structured Questions
+
+When workflows include `AskUserQuestion()` blocks, **Cursor has no native structured question tool**. Present each question as a numbered text list with descriptions and ask the user to reply with their choice number or label. Example:
+
+```
+**Working Style**
+How do you want to work?
+1. YOLO (Recommended) — Auto-approve steps, just execute
+2. Interactive — Confirm at each step
+```
 
 ## Learning Mode
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "learnship",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Agentic engineering done right — 57 structured workflows, persistent memory across sessions, integrated learning partner, and impeccable UI design system.",
   "author": "Favio Vazquez",
   "homepage": "https://faviovazquez.github.io/learnship/",

package/hooks/learnship-context-monitor.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+// learnship-hook-version: 2.2.0
+// Context Monitor — PostToolUse hook
+// Reads context metrics from the statusline bridge file and injects
+// warnings when context usage is high. Makes the AGENT aware of
+// context limits (the statusline only shows the user).
+//
+// Thresholds:
+//   WARNING  (remaining <= 35%): Agent should wrap up current task
+//   CRITICAL (remaining <= 25%): Agent should stop and save state
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const WARNING_THRESHOLD = 35;
+const CRITICAL_THRESHOLD = 25;
+const STALE_SECONDS = 60;
+const DEBOUNCE_CALLS = 5;
+
+let input = '';
+const stdinTimeout = setTimeout(() => process.exit(0), 10000);
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  clearTimeout(stdinTimeout);
+  try {
+    const data = JSON.parse(input);
+    const sessionId = data.session_id;
+
+    if (!sessionId) process.exit(0);
+    if (/[/\\]|\.\./.test(sessionId)) process.exit(0);
+
+    // Check if context warnings are disabled via config
+    const cwd = data.cwd || process.cwd();
+    const planningDir = path.join(cwd, '.planning');
+    if (fs.existsSync(planningDir)) {
+      try {
+        const configPath = path.join(planningDir, 'config.json');
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (config.hooks?.context_warnings === false) process.exit(0);
+      } catch (e) {
+        // Ignore config read errors
+      }
+    }
+
+    const tmpDir = os.tmpdir();
+    const metricsPath = path.join(tmpDir, `learnship-ctx-${sessionId}.json`);
+
+    if (!fs.existsSync(metricsPath)) process.exit(0);
+
+    const metrics = JSON.parse(fs.readFileSync(metricsPath, 'utf8'));
+    const now = Math.floor(Date.now() / 1000);
+
+    if (metrics.timestamp && (now - metrics.timestamp) > STALE_SECONDS) process.exit(0);
+
+    const remaining = metrics.remaining_percentage;
+    const usedPct = metrics.used_pct;
+
+    if (remaining > WARNING_THRESHOLD) process.exit(0);
+
+    // Debounce
+    const warnPath = path.join(tmpDir, `learnship-ctx-${sessionId}-warned.json`);
+    let warnData = { callsSinceWarn: 0, lastLevel: null };
+    let firstWarn = true;
+
+    if (fs.existsSync(warnPath)) {
+      try {
+        warnData = JSON.parse(fs.readFileSync(warnPath, 'utf8'));
+        firstWarn = false;
+      } catch (e) {}
+    }
+
+    warnData.callsSinceWarn = (warnData.callsSinceWarn || 0) + 1;
+
+    const isCritical = remaining <= CRITICAL_THRESHOLD;
+    const currentLevel = isCritical ? 'critical' : 'warning';
+    const severityEscalated = currentLevel === 'critical' && warnData.lastLevel === 'warning';
+
+    if (!firstWarn && warnData.callsSinceWarn < DEBOUNCE_CALLS && !severityEscalated) {
+      fs.writeFileSync(warnPath, JSON.stringify(warnData));
+      process.exit(0);
+    }
+
+    warnData.callsSinceWarn = 0;
+    warnData.lastLevel = currentLevel;
+    fs.writeFileSync(warnPath, JSON.stringify(warnData));
+
+    const isProjectActive = fs.existsSync(path.join(cwd, '.planning', 'STATE.md'));
+
+    let message;
+    if (isCritical) {
+      message = isProjectActive
+        ? `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Do NOT start new complex work. ' +
+          'Inform the user so they can run /pause-work at the next natural stopping point.'
+        : `CONTEXT CRITICAL: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is nearly exhausted. Inform the user that context is low and ask how they want to proceed.';
+    } else {
+      message = isProjectActive
+        ? `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Context is getting limited. Avoid starting new complex work. If not between ' +
+          'defined plan steps, inform the user so they can prepare to pause.'
+        : `CONTEXT WARNING: Usage at ${usedPct}%. Remaining: ${remaining}%. ` +
+          'Be aware that context is getting limited. Avoid unnecessary exploration or starting new complex work.';
+    }
+
+    const hookEventName = process.env.GEMINI_API_KEY ? 'AfterTool' : 'PostToolUse';
+    const output = {
+      hookSpecificOutput: {
+        hookEventName,
+        additionalContext: message
+      }
+    };
+
+    process.stdout.write(JSON.stringify(output));
+  } catch (e) {
+    process.exit(0);
+  }
+});