Plan and track work

Orek has two independent ways to organize work: Plan mode lets you review an approach before any changes, and a saved checklist tracks progress while the work happens. You can track work without planning first, and you can approve a plan without a checklist.

Choose a workflow

update_plan only shows progress in the transcript. It does not approve a plan, change the saved checklist, or start a workflow. Finishing a checklist does not finish or cancel a workflow run.

Plan an approach

Orek starts in normal mode unless you choose Plan mode. In normal mode, it can investigate your request, edit project files, and run commands, subject to your permission and approval rules.

Plan mode is an optional step before implementation. Orek reads code, searches, and asks questions to propose an approach, while project edits and commands are blocked. You review the proposal and decide when to start. Approving a plan returns Orek to normal mode; each action still follows your permission and approval rules.

Start a plan

With Orek open in your project, enter a task in the composer:

/plan Plan how to add request validation to this project. Identify the files to change and the tests to run.

You can also enter /plan on its own and describe the work in your next message. Plan mode stays on across turns until you approve a proposal or run /plan exit or /plan clear. Root PLAN.md files are not imported; approved plans use .orek/plans/.

The agent investigates with the tools Plan mode allows and presents a proposed plan. Read the approach, expected changes, and verification steps before you choose how to continue.

Review and approve the proposal

When the proposal is ready, use Tab or the arrow keys to select a choice and Enter to confirm. The default, and Esc, keep planning:

Clearing context clears the visible transcript and the model’s conversation within the same session and saves the cleared state, so resuming the session does not bring the planning conversation back. The approved plan and tracked work stay available.

Approval clears the previous checklist and sends "Implement the plan." in the current conversation, or the approved plan text in a fresh one. The agent can then create a checklist with write_tasks.

To revise the approach, stay in Plan mode and describe the change you want. Approval starts implementation immediately, but each tool action still follows your permission rules.

What’s blocked

Plan mode blocks workspace edits, shell commands, checklist changes, and starting new subagents. A blocked call is refused outright rather than turned into an approval prompt.

Plan mode applies to the whole session. Subagents already running, including workflow steps, enter Plan mode with you and leave it when planning ends, with the same tools blocked.

Each tool call is checked when it starts. If the model asked for several calls at once, entering or leaving Plan mode affects only calls that have not started; calls already running finish. See Several tool calls at once.

The memory tool is an exception. It can save information outside the workspace while you plan. Plan mode blocks project edits and commands; it does not stop everything from being saved. Orek also keeps saving the session history.

Approval mode while planning

Changing the approval mode while planning, with /permissions <default|auto_review|yolo> or Alt+Y, sets the mode that applies when Plan mode ends. Until then, blocked tools stay blocked in every mode, and pending approvals for sensitive reads or subagents wait until you leave Plan mode.

Resuming a conversation with /sessions (or orek chat --continue) restores Plan mode if the session was still planning when it stopped.

Choose when to plan

Plan when a task has several possible approaches, touches many files, or needs a decision first. State the outcome and constraints in your request, then check that the proposal covers both.

For a small change with an obvious approach, work in normal mode and review the diff. Planning is separate from the approval rules that govern what runs.

What the plan looks like

A useful plan explains the outcome, approach, affected files, and how to verify the result. The main agent and its subagents share your project files, and Orek does not lock files per step, so check that parallel steps change separate files. For example:

# Add request validation

## Outcome
Reject invalid input before it reaches the handler.

## Approach
1. Define the request schema and its validation, with unit tests, in
   `src/validation.rs`.
2. Add a `400 Bad Request` error response type in `src/errors.rs`.
3. Validate requests in the handler in `src/handlers/request.rs`, returning the
   new error response, and cover valid and invalid requests in
   `tests/request_validation.rs`.

Steps 1 and 2 are independent and change separate files, so they can run in
parallel; step 3 uses both, so it runs after them.

## Verification
Run the affected tests and review the response behavior.

When the agent tracks approved steps with write_tasks and hands one to a subagent through work_item_id, the subagent starts with that step’s text. See Subagents linked to a checklist item.

Configuration

Plan mode decides whether the agent is planning or implementing. The approval mode decides when tools ask first. Set the approval mode in your user configuration (a project’s .orek/config.toml cannot set it):

[exec]
default_approval_mode = "auto_review"   # plan | default | auto_review | yolo

The default is auto_review. Setting the approval mode to plan starts Orek in Plan mode.

For a single run:

orek --approval-mode plan run "<task>"

Use the TUI when you want to review and approve the proposal interactively.

Track work with a checklist

Ask Orek to track a multi-step task in a checklist:

Add request validation and cover it with tests. Track the work in a checklist,
show any blockers, and report the validation results when you finish.

A checklist has an overall goal and a flat, ordered list of tasks that records progress as the agent works. For saved steps you can run again with new inputs and explicit dependencies, see Create reusable workflows. Both appear in /workflows.

A typical task can start with an approved plan and continue as ordinary implementation. The agent creates its checklist with write_tasks, uses tools or subagents, and updates the checklist from actual results. It can also run a workflow for part of the work; it waits for the workflow to finish or stop and gets its status back.

Task states

Checklist order shows the intended sequence but does not enforce it. The agent decides what can proceed and coordinates subagents. Use a reusable workflow when one step must wait for another or receive its answer.

The agent uses write_tasks when it needs saved task IDs, linked subagents, or continuation. Each update replaces the whole checklist and returns the saved IDs. Only one item can be in_progress at a time. See Agent tools for the exact parameters.

Inspect progress

Watch the checklist pinned above the composer and the [tasks: done/active] chip in the status bar, or open the full view:

/workflows

