plan

package
v1.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 16, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ToolNameEnterPlanMode = "enter_plan_mode"
	ToolNameExitPlanMode  = "exit_plan_mode"
	ToolNameSubmitPlan    = "submit_plan"
)

Tool name constants

View Source
const (
	SearchHintEnterPlanMode = "switch to plan mode to design an approach before coding"
	SearchHintExitPlanMode  = "leave plan mode once the user has approved the plan"
	SearchHintSubmitPlan    = "submit the implementation plan for user review and approval"
)

Search hints

View Source
const (
	DescriptionEnterPlanMode = "" /* 346-byte string literal not displayed */
	DescriptionExitPlanMode  = "" /* 177-byte string literal not displayed */
	DescriptionSubmitPlan    = "" /* 307-byte string literal not displayed */
)

Descriptions

View Source
const EnterPlanModePrompt = `Plan mode is a read-only mode: while it is on you cannot change files, only read, investigate and design.

If the user explicitly asks you to enter plan mode, or to design or investigate without changing anything, call ` + "`enter_plan_mode`" + `.

You do NOT need plan mode to propose a plan. To put a plan in front of the user for review and approval, call ` + "`submit_plan`" + ` directly: it works in any mode, execute included.

## Enter plan mode on your own only when

You want the read-only guard while you design. This mode exists to obtain the user's
alignment, not to organise work. Enter it when a choice belongs to the user and settling
that choice before any file is touched costs less than settling it after:

- Several defensible designs exist and the user has not indicated which one they want
- The work is hard to undo or expensive to redo: data migrations, auth or permission
  changes, deletions, a published interface or schema
- The acceptance criteria themselves are ambiguous, so you cannot tell what "done" looks
  like from the repository

Investigating a wide, unfamiliar or multi-file area is NOT a reason on its own. Reading
is free in either mode, and a tracked task list carries the roadmap while you read, so a
request that is merely large and unambiguous belongs in execute mode.

## Do NOT enter plan mode when

- The task is a small, obvious, bounded fix
- The user already gave you explicit step-by-step instructions
- The request is pure research or reading with no planned implementation
- You already have enough context to start immediately and the risk is low
- The task is multi-step but unambiguous and the approach is not in question:
  open a tracked task list with ` + "`task_create`" + ` and execute it directly. A
  task list is not a plan, it needs no approval, and entering this mode just to
  be able to track the steps costs a full round of alignment for nothing.

## What to do in plan mode

1. Explore the relevant code using read-only tools (` + "`read_file`" + `, ` + "`glob`" + `, ` + "`grep`" + `, and ` + "`bash`" + ` for ls/cat/git log/find)
2. Clarify ambiguous requirements with ask_user_question if needed
3. Design a concrete, ordered implementation plan
4. Call ` + "`submit_plan`" + ` with the full plan content and a short slug
5. Wait for the user to review — they may send feedback (revise and resubmit) or approve
6. On approval, follow the approval message: implement directly if plan mode was
   already exited for you, or call ` + "`exit_plan_mode`" + ` if you are still in plan
   mode, then track the work with ` + "`task_create`" + ` / ` + "`task_update`" + `

DO NOT edit or create source files while in plan mode.
The plan is presented to the user as an interactive artifact for review and approval.`

EnterPlanModePrompt is the system prompt for the EnterPlanMode tool.

View Source
const ExitPlanModePrompt = `` /* 994-byte string literal not displayed */

ExitPlanModePrompt is the system prompt for the ExitPlanMode tool.

View Source
const SubmitPlanPrompt = `` /* 2250-byte string literal not displayed */

SubmitPlanPrompt is the system prompt for the SubmitPlan tool.

Variables

This section is empty.

Functions

This section is empty.

Types

type EnterPlanModeConfig

type EnterPlanModeConfig struct {
	SessionID types.SessionID
	AgentID   *types.AgentID
}

Config represents tool configuration.

func DefaultEnterPlanModeConfig

func DefaultEnterPlanModeConfig(sessionID types.SessionID) *EnterPlanModeConfig

DefaultEnterPlanModeConfig returns default configuration.

type EnterPlanModeTool

type EnterPlanModeTool struct {
	// contains filtered or unexported fields
}

EnterPlanModeTool represents the EnterPlanMode tool.

func NewEnterPlanModeTool

func NewEnterPlanModeTool(config *EnterPlanModeConfig) *EnterPlanModeTool

NewEnterPlanModeTool creates a new EnterPlanMode tool. Session ID may be provided later by the runtime tool context.

