Documentation
¶
Index ¶
- Constants
- type EnterPlanModeConfig
- type EnterPlanModeTool
- func (t *EnterPlanModeTool) BackfillInput(ctx context.Context, input map[string]any) map[string]any
- func (t *EnterPlanModeTool) Call(ctx context.Context, input tool.CallInput, permissionCheck types.CanUseToolFn) (tool.CallResult, error)
- func (t *EnterPlanModeTool) CheckPermissions(ctx context.Context, input map[string]any, toolCtx tool.ToolUseContext) types.PermissionResult
- func (t *EnterPlanModeTool) Definition() tool.Definition
- func (t *EnterPlanModeTool) Description(ctx context.Context) (string, error)
- func (t *EnterPlanModeTool) FormatResult(data any) string
- func (t *EnterPlanModeTool) IsConcurrencySafe(input map[string]any) bool
- func (t *EnterPlanModeTool) IsEnabled() bool
- func (t *EnterPlanModeTool) IsReadOnly(input map[string]any) bool
- func (t *EnterPlanModeTool) Prompt() string
- func (t *EnterPlanModeTool) ValidateInput(ctx context.Context, input map[string]any) (map[string]any, error)
- type ExitPlanModeConfig
- type ExitPlanModeOutput
- type ExitPlanModeTool
- func (t *ExitPlanModeTool) BackfillInput(ctx context.Context, input map[string]any) map[string]any
- func (t *ExitPlanModeTool) Call(ctx context.Context, input tool.CallInput, permissionCheck types.CanUseToolFn) (tool.CallResult, error)
- func (t *ExitPlanModeTool) CheckPermissions(ctx context.Context, input map[string]any, toolCtx tool.ToolUseContext) types.PermissionResult
- func (t *ExitPlanModeTool) Definition() tool.Definition
- func (t *ExitPlanModeTool) Description(ctx context.Context) (string, error)
- func (t *ExitPlanModeTool) ExecutesInPlanMode(input map[string]any) bool
- func (t *ExitPlanModeTool) FormatResult(data any) string
- func (t *ExitPlanModeTool) IsConcurrencySafe(input map[string]any) bool
- func (t *ExitPlanModeTool) IsEnabled() bool
- func (t *ExitPlanModeTool) IsReadOnly(input map[string]any) bool
- func (t *ExitPlanModeTool) Prompt() string
- func (t *ExitPlanModeTool) RequiresUserInteraction() bool
- func (t *ExitPlanModeTool) ValidateInput(ctx context.Context, input map[string]any) (map[string]any, error)
- type PlanPersistFn
- type SubmitPlanConfig
- type SubmitPlanOutput
- type SubmitPlanTool
- func (t *SubmitPlanTool) BackfillInput(_ context.Context, input map[string]any) map[string]any
- func (t *SubmitPlanTool) Call(ctx context.Context, input tool.CallInput, _ types.CanUseToolFn) (tool.CallResult, error)
- func (t *SubmitPlanTool) CheckPermissions(_ context.Context, _ map[string]any, _ tool.ToolUseContext) types.PermissionResult
- func (t *SubmitPlanTool) Definition() tool.Definition
- func (t *SubmitPlanTool) Description(ctx context.Context) (string, error)
- func (t *SubmitPlanTool) ExecutesInPlanMode(_ map[string]any) bool
- func (t *SubmitPlanTool) FormatResult(data any) string
- func (t *SubmitPlanTool) IsConcurrencySafe(_ map[string]any) bool
- func (t *SubmitPlanTool) IsEnabled() bool
- func (t *SubmitPlanTool) IsReadOnly(_ map[string]any) bool
- func (t *SubmitPlanTool) Prompt() string
- func (t *SubmitPlanTool) RequiresUserInteraction() bool
- func (t *SubmitPlanTool) ValidateInput(ctx context.Context, input map[string]any) (map[string]any, error)
Constants ¶
const ( ToolNameEnterPlanMode = "enter_plan_mode" ToolNameExitPlanMode = "exit_plan_mode" ToolNameSubmitPlan = "submit_plan" )
Tool name constants
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
const ( DescriptionEnterPlanMode = "" /* 346-byte string literal not displayed */ DescriptionExitPlanMode = "" /* 177-byte string literal not displayed */ DescriptionSubmitPlan = "" /* 307-byte string literal not displayed */ )
Descriptions
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.
const ExitPlanModePrompt = `` /* 994-byte string literal not displayed */
ExitPlanModePrompt is the system prompt for the ExitPlanMode tool.
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 ¶
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 ¶
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 ¶
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 ¶
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 (*SubmitPlanTool) Call ¶
func (t *SubmitPlanTool) Call( ctx context.Context, input tool.CallInput, _ types.CanUseToolFn, ) (tool.CallResult, error)
func (*SubmitPlanTool) CheckPermissions ¶
func (t *SubmitPlanTool) CheckPermissions(_ context.Context, _ map[string]any, _ tool.ToolUseContext) types.PermissionResult
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