planmode

Documentation

Overview

Package planmode implements a plan-then-execute workflow.

The TUI (or serve) creates a PlanMode, passes the agent's tool registry, and calls Enter/Exit/StartExecution at the right moments. PlanMode manages tool visibility (unregister/re-register) and provides prompt fragments.

Index

• func ExecutionPrompt(planFilePath string) string
• func IsSafeCommand(command string) bool
• func PlanningPrompt(planFilePath string) string
• type Config
• type Mode
• type PlanMode
  • func New(cfg Config) *PlanMode
  • func (pm *PlanMode) ApplyRestoredState()
  • func (pm *PlanMode) ContinueRefining()
  • func (pm *PlanMode) Enter() (string, error)
  • func (pm *PlanMode) Exit()
  • func (pm *PlanMode) FilterToolCall(toolName string, args map[string]any) (bool, string)
  • func (pm *PlanMode) GetCodeReviewConfig() ReviewConfig
  • func (pm *PlanMode) GetReviewConfig() ReviewConfig
  • func (pm *PlanMode) Mode() Mode
  • func (pm *PlanMode) OnPlanSubmitted() bool
  • func (pm *PlanMode) PlanFilePath() string
  • func (pm *PlanMode) Restore(state State)
  • func (pm *PlanMode) RestoreState(meta map[string]any)
  • func (pm *PlanMode) ReviewDone()
  • func (pm *PlanMode) SaveState() map[string]any
  • func (pm *PlanMode) SetOnChange(fn func(Mode))
  • func (pm *PlanMode) StartExecution()
  • func (pm *PlanMode) StartReview()
  • func (pm *PlanMode) SubmitPlanTool() core.Tool
  • func (pm *PlanMode) TaskStore() *tasks.Store
• type ReviewConfig
• type ReviewResult
  • func Review(ctx context.Context, cfg ReviewConfig, planPath string, ...) (ReviewResult, error)
  • func ReviewCode(ctx context.Context, cfg ReviewConfig, summary string, filesChanged []string) (ReviewResult, error)
• type ReviewStreamFunc
• type State
  • func RestoreFromMetadata(meta map[string]any) State
  • func (s *State) SaveToMetadata() map[string]any

Functions

func ExecutionPrompt

func ExecutionPrompt(planFilePath string) string

ExecutionPrompt returns the system prompt fragment for execution mode.

func IsSafeCommand

func IsSafeCommand(command string) bool

IsSafeCommand checks whether a bash command is safe for planning mode. Pipelines are allowed if every segment is a known-safe command. Shell control operators (&&, ||, ;, redirects, subshells) are always rejected.

func PlanningPrompt

func PlanningPrompt(planFilePath string) string

PlanningPrompt returns the system prompt fragment for planning mode.

Types

type Config

type Config struct {
	Registry      *core.Registry // the agent's tool registry (mutated on enter/exit)
	SessionDir    string         // directory for plan file storage
	ReviewCfg     ReviewConfig   // model/provider for plan reviewer
	CodeReviewCfg ReviewConfig   // model/provider for code reviewer
	TaskStore     *tasks.Store   // shared task store (owned externally)
}

Config configures a PlanMode instance.

type Mode

type Mode string

Mode represents the current plan mode phase.

const (
	ModeOff       Mode = "off"
	ModePlanning  Mode = "planning"
	ModeReady     Mode = "ready"
	ModeReviewing Mode = "reviewing"
	ModeExecuting Mode = "executing"
)

type PlanMode

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

PlanMode manages the plan-then-execute workflow state and tool visibility. All exported methods are safe for concurrent use.

func New

func New(cfg Config) *PlanMode

New creates a PlanMode instance. The registry is the agent's live tool registry.

func (*PlanMode) ApplyRestoredState

func (pm *PlanMode) ApplyRestoredState()

ApplyRestoredState syncs the runtime (tool registry) with the restored state. Must be called after RestoreState() and after tools are registered. For PLANNING/READY/REVIEWING: snapshots tools and switches to planning set. For EXECUTING: registers the request_review tool. For OFF: restores the full non-plan tool set.

func (*PlanMode) ContinueRefining

func (pm *PlanMode) ContinueRefining()

ContinueRefining transitions from READY back to PLANNING.

func (*PlanMode) Enter

func (pm *PlanMode) Enter() (string, error)

Enter switches to planning mode. Generates a plan file, snapshots current tools, and switches to the planning-only tool set. Returns the plan file path.

func (*PlanMode) Exit

func (pm *PlanMode) Exit()

Exit restores normal mode. Restores original tools but preserves the slug so re-entering plan mode in the same session reuses it.

func (*PlanMode) FilterToolCall

