Documentation
¶
Overview ¶
Package mode hosts agent-mode and isolation tools: EnterPlanMode / ExitPlanMode (read-only planning) and EnterWorktree / ExitWorktree (filesystem-isolated worktrees).
EnterPlanMode and ExitPlanMode are wired through a PlanModeController supplied by the agent — they mutate the owning agent's permission mode and read the plan-file path off its workdir. The Worktree pair remains stubbed pending Phase 10.
Index ¶
Constants ¶
const PlanFileName = "current.md"
PlanFileName is the workdir-relative filename EnterPlanMode prepares and ExitPlanMode reads. One plan per session — keeps state trivial. Future phases can grow this to named plans if needed.
Variables ¶
var ( EnterWorktree tools.Tool = tools.NewStub( tools.ENTER_WORKTREE, "Create an isolated git worktree and switch the session into it. "+ "Use ONLY when the user explicitly says \"worktree\" or EVVA.md/memory instructs it. "+ "Do not use for ordinary branch work. "+ "Pass `path` to enter an existing worktree instead of creating one.", `{ "type":"object", "additionalProperties":false, "properties":{ "name":{"type":"string","description":"Optional name for a new worktree. Each \"/\"-separated segment may contain only letters, digits, dots, underscores, and dashes; max 64 chars total. Mutually exclusive with path."}, "path":{"type":"string","description":"Path to an existing worktree of the current repository to switch into. Must appear in git worktree list. Mutually exclusive with name."} } }`, ) ExitWorktree tools.Tool = tools.NewStub( tools.EXIT_WORKTREE, "Exit a worktree session created by EnterWorktree and return to the original working directory. "+ "No-op if no worktree session is active. "+ "Only operates on worktrees created by EnterWorktree in this session — never touches manually-created worktrees.", `{ "type":"object", "additionalProperties":false, "required":["action"], "properties":{ "action":{"type":"string","enum":["keep","remove"],"description":"\"keep\" leaves the worktree and branch on disk; \"remove\" deletes both."}, "discard_changes":{"type":"boolean","description":"Required true when action is \"remove\" and the worktree has uncommitted files or unmerged commits."} } }`, ) )
Functions ¶
func PlanFilePath ¶
PlanFilePath returns the absolute path of the active session's plan file given a workdir. Exposed so tests and the user-guide doc can reference the canonical location.
Types ¶
type ControllerLookup ¶
type ControllerLookup func() PlanModeController
ControllerLookup is the late-bound factory closure passed to the EnterPlanMode / ExitPlanMode constructors. Returning nil disables the tool — Execute surfaces a clear "no controller installed" error instead of crashing.
type EnterPlanModeTool ¶
type EnterPlanModeTool struct {
// contains filtered or unexported fields
}
EnterPlanModeTool flips the session into plan mode, stashes the prior mode for restore, and prepares an empty plan file the model writes to.
func NewEnterPlanMode ¶
func NewEnterPlanMode(lookup ControllerLookup) *EnterPlanModeTool
NewEnterPlanMode constructs the tool with a late-bound controller lookup. The lookup is invoked once per Execute call — passing a closure (rather than the controller directly) lets toolset.Build resolve the agent after agent.New returns.
func (*EnterPlanModeTool) Description ¶
func (t *EnterPlanModeTool) Description() string
func (*EnterPlanModeTool) Execute ¶
func (t *EnterPlanModeTool) Execute(_ context.Context, logger *slog.Logger, _ json.RawMessage) (tools.Result, error)
func (*EnterPlanModeTool) Name ¶
func (t *EnterPlanModeTool) Name() string
func (*EnterPlanModeTool) Schema ¶
func (t *EnterPlanModeTool) Schema() json.RawMessage
type ExitPlanModeTool ¶
type ExitPlanModeTool struct {
// contains filtered or unexported fields
}
ExitPlanModeTool reads the plan file, asks the user to approve, and restores the pre-plan permission mode on approval. Rejection leaves the session in ModePlan with the user's reason surfaced to the model.
func NewExitPlanMode ¶
func NewExitPlanMode(lookup ControllerLookup) *ExitPlanModeTool
func (*ExitPlanModeTool) Description ¶
func (t *ExitPlanModeTool) Description() string
func (*ExitPlanModeTool) Execute ¶
func (t *ExitPlanModeTool) Execute(ctx context.Context, logger *slog.Logger, input json.RawMessage) (tools.Result, error)
func (*ExitPlanModeTool) Name ¶
func (t *ExitPlanModeTool) Name() string
func (*ExitPlanModeTool) Schema ¶
func (t *ExitPlanModeTool) Schema() json.RawMessage
type PlanModeController ¶
type PlanModeController interface {
PermissionMode() permission.Mode
SetPermissionMode(m permission.Mode)
PrePlanMode() permission.Mode
SetPrePlanMode(m permission.Mode)
Workdir() string
Broker() permission.Broker
AgentID() string
}
PlanModeController is the seam between the EnterPlanMode / ExitPlanMode tools and the owning agent. The agent satisfies it directly; the tool constructors take a lookup closure (returns a PlanModeController) so builtin registration can stay late-bound — the agent installs itself after toolset.NewToolState runs.
The interface is intentionally narrow: only what the two plan-mode tools actually touch. Permission mode mutation, the pre-plan stash (used by ExitPlanMode to restore), the workdir (for the plan-file path), the approval broker (for ExitPlanMode's user-approval gate), and the AgentID that the broker uses to route the approval event.
Source Files