func (*EnterPlanModeTool) BackfillInput

func (t *EnterPlanModeTool) BackfillInput(ctx context.Context, input map[string]any) map[string]any

BackfillInput enriches the input with derived fields.

func (*EnterPlanModeTool) Call

func (t *EnterPlanModeTool) Call(
	ctx context.Context,
	input tool.CallInput,
	permissionCheck types.CanUseToolFn,
) (tool.CallResult, error)

Call executes the tool. Aligned with OpenClaude's EnterPlanModeTool.call

func (*EnterPlanModeTool) CheckPermissions

func (t *EnterPlanModeTool) CheckPermissions(ctx context.Context, input map[string]any, toolCtx tool.ToolUseContext) types.PermissionResult

CheckPermissions performs tool-specific permission checks.

func (*EnterPlanModeTool) Definition

func (t *EnterPlanModeTool) Definition() tool.Definition

Definition returns the tool definition.

func (*EnterPlanModeTool) Description

func (t *EnterPlanModeTool) Description(ctx context.Context) (string, error)

Description returns a human-readable description.

func (*EnterPlanModeTool) FormatResult

func (t *EnterPlanModeTool) FormatResult(data any) string

FormatResult serialises the tool output.

func (*EnterPlanModeTool) IsConcurrencySafe

func (t *EnterPlanModeTool) IsConcurrencySafe(input map[string]any) bool

IsConcurrencySafe returns whether this tool use can run concurrently.

func (*EnterPlanModeTool) IsEnabled

func (t *EnterPlanModeTool) IsEnabled() bool

IsEnabled returns whether this tool is currently active.

func (*EnterPlanModeTool) IsReadOnly

func (t *EnterPlanModeTool) IsReadOnly(input map[string]any) bool

IsReadOnly returns whether this tool use is read-only.

func (*EnterPlanModeTool) Prompt

func (t *EnterPlanModeTool) Prompt() string

Prompt returns the system prompt for this tool.

func (*EnterPlanModeTool) ValidateInput

func (t *EnterPlanModeTool) ValidateInput(ctx context.Context, input map[string]any) (map[string]any, error)

ValidateInput validates and normalizes input.

type ExitPlanModeConfig

type ExitPlanModeConfig struct {
	SessionID types.SessionID
	AgentID   *types.AgentID
}

ExitPlanModeConfig represents tool configuration.

func DefaultExitPlanModeConfig

func DefaultExitPlanModeConfig(sessionID types.SessionID) *ExitPlanModeConfig

DefaultExitPlanModeConfig returns default configuration.

type ExitPlanModeOutput

type ExitPlanModeOutput struct {
	Plan     string `json:"plan"`
	FilePath string `json:"file_path,omitempty"`
	IsAgent  bool   `json:"is_agent"`
}

Output represents the result of exiting execution mode.

type ExitPlanModeTool

type ExitPlanModeTool struct {
	// contains filtered or unexported fields
}

ExitPlanModeTool represents the ExitPlanMode tool.

func NewExitPlanModeTool

func NewExitPlanModeTool(config *ExitPlanModeConfig) *ExitPlanModeTool

NewExitPlanModeTool creates a new ExitPlanMode tool. Session ID may be provided later by the runtime tool context.

func (*ExitPlanModeTool) BackfillInput

func (t *ExitPlanModeTool) BackfillInput(ctx context.Context, input map[string]any) map[string]any

BackfillInput enriches the input with derived fields.

func (*ExitPlanModeTool) Call

func (t *ExitPlanModeTool) Call(
	ctx context.Context,
	input tool.CallInput,
	permissionCheck types.CanUseToolFn,
) (tool.CallResult, error)

Call executes the tool. Aligned with OpenClaude's ExitPlanModeV2Tool.call

func (*ExitPlanModeTool) CheckPermissions

func (t *ExitPlanModeTool) CheckPermissions(ctx context.Context, input map[string]any, toolCtx tool.ToolUseContext) types.PermissionResult

CheckPermissions performs tool-specific permission checks.

func (*ExitPlanModeTool) Definition

func (t *ExitPlanModeTool) Definition() tool.Definition

Definition returns the tool definition.

func (*ExitPlanModeTool) Description

func (t *ExitPlanModeTool) Description(ctx context.Context) (string, error)

Description returns a human-readable description.

func (*ExitPlanModeTool) ExecutesInPlanMode

func (t *ExitPlanModeTool) ExecutesInPlanMode(input map[string]any) bool