func (pm *PlanMode) FilterToolCall(toolName string, args map[string]any) (bool, string)

FilterToolCall checks if a tool call is allowed in planning/ready/reviewing modes. Returns (allowed, reason). Allows everything in OFF and EXECUTING modes.

func (*PlanMode) GetCodeReviewConfig

func (pm *PlanMode) GetCodeReviewConfig() ReviewConfig

GetCodeReviewConfig returns the code review configuration.

func (*PlanMode) GetReviewConfig

func (pm *PlanMode) GetReviewConfig() ReviewConfig

GetReviewConfig returns the plan review configuration.

func (*PlanMode) Mode

func (pm *PlanMode) Mode() Mode

Mode returns the current plan mode.

func (*PlanMode) OnPlanSubmitted

func (pm *PlanMode) OnPlanSubmitted() bool

OnPlanSubmitted returns true if submit_plan was called since the last check. Resets the flag. Used by TUI to detect when to show the action menu.

func (*PlanMode) PlanFilePath

func (pm *PlanMode) PlanFilePath() string

PlanFilePath returns the current plan file path, or "" if not in plan mode.

func (*PlanMode) Restore

func (pm *PlanMode) Restore(state State)

Restore replaces the persisted plan-mode state without emitting an onChange callback. It first restores any tools restricted by the previous state, so a session restored to off cannot inherit the previous session's plan-only tool registry. Call ApplyRestoredState afterwards to install the new state's tool restrictions.

func (*PlanMode) RestoreState

func (pm *PlanMode) RestoreState(meta map[string]any)

RestoreState loads state from session.Metadata. Does NOT apply runtime effects (tool switching, etc.) — call ApplyRestoredState() after restoring to sync the runtime.

func (*PlanMode) ReviewDone

func (pm *PlanMode) ReviewDone()

ReviewDone transitions from REVIEWING back to READY.

func (*PlanMode) SaveState

func (pm *PlanMode) SaveState() map[string]any

SaveState returns the state for session.Metadata persistence.

func (*PlanMode) SetOnChange

func (pm *PlanMode) SetOnChange(fn func(Mode))

SetOnChange registers a callback fired after every state transition.

func (*PlanMode) StartExecution

func (pm *PlanMode) StartExecution()

StartExecution restores full tools and sets mode to EXECUTING.

func (*PlanMode) StartReview

func (pm *PlanMode) StartReview()

StartReview sets mode to REVIEWING.

func (*PlanMode) SubmitPlanTool

func (pm *PlanMode) SubmitPlanTool() core.Tool

SubmitPlanTool returns the submit_plan tool definition.

func (*PlanMode) TaskStore

func (pm *PlanMode) TaskStore() *tasks.Store

TaskStore returns the shared task store (may be nil).

type ReviewConfig

type ReviewConfig struct {
	ProviderFactory func(core.Model) (core.Provider, error)
	Model           core.Model
	ThinkingLevel   string
	ParentTools     *core.Registry // read-only tools extracted from here
}

ReviewConfig configures the plan reviewer subagent.

type ReviewResult

type ReviewResult struct {
	Approved bool
	Feedback string
	Round    int // review round number
}

ReviewResult holds the structured output from a plan review.

func Review

func Review(ctx context.Context, cfg ReviewConfig, planPath string, onStream ReviewStreamFunc) (ReviewResult, error)

Review runs an in-process subagent to review the plan file. The reviewer gets read-only tools (read, grep, find, ls) and a focused system prompt. Returns the verdict and full feedback text. If onStream is non-nil, it receives text deltas during review.

func ReviewCode

func ReviewCode(ctx context.Context, cfg ReviewConfig, summary string, filesChanged []string) (ReviewResult, error)

ReviewCode runs an in-process subagent to review code changes. The reviewer gets read-only tools and a focused system prompt. Blocks until the review is complete.

type ReviewStreamFunc

type ReviewStreamFunc func(delta string)

ReviewStreamFunc is called with text deltas during review.

type State

type State struct {
	Mode          Mode   `json:"mode"`
	PlanFilePath  string `json:"plan_file"`
	SessionSlug   string `json:"session_slug"`
	ReviewRounds  int    `json:"review_rounds"`
	PlanSubmitted bool   `json:"plan_submitted"`
}

State holds the full plan mode state.

func RestoreFromMetadata

func RestoreFromMetadata(meta map[string]any) State

RestoreFromMetadata deserializes state from session.Metadata. Returns a default State (ModeOff) if the metadata is missing or invalid.

func (*State) SaveToMetadata

func (s *State) SaveToMetadata() map[string]any

SaveToMetadata serializes the state for session.Metadata persistence.