Agent Modes

Agent Modes

Overview of chat modes, engine modes, and how mode switching and plans shape tool access.

Mode set

The user-facing mode set in the defaults includes:

• ask — quick Q&A with web research capability.
• explore — read-only exploration for context gathering without editing.
• plan — turn approved designs or requirements into precise implementation plans.
• agent — full multi-step workflow with tools and editing capabilities.
• quick_agent — fast autonomous coding with minimal overhead.
• debug — systematic bug diagnosis and root cause analysis.
• buddy — persistent project companion for setup, diagnostics, and knowledge management.

These modes are defined in the YAML defaults under crates/refact-yaml-configs/src/defaults/modes/. The files skimmed here include ask.yaml, explore.yaml, plan.yaml, agent.yaml, quick_agent.yaml, debug.yaml, buddy.yaml, task_planner.yaml, and task_agent.yaml.

Engine modes

AGENTS.md also describes the chat engine modes that govern tool/context scope:

Engine mode	Purpose	Tool/context profile
NO_TOOLS	Plain chat	No tools enabled.
EXPLORE	Context gathering	Read-only exploration tools.
AGENT	Autonomous task execution	Full toolset for coding, execution, and collaboration.
TASK_PLANNER	Kanban board management	Planning, cards, agents, task docs, plan handoff/compression.
TASK_AGENT	Execute task cards	Scoped execution inside a worktree/card context.

AGENTS.md frames these as the underlying engine-side modes, while the YAML mode files define user-facing presets that select tool lists, approvals, and prompts.

What each mode is for

ask

Read-only chat for short answers and current-information lookup. The defaults enable web tools, subagent, and background-agent inspection tools, but not integrations or editing. It explicitly tells the assistant to use ask_questions() instead of free-text questions and to suggest switching to Explore or Agent mode if codebase access is needed.

explore

Read-only codebase exploration. It allows codebase-reading tools, web tools, subagent, and handoff_to_mode, but not editing. The prompt says to explain a brief plan before using tools, to gather context, and to propose project changes after understanding the code.

plan

Planning mode for turning approved requirements into an executable plan. It is still read-only, but it adds plan-oriented tools such as search_trajectories, get_trajectory_context, strategic_planning, tasks_set, task_done, and handoff_to_mode. The prompt treats the approved design or requirements as the source of truth and requires exact tasks, files, tests, and verification commands.

agent

General autonomous coding mode. It enables the broad code-editing set, shell/process/scheduler tools, knowledge and trajectory tools, subagents and delegates, task tools, and plan tools. Its prompt emphasizes orchestration, delegation, and verification. In AGENTS.md, the AGENT engine mode is the corresponding full toolset mode.

quick_agent

A faster coding preset with a similar broad toolset to agent, but a lighter prompt and less ceremony. It includes editing tools, process/scheduler tools, plan tools, subagents, delegates, worktree merge, and task tools. It is designed for minimal overhead while still supporting direct edits and verification.

debug

Diagnosis-only mode for systematic root-cause analysis. It is read-only and includes search, knowledge, trajectory search, web/Chrome, process and scheduler tools, subagents, and question asking. The prompt explicitly says not to modify files and to suggest switching to Agent mode for fixes.

buddy

A persistent project companion focused on setup, diagnostics, knowledge management, and user-facing assistance. It enables a wide toolset for reading, editing, shell, knowledge, web, buddy-specific actions, and internal repo browsing via refact_engine_*. It is the broadest companion-style mode in the defaults, with integrations and MCP enabled.

Task Planner and Task Agent modes

task_planner

The planner mode for task-board execution. It begins from board_get(), reads pinned documents such as initial-plan and master-plan, converts plans into cards, and then runs the plan/review/fix/next loop. Its toolset includes board/task tools, document tools, task memories, plan tools, compression helpers, background-agent controls, and swarm_investigate.

task_agent

The worker mode for a single task card. It operates in an isolated worktree, requires agent_finish(), and is expected to read the card, implement the smallest change, verify, and report. Its toolset is the scoped execution set: code browsing, editing, shell/process/scheduler, task memory, docs, plan tools, and task-agent controls.

Mode switching and hidden events

Mode transitions are routed through handoff_to_mode. AGENTS.md says that handoff_to_mode and mode-transition endpoints create a pinned initial-plan task document when transitioning into Task Planner with an initial_plan. The document is created with kind plan, role planner, and pinned=true.

Mode switches are also represented internally as hidden events. AGENTS.md lists mode_switch under EventSubkind, with chat.session as the typical source. That means mode changes are tracked as hidden event messages rather than ordinary user transcript turns.

Initial plan propagation into Task Planner

When a Plan-mode handoff targets Task Planner, the full final plan is passed as initial_plan. Task Planner then treats the initial-plan document as authoritative:

• read the pinned document before creating cards,
• extract tasks, dependencies, files, tests, acceptance criteria, risks, and non-goals,
• preserve plan boundaries when splitting cards,
• use the plan as the source of truth for execution.

This is how the planner receives plan content without rewriting the source chat plan bytes.

Session state machine

AGENTS.md defines the chat session state machine as:

stateDiagram-v2
  Idle --> Generating
  Generating --> ExecutingTools
  ExecutingTools --> Generating
  Generating --> Paused
  ExecutingTools --> Paused
  Paused --> Generating
  Generating --> WaitingIde
  WaitingIde --> Generating
  Generating --> WaitingUserInput
  WaitingUserInput --> Generating
  Generating --> Completed
  ExecutingTools --> Completed
  Generating --> Error
  ExecutingTools --> Error
  Paused --> Error

Loading

The listed states are Idle, Generating, ExecutingTools, Paused, WaitingIde, WaitingUserInput, Completed, and Error. In short: the chat generates responses, may execute tools, can pause for approvals or IDE interactions, and ultimately completes or errors.

Cross-links

• Chat System
• Task Planner and Cards
• Subagents
• Agent Tools