feat(hooks): auto-reindex after git commit with embeddings preservation

[L1nusB]

Summary

• Adds a PostToolUse hook that automatically re-runs gitnexus analyze after git commit or git merge, keeping the knowledge graph index fresh without manual intervention
• Detects and preserves embeddings: reads .gitnexus/meta.json to check if the previous index included embeddings (stats.embeddings > 0) and passes --embeddings accordingly — preventing accidental deletion of expensive vector embeddings
• Persists embeddings count in meta.json so hooks and external tools can detect previous embeddings without opening KuzuDB
• Adds a "Keeping the Index Fresh" section to the auto-generated CLAUDE.md/AGENTS.md, providing reindex guidance for all AI coding integrations (not just Claude Code)

Why

The GitNexus index becomes stale after every commit. Currently, staleness is detected reactively — MCP tools warn the agent, and the CLAUDE.md says "run analyze if stale." This has two problems:

1. Reactive, not proactive: The agent works with stale data until it happens to trigger a staleness check, potentially making decisions based on outdated call graphs and execution flows.
2. Embeddings get silently destroyed: Running analyze without --embeddings wipes previously generated embeddings because KuzuDB is fully rebuilt every time (lines 196-200 in analyze.ts). There was no way to detect whether embeddings existed before, so a naive reindex would lose them.

This PR solves both by automating reindex at the right moment (post-commit) with the right flags (auto-detecting embeddings).

How It Works

1. PostToolUse hook fires after any Bash tool execution completes
2. Hook checks if the command matches /\bgit\s+(commit|merge)(\s|$)/ — skips everything else instantly (including git merge-base and similar subcommands)
3. Walks up the directory tree to find .gitnexus/
4. Reads meta.json → checks stats.embeddings > 0
5. Spawns gitnexus analyze [--embeddings] synchronously (120s timeout)
6. Returns additionalContext to the agent confirming the index was updated

On failure or timeout, the hook returns a recovery command that includes --embeddings when appropriate, so the user can run it manually.

For non-Claude-Code integrations (Cursor, Windsurf, etc.), the new "Keeping the Index Fresh" section in AGENTS.md provides equivalent guidance as instructions the agent can follow after committing.

Changes

File	Change
gitnexus/src/cli/analyze.ts	Query CodeEmbedding count after indexing, persist in meta.json stats.embeddings
gitnexus/hooks/claude/gitnexus-hook.cjs	Add handlePostToolUse() for auto-reindex; refactor into modular functions
gitnexus/src/cli/setup.ts	Register PostToolUse hook in ~/.claude/settings.json during gitnexus setup
gitnexus/src/cli/ai-context.ts	Add "Keeping the Index Fresh" section to generated CLAUDE.md/AGENTS.md
gitnexus-claude-plugin/hooks/gitnexus-hook.js	Add PostToolUse handler (plugin variant)
gitnexus-claude-plugin/hooks/hooks.json	Register PostToolUse hook for plugin
README.md	Update editor support table to reflect PostToolUse hooks
gitnexus/skills/gitnexus-cli.md	Document auto-reindex behavior in "When to run" section

Design Decisions

Why PostToolUse hook instead of git post-commit hook?

• Git hooks aren't committed to the repo (require core.hooksPath or husky)
• GitNexus is optional tooling — shouldn't impose workflow requirements on all contributors
• PostToolUse catches agent-initiated commits, which is the primary use case

Why blocking (synchronous) instead of background?

• The agent shouldn't proceed with stale data immediately after committing
• A few seconds of indexing is worth accurate results for subsequent queries
• Background reindex creates race conditions where the agent queries mid-rebuild

Why 120s timeout?

• Small-to-medium repos index in 5-15 seconds
• Large repos can take up to 60 seconds
• 120s provides headroom without being indefinite
• On timeout, the hook returns a fallback message suggesting manual reindex with correct flags

Why persist embeddings count in meta.json?

• The only prior way to detect embeddings was querying KuzuDB (MATCH (e:CodeEmbedding) RETURN count(e)), which requires loading the native module
• A JSON file read is instant and works from any context (shell hooks, external scripts)
• The stats.embeddings field already existed in the RepoMeta interface but was never populated

Robustness

