[codex] Add executable agent hook augmentation

README.md

@@ -13,7 +13,7 @@ RepoLens MCP is an original TypeScript implementation built around fast local ve
 ## Why It Stands Out
 
 - **MCP-native**: exposes 38 tools for indexing, version/update status, repeatable benchmarking, persistent config, project inventory/status, fleet summaries, cross-repo graphing, multi-agent setup, optional startup auto-indexing and git-aware auto-sync, BM25 code search, redacted secret scanning, symbol search, reference lookup, semantic search, vector search, context packs, source snippets, graph schema with relationship patterns and label properties, structural graph search, graph community detection, read-only Cypher-like graph queries, route-call links, runtime trace ingestion, channel/event edges, typed inheritance/implementation/use edges, receiver-aware method call edges, conservative data-flow edges, import-resolved file graphs, multi-ecosystem package manifests, lockfile resolved-dependency graphs, Docker/Kubernetes infrastructure nodes, dependency-cycle detection, architecture reports, architecture summaries, git-history hotspots, tracing, git-change impact, dead-code candidates, maintainable ADR memory, graph snapshots, and graph package exchange.
-- **Agent-ready setup**: `doctor` inspects the local Codex MCP configuration, `install-codex` can add a managed MCP block with dry-run and force safeguards, `uninstall-codex` removes only managed RepoLens config, and `agent-setup`/`install-agents` generate reviewable guidance plus opt-in hook/reminder files for Codex, Claude, Gemini, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro.
+- **Agent-ready setup**: `doctor` inspects the local Codex MCP configuration, `install-codex` can add a managed MCP block with dry-run and force safeguards, `uninstall-codex` removes only managed RepoLens config, `agent-hook` provides executable non-blocking broad-search reminders, and `agent-setup`/`install-agents` generate reviewable guidance plus opt-in hook/reminder files for Codex, Claude, Gemini, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro, including a managed local Claude PreToolUse hook config.
 - **Local-first SQLite memory**: all indexed data stays in `.repolens/memory.db`.
 - **Project catalog and cross-repo graphing**: `list-projects`, `project-status`, `fleet-summary`, `fleet-graph`, and `delete-project` track indexed repositories, aggregate languages/routes/HTTP calls/dependencies, and produce a catalog-wide graph with shared dependencies, route overlaps, and inferred consumer/provider service links.
 - **Incremental refreshes**: skip unchanged files, prune removed files, preserve the existing graph when a repo has not changed, optionally refresh on MCP startup with `REPOLENS_AUTO_INDEX`, and keep long-running MCP sessions fresh with git-aware `REPOLENS_AUTO_SYNC`.
@@ -126,6 +126,7 @@ repolens-mcp uninstall-codex [--dry-run]
 repolens-mcp agent-setup [--target .] [--agents all|codex,claude,gemini,zed,opencode,antigravity,aider,kilocode,vscode,openclaw,kiro] [--db .repolens/memory.db] [--with-hooks]
 repolens-mcp install-agents [--target .] [--agents all|codex,claude,gemini,zed,opencode,antigravity,aider,kilocode,vscode,openclaw,kiro] [--dry-run] [--with-hooks]
 repolens-mcp uninstall-agents [--target .] [--agents all|codex,claude,gemini,zed,opencode,antigravity,aider,kilocode,vscode,openclaw,kiro] [--dry-run] [--with-hooks]
+repolens-mcp agent-hook|hook-augment [--db .repolens/memory.db] [--name repolens] [--json|--claude] [--with-query]
 repolens-mcp decision --title "Use SQLite" --body "Keep memory local."
 repolens-mcp decision-update 1 --status accepted --tags sqlite,privacy
 repolens-mcp decision-delete 1
