feat(integration): scene-driven tool descriptions, hook improvements, and UX fixes

- MCP tool descriptions: all 12 tools now have "Use when:" trigger conditions
  for improved Claude Code auto-invocation (scene-driven > functional descriptions)
- MCP instructions: add 7 intent→tool decision rules mapping user goals to tools
- Skill/command descriptions: all 5 commands updated with "Use when:" triggers
- CLI: add --refs/--impact short aliases for show command
- MCP get_ast_node: add include_tests parameter, filter test callers by default
  (consistent with CLI show --include-refs behavior)
- Pre-edit hook: grep-based fallback detects containing function for body edits
  (previously only triggered on function signature lines)
- User-prompt hook: backtick symbol extraction for mixed Chinese+code prompts
- JSON safety: replace manual string escaping with serde_json in error responses
- Help text: show --refs/--impact as primary flags, expand --include-tests scope

Breaking: overview/trace/deps exit code 1 (was 0) when no results found.
This is semantically correct (no-match = error) but may affect external scripts.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: sdsrss

.claude-plugin/marketplace.json

@@ -5,14 +5,14 @@
   },
   "metadata": {
     "description": "AST knowledge graph plugin for Claude Code — semantic search, call graph, HTTP tracing, impact analysis",
-    "version": "0.7.13"
+    "version": "0.7.14"
   },
   "plugins": [
     {
       "name": "code-graph-mcp",
       "source": "./claude-plugin",
       "description": "AST knowledge graph for intelligent code navigation — auto-indexes your codebase and provides semantic search, call graph traversal, HTTP route tracing, and impact analysis via MCP tools",
-      "version": "0.7.13",
+      "version": "0.7.14",
       "author": {
         "name": "sdsrs"
       },

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "code-graph-mcp"
-version = "0.7.13"
+version = "0.7.14"
 edition = "2021"
 
 [features]

claude-plugin/.claude-plugin/plugin.json

@@ -4,7 +4,7 @@
   "author": {
     "name": "sdsrs"
   },
-  "version": "0.7.13",
+  "version": "0.7.14",
   "keywords": [
     "code-graph",
     "ast",

claude-plugin/commands/impact.md

@@ -1,5 +1,5 @@
 ---
-description: Analyze impact scope before modifying a symbol
+description: Analyze blast radius before modifying a symbol. Use when about to edit/rename/remove a function, or asked about change risk and affected callers.
 argument-hint: <symbol_name>
 ---
 

claude-plugin/commands/rebuild.md

@@ -1,5 +1,5 @@
 ---
-description: Force a full code-graph index rebuild
+description: Force code-graph index rebuild. Use when search results seem stale or wrong, after major codebase restructuring, or when index health check reports issues.
 ---
 
 Run via Bash: `code-graph-mcp incremental-index`

claude-plugin/commands/status.md

@@ -1,5 +1,5 @@
 ---
-description: Show code-graph index status
+description: Show code-graph index health and coverage. Use when search returns unexpected results, checking if index is current, or diagnosing code-graph issues.
 ---
 
 !`code-graph-mcp health-check --format json 2>/dev/null || echo '{"error":"No index found"}'`

claude-plugin/commands/trace.md

@@ -1,5 +1,5 @@
 ---
-description: Trace call flow from a handler or route
+description: Trace call flow from a handler or route. Use when debugging API behavior, understanding request processing flow, or asked how an endpoint works.
 argument-hint: <handler_or_route>
 ---
 

claude-plugin/commands/understand.md

@@ -1,5 +1,5 @@
 ---
-description: Deep dive into a module or file's architecture
+description: Deep dive into a module's architecture. Use when starting work in an unfamiliar area, asked to explain how code works, or before implementing changes in a module.
 argument-hint: <file_or_dir_path>
 ---
 

claude-plugin/scripts/pre-edit-guide.js

@@ -47,6 +47,45 @@ for (const pat of fnPatterns) {
   }
 }
 
+// Fallback: if old_string is inside a function body (not a definition),
+// extract a unique identifier from the code and grep for it to find the containing function
+if (!symbol || symbol.length < 3) {
+  const filePath = (input.tool_input && input.tool_input.file_path) || '';
+  if (filePath && oldStr.length >= 10) {
+    try {
+      // Extract identifiers from old_string, try the most specific one first
+      const identifiers = (oldStr.match(/\b([a-z]\w*(?:_\w+)+|[a-z]\w*(?:[A-Z]\w*)+|[A-Z]\w+\.\w+|[A-Z]\w+::\w+)\b/g) || [])
+        .filter(id => id.length >= 6);
+      const skipWords = new Set(['return', 'function', 'default', 'require', 'module', 'exports', 'import', 'console']);
+      // Sort by length descending (longer = more specific = fewer matches)
+      const candidates = [...new Set(identifiers)]
+        .filter(id => !skipWords.has(id.toLowerCase()))
+        .sort((a, b) => b.length - a.length);
+      for (const candidate of candidates.slice(0, 5)) {
+        try {
+          const raw = execFileSync('code-graph-mcp', ['grep', candidate, filePath, '--json'], {
+            cwd, timeout: 2000, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+          });
+          const grepResult = JSON.parse(raw);
+          // Pick this candidate if it has few matches (precise location)
+          const withContainer = (grepResult || []).filter(m => m.container && m.container.name);
+          if (withContainer.length > 0 && withContainer.length <= 5) {
+            // If multiple containers, vote for the most common one
+            const votes = {};
+            for (const m of withContainer) {
+              const cn = m.container.name;
+              votes[cn] = (votes[cn] || 0) + 1;
+            }
+            const best = Object.entries(votes).sort((a, b) => b[1] - a[1])[0][0];
+            symbol = best.includes('.') ? best.split('.').pop() : best.includes('::') ? best.split('::').pop() : best;
+            break;
+          }
+        } catch { /* try next candidate */ }
+      }
+    } catch { /* grep failed or no match — fall through */ }
+  }
+}
+
 if (!symbol || symbol.length < 3) process.exit(0);
 
 // Skip common patterns that aren't real function names

claude-plugin/scripts/user-prompt-context.js

@@ -95,12 +95,20 @@ if (/^(修复|优化|实施|执行|开始|按|实测|帮我|进入|用|重新)/.
 const filePaths = (message.match(/(?:src|lib|test|pkg|cmd|internal|app|components?)\/[\w/.-]+/g) || [])
   .slice(0, 2);
 
-// Extract potential symbol names (camelCase, snake_case, PascalCase, qualified like Foo::bar)
-const symbolCandidates = (message.match(/\b(?:[A-Z]\w*(?:::\w+)+|[a-z]\w*(?:_\w+){1,}|[a-z]\w*(?:[A-Z]\w*)+|[A-Z][a-z]+(?:[A-Z][a-z]+)+)\b/g) || [])
+// Extract potential symbol names (camelCase, snake_case, PascalCase, qualified like Foo::bar, Foo.bar, Foo::bar::baz)
+const symbolCandidates = (message.match(/\b(?:[A-Z]\w*(?:(?:::|\.)\w+)+|[a-z]\w*(?:_\w+){1,}|[a-z]\w*(?:[A-Z]\w*)+|[A-Z][a-z]+(?:[A-Z][a-z]+)+)\b/g) || [])
   .filter(s => s.length > 4)
   .filter(s => !STOP_WORDS.has(s.toLowerCase()))
   .slice(0, 3);
 
+// Fallback: extract backtick-quoted symbols (common in mixed Chinese+code: "修改 `parse_code` 函数")
+if (symbolCandidates.length === 0) {
+  const backtickSymbols = (message.match(/`([a-zA-Z_]\w{2,})`/g) || [])
+    .map(s => s.replace(/`/g, ''))
+    .filter(s => s.length >= 3 && !STOP_WORDS.has(s.toLowerCase()));
+  symbolCandidates.push(...backtickSymbols.slice(0, 3));
+}
+
 // Fallback: plain lowercase words (8+ chars) likely to be function/type names.
 // Only when strict patterns found nothing — avoids false positives from English prose.
 // Minimum 8 chars filters most common English words while keeping technical terms