ExecutesInPlanMode allows ExitPlanMode to run while the session is in plan mode so it can restore the previous permission state.

func (*ExitPlanModeTool) FormatResult

func (t *ExitPlanModeTool) FormatResult(data any) string

FormatResult serialises the tool output.

func (*ExitPlanModeTool) IsConcurrencySafe

func (t *ExitPlanModeTool) IsConcurrencySafe(input map[string]any) bool

IsConcurrencySafe returns whether this tool use can run concurrently.

func (*ExitPlanModeTool) IsEnabled

func (t *ExitPlanModeTool) IsEnabled() bool

IsEnabled returns whether this tool is currently active.

func (*ExitPlanModeTool) IsReadOnly

func (t *ExitPlanModeTool) IsReadOnly(input map[string]any) bool

IsReadOnly returns whether this tool use is read-only.

func (*ExitPlanModeTool) Prompt

func (t *ExitPlanModeTool) Prompt() string

Prompt returns the system prompt for this tool.

func (*ExitPlanModeTool) RequiresUserInteraction

func (t *ExitPlanModeTool) RequiresUserInteraction() bool

RequiresUserInteraction is deliberately false, and it is not a working gate.

The comment here used to assert that "the runtime already routes ask-decisions through the prompt bridge for non-agent sessions". That belief is what let the approval go missing: a bare Ask is replaced by an Allow in resolveToolPermissions before any prompt bridge sees it, so the user is never asked and the plan preview is never shown (see the KNOWN DEFECT note and exitPlanModeApproval_test.go).

func (*ExitPlanModeTool) ValidateInput

func (t *ExitPlanModeTool) ValidateInput(ctx context.Context, input map[string]any) (map[string]any, error)

ValidateInput validates and normalizes input.

type PlanPersistFn

type PlanPersistFn func(ctx context.Context, planID, sessionID, userID, slug, filename, content string) (id string, version int, err error)

PlanPersistFn is the callback the submit_plan tool uses to persist a plan document. Returns the plan ID (new or existing), version, and any error.

type SubmitPlanConfig

type SubmitPlanConfig struct {
	SessionID types.SessionID
	AgentID   *types.AgentID
	UserID    string
	PersistFn PlanPersistFn
}

SubmitPlanConfig holds the dependencies for SubmitPlanTool.

type SubmitPlanOutput

type SubmitPlanOutput struct {
	PlanID   string `json:"plan_id"`
	Slug     string `json:"slug"`
	Filename string `json:"filename"`
	Version  int    `json:"version"`
	Status   string `json:"status"`
	Content  string `json:"-"`
}

SubmitPlanOutput is the result returned to the agent.

type SubmitPlanTool

type SubmitPlanTool struct {
	// contains filtered or unexported fields
}

SubmitPlanTool implements submit_plan.

func NewSubmitPlanTool

func NewSubmitPlanTool(config *SubmitPlanConfig) *SubmitPlanTool

func (*SubmitPlanTool) BackfillInput

func (t *SubmitPlanTool) BackfillInput(_ context.Context, input map[string]any) map[string]any

func (*SubmitPlanTool) Call

func (*SubmitPlanTool) CheckPermissions

func (*SubmitPlanTool) Definition

func (t *SubmitPlanTool) Definition() tool.Definition

func (*SubmitPlanTool) Description

func (t *SubmitPlanTool) Description(ctx context.Context) (string, error)

func (*SubmitPlanTool) ExecutesInPlanMode

func (t *SubmitPlanTool) ExecutesInPlanMode(_ map[string]any) bool

func (*SubmitPlanTool) FormatResult

func (t *SubmitPlanTool) FormatResult(data any) string

func (*SubmitPlanTool) IsConcurrencySafe

func (t *SubmitPlanTool) IsConcurrencySafe(_ map[string]any) bool

func (*SubmitPlanTool) IsEnabled

func (t *SubmitPlanTool) IsEnabled() bool

func (*SubmitPlanTool) IsReadOnly

func (t *SubmitPlanTool) IsReadOnly(_ map[string]any) bool

func (*SubmitPlanTool) Prompt

func (t *SubmitPlanTool) Prompt() string

func (*SubmitPlanTool) RequiresUserInteraction

func (t *SubmitPlanTool) RequiresUserInteraction() bool

func (*SubmitPlanTool) ValidateInput

func (t *SubmitPlanTool) ValidateInput(ctx context.Context, input map[string]any) (map[string]any, error)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL