Method execute

src/mcp/tools.ts:2645–2796

* Execute a tool by name. * * `sessionState` is the CALLER's per-session explore history (CG-17). The * daemon shares one ToolHandler across every connected session, so this state * cannot live on the handler — each session owns one and hands it in, which is * what keeps two sessions

(
    toolName: string,
    args: Record<string, unknown>,
    sessionState?: ExploreSessionState,
  )

   * Omit it (the CLI does) and explore behaves exactly as before, untracked.
   */
  async execute(
    toolName: string,
    args: Record<string, unknown>,
    sessionState?: ExploreSessionState,
  ): Promise<ToolResult> {
    if (this.closing) return this.textResult('This MCP session is closing; retry with a connected session.');
    this.activeCalls++;
    try {
      // Block the first tool call on the engine's post-open reconcile so we
      // never serve rows for files deleted/edited while no MCP server was
      // running. The wait is time-boxed (#905): a huge-repo reconcile takes
      // minutes, and blocking the first call on all of it reads as a hang, so
      // we wait briefly then serve and let it finish in the background. The
      // gate stays installed until reconciliation settles, including on timeout.
      // Catch-up failures are logged by the engine; we proceed regardless so a
      // transient sync error never breaks tools.
      if (this.catchUpGate) {
        const gate = this.catchUpGate;
        await this.awaitCatchUpGate(gate);
      }
      // Honor the optional tool allowlist (CODEGRAPH_MCP_TOOLS): a trimmed
      // surface rejects ablated tools defensively even if a client cached them.
      if (!this.isToolAllowed(toolName)) {
        return this.errorResult(`Tool ${toolName} is disabled via CODEGRAPH_MCP_TOOLS`);
      }
      // Cross-cutting input validation. All tools accept an optional
      // `projectPath` and most accept either `query`, `task`, or
      // `symbol` — bound their lengths centrally so individual handlers
      // can stay focused on tool-specific logic.
      const pathCheck = this.validateOptionalPath(args.projectPath, 'projectPath');
      if (typeof pathCheck === 'object' && pathCheck !== undefined) {
        return pathCheck;
      }
      // An explicit project gets the same first-call guarantee as the default
      // (#1835): its post-open catch-up sync finishes (time-boxed) before we
      // serve it. Resolved on the main thread so the watcher lives here even
      // when dispatch is off-loaded to a worker.
      if (typeof pathCheck === 'string') {
        await this.awaitProjectGate(pathCheck);
      }
      // The `path` and `pattern` properties used by codegraph_files are
      // also path-shaped — apply the same cap.
      if (args.path !== undefined) {
        const check = this.validateOptionalPath(args.path, 'path');
        if (typeof check === 'object' && check !== undefined) return check;
      }
      if (args.pattern !== undefined) {
        const check = this.validateOptionalPath(args.pattern, 'pattern');
        if (typeof check === 'object' && check !== undefined) return check;
      }

      const project = await this.getCodeGraph(args.projectPath as string | undefined);
      // Recover a watcher disabled by prolonged lock contention on the next call.
      // The stale banner remains until the watcher finishes its full scan;
      // frequent calls cannot bypass its cooldown (#1959).
      if (project.rearmWatcherAfterLockContention?.()) {
        process.stderr.write('[CodeGraph MCP] Re-armed file watcher; full catch-up pending.\n');
      }