gitnexus 1.6.8-rc.3 → 1.6.8-rc.5

package/README.md

@@ -436,6 +436,26 @@ After scope resolution, analyze prunes inert block-local value symbols (a functi
 
 Programmatic callers can pass `keepLocalValueSymbols: true` in `PipelineOptions` instead of setting the env var.
 
+### Hook augmentation/notifications are silently skipped
+
+The Claude Code / Antigravity hooks intentionally stay **silent** on normal skip
+paths so strict hook runners (e.g. Codex `PreToolUse`) never see unexpected
+output. A search may not be augmented — or a stale-index reminder may not appear
+on stderr — when the GitNexus MCP server owns the repo DB, when the DB-lock probe
+times out and fails closed, or when the index is already current.
+
+To see why a hook skipped, set `GITNEXUS_DEBUG=1` and re-run the action — the hook
+writes the reason (e.g. `[GitNexus] augment skipped: MCP server owns DB`) and the
+stale-index hint to its stderr:
+
+```bash
+GITNEXUS_DEBUG=1 <your command>   # surfaces hook skip/diagnostic reasons on stderr
+```
+
+Only `GITNEXUS_DEBUG=1` and `GITNEXUS_DEBUG=true` enable diagnostics; every other
+value (including `0` and `false`) is treated as off. Diagnostics go to stderr
+only — the hook's structured stdout (the JSON the agent consumes) is unaffected.
+
 ## Privacy
 
 - All processing happens locally on your machine

package/dist/core/group/extractors/http-patterns/java.js

@@ -1,31 +1,6 @@
 import Java from 'tree-sitter-java';
 import { compilePatterns, runCompiledPatterns, unquoteLiteral, } from '../tree-sitter-scanner.js';
-/**
- * Java HTTP plugin. Handles:
- *   - Spring `@RequestMapping` class prefixes + `@(Get|Post|...)Mapping` method annotations
- *   - Spring `RestTemplate.getForObject/...`, `exchange(...)`
- *   - Spring `WebClient.method(HttpMethod.X, ...)`, `WebClient.get().uri(...)`
- *   - OkHttp `new Request.Builder().url("...")`
- *   - OpenFeign interfaces with Spring MVC method annotations or
- *     native `@RequestLine("METHOD /path")` annotations
- *   - Java / Apache HttpClient literal request construction
- *
- * Every route-defining annotation (class/interface `@RequestMapping`
- * prefixes, `@FeignClient(path)` prefixes, `@(Get|...)Mapping` method
- * routes and native `@RequestLine`s) is matched by a single consolidated
- * query (`JAVA_ROUTE_ANNOTATION_PATTERNS`) in one pass via
- * `scanRouteAnnotations`. The `scan` function then walks up from each
- * matched method to its enclosing class/interface to combine the prefix
- * with the method path. Call-site consumers (RestTemplate, WebClient,
- * OkHttp, Java/Apache HttpClient) keep their own focused queries.
- */
-const METHOD_ANNOTATION_TO_HTTP = {
-    GetMapping: 'GET',
-    PostMapping: 'POST',
-    PutMapping: 'PUT',
-    DeleteMapping: 'DELETE',
-    PatchMapping: 'PATCH',
-};
+import { METHOD_ANNOTATION_TO_HTTP, isRouteMemberKey, findEnclosingClass, } from '../../../ingestion/route-extractors/spring-shared.js';
 // ─── Route-defining annotations (one generic query, one pass) ─────────
 // Every Java route-mapper annotation shares one shape: an annotation carrying a
 // single string argument — positional `"..."` or named `key = "..."` — on a
@@ -300,19 +275,9 @@ const APACHE_HTTP_CLIENT_PATTERNS = compilePatterns({
     ],
 });
 /**
- * Find the nearest enclosing class/interface declaration ancestor for
- * a node, or null if the node is top-level. Tree-sitter's
- * SyntaxNode.parent walks one level at a time.
+ * Find the nearest enclosing interface declaration ancestor for a node, or
+ * null if the node is top-level.
  */
