@mrclrchtr/supi-code-intelligence 1.6.0 → 1.7.0

package/src/target-resolution.ts

@@ -8,7 +8,7 @@ import { isWithinOrEqual } from "@mrclrchtr/supi-core/api";
 import { type Position, type SessionLspService, toLspPosition } from "@mrclrchtr/supi-lsp/api";
 import { getSemanticService, getSemanticServiceState } from "./providers/semantic-provider.ts";
 import { withStructuralSession } from "./providers/structural-provider.ts";
-import { escapeRegex, normalizePath } from "./search-helpers.ts";
+import { normalizePath } from "./search-helpers.ts";
 import { highestConfidence } from "./semantic-action-helpers.ts";
 import type { ConfidenceMode, DisambiguationCandidate } from "./types.ts";
 
@@ -64,7 +64,7 @@ export function resolveAnchoredTarget(
   if (isBinaryFile(resolvedFile)) {
     return {
       kind: "error",
-      message: `File type not supported for semantic analysis: \`${file}\`. Try \`code_intel pattern\` for text search.`,
+      message: `File type not supported for semantic analysis: \`${file}\`. Use \`code_pattern\` for explicit text search.`,
     };
   }
 
@@ -101,7 +101,7 @@ export async function resolveFileTargetGroup(
   if (isBinaryFile(resolvedFile)) {
     return {
       kind: "error",
-      message: `File type not supported for semantic analysis: \`${file}\`. Try \`code_intel pattern\` for text search.`,
+      message: `File type not supported for semantic analysis: \`${file}\`. Use \`code_pattern\` for explicit text search.`,
     };
   }
 
@@ -132,7 +132,7 @@ export async function resolveFileTargetGroup(
 
 /**
  * Resolve a target from symbol discovery — finds matching declarations.
- * Uses LSP workspace symbols when available, falls back to Tree-sitter/text search.
+ * Symbol discovery is semantic-only; it does not fall back to text search.
  */
 export async function resolveSymbolTarget(
   symbol: string,
@@ -145,14 +145,19 @@ export async function resolveSymbolTarget(
 ): Promise<TargetResolutionResult> {
   const lspState = await getSemanticServiceState(cwd, { waitForReady: true });
 
-  if (lspState.kind === "ready") {
-    return resolveSymbolViaLsp(symbol, cwd, lspState.service, options);
+  if (lspState.kind !== "ready") {
+    return {
+      kind: "error",
+      message:
+        `Symbol discovery for \`${symbol}\` requires active LSP. ` +
+        "Use `file` + coordinates, or enable LSP and retry.",
+    };
   }
 
-  // Structural fallback via text search
-  return resolveSymbolViaSearch(symbol, cwd, options);
+  return resolveSymbolViaLsp(symbol, cwd, lspState.service, options);
 }
 
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: pre-existing — not introduced by this change
 async function resolveSymbolViaLsp(
   symbol: string,
   cwd: string,
@@ -202,7 +207,12 @@ async function resolveSymbolViaLsp(
 
   if (candidates.length === 1) {
     const c = candidates[0];
-    const loc = "location" in c ? c.location : null;
+    const rawLoc = "location" in c ? c.location : null;
+    // WorkspaceSymbol.location may be Location | { uri: string }; we need range.
+    const loc =
+      rawLoc && "range" in rawLoc
+        ? (rawLoc as { uri: string; range: { start: { line: number; character: number } } })
+        : null;
     if (!loc) {
       return { kind: "error", message: `Symbol not found: \`${symbol}\`` };
     }
@@ -235,95 +245,6 @@ async function resolveSymbolViaLsp(
   };
 }
 
-// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: ripgrep-based symbol discovery with pattern parsing
-async function resolveSymbolViaSearch(
-  symbol: string,
-  cwd: string,
-  options?: { path?: string; kind?: string; exportedOnly?: boolean },
-): Promise<TargetResolutionResult> {
-  const { execFileSync } = await import("node:child_process");
-  const scopePath = options?.path ? normalizePath(options.path, cwd) : cwd;
-
-  try {
-    const exportOnly = options?.exportedOnly;
-    const pattern = exportOnly
-      ? `export\\s+(function|class|interface|type|const|let|var)\\s+${escapeRegex(symbol)}\\b`
-      : `(function|class|interface|type|const|let|var|export)\\s+${escapeRegex(symbol)}\\b`;
-    let output: string;
-    try {
-      output = execFileSync("rg", ["--json", "-m", "10", "-e", pattern, scopePath], {
-        encoding: "utf-8",
-        cwd,
-        timeout: 5000,
-        stdio: ["pipe", "pipe", "pipe"],
-      });
-    } catch (err: unknown) {
-      // rg exits 1 for no-match; capture stdout if available
-      const e = err as { status?: number; stdout?: string };
-      output = e.stdout ?? "";
-    }
-
-    const matches: Array<{ file: string; line: number; text: string }> = [];
-    for (const line of output.split("\n")) {
-      if (!line.trim()) continue;
-      try {
-        const parsed = JSON.parse(line);
-        if (parsed.type === "match" && parsed.data) {
-          const filePath = parsed.data.path?.text;
-          const lineNum = parsed.data.line_number;
-          const text = parsed.data.lines?.text?.trim();
-          if (filePath && lineNum) {
-            matches.push({ file: filePath, line: lineNum, text: text ?? "" });
-          }
-        }
-      } catch {
-        // Skip malformed JSON lines
-      }
-    }
-
-    if (matches.length === 0) {
-      return { kind: "error", message: `Symbol not found: \`${symbol}\`` };
-    }
-
-    if (matches.length === 1) {
-      const m = matches[0];
-      const resolvedFile = path.resolve(cwd, m.file);
-      return {
-        kind: "resolved",
-        target: {
-          file: resolvedFile,
-          position: { line: m.line - 1, character: 0 },
-          displayLine: m.line,
-          displayCharacter: 1,
-          name: symbol,
-          kind: null,
-          confidence: "heuristic",
-        },
-      };
-    }
-
-    // Multiple matches — disambiguation
-    const disambiguated: DisambiguationCandidate[] = matches.slice(0, 8).map((m, idx) => ({
-      name: symbol,
-      kind: null,
-      container: null,
-      file: m.file,
-      line: m.line,
-      character: 1,
-      reason: m.text.slice(0, 80),
-      rank: idx + 1,
-    }));
-
-    return {
-      kind: "disambiguation",
-      candidates: disambiguated,
-      omittedCount: Math.max(0, matches.length - 8),
-    };
-  } catch {
-    return { kind: "error", message: `Symbol not found: \`${symbol}\`` };
-  }
-}
-
 async function resolveFileTargetsViaLsp(
   resolvedFile: string,
   cwd: string,
@@ -488,26 +409,30 @@ function mapCandidateToDisambiguation(
     name: string;
     kind: number;
     containerName?: string | null;
-    location?: { uri: string; range: { start: { line: number; character: number } } } | null;
+    location?: { uri: string } | null;
   },
   idx: number,
   cwd: string,
 ): DisambiguationCandidate {
-  const loc = "location" in c ? c.location : null;
+  const loc = c.location;
   const filePath = loc
     ? loc.uri.startsWith("file://")
       ? decodeURIComponent(loc.uri.slice(7))
       : loc.uri
     : "";
   const relPath = filePath ? path.relative(cwd, filePath) : "";
+  const rangeObj =
+    loc && "range" in loc
+      ? (loc as unknown as { range: { start: { line: number; character: number } } }).range
+      : null;
 
   return {
     name: c.name,
     kind: symbolKindName(c.kind),
     container: "containerName" in c ? (c.containerName ?? null) : null,
     file: relPath,
-    line: loc ? loc.range.start.line + 1 : 0,
-    character: loc ? loc.range.start.character + 1 : 0,
+    line: rangeObj ? rangeObj.start.line + 1 : 0,
+    character: rangeObj ? rangeObj.start.character + 1 : 0,
     reason: relPath,
     rank: idx + 1,
   };

package/src/tool/execute-affected.ts

@@ -0,0 +1,25 @@
+import { executeAffectedAction } from "../actions/affected-action.ts";
+import type { CodeIntelResult } from "../types.ts";
+import { validateFocusedToolParams } from "./validation.ts";
+
+export interface CodeAffectedToolParams {
+  file?: string;
+  line?: number;
+  character?: number;
+  symbol?: string;
+  exportedOnly?: boolean;
+  maxResults?: number;
+}
+
+/** Execute the public code_affected tool through the substrate-only affected action. */
+export async function executeAffectedTool(
+  params: CodeAffectedToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const error = validateFocusedToolParams(params, ctx.cwd);
+  if (error) {
+    return { content: error, details: undefined };
+  }
+
+  return executeAffectedAction(params, ctx.cwd);
+}

package/src/tool/execute-brief.ts

@@ -0,0 +1,25 @@
+import { executeBriefAction } from "../actions/brief-action.ts";
+import type { CodeIntelResult } from "../types.ts";
+import { validateFocusedToolParams } from "./validation.ts";
+
+export interface CodeBriefToolParams {
+  path?: string;
+  file?: string;
+  line?: number;
+  character?: number;
+  symbol?: string;
+  maxResults?: number;
+}
+
+/** Execute the public code_brief tool through the existing brief action. */
+export async function executeBriefTool(
+  params: CodeBriefToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const error = validateFocusedToolParams(params, ctx.cwd);
+  if (error) {
+    return { content: error, details: undefined };
+  }
+
+  return executeBriefAction(params, ctx.cwd);
+}

package/src/tool/execute-map.ts

@@ -0,0 +1,32 @@
+import * as fs from "node:fs";
+import { executeMapAction } from "../actions/map-action.ts";
+import { normalizePath } from "../search-helpers.ts";
+import type { CodeIntelResult } from "../types.ts";
+
+export interface CodeMapToolParams {
+  path?: string;
+}
+
+/** Execute the public code_map tool with focused directory validation. */
+export async function executeMapTool(
+  params: CodeMapToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const scopePath = params.path ? normalizePath(params.path, ctx.cwd) : ctx.cwd;
+
+  if (!fs.existsSync(scopePath)) {
+    return {
+      content: `**Error:** code_map path not found: \`${params.path ?? scopePath}\``,
+      details: undefined,
+    };
+  }
+
+  if (!fs.statSync(scopePath).isDirectory()) {
+    return {
+      content: "**Error:** code_map requires a directory path, not a file.",
+      details: undefined,
+    };
+  }
+
+  return executeMapAction(scopePath, ctx.cwd);
+}

package/src/tool/execute-pattern.ts

@@ -0,0 +1,26 @@
+import { executePatternAction } from "../actions/pattern-action.ts";
+import type { CodeIntelResult } from "../types.ts";
+import { validatePatternToolParams } from "./validation.ts";
+
+export interface CodePatternToolParams {
+  path?: string;
+  pattern: string;
+  regex?: boolean;
+  kind?: string;
+  maxResults?: number;
+  contextLines?: number;
+  summary?: boolean;
+}
+
+/** Execute the public code_pattern tool as the sole heuristic/structured search surface. */
+export async function executePatternTool(
+  params: CodePatternToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const error = validatePatternToolParams(params, ctx.cwd);
+  if (error) {
+    return { content: error, details: undefined };
+  }
+
+  return executePatternAction(params, ctx.cwd);
+}

package/src/tool/execute-relations.ts

@@ -0,0 +1,48 @@
+import { executeCalleesAction } from "../actions/callees-action.ts";
+import { executeCallersAction } from "../actions/callers-action.ts";
+import { executeImplementationsAction } from "../actions/implementations-action.ts";
+import type { CodeIntelResult } from "../types.ts";
+import type { CodeRelationsKind } from "./tool-specs.ts";
+import { validateFocusedToolParams } from "./validation.ts";
+
+export interface CodeRelationsToolParams {
+  kind: CodeRelationsKind;
+  path?: string;
+  file?: string;
+  line?: number;
+  character?: number;
+  symbol?: string;
+  exportedOnly?: boolean;
+  maxResults?: number;
+}
+
+const RELATION_HANDLERS = {
+  callers: executeCallersAction,
+  callees: executeCalleesAction,
+  implementations: executeImplementationsAction,
+} as const;
+
+/** Execute the public code_relations tool by dispatching to the selected substrate-backed relation action. */
+export async function executeRelationsTool(
+  params: CodeRelationsToolParams,
+  ctx: { cwd: string },
+): Promise<CodeIntelResult> {
+  const error = validateFocusedToolParams(params, ctx.cwd);
+  if (error) {
+    return { content: error, details: undefined };
+  }
+
+  const handler = RELATION_HANDLERS[params.kind];
+  return handler(
+    {
+      path: params.path,
+      file: params.file,
+      line: params.line,
+      character: params.character,
+      symbol: params.symbol,
+      exportedOnly: params.exportedOnly,
+      maxResults: params.maxResults,
+    },
+    ctx.cwd,
+  );
+}

package/src/tool/guidance.ts

@@ -1,18 +1,29 @@
-// Prompt guidance and tool description for the code_intel tool.
+// Prompt guidance and tool descriptions for the focused code-intelligence tool surface.
 
-import { CODE_INTEL_ACTION_SPECS, formatCodeIntelActionList } from "./action-specs.ts";
+import { CODE_INTELLIGENCE_TOOL_SPECS, type CodeIntelligenceToolName } from "./tool-specs.ts";
 
-export const toolDescription = `Code intelligence tool — codebase orientation, semantic relationships, impact analysis, and scoped search.
+export interface CodeIntelligenceToolPromptSurface {
+  description: string;
+  promptSnippet: string;
+  promptGuidelines: string[];
+}
 
-Actions: ${formatCodeIntelActionList()}.
+export type CodeIntelligenceToolPromptSurfaceMap = Record<
+  CodeIntelligenceToolName,
+  CodeIntelligenceToolPromptSurface
+>;
 
-Use code_intel to localize relevant files before precise drill-down: summarize a project/package/file, find callers/callees/implementations, estimate blast radius, or search within a scope. Prefer lsp_lookup, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_refactor, and lsp_recover for semantic drill-down once the target is known; use tree_sitter for exact syntax and read/rg once you know the file. line and character are 1-based and require file. pattern is literal unless regex is true; kind supports definition, export, or import. Relative paths resolve from cwd, and leading @ on path/file is stripped.`;
+export function buildCodeIntelligenceToolPromptSurfaces(): CodeIntelligenceToolPromptSurfaceMap {
+  return Object.fromEntries(
+    CODE_INTELLIGENCE_TOOL_SPECS.map((spec) => [
+      spec.name,
+      {
+        description: spec.description,
+        promptSnippet: spec.promptSnippet,
+        promptGuidelines: [...spec.basePromptGuidelines],
+      } satisfies CodeIntelligenceToolPromptSurface,
+    ]),
+  ) as CodeIntelligenceToolPromptSurfaceMap;
+}
 
-export const promptGuidelines = [
-  ...CODE_INTEL_ACTION_SPECS.map((spec) => spec.promptGuideline),
-  "Use code_intel with `file`, `line`, and `character` for anchored positions; do not pair `line` or `character` with `path`.",
-  "Use code_intel first when the area is not yet localized; switch to lsp_lookup, lsp_document_symbols, lsp_workspace_symbols, lsp_diagnostics, lsp_refactor, or lsp_recover for semantic drill-down once code_intel narrows the target.",
-];
-
-export const promptSnippet =
-  "code_intel — codebase orientation, callers/callees, blast radius, and scoped search before file drill-down";
+export const CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES = buildCodeIntelligenceToolPromptSurfaces();

package/src/tool/register-tools.ts

@@ -0,0 +1,32 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES,
+  type CodeIntelligenceToolPromptSurfaceMap,
+} from "./guidance.ts";
+import { CODE_INTELLIGENCE_TOOL_SPECS } from "./tool-specs.ts";
+
+/** Register the focused code-intelligence tool surface from shared specs. */
+export function registerCodeIntelligenceTools(
+  pi: ExtensionAPI,
+  promptSurfaces: CodeIntelligenceToolPromptSurfaceMap = CODE_INTELLIGENCE_TOOL_PROMPT_SURFACES,
+): void {
+  for (const spec of CODE_INTELLIGENCE_TOOL_SPECS) {
+    const surface = promptSurfaces[spec.name];
+    pi.registerTool({
+      name: spec.name,
+      label: spec.label,
+      description: surface.description,
+      promptSnippet: surface.promptSnippet,
+      promptGuidelines: surface.promptGuidelines,
+      parameters: spec.parameters,
+      // biome-ignore lint/complexity/useMaxParams: pi ToolDefinition.execute signature
+      execute: async (_toolCallId, params, _signal, _onUpdate, ctx: ExtensionContext) => {
+        const { content, details } = await spec.run(params, { cwd: ctx.cwd });
+        return {
+          content: [{ type: "text" as const, text: content }],
+          details,
+        };
+      },
+    });
+  }
+}

package/src/tool/tool-specs.ts

@@ -0,0 +1,184 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type TSchema, Type } from "typebox";
+import type { CodeIntelResult } from "../types.ts";
+import { executeAffectedTool } from "./execute-affected.ts";
+import { executeBriefTool } from "./execute-brief.ts";
+import { executeMapTool } from "./execute-map.ts";
+import { executePatternTool } from "./execute-pattern.ts";
+import { executeRelationsTool } from "./execute-relations.ts";
+
+const PathParam = Type.String({ description: "Scope or focus path (package, directory, or file)" });
+const FileParam = Type.String({
+  description:
+    "Anchored target file (use with line/character) or a file-level semantic target where supported",
+});
+const LineParam = Type.Number({ description: "1-based line number for anchored target" });
+const CharacterParam = Type.Number({
+  description: "1-based character column (UTF-16) for anchored target",
+});
+const SymbolParam = Type.String({ description: "Symbol name for discovery-based resolution" });
+const PatternParam = Type.String({ description: "Text search pattern" });
+const RegexParam = Type.Boolean({ description: "Use regex semantics instead of literal matching" });
+const ExportedOnlyParam = Type.Boolean({ description: "Limit discovery to exported symbols" });
+const MaxResultsParam = Type.Number({ description: "Maximum results to return" });
+const ContextLinesParam = Type.Number({ description: "Context lines around matches" });
+const SummaryParam = Type.Boolean({
+  description: "Aggregate counts by directory instead of line-level matches",
+});
+const StructuredPatternKindParam = Type.String({
+  description: "Structured pattern kind (`definition` | `export` | `import`)",
+});
+
+export const CODE_INTELLIGENCE_TOOL_NAMES = [
+  "code_brief",
+  "code_map",
+  "code_relations",
+  "code_affected",
+  "code_pattern",
+] as const;
+export type CodeIntelligenceToolName = (typeof CODE_INTELLIGENCE_TOOL_NAMES)[number];
+
+export const CODE_RELATION_KIND_NAMES = ["callers", "callees", "implementations"] as const;
+export type CodeRelationsKind = (typeof CODE_RELATION_KIND_NAMES)[number];
+
+const CodeRelationsKindEnum = StringEnum(CODE_RELATION_KIND_NAMES);
+
+const CodeBriefParameters = Type.Object(
+  {
+    path: Type.Optional(PathParam),
+    file: Type.Optional(FileParam),
+    line: Type.Optional(LineParam),
+    character: Type.Optional(CharacterParam),
+    symbol: Type.Optional(SymbolParam),
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+const CodeMapParameters = Type.Object(
+  {
+    path: Type.Optional(Type.String({ description: "Project, package, or directory path to map" })),
+  },
+  { additionalProperties: false },
+);
+
+const CodeRelationsParameters = Type.Object(
+  {
+    kind: CodeRelationsKindEnum,
+    path: Type.Optional(PathParam),
+    file: Type.Optional(FileParam),
+    line: Type.Optional(LineParam),
+    character: Type.Optional(CharacterParam),
+    symbol: Type.Optional(SymbolParam),
+    exportedOnly: Type.Optional(ExportedOnlyParam),
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+const CodeAffectedParameters = Type.Object(
+  {
+    file: Type.Optional(FileParam),
+    line: Type.Optional(LineParam),
+    character: Type.Optional(CharacterParam),
+    symbol: Type.Optional(SymbolParam),
+    exportedOnly: Type.Optional(ExportedOnlyParam),
+    maxResults: Type.Optional(MaxResultsParam),
+  },
+  { additionalProperties: false },
+);
+
+const CodePatternParameters = Type.Object(
+  {
+    path: Type.Optional(PathParam),
+    pattern: PatternParam,
+    regex: Type.Optional(RegexParam),
+    kind: Type.Optional(StructuredPatternKindParam),
+    maxResults: Type.Optional(MaxResultsParam),
+    contextLines: Type.Optional(ContextLinesParam),
+    summary: Type.Optional(SummaryParam),
+  },
+  { additionalProperties: false },
+);
+
+export interface CodeIntelligenceToolDefinitionSpec {
+  name: CodeIntelligenceToolName;
+  label: string;
+  description: string;
+  promptSnippet: string;
+  basePromptGuidelines: string[];
+  parameters: TSchema;
+  run: (params: unknown, ctx: { cwd: string }) => Promise<CodeIntelResult> | CodeIntelResult;
+}
+
+export const CODE_INTELLIGENCE_TOOL_SPECS = [
+  {
+    name: "code_brief",
+    label: "Code Brief",
+    description:
+      "Code brief tool — interpretive orientation for a project, package, directory, file, or symbol. Use code_brief when you need prioritized context and start-here guidance rather than raw search output.",
+    promptSnippet: "code_brief — interpretive orientation and start-here guidance",
+    basePromptGuidelines: [
+      "Use code_brief for a project, package, directory, file, or symbol overview when you need prioritized context.",
+      "Use code_brief before deeper drill-down when you want a start-here recommendation instead of raw inventory output.",
+    ],
+    parameters: CodeBriefParameters,
+    run: (params, ctx) => executeBriefTool(params as Parameters<typeof executeBriefTool>[0], ctx),
+  },
+  {
+    name: "code_map",
+    label: "Code Map",
+    description:
+      "Code map tool — factual inventory for a repo, package, or directory. Use code_map when you want counts, child directories, language mix, and landmark files without interpretive guidance.",
+    promptSnippet: "code_map — factual project, package, or directory inventory",
+    basePromptGuidelines: [
+      "Use code_map for a factual repo, package, or directory map when you need counts, landmark files, and local structure without interpretation.",
+      "Use code_map with `path` for any directory path you want to inventory; code_map should stay factual rather than prioritized.",
+    ],
+    parameters: CodeMapParameters,
+    run: (params, ctx) => executeMapTool(params as Parameters<typeof executeMapTool>[0], ctx),
+  },
+  {
+    name: "code_relations",
+    label: "Code Relations",
+    description:
+      'Code relations tool — trace callers, callees, or implementations for a resolved target. Use code_relations with `kind: "callers" | "callees" | "implementations"` when you need semantic or structural relationships rather than broad search.',
+    promptSnippet: "code_relations — callers, callees, or implementations for a resolved target",
+    basePromptGuidelines: [
+      'Use code_relations with `kind: "callers"` to find who invokes a symbol or file-level surface.',
+      'Use code_relations with `kind: "callees"` to inspect outgoing calls from a function or method at a known position.',
+      'Use code_relations with `kind: "implementations"` to find which concrete types implement a declaration.',
+    ],
+    parameters: CodeRelationsParameters,
+    run: (params, ctx) =>
+      executeRelationsTool(params as Parameters<typeof executeRelationsTool>[0], ctx),
+  },
+  {
+    name: "code_affected",
+    label: "Code Affected",
+    description:
+      "Code affected tool — estimate blast radius, downstream impact, and risk for a target. Use code_affected before edits when you need an impact-oriented view rather than a plain relationship list.",
+    promptSnippet: "code_affected — blast radius, downstream impact, and risk",
+    basePromptGuidelines: [
+      "Use code_affected before edits when you need blast radius, downstream impact, and likely follow-up checks.",
+      "Use code_affected after you have a concrete file/position or symbol target to estimate change risk.",
+    ],
+    parameters: CodeAffectedParameters,
+    run: (params, ctx) =>
+      executeAffectedTool(params as Parameters<typeof executeAffectedTool>[0], ctx),
+  },
+  {
+    name: "code_pattern",
+    label: "Code Pattern",
+    description:
+      "Code pattern tool — explicit literal, regex, or structured search within a bounded scope. Use code_pattern when you intentionally want search behavior rather than semantic or structural relationships.",
+    promptSnippet: "code_pattern — explicit literal, regex, or structured search",
+    basePromptGuidelines: [
+      "Use code_pattern for explicit literal or regex search within a bounded path.",
+      'Use code_pattern with `kind: "definition" | "export" | "import"` for structured search instead of plain text matching.',
+    ],
+    parameters: CodePatternParameters,
+    run: (params, ctx) =>
+      executePatternTool(params as Parameters<typeof executePatternTool>[0], ctx),
+  },
+] as const satisfies readonly CodeIntelligenceToolDefinitionSpec[];

package/src/tool/validation.ts

@@ -0,0 +1,43 @@
+import * as fs from "node:fs";
+import type { CodeQueryParams } from "../query-params.ts";
+import { normalizePath } from "../search-helpers.ts";
+
+const STRUCTURED_PATTERN_KINDS = new Set(["definition", "export", "import"]);
+
+/** Shared validation for focused tool inputs that can anchor into files. */
+export function validateFocusedToolParams(
+  params: Pick<CodeQueryParams, "path" | "file" | "line" | "character">,
+  cwd: string,
+): string | null {
+  if (params.path && (params.line != null || params.character != null)) {
+    return "**Error:** `line` and `character` require `file`, not `path`. Use `path` to scope/focus; use `file` to anchor a position.";
+  }
+
+  if (params.file) {
+    const resolvedFile = normalizePath(params.file, cwd);
+    if (fs.existsSync(resolvedFile) && fs.statSync(resolvedFile).isDirectory()) {
+      return "**Error:** `file` points to a directory. Use `path` to scope a directory; use `file` to anchor a position in a file.";
+    }
+  }
+
+  if ((params.line != null || params.character != null) && !params.file) {
+    return "**Error:** `line` and `character` require `file`.";
+  }
+
+  return null;
+}
+
+/** Shared validation for explicit pattern-tool input. */
+export function validatePatternToolParams(
+  params: Pick<CodeQueryParams, "path" | "file" | "line" | "character" | "kind">,
+  cwd: string,
+): string | null {
+  const commonError = validateFocusedToolParams(params, cwd);
+  if (commonError) return commonError;
+
+  if (params.kind && !STRUCTURED_PATTERN_KINDS.has(params.kind)) {
+    return "**Error:** `code_pattern` `kind` must be one of `definition`, `export`, or `import`.";
+  }
+
+  return null;
+}