@@ -325,7 +326,7 @@ repolens-mcp install-agents --target . --agents codex,claude,gemini
 repolens-mcp uninstall-agents --target . --agents codex,claude,gemini --with-hooks --dry-run
 ```
 
-`install-agents` writes managed markdown blocks into project-local instruction files and a `docs/repolens-agent-setup.md` guide. For VS Code it also writes a project-local `.vscode/mcp.json` `servers.repolens` entry while preserving unrelated servers. Add `--with-hooks` to generate opt-in, non-blocking hook/reminder files plus `docs/repolens-agent-hooks.md`; these files tell agents when to call RepoLens before broad searches or risky edits, but they do not execute code by themselves. `uninstall-agents --with-hooks` removes those managed reminder files alongside managed RepoLens markdown blocks and managed VS Code config entries while preserving hand-written content. The guide includes MCP config snippets for Codex, Claude, Gemini, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro.
+`install-agents` writes managed markdown blocks into project-local instruction files and a `docs/repolens-agent-setup.md` guide. For VS Code it also writes a project-local `.vscode/mcp.json` `servers.repolens` entry while preserving unrelated servers. Add `--with-hooks` to generate opt-in, non-blocking hook/reminder files plus `docs/repolens-agent-hooks.md`; for Claude Code it also merges a managed `.claude/settings.local.json` PreToolUse hook entry while preserving unrelated hooks and settings. These files tell agents when to call RepoLens before broad searches or risky edits and include an executable `hook-augment --claude` command for agents that pass hook payload JSON through stdin. `agent-hook`/`hook-augment` recognizes PreToolUse-style Grep, Glob, and broad shell search payloads, emits either text, JSON, or Claude-compatible `hookSpecificOutput.additionalContext`, exits successfully, and does not intercept Read/Edit/Write tools. The hook does not query or mutate the local graph by default; add `--with-query` only when you want it to open the RepoLens database and append symbol metadata matches. `uninstall-agents --with-hooks` removes those managed reminder files and the managed Claude hook entry alongside managed RepoLens markdown blocks and managed VS Code config entries while preserving hand-written content. The guide includes MCP config snippets for Codex, Claude, Gemini, Zed, OpenCode, Antigravity, Aider, KiloCode, VS Code, OpenClaw, and Kiro.
 
 ```json
 {

docs/BENCHMARK.md

@@ -14,7 +14,7 @@ npm run test:skip-gate
 Latest result:
 
 - TypeScript build passed.
-- Node test suite passed: 57 tests, 56 passing, 0 failures, 1 sandbox-only dashboard socket skip.
+- Node test suite passed: 73 tests, 72 passing, 0 failures, 1 sandbox-only dashboard socket skip.
 - Test skip gate passed with explicit policies for the dashboard sandbox socket skip and git-unavailable skips.
 - Coverage includes indexing, incremental refresh, git-aware watch refresh, MCP startup auto-index and auto-sync wiring, project catalog and fleet summaries, graph package import/export, code search, symbol/reference lookup, semantic and vector search, context packs, graph queries, dependency cycles, git-history hotspots, change impact, secret scanning, agent setup, Codex config safeguards, package bootstrap, installer metadata, and MCP JSON-RPC robustness.
 

docs/agent-guide.md

@@ -24,6 +24,14 @@ node --experimental-sqlite dist/src/cli.js doctor
 node --experimental-sqlite dist/src/cli.js install-codex --dry-run
 ```
 
+For hook-capable agents, RepoLens can emit non-blocking broad-search context reminders from hook payload JSON:
+
+```bash
+node --experimental-sqlite dist/src/cli.js hook-augment --db .repolens/memory.db --claude
+```
+
+Use this for PreToolUse-style Grep, Glob, or broad shell-search hooks. It exits successfully when RepoLens is unavailable and does not intercept Read/Edit/Write tools. By default it only parses stdin and emits guidance; add `--with-query` when you want it to open the local RepoLens database and append symbol metadata matches. `install-agents --with-hooks --agents claude` can merge this as an exec-form command hook into `.claude/settings.local.json` while preserving unrelated local hooks.
+
 On Windows PowerShell, the local installer mirrors the shell installer:
 
 ```powershell

docs/research-notes.md

@@ -33,6 +33,7 @@ RepoLens MCP is not a fork or a drop-in static C replacement. It is an original
 - Self-contained graph and architecture report exports for sharing HTML or Markdown artifacts without running a server, plus compressed checksummed `.rlgz` graph packages for reusing a SQLite graph without reindexing. A successful index can write a fresh package with `--write-package`, and a missing database can bootstrap from `.repolens/graph.rlgz` before the incremental pass.
 - CI runs explicit test-skip governance, type-check, tests, production dependency audit, package dry-run, package contents gating, installer dry-run auditing, CycloneDX SBOM generation, self-indexing, and architecture output; separate workflows cover OpenSSF Scorecard and release build-provenance attestations.
 - `llms.txt`, `docs/agent-guide.md`, and `docs/BENCHMARK.md` provide concise agent-facing operating instructions, sanitized validation evidence, and local-data boundaries in the npm package.
+- Executable `agent-hook` / `hook-augment` support turns broad-search hook payloads into non-blocking RepoLens context reminders while skipping direct Read/Edit/Write tools; `--with-query` can opt in to local graph metadata matches when the maintainer wants DB-backed augmentation. Claude Code setup can also merge a managed local PreToolUse hook entry using exec-form `command` plus `args`, avoiding shell parsing and preserving unrelated hooks.
 - `install.ps1` mirrors the Unix installer for Windows users, and `scripts/github-security-summary.mjs` gives maintainers a repeatable GitHub Security tab summary that separates actionable alerts from Scorecard process signals.
 - The release workflow separates unprivileged verify/package work from privileged attestation, GitHub release, and npm publish work.
 

docs/validation-report.md

@@ -21,7 +21,7 @@ npm run test:skip-gate
 Result:
 
 - TypeScript build passed.
-- Node test suite passed: 57 tests, 56 passing, 0 failures, 1 sandbox-only dashboard socket skip.
+- Node test suite passed: 73 tests, 72 passing, 0 failures, 1 sandbox-only dashboard socket skip.
 - Test skip gate passed with explicit policies for the dashboard sandbox socket skip and git-unavailable skips.
 - Covered multi-agent MCP setup rendering/dry-run/write/uninstall behavior, version/update status with npm-compatible registry checks, persistent config list/get/set/reset behavior, Codex MCP config rendering/install/uninstall safeguards including forced replacement of old unmanaged sections, project catalog list/status/delete behavior, fleet summary aggregation with inferred service links, cross-repo fleet graph generation, concurrent catalog writes, decision persistence, repository indexing, benchmark full/no-op incremental evidence, incremental refresh, removed-file pruning, watch-mode refresh, git-aware watch skipping unchanged polls and refreshing dirty worktrees, MCP startup auto-indexing and git-aware auto-sync wiring from env and persisted config, MCP stdio JSON-RPC initialization, tool listing, and invalid tool-call rejection under bounded fuzzing, graph package bootstrap from `.repolens/graph.rlgz`, index-writer locking, graph package export/import, index-time graph package writing with `--write-package`, Swift extraction, Next.js App Router route extraction, GraphQL/protobuf/tRPC/OpenAPI protocol extraction, import-resolved file edge extraction with aliases/workspace packages/relative imports, typed `INHERITS`/`IMPLEMENTS`/`USES_TYPE` relationship extraction, conservative `DATA_FLOWS` extraction, positional argument-to-parameter mapping, ambiguous callee suppression, stale data-flow edge pruning on incremental refresh, trace modes for calls/data-flow/cross-service edges, multi-ecosystem manifest extraction, package-manager lockfile extraction, Dockerfile/Kubernetes/Kustomize graph extraction, channel/event graph extraction with `EMITS` and `LISTENS_ON`, runtime trace ingestion with `OBSERVED_*` edges, symbol search, indexed reference lookup, BM25 code search with camelCase/snake_case token expansion, redacted secret scanning, semantic search, local vector search, context-pack assembly, first-class `http_call` nodes with `CALLS_HTTP_ENDPOINT`, generated `HTTP_CALLS` route-call edges, graph community detection, source snippets, graph schema including relationship patterns and label property hints, structural graph search, read-only Cypher-like graph queries including `DISTINCT`, `count`, `ORDER BY`, `SKIP`, `IN`, and numeric comparisons, relative and workspace-package import cycle resolution, git-history hotspot extraction, history-aware architecture recommendations, architecture recommendations, dead-code candidates, architecture summary, property-based resolver fuzzing, and trace behavior on fixture repositories.
 
@@ -54,15 +54,16 @@ Result:
 
 - Production dependency audit passed with `npm run audit:prod`: 0 vulnerabilities.
 - Package dry run passed for `repolens-mcp@1.0.0`.
-- Packed artifact: `repolens-mcp-1.0.0.tgz`, 183,403 bytes packed, 938,818 bytes unpacked, 86 runtime/doc entries.
+- Packed artifact: `repolens-mcp-1.0.0.tgz`, 200,896 bytes packed, 1,029,092 bytes unpacked, 92 runtime/doc entries.
 - Package contents are scoped to `dist/src`, `README.md`, `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, selected public docs, `llms.txt`, scripts, `package.json`, `server.json`, `install.sh`, and `install.ps1`; compiled tests, source TypeScript, local graph memory, SQLite databases, graph packages, fixtures, private validation output, and local workstation paths are excluded.
-- Package contents gate passed: 86 files inspected.
+- Package contents gate passed: 92 files inspected.
 - Installer audit passed for `install.sh` dry-run setup under a temporary home and target directory. `install.ps1` dry-run audit is enforced when `pwsh` is available and in CI.
 - CycloneDX SBOM generation passed with `npm sbom --sbom-format cyclonedx --json`.
 - Local installer syntax check passed for `install.sh`; the script verifies Node 24, runs `npm ci`, builds the project, runs `doctor`, can apply `install-codex` with `--dry-run`/`--force` controls, and can render or write project-local setup guidance through `install-agents`.
 - PowerShell installer parser check is enforced in CI for `install.ps1`; it mirrors the Unix installer's Node 24 check, npm/build flow, doctor command, Codex install/uninstall, agent install/uninstall, `-DryRun`, `-Force`, `-Db`, `-Agents`, `-Target`, and `-SkipNpm` options. Local macOS validation could not execute `pwsh` because it is not installed in this environment.
 - GitHub security summary script reported 0 actionable open alerts, 0 CodeQL alerts, 0 Dependabot alerts, 0 secret-scanning alerts, 3 OpenSSF Scorecard process signals, and 0 other code-scanning alerts.
 - `agent-setup` dry-run rendered the expected guide and instruction targets for Codex, Claude, and Gemini without writing files.
+- `hook-augment --claude` smoke test emitted Claude-compatible `hookSpecificOutput.additionalContext` for a fake Grep PreToolUse payload without querying the local graph by default; the opt-in `--with-query` smoke on the fixture graph appended local symbol metadata matches, a fake Read payload exited 0 with no blocking output, and Claude hook setup tests verified managed `.claude/settings.local.json` install/update/uninstall behavior while preserving unrelated hooks.
 - `config set/get/reset` persisted startup defaults in an isolated temp config file and removed the managed key cleanly.
 - `uninstall-codex --dry-run` detected the managed Codex block without writing, and `uninstall-agents` removed generated managed blocks from a temporary project target.
 - `benchmark` on the fixture repository ran a full index plus no-op incremental index, returned graph totals and throughput, and reported 0 medium/high secret findings.

package.json

@@ -1,7 +1,7 @@
 {
   "name": "repolens-mcp",
   "version": "1.0.0",
-  "description": "Local-first repository intelligence MCP server with multi-agent setup, persistent config, project catalog, fleet summaries, cross-repo graphing, graph package bootstrap, optional startup auto-indexing, git-aware MCP auto-sync, incremental indexing, BM25 code search, reference lookup, typed relationship and data-flow edges, local vector search, redacted secret scanning, context packs, runtime trace ingestion, import-resolved file graphs, multi-ecosystem manifest and lockfile parsing, Docker/Kubernetes graph indexing, channel/event graph edges, git-history hotspots, watch mode, graph search, graph communities, semantic search, route-call links, read-only graph queries, source snippets, dependency-cycle checks, architecture reports, graph packages, ADR memory, graph export, and a dashboard.",
+  "description": "Local-first repository intelligence MCP server with multi-agent setup, executable agent hook reminders, persistent config, project catalog, fleet summaries, cross-repo graphing, graph package bootstrap, optional startup auto-indexing, git-aware MCP auto-sync, incremental indexing, BM25 code search, reference lookup, typed relationship and data-flow edges, local vector search, redacted secret scanning, context packs, runtime trace ingestion, import-resolved file graphs, multi-ecosystem manifest and lockfile parsing, Docker/Kubernetes graph indexing, channel/event graph edges, git-history hotspots, watch mode, graph search, graph communities, semantic search, route-call links, read-only graph queries, source snippets, dependency-cycle checks, architecture reports, graph packages, ADR memory, graph export, and a dashboard.",
   "type": "module",
   "mcpName": "io.github.sameer2191/repolens-mcp",
   "bin": {