Plan Mode

Role

Plan Mode lets the agent “figure out and write down intent” before executing. While active, the agent is in a read-only phase:

Only read-only tools plus 4 whitelisted tools work: plan_enter / plan_write / plan_exit / todo_write (the shell can be opted in — see below).
Any other tool call is rejected immediately (the agent sees a “plan-mode denied” note).
Exiting Plan Mode requires HITL confirmation (reusing the permission system’s ASK), so the model can’t unilaterally jump into execution.

This pipeline encodes “design → plan → human review → execute” — combined with todo_write and subagents, it noticeably reduces “improvise-then-break-things” outcomes on long tasks.

Opt-in

HarnessAgent agent = HarnessAgent.builder()
    .name("planner")
    .model(model)
    .workspace(workspace)
    .enablePlanMode()                          // installs the Plan Mode trio
    .planFileDirectory("plans")                // optional; default "plans"
    .build();

Builder options:

Method	Default	Notes
`enablePlanMode()` / `enablePlanMode(boolean)`	`false`	enable Plan Mode
`planFileDirectory(String)`	`"plans"`	plan-file root (workspace-relative)
`allowShellInPlanMode()` / `allowShellInPlanMode(boolean)`	`false`	opt in to running the shell (`execute`) during the plan phase — see Allowing the shell during the plan phase

You can also call enableTaskList() so that todos created during the plan phase show up as a small reminder before each reasoning step.

The three tools

Tool	Purpose	Params
`plan_enter`	Enter Plan Mode	none
`plan_write`	Write content to the current plan file (default `plans/PLAN.md`)	`content`
`plan_exit`	Exit Plan Mode → execution phase; HITL confirmation	`rationale` (optional)

plan_write is a dedicated write entry for Plan Mode — avoids the security risk of whitelisting the generic write_file (which would let the model write anywhere during plan).

Workflow

Any non-whitelisted tool call (e.g. write_file, or execute unless you opt in) during the plan phase is rejected immediately with something like:

[Tool denied — plan mode is active]
Only read-only tools and plan_enter / plan_write / plan_exit / todo_write are allowed.

Seeing the denial, the model naturally switches back to “write the plan first”.

Reading the outcome

Plan-mode entry is autonomous, so a run can end in four states. isPlanModeActive() == false alone is ambiguous — don’t treat it as success without checking whether planning actually happened:

Terminal state	Meaning
Never entered plan mode	Model chose to work directly in build mode — a valid decision, often because the task doesn’t match the workspace.
Entered → `plan_exit`	Success: planned, got approval, now in build mode.
Still in plan mode + `PLAN.md` exists	Drafted a plan but didn’t exit; resume the session to approve.
Still in plan mode + no `PLAN.md`	”Narrate but don’t act”: the final message may read like a plan but none was written — give more specific input or a matching codebase.

To tell these apart programmatically, track whether plan_enter / plan_write were called (e.g. from ToolCallStartEvent) alongside the final isPlanModeActive() and the plan file’s existence.

Allowing the shell during the plan phase (opt-in)

By default the shell tool (execute) is denied during the plan phase. The shell is dual-use: a single tool call can read (cat / ls / grep / git log) or mutate (rm / > / git commit / npm install), and Plan Mode decides what to permit purely by tool name — so it cannot tell a read invocation from a write one. Denying the shell keeps the read-only guarantee intact. But shell access is often the most flexible way to investigate a codebase and produce a realistic plan. When you accept that trade-off, opt in:

HarnessAgent agent = HarnessAgent.builder()
    .name("planner")
    .model(model)
    .workspace(workspace)
    .enablePlanMode()
    .allowShellInPlanMode()   // let the model run the shell read-only during plan
    .build();

With the opt-in enabled:

execute is added to the plan-phase allow-list, so the model can investigate via the shell.
The plan banner gains an extra instruction telling the model to keep shell usage read-only (cat / ls / grep / git log/diff/show/status) and not to run mutating commands until the plan is approved.
The dedicated file-editing tools (write_file / edit_file) remain denied — they are the primary mutation path, so the read-only intent is still enforced for file writes.

This mirrors how OpenCode handles its plan agent: it allows the shell for investigation, hard-blocks the edit/write tools, and relies on the prompt to keep the shell read-only. The guarantee is therefore softer than the default (the model could still mutate via the shell), so prefer enabling this together with a sandboxed filesystem to contain the blast radius.

Runtime permission switching (the “bypass” escape hatch)

Plan Mode is one specific phase switch. Underneath it, every session carries a PermissionMode that the permission engine evaluates against. You can flip that mode at runtime — for example to grant a deliberate, user-initiated “skip all permission prompts” toggle (similar to a YOLO / dangerous-skip switch in other coding tools):

RuntimeContext ctx = RuntimeContext.builder().sessionId("my-session").build();

