QueryMT Agent - Agent Modes

QueryMT Agent supports three runtime modes that control what the agent can do and how it behaves. Modes can be switched at runtime, allowing flexible workflows.

Available Modes

Mode Details

Build Mode

Default mode - Full read and write access to the workspace.

Capabilities: - Read and modify any file - Execute shell commands (including mutating ones) - Create and delete files - Use all configured tools

System Reminder: None (full access)

When to use: - Implementing features - Fixing bugs - Making code changes - Any task requiring modifications

Example:

1
2
3
4
5
6

User: "Add a new API endpoint for user registration"
Agent: [In Build mode]
  - Reads existing routes
  - Creates new controller file
  - Updates database schema
  - Writes tests

Plan Mode

Read-only mode - Agent can observe and analyze but cannot make changes.

Capabilities: - Read files - Search code - List directories - Run read-only shell commands (git log, grep, find, etc.) - Create todo lists - Ask clarifying questions

Restrictions: - Cannot edit files - Cannot create files - Cannot delete files - Cannot run mutating shell commands (sed, tee, echo >, rm, cargo build, etc.)

System Reminder:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# Plan Mode

You are in **plan mode**. You may only observe, analyze, and plan.

## What You CAN Do
- Read files, search code, list directories
- Analyze architecture and patterns
- Create todo lists and task breakdowns
- Ask the user clarifying questions
- Run read-only shell commands (git log, grep, find, etc.)

## What You MUST NOT Do
- Do NOT edit, create, or delete files
- Do NOT run mutating shell commands (no sed, tee, echo >, rm, cargo build, etc.)
- Do NOT write code — only plan what code should be written

## Your Goal
Produce a clear, actionable implementation plan. Break work into small, concrete
steps. Identify risks and tradeoffs. When the user is ready to implement, they
will switch to Build mode.

Ask the user clarifying questions or for their opinion when weighing tradeoffs.

When to use: - Before implementing complex changes - Understanding existing codebase - Creating implementation plans - Risk assessment - Architecture analysis

Example:

1
2
3
4
5
6
7

User: "I want to add user registration"
Agent: [In Plan mode]
  - Reads existing user models
  - Analyzes authentication flow
  - Creates implementation plan
  - Lists required changes
  - Asks about preferred approach

Review Mode

Read-only mode - Agent acts as a code reviewer providing feedback.

Capabilities: - Read files and search code - Analyze code quality - Identify bugs and issues - Check for security concerns - Run read-only commands (tests with --dry-run, linting, etc.)

Restrictions: - Cannot edit files - Cannot create files - Cannot delete files - Cannot run mutating shell commands

System Reminder:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# Review Mode

You are in **review mode**. You are a code reviewer providing constructive feedback.

## What You CAN Do
- Read files and search code to understand context
- Analyze code quality, correctness, and style
- Identify bugs, performance issues, and security concerns
- Suggest improvements and alternative approaches
- Check adherence to best practices and project conventions
- Run read-only commands (tests with --dry-run, linting, etc.)

## What You MUST NOT Do
- Do NOT edit, create, or delete files
- Do NOT run mutating shell commands
- Do NOT implement fixes — only describe what should be fixed

## Your Goal
Provide thorough, constructive code review feedback. Be specific about issues
and suggest concrete fixes. Prioritize findings by severity. Focus on:
1. Correctness — bugs, logic errors, edge cases
2. Security — vulnerabilities, unsafe patterns
3. Performance — bottlenecks, unnecessary allocations
4. Maintainability — readability, naming, documentation
5. Architecture — design patterns, coupling, cohesion

When to use: - Reviewing PRs - Code quality checks - Security audits - Performance reviews - Architecture validation

Example:

1
2
3
4
5
6

User: "Review this authentication implementation"
Agent: [In Review mode]
  - Reads authentication code
  - Identifies security issues
  - Suggests improvements
  - Provides specific fix recommendations

Switching Modes

Via Dashboard (Interactive)

The embedded dashboard exposes the agent mode as an ACP session configuration option. Use the mode control in the session composer to select Build, Plan, or Review.

Via API

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

use querymt_agent::prelude::*;

// Create session
let session = agent.new_session().await?;

// Switch to plan mode
session.set_mode(AgentMode::Plan)?;

// Switch to review mode
session.set_mode(AgentMode::Review)?;

// Switch back to build mode
session.set_mode(AgentMode::Build)?;

Via ACP

1
2
3
4
5

// Send notification to change mode
agent.notify_session(SessionNotification::SetAgentMode {
    session_id: session_id.to_string(),
    mode: AgentMode::Plan,
})?;

ACP Session Updates

QueryMT publishes the session state it already tracks so ACP clients stay synchronized. Stable updates are emitted to every ACP v1 client; Preview updates are emitted only when the client advertises the matching capability during initialize.

Stable updates

A mode change produces current_mode_update first, followed by config_option_update. usage_update reports used as the tokens currently occupying model context (cached tokens included) and size as the active model's effective context limit; the update is omitted when the limit is unknown, and cumulative USD cost is included only when available.

Preview (capability-gated) updates

Omitted and null capability fields mean unsupported. Capabilities are parsed per connection, so one client's Preview support never affects another client.

A fully capable client advertises all three during initialize:

1
2
3
4
5
6
7
8
9

