How Exit Plan Mode Enables Structured Planning in Kimi Code

Exit Plan Mode is a built-in tool that captures a drafted plan from the agent, persists it as a queryable fact in the session transcript, and toggles the agent back to normal execution mode.

In the MoonshotAI/kimi-code repository, structured planning is implemented through a dedicated lifecycle that allows agents to pause normal tool execution, compose multi-step plans, and commit those plans to the session history. The ExitPlanModeTool defined in packages/agent-core/src/tools/builtin/planning/exit-plan-mode.ts serves as the critical checkpoint that finalizes the planning phase and bridges the gap between plan composition and task execution.

The Planning Lifecycle: Enter, Draft, and Exit

Structured planning in Kimi Code follows a three-phase lifecycle managed by complementary tools in the packages/agent-core/src/tools/builtin/planning/ directory.

Entering Planning Mode

Before an agent can draft a structured plan, it must invoke Enter Plan Mode (EnterPlanModeTool). This tool switches the agent into a special "planning" state where the runtime prepares a temporary plan file and disables normal tool execution. According to the implementation in enter-plan-mode.ts, the tool binds three key dependencies: a toggle function to enable plan mode, a path getter that returns the location of the temporary plan file (typically under the agent's workspace), and a checker function that validates the agent remains in planning state.

Exiting and Persisting the Plan

When the agent finishes drafting, it calls Exit Plan Mode (ExitPlanModeTool). This tool performs three atomic operations:

1. Binding dependencies – It receives the plan-mode toggle function, the plan file path getter, and the mode checker to ensure consistency with the entering state.
2. Recording the plan fact – The tool creates a plan fact in the session transcript containing the plan content, file path, reviewer options, and approval status. This fact is defined in packages/transcript/src/contract/schema.ts (lines 606-640) and links back to the originating tool call.
3. Resuming execution – The toggle function flips the agent back to normal mode, allowing subsequent turns to read the persisted plan file or reference the stored plan fact.

Implementation in exit-plan-mode.ts

The core implementation resides in packages/agent-core/src/tools/builtin/planning/exit-plan-mode.ts. The ExitPlanModeTool class extends the base tool architecture and defines a schema that validates the plan's structural integrity before persistence.

The tool's bind() method accepts three functional dependencies:

• toggle: A function that disables plan mode and restores normal tool execution
• getPath: A getter returning the absolute path to the draft plan file
• isInPlanMode: A checker confirming the agent is currently in planning state

When executed, the tool reads the plan content from the resolved path, constructs a plan fact object conforming to the transcript schema, and appends it to the session history. This design ensures that even if the session is reconstructed from wire records (cold rebuild), the plan remains accessible.

Transcript Integration and API Access

Once persisted, plans become queryable through the Transcript Service. In packages/kap-server/src/routes/transcript.ts (lines 530-560), the GET /sessions/{id}/transcript/plan endpoint projects plan facts from the transcript, supporting both live sessions and cold rebuild scenarios.

The endpoint extracts the plan content, associated metadata, and reviewer decisions from the transcript facts, making them available to downstream services or human reviewers through a standardized REST interface.

Practical Usage Example

The following TypeScript example demonstrates the complete planning lifecycle:

// Step 1: Enter planning mode
await agent.toolset.find('EnterPlanMode')!.bind(
  () => agent.togglePlanMode(true),
  () => '/workspace/.kimi-plan.md',
  () => true
);

// Step 2: Draft the plan using WriteFile bound to plan mode
await agent.toolset.find('WriteFile')!.bindPlanMode(
  () => true,
  () => '/workspace/.kimi-plan.md'
);
await agent.toolset.find('WriteFile')!.execute({
  path: '/workspace/.kimi-plan.md',
  content: `## Implementation Plan\n1. Refactor authentication module\n2. Update unit tests\n3. Verify integration`

});

// Step 3: Exit planning mode to persist and resume
await agent.toolset.find('ExitPlanMode')!.bind(
  () => agent.togglePlanMode(false),
  () => '/workspace/.kimi-plan.md',
  () => true
);
await agent.toolset.find('ExitPlanMode')!.execute({});

After execution, the plan is accessible via the transcript API:

import { Klient } from '@moonshot-ai/klient';

const client = new Klient({ baseUrl: 'http://localhost:58627' });
const plan = await client
  .session('session-id')
  .agent('agent-id')
  .transcript.plan.get();

Summary

• Exit Plan Mode (ExitPlanModeTool) finalizes the structured planning phase in Kimi Code by capturing the drafted plan and returning the agent to normal execution.
• The tool persists plan data as a typed fact in the session transcript, defined in packages/transcript/src/contract/schema.ts, enabling both programmatic access and cold rebuild support.
• Plans are queryable through the REST endpoint GET /sessions/{id}/transcript/plan implemented in packages/kap-server/src/routes/transcript.ts.
• The implementation requires binding toggle functions, path getters, and mode checkers to ensure atomic transitions between planning and execution states.

Frequently Asked Questions

What is the difference between Enter Plan Mode and Exit Plan Mode?

Enter Plan Mode (EnterPlanModeTool) initializes the planning state by creating a temporary plan file and disabling normal tool execution, while Exit Plan Mode (ExitPlanModeTool) finalizes the process by reading the completed plan, persisting it as a transcript fact, and re-enabling normal tool execution. The two tools share the same binding interface but perform inverse operations on the agent's runtime state.

Where is the plan stored after exiting plan mode?

The plan content is stored in two locations: first, as a text file at the path provided to the binding function (typically in the workspace), and second, as a structured plan fact in the session transcript. The transcript fact is defined in packages/transcript/src/contract/schema.ts and contains the plan content, file path, and review metadata, making it available via the transcript/plan REST endpoint even if the original file is moved or deleted.

Can plans be reviewed after the session ends?

Yes. Plans are persisted as facts within the session transcript, which supports cold rebuild from wire records. The transcript projection logic in packages/kap-server/src/routes/transcript.ts handles reconstruction of plan facts from historical tool results, allowing downstream systems to query completed plans through the REST API long after the original agent process has terminated.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}