/workflows opens a full-width view with [1 Overview], [2 Tasks], [3 Runs & Agents], and [4 Recipes] sections (press 1–4 or Tab to switch). Select an item and press Space to see its status and linked work, press Enter on a subagent to switch to its conversation, or press Esc to return.

Session rows show each session’s opening message, full session ID, last model, and update time. Use the session picker to inspect or resume an earlier conversation; see Manage sessions.

These views exist only in the TUI; there is no shell command for them.

Blocking and unblocking

A blocked item records what prevents progress. For example:

Status: blocked
Reason: The request format allows two interpretations.
        Need clarification before changing validation behavior.

Reply in chat with the missing information or changed requirement, and the agent can update the checklist and continue on the next turn. If other items do not depend on the blocker, tell it to continue with those.

An item marked completed is the agent’s own report. Check its result and test evidence before treating the task as verified.

Continue from the interface

While a turn is running, use /steer <message> to add guidance at the next checkpoint, or type an ordinary message to queue it for the next turn.

At the end of a turn:

• Completion: the checklist completes when the main agent’s turn ends with no item pending, in_progress, or blocked and no subagent started by the main agent still running. If every task was cancelled, the summary reads "Goal ended: all tasks cancelled" instead of "Tasks complete", and the count shows cancelled tasks, as in Tasks 1/2 · 1 cancelled.
• Subagent results: when a subagent started by the main agent finishes, or messages main with send_input, the main agent takes another turn (see When a subagent finishes). Closing a subagent (close_agent or /agent close) stops it without waking main.
• Waiting for you: while unfinished tasks from your request remain, automatic continuation pauses when the agent asks for confirmation or approval, or ends with a direct question or offer to act.
• Manual or automatic: by default (agent.auto_continue = false), Orek stops at the end of the turn and shows "N tasks remaining — type \continue`“. With agent.auto_continue = true(or/auto-continue on`), the TUI continues on its own until one of the stop conditions under Headless work and continuation applies.

What survives an interruption

Conversation compaction

The checklist is saved separately from the conversation, so Orek restores it after the conversation is summarized and shortened.

Session resumption

Resuming a session restores its plan approval and active checklist. A checklist whose tasks are all completed or cancelled is not restored as active work. Check the last recorded work before deciding what to retry.

Subagents linked to a checklist item

spawn_agent, fanout, and saved workflow files can link a subagent to a checklist item with work_item_id. While the checklist has items, a link to an unknown ID is rejected with an error that lists the current IDs. If the linked item was removed or cancelled by the time the subagent finishes, the subagent still reports its result without changing the checklist.

A linked subagent’s first prompt holds its task, followed by the item’s text and any blocked reason or earlier result. When it finishes, success marks the item completed and failure marks it blocked with the error. Each subagent’s conversation is saved with the session that started it; see Saved subagent transcripts.

Resume workflow steps without repeating them

Orek records each workflow step’s subagent and result, so resuming a run does not repeat finished work:

This prevents repeated workflow steps, but does not make shell commands or network requests run exactly once. A command may have changed files or an external service before it was interrupted, so review interrupted actions before repeating them.

Every subagent and workflow step works directly in your project files, so its edits appear immediately. See Delegate to subagents.

Where work is saved

Orek saves checklist changes, plan approvals, and workflow progress next to the session file in your user data folder:

<sessions_root>/<project_hash>/<id>.workflow.jsonl

See session storage locations for the path on each platform. This file is separate from the project’s .orek/plans/ folder. It records progress only; it cannot roll back file edits or undo external commands.

Trace integration

When observe.otlp_endpoint is set, changes to tracked work are exported as trace events. See OpenTelemetry export for the fields.

Headless work and continuation

Run a task without the TUI. Actions follow the approval mode: default prompts on an interactive terminal, and auto_review applies edits without asking and checks each shell command’s risk locally:

orek run --approval-mode auto_review "Update the database models and verify the migration. Track the remaining steps in a checklist."

orek run and editor sessions (orek acp) never continue unfinished checklist items on their own, although finishing subagents still wake the main agent (see When a subagent finishes):

• orek run --json (orek.run/v1): when pending, in_progress, or blocked tasks remain, the output includes remaining_work with stop_reason and tasks (id, title, status, and optional blocked_reason). remaining_work is left out when nothing is unfinished.
• orek acp: checklist updates appear in the editor’s plan view. Editors using the older protocol version show a blocked item as pending, marked [blocked] with its reason.

In the TUI, type continue to run one more turn, or turn on automatic continuation with /auto-continue on (status-bar chip [auto-continue]; save it with /auto-continue persist on). Orek then continues tasks from your current request (or one resumed with continue) until:

• Your input or approval is needed.
• All unfinished items are blocked.
• The continuation limit is reached.
• Three continuation turns in a row make no tool calls.
• Another limit or failure ends the run.

Each automatic continuation adds a short message telling the model to keep going; the transcript shows it as an Auto-continue: notice, not as something you typed.

Unfinished tasks from an earlier request do not continue under an unrelated prompt. Orek waits for subagents the main agent started, whether or not agent.auto_continue is on, and that wait does not use up continuation attempts.

The TUI continues at most 8 times per request by default (1–255). agent.auto_continue is saved in your user configuration by default, and agent.max_auto_continuation_attempts in the project configuration:

[agent]
auto_continue = false
max_auto_continuation_attempts = 8

Resume a saved run with a new instruction:

orek run --approval-mode auto_review --resume <ID> "Continue the remaining work"

Use orek session list to find the session ID. For interactive work, orek chat --continue resumes the newest session in the current project.

Next steps

• Delegate to subagents to split independent work.
• Create reusable workflows for explicit dependencies and repeatable runs.
• Manage sessions to find, resume, or export a conversation.
• Permissions and security for what runs and when Orek asks.