claude-dev-env 1.17.1 → 1.17.5

package/bin/install.mjs

@@ -5,14 +5,77 @@ import { join, dirname, resolve, relative } from 'node:path';
 import { homedir } from 'node:os';
 import { execSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 
 const CLAUDE_HOME = join(homedir(), '.claude');
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const MANIFEST_FILE = join(CLAUDE_HOME, '.claude-dev-env-manifest.json');
 const PACKAGE_NAME = 'claude-dev-env';
+const packageRequire = createRequire(import.meta.url);
 
 const CONTENT_DIRECTORIES = ['rules', 'docs', 'commands', 'agents'];
 
+function resolveDependencyPackageRoot(dependencyPackageName) {
+    const dependencyPackageJsonPath = packageRequire.resolve(
+        `${dependencyPackageName}/package.json`
+    );
+    return dirname(dependencyPackageJsonPath);
+}
+
+function discoverDependencyGroups() {
+    const ownPackageJsonPath = join(PACKAGE_ROOT, 'package.json');
+    const ownPackageJson = JSON.parse(readFileSync(ownPackageJsonPath, 'utf8'));
+    const dependencies = ownPackageJson.dependencies || {};
+    const discoveredGroups = {};
+    for (const dependencyName of Object.keys(dependencies)) {
+        let dependencyRoot;
+        try {
+            dependencyRoot = resolveDependencyPackageRoot(dependencyName);
+        } catch {
+            console.error(`  WARNING: Could not resolve dependency ${dependencyName}, skipping`);
+            continue;
+        }
+        const dependencyPackageJson = JSON.parse(
+            readFileSync(join(dependencyRoot, 'package.json'), 'utf8')
+        );
+        const groupName = dependencyPackageJson.claudeDevEnv?.groupName
+            || dependencyName.replace(/^@[^/]+\//, '');
+        const group = {
+            description: dependencyPackageJson.description || dependencyName,
+            packageRoot: dependencyRoot,
+        };
+        const skillsDirectory = join(dependencyRoot, 'skills');
+        if (existsSync(skillsDirectory)) {
+            group.skills = readdirSync(skillsDirectory, { withFileTypes: true })
+                .filter(entry => entry.isDirectory())
+                .map(entry => entry.name);
+        }
+        const hooksDirectory = join(dependencyRoot, 'hooks');
+        if (existsSync(hooksDirectory)) {
+            const hookFiles = collectFiles(hooksDirectory)
+                .filter(file => !file.endsWith('hooks.json'))
+                .filter(file => {
+                    const baseName = file.replace(/\\/g, '/').split('/').pop();
+                    return !baseName.startsWith('test_');
+                })
+                .map(file => relative(hooksDirectory, file).replace(/\\/g, '/'));
+            if (hookFiles.length > 0) {
+                group.includeHookFiles = hookFiles;
+            }
+        }
+        const rulesDirectory = join(dependencyRoot, 'rules');
+        if (existsSync(rulesDirectory)) {
+            const ruleFiles = readdirSync(rulesDirectory)
+                .filter(file => file.endsWith('.md'));
+            if (ruleFiles.length > 0) {
+                group.includeRules = ruleFiles;
+            }
+        }
+        discoveredGroups[groupName] = group;
+    }
+    return discoveredGroups;
+}
+
 const INSTALL_GROUPS = {
     core: {
         description: 'Development standards, hooks, agents, commands',
@@ -25,17 +88,6 @@ const INSTALL_GROUPS = {
         includeDirectories: ['rules', 'docs', 'commands', 'agents'],
         includeAllHooks: true,
     },
-    prompts: {
-        description: 'Prompt engineering tools',
-        skills: ['prompt-generator', 'agent-prompt'],
-        includeHookFiles: [
-            'blocking/prompt_workflow_gate_config.py',
-            'blocking/prompt_workflow_gate_core.py',
-            'blocking/prompt-workflow-stop-guard.py',
-            'HOOK_SPECS_PROMPT_WORKFLOW.md',
-        ],
-        includeRules: ['prompt-workflow-context-controls.md'],
-    },
     journal: {
         description: 'Session logging and memory',
         skills: ['dream', 'session-log', 'session-tidy'],
@@ -44,6 +96,7 @@ const INSTALL_GROUPS = {
         description: 'Deep research and citation tools',
         skills: ['deep-research', 'research-mode'],
     },
+    ...discoverDependencyGroups(),
 };
 
 function detectPython() {
@@ -99,8 +152,8 @@ function copyTree(sourceBase, destBase) {
     return stats;
 }
 
-function mergeHooks(pythonCommand) {
-    const hooksJsonPath = join(PACKAGE_ROOT, 'hooks', 'hooks.json');
+function mergeHooks(hooksSourceRoot, pythonCommand) {
+    const hooksJsonPath = join(hooksSourceRoot, 'hooks', 'hooks.json');
     if (!existsSync(hooksJsonPath)) return 0;
     const hooksConfig = JSON.parse(readFileSync(hooksJsonPath, 'utf8'));
     const settingsPath = join(CLAUDE_HOME, 'settings.json');
@@ -163,58 +216,85 @@ function install(selectedGroups) {
     console.log(`  Python: ${pythonCommand}`);
     mkdirSync(CLAUDE_HOME, { recursive: true });
 
+    const activeGroups = selectedGroups
+        ? selectedGroups.map(groupName => ({ groupName, ...INSTALL_GROUPS[groupName] }))
+        : Object.entries(INSTALL_GROUPS).map(([groupName, group]) => ({ groupName, ...group }));
+
     const allowedSkills = selectedGroups
-        ? new Set(selectedGroups.flatMap(groupName => INSTALL_GROUPS[groupName].skills || []))
+        ? new Set(activeGroups.flatMap(group => group.skills || []))
         : null;
     const allowedDirectories = selectedGroups
-        ? new Set(selectedGroups.flatMap(groupName => INSTALL_GROUPS[groupName].includeDirectories || []))
+        ? new Set(activeGroups.flatMap(group => group.includeDirectories || []))
         : null;
     const shouldInstallAllHooks = selectedGroups
-        ? selectedGroups.some(groupName => INSTALL_GROUPS[groupName].includeAllHooks)
+        ? activeGroups.some(group => group.includeAllHooks)
         : true;
     const allowedHookFiles = selectedGroups
-        ? new Set(selectedGroups.flatMap(groupName => INSTALL_GROUPS[groupName].includeHookFiles || []))
+        ? new Set(activeGroups.flatMap(group => group.includeHookFiles || []))
         : null;
     const allowedRules = selectedGroups
-        ? new Set(selectedGroups.flatMap(groupName => INSTALL_GROUPS[groupName].includeRules || []))
+        ? new Set(activeGroups.flatMap(group => group.includeRules || []))
         : null;
 
+    const dependencyRoots = [...new Set(
+        activeGroups.filter(group => group.packageRoot).map(group => group.packageRoot)
+    )];
+    const builtinGroupsActive = activeGroups.some(group => !group.packageRoot);
+    const allSourceRoots = [
+        ...(builtinGroupsActive ? [PACKAGE_ROOT] : []),
+        ...dependencyRoots,
+    ];
+
     const allInstalledFiles = [];
     const summary = {};
     for (const directory of CONTENT_DIRECTORIES) {
         const hasFullAccess = !allowedDirectories || allowedDirectories.has(directory);
         const hasPartialRules = directory === 'rules' && allowedRules && allowedRules.size > 0;
         if (!hasFullAccess && !hasPartialRules) continue;
-        const sourceDir = join(PACKAGE_ROOT, directory);
-        if (!existsSync(sourceDir)) continue;
-        const destDir = join(CLAUDE_HOME, directory);
-        if (hasFullAccess) {
-            const stats = copyTree(sourceDir, destDir);
-            summary[directory] = stats;
-            allInstalledFiles.push(...stats.paths);
-        } else if (hasPartialRules) {
-            let rulesCreated = 0;
-            let rulesUpdated = 0;
-            for (const ruleFile of allowedRules) {
-                const sourcePath = join(sourceDir, ruleFile);
-                if (!existsSync(sourcePath)) continue;
-                const destPath = join(destDir, ruleFile);
-                mkdirSync(dirname(destPath), { recursive: true });
-                const existed = existsSync(destPath);
-                copyFileSync(sourcePath, destPath);
-                allInstalledFiles.push(destPath);
-                if (existed) { rulesUpdated++; } else { rulesCreated++; }
-                console.log(`  ${existed ? '\u21bb' : '\u2713'} ${join(directory, ruleFile)} (${existed ? 'updated' : 'new'})`);
+        for (const sourceRoot of allSourceRoots) {
+            const sourceDir = join(sourceRoot, directory);
+            if (!existsSync(sourceDir)) continue;
+            const destDir = join(CLAUDE_HOME, directory);
+            if (hasFullAccess) {
+                const stats = copyTree(sourceDir, destDir);
+                if (!summary[directory]) {
+                    summary[directory] = stats;
+                } else {
+                    summary[directory].created += stats.created;
+                    summary[directory].updated += stats.updated;
+                    summary[directory].paths.push(...stats.paths);
+                }
+                allInstalledFiles.push(...stats.paths);
+            } else if (hasPartialRules) {
+                let rulesCreated = 0;
+                let rulesUpdated = 0;
+                for (const ruleFile of allowedRules) {
+                    const sourcePath = join(sourceDir, ruleFile);
+                    if (!existsSync(sourcePath)) continue;
+                    const destPath = join(destDir, ruleFile);
+                    mkdirSync(dirname(destPath), { recursive: true });
+                    const existed = existsSync(destPath);
+                    copyFileSync(sourcePath, destPath);
+                    allInstalledFiles.push(destPath);
+                    if (existed) { rulesUpdated++; } else { rulesCreated++; }
+                    console.log(`  ${existed ? '\u21bb' : '\u2713'} ${join(directory, ruleFile)} (${existed ? 'updated' : 'new'})`);
+                }
+                if (!summary[directory]) {
+                    summary[directory] = { created: rulesCreated, updated: rulesUpdated, paths: [] };
+                } else {
+                    summary[directory].created += rulesCreated;
+                    summary[directory].updated += rulesUpdated;
+                }
             }
-            summary[directory] = { created: rulesCreated, updated: rulesUpdated, paths: [] };
         }
     }
-    const skillsSource = join(PACKAGE_ROOT, 'skills');
-    if (existsSync(skillsSource)) {
+    let skillsCreated = 0;
+    let skillsUpdated = 0;
+    const skillPaths = [];
+    for (const sourceRoot of allSourceRoots) {
+        const skillsSource = join(sourceRoot, 'skills');
+        if (!existsSync(skillsSource)) continue;
         const skillDirs = readdirSync(skillsSource, { withFileTypes: true }).filter(entry => entry.isDirectory());
-        let skillsCreated = 0;
-        let skillsUpdated = 0;
-        const skillPaths = [];
         for (const skillDir of skillDirs) {
             if (allowedSkills && !allowedSkills.has(skillDir.name)) continue;
             const stats = copyTree(join(skillsSource, skillDir.name), join(CLAUDE_HOME, 'skills', skillDir.name));
@@ -222,13 +302,17 @@ function install(selectedGroups) {
             skillsUpdated += stats.updated;
             skillPaths.push(...stats.paths);
         }
-        summary.skills = { created: skillsCreated, updated: skillsUpdated, paths: skillPaths };
-        allInstalledFiles.push(...skillPaths);
     }
+    summary.skills = { created: skillsCreated, updated: skillsUpdated, paths: skillPaths };
+    allInstalledFiles.push(...skillPaths);
     const shouldInstallAnyHooks = shouldInstallAllHooks || (allowedHookFiles && allowedHookFiles.size > 0);
     if (shouldInstallAnyHooks) {
-        const hooksSource = join(PACKAGE_ROOT, 'hooks');
-        if (existsSync(hooksSource)) {
+        let totalHooksCreated = 0;
+        let totalHooksUpdated = 0;
+        let totalHookGroups = 0;
+        for (const sourceRoot of allSourceRoots) {
+            const hooksSource = join(sourceRoot, 'hooks');
+            if (!existsSync(hooksSource)) continue;
             const hooksDestination = join(CLAUDE_HOME, 'hooks');
             const filesToCopy = collectFiles(hooksSource)
                 .filter(file => !file.endsWith('hooks.json'))
@@ -237,8 +321,6 @@ function install(selectedGroups) {
                     const relativePath = relative(hooksSource, file).replace(/\\/g, '/');
                     return allowedHookFiles.has(relativePath);
                 });
-            let hooksCreated = 0;
-            let hooksUpdated = 0;
             for (const sourceFile of filesToCopy) {
                 const relativePath = relative(hooksSource, sourceFile);
                 const destFile = join(hooksDestination, relativePath);
@@ -246,14 +328,15 @@ function install(selectedGroups) {
                 const existed = existsSync(destFile);
                 copyFileSync(sourceFile, destFile);
                 allInstalledFiles.push(destFile);
-                if (existed) { hooksUpdated++; } else { hooksCreated++; }
+                if (existed) { totalHooksUpdated++; } else { totalHooksCreated++; }
             }
-            summary.hookFiles = { created: hooksCreated, updated: hooksUpdated };
-            console.log(`  Hook files: ${hooksCreated} new, ${hooksUpdated} updated`);
-            const groupCount = mergeHooks(pythonCommand);
-            summary.hookGroups = groupCount;
-            console.log(`  Hook groups: ${groupCount} merged into settings.json`);
+            const groupCount = mergeHooks(sourceRoot, pythonCommand);
+            totalHookGroups += groupCount;
         }
+        summary.hookFiles = { created: totalHooksCreated, updated: totalHooksUpdated };
+        console.log(`  Hook files: ${totalHooksCreated} new, ${totalHooksUpdated} updated`);
+        summary.hookGroups = totalHookGroups;
+        console.log(`  Hook groups: ${totalHookGroups} merged into settings.json`);
     }
     writeManifest(allInstalledFiles);
     console.log(`\nInstalled ${PACKAGE_NAME}:`);
@@ -330,14 +413,14 @@ Usage:
   npx ${PACKAGE_NAME} --help       Show this help
 
 Groups:
-  core      Development standards, hooks, agents, commands
-  prompts   Prompt engineering tools
-  journal   Session logging and memory
-  research  Deep research and citation tools
+  core              Development standards, hooks, agents, commands
+  prompt-generator  Prompt engineering tools
+  journal           Session logging and memory
+  research          Deep research and citation tools
 
 Examples:
-  npx ${PACKAGE_NAME} --only prompts
-  npx ${PACKAGE_NAME} --only prompts,research
+  npx ${PACKAGE_NAME} --only prompt-generator
+  npx ${PACKAGE_NAME} --only prompt-generator,research
 
 Install location: ~/.claude/
 `);

package/hooks/HOOK_SPECS_PROMPT_WORKFLOW.md

@@ -6,18 +6,20 @@ Deterministic runtime gates for prompt workflows.
 
 The former `agent-execution-intent-gate.py` hook is **removed**. Native Agent/Task launches do not carry stable custom metadata; enforcing scope text on every spawn blocked legitimate `/agent-prompt` and refinement delegations. Scope and checklist rules remain enforced by the Stop guard when a prompt-workflow response is detected.
 
-## Gate: Leakage + Checklist + Scope (Stop)
+## Gate: Leakage + Checklist + Scope (file-based validation loop)
 
-- Hook: `hooks/blocking/prompt-workflow-stop-guard.py`
-- Event: `Stop`
-- Fail condition:
+- Validator: `hooks/blocking/prompt_workflow_validate.py`
+- Invocation: CLI against `data/prompts/.draft-prompt.xml` (exit 0 allowed, exit 2 blocked)
+- Fail conditions:
   - Raw internal refinement object appears in assistant output without explicit debug intent
   - Prompt-workflow response detected but deterministic checklist container is missing
   - Prompt-workflow response detected and required deterministic checklist rows are missing
   - Prompt-workflow response detected and required scope anchors are missing
   - Prompt-workflow response detected and runtime context-control signals are missing
   - Scope-bound text uses banned ambiguous scope terms
-- Action: `block` with correction reason.
+  - Banned negative keywords found inside fenced XML artifact
+  - Fenced XML artifact missing required sections
+- Enforcement: The drafting subagent writes the draft file, runs the validator, reads stderr violations (each prefixed with `[reason_code]`), edits the file, and re-runs until exit 0.
 
 ## Required Scope Anchors
 
@@ -49,7 +51,7 @@ The former `agent-execution-intent-gate.py` hook is **removed**. Native Agent/Ta
 - `base_minimal_instruction_layer: true`
 - `on_demand_skill_loading: true`
 
-These two signals are runtime-checked by the Stop guard whenever a prompt-workflow response is detected.
+These two signals are checked by the validator CLI whenever a prompt-workflow response is detected.
 
 ## Deterministic Boundary
 

package/hooks/blocking/content-search-to-zoekt-redirector.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""PreToolUse hook: deny Grep, Search, and shell search in indexed trees; steer to Zoekt MCP."""
+
+import json
+import os
+import sys
+
+from content_search_zoekt_bash_block_reason import block_reason_for_bash_command
+from content_search_zoekt_block_payload import build_block_payload
+from content_search_zoekt_indexed_paths import is_in_indexed_repo, is_specific_file
+from content_search_zoekt_redirect_guidance import get_zoekt_redirect_guidance
+
+
+def main() -> None:
+    try:
+        input_data = json.load(sys.stdin)
+    except json.JSONDecodeError:
+        sys.exit(0)
+
+    tool_name = input_data.get("tool_name", "")
+    tool_input = input_data.get("tool_input", {})
+
+    content_search_tools = frozenset({"Grep", "Search"})
+    block_reason = None
+
+    if tool_name in content_search_tools:
+        pattern = tool_input.get("pattern", "")
+        path = tool_input.get("path", "")
+
+        if not path:
+            path = os.getcwd()
+
+        if is_specific_file(path):
+            sys.exit(0)
+
+        if is_in_indexed_repo(path):
+            block_reason = f"{tool_name}(pattern: \"{pattern}\", path: \"{path}\")"
+
+    elif tool_name == "Bash":
+        command = tool_input.get("command", "")
+        block_reason = block_reason_for_bash_command(command)
+
+    if block_reason is None:
+        sys.exit(0)
+    short_label = f"blocked {block_reason}; use Zoekt MCP"
+    payload = build_block_payload(
+        brief_label=short_label,
+        permission_decision_reason=get_zoekt_redirect_guidance(),
+    )
+    print(json.dumps(payload))
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/hooks/blocking/content_search_zoekt_bash_block_reason.py

@@ -0,0 +1,25 @@
+"""Match Bash one-liners that act as content search (grep, rg, findstr, etc.)."""
+
+import re
+
+
+def block_reason_for_bash_command(command: str) -> str | None:
+    bash_content_search_patterns = (
+        (re.compile(r"^\s*grep\s", re.IGNORECASE), "grep"),
+        (re.compile(r"^\s*grep$", re.IGNORECASE), "grep"),
+        (re.compile(r"\|\s*grep\s", re.IGNORECASE), "piped grep"),
+        (re.compile(r"\|\s*grep$", re.IGNORECASE), "piped grep"),
+        (re.compile(r"^\s*rg\s", re.IGNORECASE), "ripgrep"),
+        (re.compile(r"^\s*rg$", re.IGNORECASE), "ripgrep"),
+        (re.compile(r"\|\s*rg\s", re.IGNORECASE), "piped ripgrep"),
+        (re.compile(r"^\s*findstr\s", re.IGNORECASE), "findstr"),
+        (re.compile(r"^\s*Select-String", re.IGNORECASE), "PowerShell Select-String"),
+        (re.compile(r"^\s*sls\s", re.IGNORECASE), "PowerShell sls"),
+        (re.compile(r"^\s*ack\s", re.IGNORECASE), "ack"),
+        (re.compile(r"^\s*ag\s", re.IGNORECASE), "silver searcher"),
+        (re.compile(r"^\s*git\s+grep\s", re.IGNORECASE), "git grep"),
+    )
+    for regex, command_name in bash_content_search_patterns:
+        if regex.search(command):
+            return f"Bash({command_name})"
+    return None

package/hooks/blocking/content_search_zoekt_block_payload.py

@@ -0,0 +1,17 @@
+"""JSON shape for Claude Code PreToolUse deny: hookSpecificOutput plus short systemMessage."""
+
+
+def build_block_payload(
+    brief_label: str,
+    permission_decision_reason: str,
+) -> dict:
+    destructive_gate_label_prefix = "[destructive-gate]"
+    return {
+        "hookSpecificOutput": {
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": permission_decision_reason,
+        },
+        "systemMessage": f"{destructive_gate_label_prefix} {brief_label}",
+        "suppressOutput": True,
+    }

package/hooks/blocking/content_search_zoekt_indexed_paths.py

@@ -0,0 +1,24 @@
+"""Normalize paths and test membership under Zoekt-indexed roots (from env, JSON file, or defaults)."""
+
+import re
+
+
+def normalize_path(path: str) -> str:
+    return path.replace("\\", "/").lower()
+
+
+def is_specific_file(path: str) -> bool:
+    file_extension_pattern = re.compile(r"\.\w{1,10}$")
+    return bool(file_extension_pattern.search(path))
+
+
+def is_in_indexed_repo(path: str) -> bool:
+    from content_search_zoekt_indexed_roots_config import indexed_root_prefixes
+
+    norm = normalize_path(path)
+    if not norm.endswith("/"):
+        norm += "/"
+    for prefix in indexed_root_prefixes():
+        if norm.startswith(prefix):
+            return True
+    return False

package/hooks/blocking/content_search_zoekt_indexed_roots_config.py

@@ -0,0 +1,131 @@
+"""Resolve Zoekt-indexed filesystem roots from environment or JSON file (no built-in roots in this package)."""
+
+import json
+import os
+from functools import lru_cache
+from pathlib import Path
+
+from content_search_zoekt_indexed_paths import normalize_path
+
+
+def _environment_variable_indexed_roots() -> str:
+    return "ZOEKT_REDIRECT_INDEXED_ROOTS"
+
+
+def _environment_variable_roots_file() -> str:
+    return "ZOEKT_REDIRECT_INDEXED_ROOTS_FILE"
+
+
+def _json_object_roots_key() -> str:
+    return "roots"
+
+
+def _default_config_relative_parts() -> tuple[str, str]:
+    return (".claude", "zoekt-indexed-roots.json")
+
+
+def _built_in_fallback_roots() -> tuple[str, ...]:
+    return ()
+
+
+def _parse_json_roots_list(raw: str) -> list[str] | None:
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(parsed, list):
+        return None
+    if not all(isinstance(item, str) for item in parsed):
+        return None
+    return list(parsed)
+
+
+def _config_file_path() -> Path:
+    override = os.environ.get(_environment_variable_roots_file())
+    if override is not None and override.strip() != "":
+        return Path(override).expanduser()
+    relative_dot_claude, relative_file_name = _default_config_relative_parts()
+    return Path.home() / relative_dot_claude / relative_file_name
+
+
+def _roots_from_json_file() -> list[str] | None:
+    path = _config_file_path()
+    if not path.is_file():
+        return None
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    try:
+        data = json.loads(text)
+    except json.JSONDecodeError:
+        return None
+    if not isinstance(data, dict):
+        return None
+    roots_key = _json_object_roots_key()
+    roots_value = data.get(roots_key)
+    if roots_value is None:
+        return None
+    if not isinstance(roots_value, list):
+        return None
+    if not all(isinstance(item, str) for item in roots_value):
+        return None
+    return list(roots_value)
+
+
+def _roots_from_environment_variable() -> list[str] | None:
+    variable_name = _environment_variable_indexed_roots()
+    if variable_name not in os.environ:
+        return None
+    raw = os.environ.get(variable_name, "")
+    if raw.strip() == "":
+        return []
+    parsed = _parse_json_roots_list(raw)
+    if parsed is None:
+        return None
+    return parsed
+
+
+def _expand_root_to_prefix_variants(root: str) -> list[str]:
+    trimmed = root.strip()
+    if trimmed == "":
+        return []
+    norm = normalize_path(trimmed)
+    if not norm.endswith("/"):
+        norm = norm + "/"
+    variants = [norm]
+    if len(norm) >= 3 and norm[1] == ":" and norm[0].isalpha() and norm[2] == "/":
+        drive_letter = norm[0]
+        remainder = norm[2:]
+        wsl_prefix = f"/mnt/{drive_letter}{remainder}"
+        if wsl_prefix not in variants:
+            variants.append(wsl_prefix)
+    return variants
+
+
+def _expand_all_roots(raw_roots: list[str]) -> tuple[str, ...]:
+    prefixes: list[str] = []
+    for root in raw_roots:
+        prefixes.extend(_expand_root_to_prefix_variants(root))
+    unique = frozenset(prefixes)
+    return tuple(sorted(unique, key=len, reverse=True))
+
+
+def _raw_roots_resolution_order() -> list[str]:
+    from_env = _roots_from_environment_variable()
+    if from_env is not None:
+        return from_env
+    from_file = _roots_from_json_file()
+    if from_file is not None:
+        return from_file
+    return list(_built_in_fallback_roots())
+
+
+@lru_cache(maxsize=1)
+def indexed_root_prefixes() -> tuple[str, ...]:
+    raw_roots = _raw_roots_resolution_order()
+    return _expand_all_roots(raw_roots)
+
+
+def clear_indexed_root_prefixes_cache() -> None:
+    indexed_root_prefixes.cache_clear()

package/hooks/blocking/content_search_zoekt_redirect_guidance.py

@@ -0,0 +1,19 @@
+"""Zoekt MCP usage and repo-to-disk path mapping for PreToolUse permissionDecisionReason."""
+
+
+def get_zoekt_redirect_guidance() -> str:
+    return (
+        "Use Zoekt MCP instead: mcp__zoekt__search(query=\"your pattern\"). "
+        "Supports regex, 'file:pattern' for file filtering, 'lang:py' for language. "
+        "Also available: mcp__zoekt__search_symbols, mcp__zoekt__find_references, mcp__zoekt__file_content. "
+        "Example: mcp__zoekt__search(query=\"verify_theme_assets file:\\.py$\")\n\n"
+        "INDEX ROOTS (when Grep/Search in a tree is redirected): set ZOEKT_REDIRECT_INDEXED_ROOTS to a JSON array "
+        "of absolute paths, or ~/.claude/zoekt-indexed-roots.json as {\"roots\": [\"/abs/path/to/repo/\", ...]}. "
+        "Optional ZOEKT_REDIRECT_INDEXED_ROOTS_FILE points to a different JSON file. "
+        "WSL /mnt/<drive>/... prefixes are derived from Windows roots automatically. "
+        "This package ships no built-in roots (public repo); you must configure roots locally.\n\n"
+        "ZOEKT REPO LABEL -> LOCAL DISK (for editing files after a Zoekt hit): "
+        "keep the same directories in zoekt-indexed-roots.json as you index in Zoekt. "
+        "Example pattern only — yours will differ: if Zoekt shows \"acme-lib - src/foo.py\" and that repo "
+        "lives at /srv/checkout/acme-lib/ on your machine, edit /srv/checkout/acme-lib/src/foo.py."
+    )