Several hardening measures were applied during review:

• Strict git regex: /\bgit\s+(commit|merge)(\s|$)/ prevents false triggers on git merge-base, git commit-tree, etc.
• Proper spawnSync error handling: Checks child.error/child.signal instead of relying on try/catch (spawnSync doesn't throw on timeout)
• PreToolUse stderr guard: Only forwards augment output as additionalContext when exit code is 0 — CLI errors no longer leak into agent context
• Single-launch CLI resolution (plugin): Detects gitnexus binary via which/where once, then runs exactly once (prevents double execution)
• Windows compatibility: shell: true for npx fallback on Windows where .cmd files need a shell
• Hook timeouts in correct units: seconds (not milliseconds) matching Claude Code's expected format

🤖 Generated with Claude Code

[vercel]

@L1nusB is attempting to deploy a commit to the NexusCore Team on Vercel.

A member of the Team first needs to authorize it.

[magyargergo]

Security & Cross-Platform Hardening (Review Round 2)

After multi-agent code review, this commit addresses 7 findings across both hook variants and the setup installer:

Critical Fix

• Removed shell: true from CJS hook (gitnexus-hook.cjs) — the npm-packaged hook still used shell: isWin for the npx fallback, creating a command injection vector. Now uses npx.cmd directly on Windows, matching the plugin variant.

Medium Fixes

• Consistent sendHookResponse() — CJS handlePreToolUse was inlining JSON output instead of using the shared helper. Now both handlers in both hook variants use the same output function.
• Safe path escaping in setup.ts — replaced manual single-quote escaping with JSON.stringify() for the injected CLI path, which correctly handles backslashes, newlines, and all special characters.

Low-Risk Hardening

• path.isAbsolute(cwd) guards in both hook variants — defense-in-depth against crafted stdin input providing relative paths.
• Reduced PreToolUse CLI timeout from 8s to 7s to stay within the 10s hook timeout with margin.
• Truncated debug error messages to 200 chars to prevent log flooding.
• Cleaned up verbose comments in Windows .cmd explanation.

Regression Tests

Added 73 new tests in test/unit/hooks.test.ts covering:

• Shell injection prevention (no shell: true anywhere)
• Windows .cmd extension usage
• cwd validation (relative paths rejected)
• sendHookResponse consistency across both variants
• Dispatch map routing (unknown events, empty input, invalid JSON)
• extractPattern for Grep/Glob/Bash tool inputs
• Git mutation regex coverage (commit/merge/rebase/cherry-pick/pull)
• PostToolUse staleness detection with temp git repos
• Embeddings flag preservation in reindex commands

All 921 tests pass (41 test files), build clean.

[magyargergo]

Design Note: Notify-Only Staleness Detection (Not Auto-Reindex)

This PR intentionally does not run gitnexus analyze automatically. Instead, the PostToolUse hook performs a lightweight staleness check and notifies the agent to reindex when ready.

Why this approach is better

Running gitnexus analyze synchronously in a hook is dangerous:

• Blocks the agent for up to 120s while KuzuDB rebuilds
• Risk of KuzuDB corruption if the hook times out mid-write
• Claude Code hook timeout is 10s — a full analyze would always be killed
• The killed process leaves the database in an inconsistent state

Notify-only is safer and smarter:

• The staleness check takes <100ms (just git rev-parse HEAD vs meta.json)
• The agent decides when to reindex — it can finish its current task first
• No risk of database corruption from timeouts
• The notification includes the right command (--embeddings flag preserved if previously used)

How it works

Agent runs: git commit -m "fix: something"
  ↓
PostToolUse hook fires (matcher: Bash)
  ↓
Checks: was it a git mutation? (commit|merge|rebase|cherry-pick|pull)
  ↓
Checks: did it succeed? (exit_code === 0)
  ↓
Compares: git rev-parse HEAD vs .gitnexus/meta.json.lastCommit
  ↓
If stale → sends: "GitNexus index is stale. Run `npx gitnexus analyze` to update."
  ↓
Agent decides when to run it (not forced mid-task)

This pattern follows the same principle as LSP diagnostics — the tool reports, the user (or agent) acts.

[magyargergo]

Thank you for your contribution @L1nusB !