feat(hooks): strict search gate with per-agent query evidence

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 Full release notes with details on each version: [GitHub Releases](https://github.com/safishamsi/graphify/releases)
 
+## Unreleased
+
+- Fix: generated agent guidance now prefers the MCP `query_graph` tool and uses the graph's recorded Python interpreter as the CLI fallback, so hardened Windows hosts do not route agents through an unsigned `graphify.exe` shim.
+- Fix: strict Claude hooks no longer use one graph-wide 30-minute query stamp that let any agent disable the first-read block for every other session; deny markers now key subagents by `session_id` plus `agent_id`, so a parent's first read cannot silently consume every subagent's guard.
+- Fix: project-scoped hooks now resolve Graphify through each clone's `graphify-out/.graphify_python` sidecar instead of a bare PATH launcher, preserving committed-config portability without producing an unrunnable hook on Application Control hosts (#3280, follow-up to #3129).
+- Feature: strict Claude hooks now record query evidence per session and agent (a PostToolUse `hook-guard mark-queried` on the MCP graph tools and on `graphify query|explain|path`) and deny a recursive in-project search issued through Bash, the Grep tool, or Claude Code's PowerShell tool (`Get-ChildItem -Recurse | Select-String`, `Select-String -Path <dir>`) until that evidence exists; both marker writers garbage-collect markers older than 24 hours; the retry after one traversal is allowed, and exact-file grep, stdin grep, `git grep`, out-of-project targets, Glob, soft mode and malformed input never block. Closes the escape where an agent instructed to read and search through Bash never met the Read-only strict block.
+
 ## 0.9.53 (2026-08-30)
 
 - Fix: a batch of cross-language inheritance-edge corrections (thanks @Synvoya): JavaScript `class X extends Y` now emits an `inherits` edge (#1790); PHP interfaces, enums, and traits are captured as class-like nodes with their heritage (#1791); Scala `trait` declarations become class-like nodes (#1792) and qualified `extends`/`with` bases resolve to the tail type (#1794); a qualified Kotlin supertype resolves to its tail type instead of the package head (#1793); a C# interface extending an interface is classified as `inherits`, not `implements` (#1817); and a Go interface type-set constraint no longer emits a spurious `embeds` edge (#1818).

README.md

@@ -203,7 +203,9 @@ for example `graphify claude install --project` or `graphify codex install --pro
 
 > **Git hooks and uv tool / pipx:** `graphify hook install` embeds the current interpreter path directly into the hook scripts at install time, so the post-commit hook fires correctly even in GUI git clients and CI runners where `~/.local/bin` is not on PATH. If you reinstall or upgrade graphify, re-run `graphify hook install` to refresh the embedded path.
 
-> **Strict mode (Claude Code):** `graphify install --project --strict` makes the assistant actually use the graph. The default install *nudges* it to run `graphify query` before reading files; strict mode *blocks* the first raw source read of a session and redirects it to the graph, then reverts to the nudge (so it fires at most once per session and never gets stuck). Toggle at runtime with `GRAPHIFY_HOOK_STRICT=1`/`0`; the default install is unchanged (soft nudge).
+> **Strict mode (Claude Code):** `graphify install --project --strict` makes the assistant actually use the graph. The default install *nudges* it to use the MCP `query_graph` tool (or the recorded Python-interpreter fallback) before reading files; strict mode *blocks* the first raw source read of a session and redirects it to the graph, then reverts to the nudge (so it fires at most once per session and never gets stuck). Strict mode also *blocks* a recursive in-project search (`grep -r`, `rg`, `find`, `ack`, `ag`, the Grep tool on a directory, or on Windows a PowerShell `Get-ChildItem -Recurse | Select-String` / `Select-String -Path <dir>`) until the session has run one graph traversal — a PostToolUse hook records the MCP graph tools and `graphify query|explain|path` per session and agent; the retry after a query is allowed, and searching a single named file, piping into grep, or paths outside the project are never blocked. Set `GRAPHIFY_HOOK_STRICT=1`/`0` in the Claude process environment to override the installed mode; the default install is unchanged (soft nudge).
+
+> **Project hook interpreter:** committed project hooks read `graphify-out/.graphify_python`, which each clone writes when Graphify resolves its environment. Until that sidecar exists, the hook fails open and emits no graph decision; run the installed Graphify skill once in a fresh clone before relying on strict enforcement.
 
 <details>
 <summary><b>Pick your platform</b> (20+ assistants, click to expand)</summary>

graphify/always_on/agents-md.md

@@ -5,8 +5,8 @@ This project has a knowledge graph at graphify-out/ with god nodes, community st
 When the user types `/graphify`, use the installed graphify skill or instructions before doing anything else.
 
 Rules:
-- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- For codebase questions, first use the graph when graphify-out/graph.json exists. Prefer the MCP `query_graph` tool. CLI fallback: `"$(cat graphify-out/.graphify_python)" -m graphify query "<question>"` (PowerShell: `& (Get-Content graphify-out\.graphify_python) -m graphify query "<question>"`); use the same recorded interpreter with `path` or `explain` for relationships and focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
 - Dirty graphify-out/ files are expected after hooks or incremental updates; dirty graph files are not a reason to skip graphify. Only skip graphify if the task is about stale or incorrect graph output, or the user explicitly says not to use it.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
-- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
+- After modifying code, run `"$(cat graphify-out/.graphify_python)" -m graphify update .` (PowerShell: `& (Get-Content graphify-out\.graphify_python) -m graphify update .`) to keep the graph current (AST-only, no API cost).

graphify/always_on/antigravity-rules.md

@@ -8,7 +8,7 @@ description: Consult the graphify knowledge graph at graphify-out/ for codebase
 This project has a graphify knowledge graph at graphify-out/.
 
 Rules:
-- For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (CLI) or `query_graph` (MCP). Use `graphify path "<A>" "<B>"` / `shortest_path` for relationships and `graphify explain "<concept>"` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output.
+- For codebase or architecture questions, when `graphify-out/graph.json` exists, first use the graph. Prefer the MCP `query_graph` tool. CLI fallback: `"$(cat graphify-out/.graphify_python)" -m graphify query "<question>"` (PowerShell: `& (Get-Content graphify-out\.graphify_python) -m graphify query "<question>"`); use the same recorded interpreter with `path` or `explain` for relationships and focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output.
 - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context
-- After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)
+- After modifying code files in this session, run `"$(cat graphify-out/.graphify_python)" -m graphify update .` (PowerShell: `& (Get-Content graphify-out\.graphify_python) -m graphify update .`) to keep the graph current (AST-only, no API cost)

graphify/always_on/claude-md.md

@@ -3,7 +3,7 @@
 This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
 
 Rules:
-- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- For codebase questions, first use the graph when graphify-out/graph.json exists. Prefer the MCP `query_graph` tool. CLI fallback: `"$(cat graphify-out/.graphify_python)" -m graphify query "<question>"` (PowerShell: `& (Get-Content graphify-out\.graphify_python) -m graphify query "<question>"`); use the same recorded interpreter with `path` or `explain` for relationships and focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
-- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
+- After modifying code, run `"$(cat graphify-out/.graphify_python)" -m graphify update .` (PowerShell: `& (Get-Content graphify-out\.graphify_python) -m graphify update .`) to keep the graph current (AST-only, no API cost).

graphify/always_on/gemini-md.md

@@ -3,7 +3,7 @@
 This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
 
 Rules:
-- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
+- For codebase questions, first use the graph when graphify-out/graph.json exists. Prefer the MCP `query_graph` tool. CLI fallback: `"$(cat graphify-out/.graphify_python)" -m graphify query "<question>"` (PowerShell: `& (Get-Content graphify-out\.graphify_python) -m graphify query "<question>"`); use the same recorded interpreter with `path` or `explain` for relationships and focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
 - If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
 - Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
-- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).
+- After modifying code, run `"$(cat graphify-out/.graphify_python)" -m graphify update .` (PowerShell: `& (Get-Content graphify-out\.graphify_python) -m graphify update .`) to keep the graph current (AST-only, no API cost).

graphify/always_on/kiro-steering.md

@@ -2,4 +2,4 @@
 inclusion: always
 ---
 
-graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` / `graphify explain "<concept>"`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context.
+graphify: A knowledge graph of this project lives in `graphify-out/`. For codebase, architecture, or dependency questions, when `graphify-out/graph.json` exists, prefer the MCP `query_graph` tool. CLI fallback: `"$(cat graphify-out/.graphify_python)" -m graphify query "<question>"` (PowerShell: `& (Get-Content graphify-out\.graphify_python) -m graphify query "<question>"`); use the same recorded interpreter with `path` or `explain`. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output. Read `GRAPH_REPORT.md` only for broad architecture review or when those commands do not surface enough context.

graphify/always_on/vscode-instructions.md

@@ -1,10 +1,11 @@
 ## graphify
 
 For any question about this repo's architecture, structure, components, or how to add/modify/find
-code, your first action should be `graphify query "<question>"` when `graphify-out/graph.json`
-exists. Use `graphify path "<A>" "<B>"` for relationship questions and `graphify explain "<concept>"`
-for focused-concept questions. These return a scoped subgraph, usually much smaller than the full
-report or raw grep output.
+code, first use the graph when `graphify-out/graph.json` exists. Prefer the MCP `query_graph` tool.
+CLI fallback: `"$(cat graphify-out/.graphify_python)" -m graphify query "<question>"` (PowerShell:
+`& (Get-Content graphify-out\.graphify_python) -m graphify query "<question>"`); use the same recorded
+interpreter with `path` or `explain`. These return a scoped subgraph, usually much smaller than the
+full report or raw grep output.
 
 Triggers: "how do I…", "where is…", "what does … do", "add/modify a <component>",
 "explain the architecture", or anything that depends on how files or classes relate.