Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

5.0 KB
Raw Blame
/**
 * Built-in hook `plan-mode/plan-file-path`.
 *
 * Background (measured, not assumed). Claude Code 2.1.220's ExitPlanModeV2 takes
 * NO plan parameter — its advertised schema is `{allowedPrompts?}` and the tool
 * description says outright: "This tool does NOT take the plan content as a
 * parameter - it will read the plan from the file you wrote". CC's
 * `normalizeToolInput` injects `plan` from disk at the session's assigned path.
 *
 * So `ExitPlanMode({})` is CORRECT, and the real failure is upstream: the model
 * writes its plan somewhere else. gpt-5.6-sol produced a complete 12.9 KB plan
 * under a filename it invented; CC read the assigned path, found nothing, and
 * returned `plan: null`. That downgrades the approval dialog from the rich form
 * ("Here is Claude's plan" + `Yes, and bypass permissions` / `Yes, auto-accept
 * edits` / `Yes, manually approve edits`) to a bare "Exit plan mode?" yes/no —
 * and since the rich dialog is the only surface that offers permission
 * elevation on exit, the session always falls back to manual approval.
 *
 * Across 115 recorded ExitPlanMode calls the discriminator was exact: sessions
 * that wrote to the assigned path got the rich dialog 7/7, sessions that did not
 * got the degraded one 17/17. Native Claude models were 87/87 correct, so this
 * hook is scoped to foreign routes (`routes: "foreign"`, where nativeness is
 * `RouteInfo.native`: `claude-*` names and the `anthropic` provider, unless the
 * provider profile sets `forceForeignModel`).
 *
 * The request half rewrites the ExitPlanMode tool DESCRIPTION, because a tool
 * description is re-read at the instant the model decides to call the tool,
 * while the plan-mode reminder can sit ~180K tokens behind the current turn. The
 * action is applied at stage B, after tool conversion, so `--summarize-tools`
 * (first sentence, 150 characters) can never cut it.
 *
 * The tool half redirects a Write/Edit/NotebookEdit that is ALREADY aimed at
 * the plan directory onto the assigned plan file. It is armed only in plan
 * mode: outside it the hook cannot fire, so it must not make the seam hold
 * Write/Edit arguments, which would suppress incremental streaming of file
 * contents on every ordinary request.
 */

import {
  type RequestAction,
  type RequestContext,
  type ToolCallAction,
  type ToolCallContext,
  act,
} from "../public.js";
import type { BuiltinHook } from "../registry.js";

export const PLAN_MODE_HOOK_ID = "plan-mode/plan-file-path";

/** Tools that can create the plan file, and so can target the wrong path. */
export const PLAN_WRITE_TOOLS: ReadonlyArray<string> = ["Write", "Edit", "NotebookEdit"];

function directoryOf(filePath: string): string | undefined {
  const slash = filePath.lastIndexOf("/");
  return slash > 0 ? filePath.slice(0, slash) : undefined;
}

/** The text appended to the ExitPlanMode description. Unchanged from the behavior rule. */
export function planFileInstruction(planFilePath: string): string {
  return `

## Plan file for THIS session
Your plan MUST be written to exactly this path:
${planFilePath}
Do not invent a different filename, and do not derive one from the task. Claude Code reads only that exact path; a plan written anywhere else is invisible to it and the approval will show "No plan found".`;
}

/** The request handler, exported for unit tests. */
export function planModeRequest(ctx: RequestContext): RequestAction[] {
  const { planModeActive, planFilePath } = ctx.harness;
  if (!planModeActive || !planFilePath) return [];

  // Only speak up if the tool is actually on offer this turn.
  if (!ctx.request.tools.some((t) => t?.name === "ExitPlanMode")) return [];

  return [act.rewriteToolDescription("ExitPlanMode", planFileInstruction(planFilePath))];
}

/** The tool-call handler, exported for unit tests. */
export function planModeToolCall(ctx: ToolCallContext): ToolCallAction[] {
  const { planFilePath, planDir } = ctx.harness;
  if (!planFilePath || !planDir) return [];

  const filePath = ctx.tool.args.file_path;
  if (typeof filePath !== "string" || filePath === planFilePath) return [];

  // Only ever redirect writes that are ALREADY aimed at the plan directory. A
  // model writing source files, docs, or session artifacts elsewhere is doing
  // normal work and must not be touched.
  if (directoryOf(filePath) !== planDir) return [];

  return [
    act.repairToolArgs(
      { ...ctx.tool.args, file_path: planFilePath },
      `redirected ${ctx.tool.name} from ${filePath} to the session's assigned plan file ${planFilePath}`
    ),
  ];
}

export const planModeHook: BuiltinHook = {
  apiVersion: 1,
  id: PLAN_MODE_HOOK_ID,
  description:
    "Keep plan-mode writes on the plan file Claude Code assigned, and name that " +
    "path in the ExitPlanMode description.",
  defaultSeverity: "fix",
  // Native Claude models are already 87/87 on this; running the hook for them
  // would be pure risk with no upside.
  routes: "foreign",
  on: {
    request: planModeRequest,
    toolCall: {
      tools: PLAN_WRITE_TOOLS,
      armed: (ctx) => ctx.harness.planModeActive === true,
      handle: planModeToolCall,
    },
  },
};