{
  "clientCapabilities": {
    "plan": {},
    "session": {
      "notices": {},
      "compaction": {}
    }
  }
}

Leaving any of these fields out (or setting them to null) treats that Preview surface as unsupported for that connection.

Fallbacks

Clients without plan operations receive the legacy full-replacement plan update (an empty snapshot stays an empty replacement because v1 has no removal primitive). Clients without compaction support receive neither compaction_update nor compaction_summary_chunk. Notices fall back to the event source's existing user-visible behavior.

Replay semantics

When session history is replayed (for example on session/load), QueryMT materializes current state instead of replaying every historical event:

• One current mode/config snapshot, one folded metadata patch, and the latest valid usage_update.
• The current todo plan using its stable ID.
• Terminal compactions with their original IDs and final summaries.
• Notices, historical compaction summary chunks, and obsolete in-progress compaction states are never replayed.

Replay applies the connection's capabilities after materialization, so unsupported Preview variants are never sent.

Via Configuration

Set default mode in configuration:

1
2
3

[[middleware]]
type = "agent_mode"
default = "plan"  # "build", "plan", or "review"

Mode Transition Flow

flowchart LR
    B["Build Mode<br/>(default)"]
    P[Plan Mode]
    R[Review Mode]

    B -->|"Select Plan"| P
    P -->|"Select Review"| R
    R -->|"Select Build"| B

Mode-Aware Behavior

Tool Access

*Shell commands are restricted in Plan/Review mode

System Prompt Injection

When in Plan or Review mode, the AgentModeMiddleware injects a system reminder that: - Reminds the agent of its mode restrictions - Clarifies what actions are allowed - Provides guidance on the mode's purpose

Permission Handling

In Plan and Review modes: - Mutating tools are automatically denied - No permission prompts are shown (access is denied by design) - The agent receives clear feedback about mode restrictions

Use Cases

Development Workflow

1. Plan Phase (Plan Mode)
2. Analyze requirements
3. Understand existing code
4. Create implementation plan

5. Get user approval

6. Implementation Phase (Build Mode)

7. Implement the planned changes
8. Write tests

9. Verify functionality

10. Review Phase (Review Mode)

11. Review own changes
12. Check for issues

13. Ensure code quality

14. Repeat as needed

Code Review Workflow

1. Submit Changes

2. Developer makes changes in Build mode

3. Request Review

4. Switch to Review mode

5. Ask agent to review changes

6. Get Feedback

7. Agent provides detailed feedback
8. Lists issues by severity

9. Suggests specific fixes

10. Iterate

11. Developer addresses feedback in Build mode
12. Request additional review if needed

Architecture Analysis

1. Initial Analysis (Plan Mode)
2. Explore codebase structure
3. Identify dependencies

4. Map data flow

5. Planning (Plan Mode)

6. Create migration plan
7. Identify risks

8. Estimate effort

9. Implementation (Build Mode)

10. Execute the plan

11. Make changes incrementally

12. Validation (Review Mode)

13. Verify changes meet requirements
14. Check for regressions

Configuration

Custom Mode Reminders

Customize the system reminders for Plan and Review modes:

1
2
3
4
5
6
7
8
9

[[middleware]]
type = "agent_mode"
default = "build"
reminder = """<system-reminder>
Custom plan mode reminder here.
</system-reminder>"""
review_reminder = """<system-reminder>
Custom review mode reminder here.
</system-reminder>"""

Mode-Specific Tools

Configure different tools per mode:

1
2
3
4
5
6
7
8

# Build mode tools (default)
tools = ["read_tool", "edit", "write_file", "shell"]

# Plan mode tools (automatically filtered)
# Only read-only tools are available

# Review mode tools (automatically filtered)
# Only read-only tools are available

Best Practices

When to Use Each Mode

Use Plan Mode when: - Task complexity is high - You want to avoid accidental changes - You need to understand the codebase first - You want user approval before implementing

Use Review Mode when: - You want objective code feedback - You're checking for security issues - You need quality assurance - You're doing a pre-commit check

Use Build Mode when: - You're ready to implement - You need to make changes - You're fixing bugs - You're adding features

Mode Switching Tips

1. Start in Plan Mode for complex tasks
2. Switch to Build Mode when ready to implement
3. Use Review Mode before finalizing changes
4. Cycle through modes for thorough development

Communication

When switching modes, communicate with the user: - "Switching to Plan mode to analyze the requirements" - "Ready to implement, switching to Build mode" - "Changes complete, switching to Review mode for final check"

Troubleshooting

Agent Still Making Changes in Plan/Review Mode

1. Check that AgentModeMiddleware is in the middleware stack
2. Verify the mode is actually set in the session configuration
3. Check logs for mode-related warnings
4. Ensure mutating tools are in the mutating_tools list

Mode Not Switching

1. Verify the dashboard was built with the dashboard feature and started with --dashboard
2. Check that the mode session configuration option is available
3. Try switching via the ACP API instead
4. Check for middleware errors in logs

Permission Errors in Build Mode

1. Verify assume_mutating setting
2. Check mutating_tools configuration
3. Ensure tools are properly registered
4. Check for tool-specific permission requirements

Examples

See examples/confs/single_coder.toml for a complete configuration with mode-aware middleware.

Related Documentation

• Middleware Guide - AgentModeMiddleware configuration
• Configuration Guide - Full config reference
• API Reference - Mode API types