agent.setPermissionMode(ctx, PermissionMode.BYPASS);    // allow everything, no prompts
// ... run the operations that need full access ...
agent.setPermissionMode(ctx, PermissionMode.DEFAULT);   // restore normal enforcement

PermissionMode current = agent.getPermissionMode(userId, sessionId);

setPermissionMode(...) preserves the session’s configured allow/deny/ask rules and working directories — only the mode changes — and rebuilds that session’s cached permission engine so the switch takes effect on the next call. An in-flight call keeps the engine it started with. ⚠ BYPASS disables all rule evaluation, so treat it as an explicit, per-session, opt-in action and prefer pairing it with a sandbox. To run unattended without prompts but with enforcement, use PermissionMode.DONT_ASK instead (ASK decisions become DENY rather than being auto-allowed).

Plan state is persisted

Plan Mode is runtime state and is auto-persisted along with AgentState — process restarts, node failovers, and cross-replica restores all bring back the plan phase. The plan file itself is written to plans/ in the workspace and goes through whichever filesystem mode you’ve configured (local / sandbox / remote KV), so it’s distributed-safe.

Programmatic enter/exit

When app code drives Plan Mode (e.g. an admin console button):

RuntimeContext ctx = RuntimeContext.builder().sessionId("my-session").build();
agent.enterPlanMode(ctx);    // equivalent to the LLM calling plan_enter
agent.exitPlanMode(ctx);     // equivalent to plan_exit; programmatic entry does NOT trigger HITL
agent.isPlanModeActive(ctx);

If you use agentscope-admin-spring-boot-starter, the admin HTTP API also exposes Plan Mode controls (POST /v1/admin/sessions/{id}:enter-plan-mode / :exit-plan-mode / GET /v1/admin/sessions/{id}/plan).

Interaction with subagents

⚠ Current known gap: subagents spawned via agent_spawn during Plan Mode do not automatically inherit the read-only restriction. To restrict the child:

Narrow tools in the child’s declaration to a read-only set, or
Also enablePlanMode() on the child’s own builder and enter it explicitly

A future release will propagate plan-mode restrictions parent → child automatically.

Interaction with `todo_write`

Plan Mode and todo_write (provided by core) are independent but commonly used together:

Plan Mode — phase switch + plan file + HITL exit
todo_write — maintain a structured “what to do now” list during execution (whole-list replace; exactly one in_progress)

Typical workflow: write PLAN.md during the plan phase → plan_exit → in execution use todo_write to slice the PLAN into 5–8 todos → progress one at a time. Each reasoning step shows the agent a todos reminder to stay focused. ⚠ Don’t confuse with subagent background tasks (task_output / task_cancel / task_list) — that’s a different concept; see Subagent.

Viewing the task list

The task list lives in AgentState.tasksContext and is persisted automatically with every call(). To read it from application code:

List<Task> tasks = agent.getAgentState(userId, sessionId)
        .getTasksContext()
        .getTasks();

for (Task t : tasks) {
    System.out.printf("[%s] %s%n", t.getState(), t.getSubject());
    // state: PENDING / IN_PROGRESS / COMPLETED
}

If you use agentscope-admin-spring-boot-starter, the admin REST API provides a ready-made endpoint:

GET /v1/admin/sessions/{sessionId}/tasks

It returns each task’s subject, state, owner, and dependency info (blocks / blockedBy). To observe task changes in real time through the event stream, listen for todo_write tool calls in streamEvents():

agent.streamEvents(message)
    .filter(e -> e.getType() == AgentEventType.TOOL_RESULT_END)
    .filter(e -> "todo_write".equals(((ToolResultEndEvent) e).getToolCallName()))
    .doOnNext(e -> {
        // Re-read the latest task list from state
        var tasks = agent.getAgentState(userId, sessionId)
                .getTasksContext().getTasks();
        updateUI(tasks);
    })
    .subscribe();

Workspace — plans/ directory location
Subagent — todo_write ≠ subagent task; don’t confuse them
Architecture — where Plan Mode sits in the call() timeline

Quick Start

Building Blocks

Harness

Reference

Role

Opt-in

The three tools

Workflow

Reading the outcome

Allowing the shell during the plan phase (opt-in)

Runtime permission switching (the “bypass” escape hatch)

Plan state is persisted

Programmatic enter/exit

Interaction with subagents

Interaction with `todo_write`

Viewing the task list

​Role

​Opt-in

​The three tools

​Workflow

​Reading the outcome

​Allowing the shell during the plan phase (opt-in)

​Runtime permission switching (the “bypass” escape hatch)

​Plan state is persisted

​Programmatic enter/exit

​Interaction with subagents

​Interaction with todo_write

​Viewing the task list

​Related Pages

Role

Opt-in

The three tools

Workflow

Reading the outcome

Allowing the shell during the plan phase (opt-in)

Runtime permission switching (the “bypass” escape hatch)

Plan state is persisted

Programmatic enter/exit

Interaction with subagents

Interaction with `todo_write`

Viewing the task list

Related Pages