-function findEnclosingClass(node) {
-    let cur = node.parent;
-    while (cur) {
-        if (cur.type === 'class_declaration')
-            return cur;
-        cur = cur.parent;
-    }
-    return null;
-}
 function findEnclosingInterface(node) {
     let cur = node.parent;
     while (cur) {
@@ -369,18 +334,6 @@ function hasAnnotation(node, names) {
     }
     return false;
 }
-/**
- * A named annotation argument contributes a route only when its member key is
- * `path` or `value`; a positional argument (no key node) always qualifies.
- * This is the JS-side replacement for the in-query `^(path|value)$` filter and
- * drops Spring's non-route string attributes (`produces`, `consumes`,
- * `headers`, `name`, `params`) that would otherwise be mis-read as routes.
- */
-function isRouteMemberKey(keyNode) {
-    if (!keyNode)
-        return true;
-    return keyNode.text === 'path' || keyNode.text === 'value';
-}
 /**
  * Resolve every Java route-defining annotation in a single tree-sitter pass.
  *

package/dist/core/ingestion/language-provider.d.ts

@@ -20,6 +20,8 @@ import type { VariableExtractor } from './variable-types.js';
 import type { ImportResolverFn } from './import-resolvers/types.js';
 import type { SyntaxNode } from './utils/ast-helpers.js';
 import type { NodeLabel } from '../../_shared/index.js';
+import type Parser from 'tree-sitter';
+import type { ExtractedDecoratorRoute } from './workers/parse-worker.js';
 /** Tree-sitter query captures: capture name → AST node (or undefined if not captured). */
 export type CaptureMap = Record<string, SyntaxNode | undefined>;
 /** Configuration for AST-based framework detection patterns. */
@@ -185,6 +187,17 @@ interface LanguageProviderConfig {
      *  When true, the worker extracts routes via the language's route extraction logic.
      *  Default: undefined (no route files). */
     readonly isRouteFile?: (filePath: string) => boolean;
+    /**
+     * Extract decorator-style route annotations from a parsed file.
+     *
+     * When defined, the parse worker calls this after per-file capture processing
+     * to extract framework route definitions that require AST-level analysis beyond
+     * generic `@decorator` captures (e.g., Java Spring class-level prefix joining,
+     * multi-class handling). The returned routes are appended to `decoratorRoutes`.
+     *
+     * Default: undefined (no language-specific decorator route extraction).
+     */
+    readonly extractDecoratorRoutes?: (tree: Parser.Tree, filePath: string, lineOffset: number) => ExtractedDecoratorRoute[];
     /** Built-in/stdlib names that should be filtered from the call graph for this language.
      *  Default: undefined (no language-specific filtering). */
     readonly builtInNames?: ReadonlySet<string>;

package/dist/core/ingestion/languages/java.js

@@ -11,6 +11,7 @@ import { createClassExtractor } from '../class-extractors/generic.js';
 import { javaClassConfig } from '../class-extractors/configs/jvm.js';
 import { defineLanguage } from '../language-provider.js';
 import { javaTypeConfig } from '../type-extractors/jvm.js';
+import { extractSpringRoutes } from '../route-extractors/spring.js';
 import { javaExportChecker } from '../export-detection.js';
 import { createImportResolver } from '../import-resolvers/resolver-factory.js';
 import { javaImportConfig } from '../import-resolvers/configs/jvm.js';
@@ -103,4 +104,6 @@ export const javaProvider = defineLanguage({
     arityCompatibility: javaArityCompatibility,
     resolveImportTarget: resolveJavaImportTarget,
     orderSameNameTypeCandidates: orderJavaSameNameTypeCandidates,
+    // ── Route extraction ──
+    extractDecoratorRoutes: extractSpringRoutes,
 });

package/dist/core/ingestion/route-extractors/spring-shared.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Shared Spring route-annotation primitives.
+ *
+ * These are the low-level building blocks the two Spring route extractors —
+ * the ingestion-layer `route-extractors/spring.ts` (produces graph `Route`
+ * nodes) and the group-layer `group/extractors/http-patterns/java.ts`
+ * (produces cross-repo HTTP contracts) — would otherwise each maintain
+ * independently. Centralising the annotation→method map, the enclosing-class
+ * lookup, and the route-key filter keeps those semantics in one place so the
+ * two extractors can't drift apart.
+ *
+ * This module lives in `ingestion/` (the lower layer); the group layer imports
+ * from it, matching the existing `group → ingestion` dependency direction
+ * (e.g. `group/extractors/include-extractor.ts` already imports
+ * `ingestion/import-resolvers/utils.ts`). It MUST NOT import anything from
+ * `group/` to avoid a dependency cycle.
+ */
+import type Parser from 'tree-sitter';
+/**
+ * Spring shortcut method-annotation → HTTP verb.
+ *
+ * `@RequestMapping` is intentionally absent: on a method it carries no implicit
+ * verb (the verb lives in its `method = RequestMethod.X` attribute), and on a
+ * class it is a URL prefix rather than a route. Callers handle `@RequestMapping`
+ * separately.
+ */
+export declare const METHOD_ANNOTATION_TO_HTTP: Record<string, string>;
+/**
+ * A named annotation argument contributes a route only when its member key is
+ * `path` or `value`; a positional argument (no key node) always qualifies.
+ * Drops Spring's non-route string attributes (`produces`, `consumes`,
+ * `headers`, `name`, `params`) that would otherwise be mis-read as routes.
+ */
+export declare function isRouteMemberKey(keyNode: Parser.SyntaxNode | undefined): boolean;
+/**
+ * Find the nearest enclosing `class_declaration` ancestor for a node, or null
+ * if the node is top-level. Tree-sitter's `SyntaxNode.parent` walks one level
+ * at a time.
+ */
+export declare function findEnclosingClass(node: Parser.SyntaxNode): Parser.SyntaxNode | null;
+/**
+ * Strip enclosing quotes from a tree-sitter string-literal node's text.
+ * Handles single / double / template (backtick) quotes and triple-quoted
+ * strings. Mirrors the safer semantics of the group layer's `unquoteLiteral`:
+ * returns `null` for empty / nullish input so callers can uniformly skip
+ * captures whose value is missing, and returns the text unchanged when it
+ * carries no recognisable surrounding quotes (some grammars expose string
+ * content without quotes already).
+ */
+export declare function unquoteSpringLiteral(raw: string): string | null;

package/dist/core/ingestion/route-extractors/spring-shared.js

@@ -0,0 +1,80 @@
+/**
+ * Shared Spring route-annotation primitives.
+ *
+ * These are the low-level building blocks the two Spring route extractors —
+ * the ingestion-layer `route-extractors/spring.ts` (produces graph `Route`
+ * nodes) and the group-layer `group/extractors/http-patterns/java.ts`
+ * (produces cross-repo HTTP contracts) — would otherwise each maintain
+ * independently. Centralising the annotation→method map, the enclosing-class
+ * lookup, and the route-key filter keeps those semantics in one place so the
+ * two extractors can't drift apart.
+ *
+ * This module lives in `ingestion/` (the lower layer); the group layer imports
+ * from it, matching the existing `group → ingestion` dependency direction
+ * (e.g. `group/extractors/include-extractor.ts` already imports
+ * `ingestion/import-resolvers/utils.ts`). It MUST NOT import anything from
+ * `group/` to avoid a dependency cycle.
+ */
+/**
+ * Spring shortcut method-annotation → HTTP verb.
+ *
+ * `@RequestMapping` is intentionally absent: on a method it carries no implicit
+ * verb (the verb lives in its `method = RequestMethod.X` attribute), and on a
+ * class it is a URL prefix rather than a route. Callers handle `@RequestMapping`
+ * separately.
+ */
+export const METHOD_ANNOTATION_TO_HTTP = {
+    GetMapping: 'GET',
+    PostMapping: 'POST',
+    PutMapping: 'PUT',
+    DeleteMapping: 'DELETE',
+    PatchMapping: 'PATCH',
+};
+/**
+ * A named annotation argument contributes a route only when its member key is
+ * `path` or `value`; a positional argument (no key node) always qualifies.
+ * Drops Spring's non-route string attributes (`produces`, `consumes`,
+ * `headers`, `name`, `params`) that would otherwise be mis-read as routes.
+ */
+export function isRouteMemberKey(keyNode) {
+    if (!keyNode)
+        return true;
+    return keyNode.text === 'path' || keyNode.text === 'value';
+}
+/**
+ * Find the nearest enclosing `class_declaration` ancestor for a node, or null
+ * if the node is top-level. Tree-sitter's `SyntaxNode.parent` walks one level
+ * at a time.
+ */
+export function findEnclosingClass(node) {
+    let cur = node.parent;
+    while (cur) {
+        if (cur.type === 'class_declaration')
+            return cur;
+        cur = cur.parent;
+    }
+    return null;
+}
+/**
+ * Strip enclosing quotes from a tree-sitter string-literal node's text.
+ * Handles single / double / template (backtick) quotes and triple-quoted
+ * strings. Mirrors the safer semantics of the group layer's `unquoteLiteral`:
+ * returns `null` for empty / nullish input so callers can uniformly skip
+ * captures whose value is missing, and returns the text unchanged when it
+ * carries no recognisable surrounding quotes (some grammars expose string
+ * content without quotes already).
+ */
+export function unquoteSpringLiteral(raw) {
+    if (!raw)
+        return null;
+    if ((raw.startsWith('"""') && raw.endsWith('"""')) ||
+        (raw.startsWith("'''") && raw.endsWith("'''"))) {
+        return raw.slice(3, -3);
+    }
+    const first = raw[0];
+    const last = raw[raw.length - 1];
+    if ((first === '"' || first === "'" || first === '`') && last === first && raw.length >= 2) {
+        return raw.slice(1, -1);
+    }
+    return raw;
+}

package/dist/core/ingestion/route-extractors/spring.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Spring route annotation extractor for the ingestion pipeline.
+ *
+ * Extracts `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`,
+ * `@PatchMapping`, and `@RequestMapping` annotations from Java source files
+ * and returns `ExtractedDecoratorRoute[]` with class-level `@RequestMapping`
+ * prefixes already resolved per-class.
+ *
+ * This module is the ingestion-layer counterpart of
+ * `group/extractors/http-patterns/java.ts` (which extracts HTTP contracts
+ * for cross-repo matching). It uses the same tree-sitter capture approach:
+ * a single predicate-free query matches all route annotations generically,
+ * then a for-loop discriminates class-level prefixes from method-level routes
+ * by reading `@node.type` and the annotation name.
+ *
+ * The query is predicate-free to avoid the tree-sitter 0.21.x hazard where
+ * `#match?` / `#eq?` predicates in a top-level `[...]` alternation silently
+ * drop sibling-branch matches (see group-layer `JAVA_ROUTE_ANNOTATION_PATTERNS`
+ * header comment for details).
+ */
+import Parser from 'tree-sitter';
+import type { ExtractedDecoratorRoute } from '../workers/parse-worker.js';
+/**
+ * Extract Spring route annotations from a parsed Java file.
+ *
+ * Uses a single tree-sitter query pass to capture all annotations, then
+ * discriminates class-level prefixes from method-level routes in a loop.
+ * Handles multiple classes per file, each with its own prefix.
+ *
+ * @param tree - tree-sitter parse tree
+ * @param filePath - relative file path (for `ExtractedDecoratorRoute.filePath`)
+ * @param lineOffset - line offset for pre-processing (usually 0)
+ * @returns Decorator routes with prefix already set per-class
+ */
+export declare function extractSpringRoutes(tree: Parser.Tree, filePath: string, lineOffset?: number): ExtractedDecoratorRoute[];

package/dist/core/ingestion/route-extractors/spring.js

@@ -0,0 +1,136 @@
+/**
+ * Spring route annotation extractor for the ingestion pipeline.
+ *
+ * Extracts `@GetMapping`, `@PostMapping`, `@PutMapping`, `@DeleteMapping`,
+ * `@PatchMapping`, and `@RequestMapping` annotations from Java source files
+ * and returns `ExtractedDecoratorRoute[]` with class-level `@RequestMapping`
+ * prefixes already resolved per-class.
+ *
+ * This module is the ingestion-layer counterpart of
+ * `group/extractors/http-patterns/java.ts` (which extracts HTTP contracts
+ * for cross-repo matching). It uses the same tree-sitter capture approach:
+ * a single predicate-free query matches all route annotations generically,
+ * then a for-loop discriminates class-level prefixes from method-level routes
+ * by reading `@node.type` and the annotation name.
+ *
+ * The query is predicate-free to avoid the tree-sitter 0.21.x hazard where
+ * `#match?` / `#eq?` predicates in a top-level `[...]` alternation silently
+ * drop sibling-branch matches (see group-layer `JAVA_ROUTE_ANNOTATION_PATTERNS`
+ * header comment for details).
+ */
+import Parser from 'tree-sitter';
+import Java from 'tree-sitter-java';
+import { METHOD_ANNOTATION_TO_HTTP, isRouteMemberKey, findEnclosingClass, unquoteSpringLiteral, } from './spring-shared.js';
+/**
+ * Single predicate-free tree-sitter query that captures all route annotations
+ * on classes and methods. Discrimination by annotation name and node type
+ * happens in the loop below.
+ *
+ * Captures:
+ *   @ann   → annotation name identifier (RequestMapping, GetMapping, etc.)
+ *   @node  → enclosing declaration (class_declaration | method_declaration)
+ *   @value → the string-literal argument
+ *   @key   → the named-argument member key (absent for positional form)
+ */
+const ROUTE_ANNOTATION_QUERY = new Parser.Query(Java, `
+  [
+    (class_declaration
+      (modifiers
+        (annotation
+          name: (identifier) @ann
+          arguments: (annotation_argument_list (string_literal) @value)))) @node
+    (class_declaration
+      (modifiers
+        (annotation
+          name: (identifier) @ann
+          arguments: (annotation_argument_list
+            (element_value_pair
+              key: (identifier) @key
+              value: (string_literal) @value))))) @node
+    (method_declaration
+      (modifiers
+        (annotation
+          name: (identifier) @ann
+          arguments: (annotation_argument_list (string_literal) @value)))) @node
+    (method_declaration
+      (modifiers
+        (annotation
+          name: (identifier) @ann
+          arguments: (annotation_argument_list
+            (element_value_pair
+              key: (identifier) @key
+              value: (string_literal) @value))))) @node
+  ]
+`);
+/**
+ * Extract Spring route annotations from a parsed Java file.
+ *
+ * Uses a single tree-sitter query pass to capture all annotations, then
+ * discriminates class-level prefixes from method-level routes in a loop.
+ * Handles multiple classes per file, each with its own prefix.
+ *
+ * @param tree - tree-sitter parse tree
+ * @param filePath - relative file path (for `ExtractedDecoratorRoute.filePath`)
+ * @param lineOffset - line offset for pre-processing (usually 0)
+ * @returns Decorator routes with prefix already set per-class
+ */
+export function extractSpringRoutes(tree, filePath, lineOffset = 0) {
+    const matches = ROUTE_ANNOTATION_QUERY.matches(tree.rootNode);
+    // Phase 1: collect class-level @RequestMapping prefixes keyed by node id
+    const prefixByClassId = new Map();
+    for (const match of matches) {
+        const caps = {};
+        for (const { name, node } of match.captures) {
+            caps[name] = node;
+        }
+        const annNode = caps['ann'];
+        const node = caps['node'];
+        const valueNode = caps['value'];
+        const keyNode = caps['key'];
+        if (!annNode || !node || !valueNode)
+            continue;
+        if (node.type === 'class_declaration' && annNode.text === 'RequestMapping') {
+            if (!isRouteMemberKey(keyNode))
+                continue;
+            const prefix = unquoteSpringLiteral(valueNode.text);
+            if (prefix !== null)
+                prefixByClassId.set(node.id, prefix);
+        }
+    }
+    // Phase 2: collect method-level routes and resolve their class prefix
+    const routes = [];
+    for (const match of matches) {
+        const caps = {};
+        for (const { name, node } of match.captures) {
+            caps[name] = node;
+        }
+        const annNode = caps['ann'];
+        const node = caps['node'];
+        const valueNode = caps['value'];
+        const keyNode = caps['key'];
+        if (!annNode || !node || !valueNode)
+            continue;
+        if (node.type !== 'method_declaration')
+            continue;
+        const ann = annNode.text;
+        const httpMethod = METHOD_ANNOTATION_TO_HTTP[ann];
+        if (!httpMethod)
+            continue; // skip @RequestMapping on methods (ambiguous verb)
+        if (!isRouteMemberKey(keyNode))
+            continue;
+        const routePath = unquoteSpringLiteral(valueNode.text);
+        if (routePath === null)
+            continue;
+        const enclosingClass = findEnclosingClass(node);
+        const classPrefix = enclosingClass ? (prefixByClassId.get(enclosingClass.id) ?? '') : '';
+        routes.push({
+            filePath,
+            routePath,
+            httpMethod,
+            decoratorName: ann,
+            lineNumber: annNode.startPosition.row + lineOffset,
+            ...(classPrefix ? { prefix: classPrefix } : {}),
+        });
+    }
+    return routes;
+}

package/dist/core/ingestion/workers/parse-worker.js

@@ -678,6 +678,7 @@ const ROUTE_DECORATOR_NAMES = new Set([
     'PostMapping',
     'PutMapping',
     'DeleteMapping',
+    'PatchMapping',
 ]);
 // ============================================================================
 // ORM Query Detection (Prisma + Supabase)
@@ -1743,6 +1744,15 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
         if (language === SupportedLanguages.Python) {
             extractFastAPIRouterBindings(file.path, parseContent, result.routerIncludes, result.routerImports, (result.routerModuleAliases ??= []));
         }
+        // Language-specific decorator route extraction via provider hook.
+        // The provider's extractDecoratorRoutes walks the AST for framework-specific
+        // route patterns (e.g., Java Spring class-level prefix joining). Routes are
+        // appended to decoratorRoutes for the routes phase to emit as Route nodes.
+        if (provider.extractDecoratorRoutes) {
+            const frameworkRoutes = provider.extractDecoratorRoutes(tree, file.path, lineOffset);
+            for (const r of frameworkRoutes)
+                result.decoratorRoutes.push(r);
+        }
         // Vue: emit CALLS edges for components used in <template>
         if (language === SupportedLanguages.Vue) {
             const templateComponents = extractTemplateComponents(file.content);

package/hooks/antigravity/gitnexus-antigravity-hook.cjs

@@ -91,10 +91,20 @@ function hasGitNexusServerOwner(gitNexusDir) {
   return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid);
 }
 
+/**
+ * Whether opt-in diagnostics should be written to the hook's stderr. Strict
+ * hook runners validate hook output, so normal, non-error skip paths must stay
+ * silent unless the operator explicitly asks for diagnostics via GITNEXUS_DEBUG.
+ * See issue #1913.
+ */
+function isDebugEnabled() {
+  return process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+}
+
 function extractAugmentContext(stderr) {
   const output = (stderr || '').trim();
   const marker = output.indexOf('[GitNexus]');
-  const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+  const debug = isDebugEnabled();
   if (debug && output.length > 0) {
     // Emit the FULL discarded prefix (everything before the marker, or all of
     // it when no marker is present) so suppressed diagnostics — LadybugDB lock
@@ -258,8 +268,14 @@ function buildAfterToolContext(input) {
     if (/\bgit\s+(commit|merge|rebase|cherry-pick|pull)(\s|$)/.test(command)) {
       const hint = buildStaleIndexHint(gitNexusDir, cwd);
       if (hint) {
-        process.stderr.write(`${hint}\n`);
+        // The hint always reaches the agent via additionalContext (parts). Mirror
+        // it to stderr (for terminal users) only under GITNEXUS_DEBUG, so strict
+        // hook runners see no unexpected output on this normal path (#1913). The
+        // claude hook never mirrored this to stderr — this aligns the two adapters.
         parts.push(hint);
+        if (isDebugEnabled()) {
+          process.stderr.write(`${hint}\n`);
+        }
       }
     }
   }
@@ -269,7 +285,11 @@ function buildAfterToolContext(input) {
 
 function runAugment(gitNexusDir, cwd, pattern) {
   if (hasGitNexusServerOwner(gitNexusDir)) {
-    process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    // Normal skip path: the MCP server owns the DB. Stay silent for strict
+    // hook runners (issue #1913); surface the reason only under GITNEXUS_DEBUG.
+    if (isDebugEnabled()) {
+      process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    }
     return '';
   }
   const release = acquireHookSlot(gitNexusDir);
@@ -338,7 +358,7 @@ function main() {
     const handler = handlers[input.hook_event_name || ''];
     if (handler) handler(input);
   } catch (err) {
-    if (process.env.GITNEXUS_DEBUG) {
+    if (isDebugEnabled()) {
       console.error('GitNexus antigravity hook error:', (err.message || '').slice(0, 200));
     }
   }

package/hooks/claude/gitnexus-hook.cjs

@@ -110,10 +110,20 @@ function hasGitNexusServerOwner(gitNexusDir) {
   return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid);
 }
 
+/**
+ * Whether opt-in diagnostics should be written to the hook's stderr. Strict
+ * hook runners (e.g. Codex `PreToolUse`) validate hook output, so normal,
+ * non-error skip paths must stay silent unless the operator explicitly asks
+ * for diagnostics via GITNEXUS_DEBUG. See issue #1913.
+ */
+function isDebugEnabled() {
+  return process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+}
+
 function extractAugmentContext(stderr) {
   const output = (stderr || '').trim();
   const marker = output.indexOf('[GitNexus]');
-  const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true';
+  const debug = isDebugEnabled();
   if (debug && output.length > 0) {
     // Emit the FULL discarded prefix (everything before the marker, or all of
     // it when no marker is present) so suppressed diagnostics — KuzuDB lock
@@ -250,7 +260,12 @@ function handlePreToolUse(input) {
   const pattern = extractPattern(toolName, toolInput);
   if (!pattern || pattern.length < 3) return;
   if (hasGitNexusServerOwner(gitNexusDir)) {
-    process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    // Normal skip path: the MCP server owns the DB, so the CLI augment would
+    // contend on the lock. Stay silent for strict hook runners (issue #1913);
+    // surface the reason only when diagnostics are explicitly requested.
+    if (isDebugEnabled()) {
+      process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n');
+    }
     return;
   }
 
@@ -361,7 +376,7 @@ function main() {
     const handler = handlers[input.hook_event_name || ''];
     if (handler) handler(input);
   } catch (err) {
-    if (process.env.GITNEXUS_DEBUG) {
+    if (isDebugEnabled()) {
       console.error('GitNexus hook error:', (err.message || '').slice(0, 200));
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.8-rc.3",
+  "version": "1.6.8-rc.5",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",