Design: ReAct loop quality improvements + dual-mode execution (ReAct vs Planner)

[zjshen14]

Background

Research into Claude Code, OpenHands, Cline, Aider, Goose, and Cursor reveals a consistent set of techniques the best agents use to improve loop quality. This issue proposes adopting the most impactful ones and adds a broader architectural question: should OpenCLI support both a ReAct loop and a Planner mode, and when should each be used?

---

Part 1: ReAct Loop Quality Improvements

1. Tool output truncation (middle-truncation)

Current state: Tool results pass through to context raw with no size limit. A single bash call outputting 10,000 lines consumes most of the context window.

What others do:

• Claude Code: 30k char hard cap, middle-truncation (head + tail preserved, middle elided), configurable via BASH_MAX_OUTPUT_LENGTH
• OpenHands: 30k chars, saves full output to a temp file, gives agent the path to read if needed
• Cursor: 20k chars (tail-only — users report this as a frustration)

Proposal:

• Default cap: 20k characters per tool result
• Strategy: middle-truncation — preserve the first ~30% and last ~70% of output; the head contains command context, the tail contains the most recent errors
• For bash: append [... N lines truncated — full output saved to {SESSION_TMP}/tool-output-<id>.txt ...] so agent can read it if needed
• Configurable via OPENCLI_MAX_TOOL_OUTPUT env var

---

2. Max iterations guard

Current state: while (true) in core.ts — no ceiling. Issue #4 covers failing tools but not runaway successful loops.

What others do:

• Claude Code: maxTurns param (no default, but docs recommend 30 for production)
• OpenHands: 500 iterations default, GLOBAL_MAX_ITERATIONS for nested agents
• Goose: --max-turns 1000, separate --max-tool-repetitions for consecutive identical calls

Proposal:

• Add maxTurns?: number to Agent constructor (default: 50)
• On breach: yield a final { type: "error", message: "Maximum iterations (N) reached. The task may be too complex — try breaking it into smaller steps." } event and return
• Add --max-turns CLI flag to opencli chat / opencli run
• Separately: detect stuck loops (same tool + same args called 3× consecutively) and break early with a targeted message

---

3. Git context injected at session start

Current state: System prompt injects {CWD} but no git state. Agent wastes its first turn running git status / git log on almost every coding task.

What others do:

• Claude Code: Injects branch name, default branch, git user, git status --short (capped at 2k chars), last 5 commits from git log --oneline — all at session start, labeled "snapshot in time"
• Aider: Repo map with ranked symbol graph (heavier but more powerful)
• Cline/OpenHands/Goose: No static injection — agent runs git commands manually

Proposal:
Add a getGitContext() helper in src/agent/prompt.ts that runs at session start (non-fatal if not a git repo) and injects into the system prompt:

## Repository
Branch: main (default: main)
Status: (clean) / M src/agent/core.ts, ?? dist/
Recent commits:
  abc1234 fix: session tool call IDs
  def5678 feat: Anthropic client

Cap at ~2k chars. Skip gracefully if git is not available or CWD is not a repo.

---

4. think tool for private reasoning

Current state: No scratchpad. Model must embed reasoning in its visible response text or just act immediately.

What others do:

• OpenHands: Built-in ThinkTool — always present, cannot be disabled, displayed as collapsible in UI. Anthropic's own research shows the think tool pattern measurably reduces wrong-turn tool calls on complex tasks.
• Cline: <thinking> XML tags enforced in system prompt (inline, not a function call)
• Claude Code: System-reminder tunes thinking frequency; effort param enables extended thinking

Proposal:
Register a built-in think tool in createDefaultRegistry():

// Tool definition
name: "think"
description: "Use this to reason privately before acting. The output is never shown to the user — it's a scratchpad for working through complex problems before committing to a tool call."
parameters: { thought: { type: "string" } }
// Execution: no-op, returns { success: true, output: "" }

Display: render as a dim, collapsible block in the renderer (not highlighted like real tool calls). This keeps the visible output clean while giving the model structured reasoning space.

---

5. System-reminder injection mid-loop

Current state: System instruction is injected once at conversation start. On long sessions, models drift from the original instruction (especially around formatting, git rules, and tool usage).

What others do:

• Claude Code: Injects tiny system-reminder blocks into tool results mid-loop (e.g., suggesting TodoWrite when tracking is relevant, reminding about git rules when a commit is detected)

Proposal:
After every N tool result rounds (e.g., every 5), append a compact reminder to the tool results message:

[reminder: commit only when explicitly asked; prefer targeted edits over full rewrites; run tests after changes]

Keep it under 50 tokens. This is cheap and highly effective at preventing drift in long sessions.

---

6. Context compaction (auto-summarize on pressure)

Current state: ContextManager prunes with slice(-maxHistoryMessages) — hard-drops old messages. Issue #2 covers the tool-pair split problem. No summarization.

What others do:

• Claude Code: Five-layer budget reduction → auto-compact pipeline; older turns are summarized by the model, not dropped
• Cline: At 80% context utilization, "Auto Compact" summarizes with middle-removal

Proposal (longer term):
Before dropping messages, call the LLM with a compact prompt: "Summarize the key decisions, files changed, and current state from this conversation in under 200 words." Replace the dropped messages with a single synthetic user message containing the summary. Implement behind a --compaction flag initially so it can be tested.

---

Part 2: ReAct vs Planner Mode

The difference

	ReAct Loop	Planner Mode
How it works	Model reasons and acts interleaved — each tool result informs the next decision	Model generates a full step-by-step plan first, user approves, then executes
Best for	Simple tasks, exploratory work, quick fixes	Complex multi-file refactors, risky operations, unfamiliar codebases
Latency	Lower (starts immediately)	Higher (plan generation round-trip before any action)
Transparency	Low (decisions happen turn-by-turn)	High (full plan visible before execution)
User control	Low (hard to interrupt mid-chain)	High (approve/edit/reject plan before any code changes)
Risk of wrong direction	Higher (can go 10 turns down the wrong path)	Lower (course-correct at the plan stage)

What others do

• Cline: Explicit Plan / Act mode — Plan mode is read-only (no writes), Act mode enables all tools. User switches manually or Cline asks.
• OpenHands: Planning Mode (v1.6.0 beta) — agent generates a plan as a markdown checklist, user approves before any code is written.
• Aider: Architect mode — one model proposes the plan in plain text, a separate (cheaper) editor model implements it.
• Claude Code: No explicit planner mode, but the system prompt's three-phase workflow (Research → Plan → Execute) nudges the model to plan internally before acting.

Proposal: support both modes in OpenCLI

Mode A — ReAct (current, default): Unchanged. Best for quick tasks.

Mode B — Planner: Invoked via /plan <task> slash command or --plan CLI flag.

Flow:

1. Agent runs a read-only planning pass (tools restricted to read, glob, grep, bash with a read-only flag) — no writes, no edits
2. Produces a numbered markdown plan of steps with file paths and rationale
3. Displays plan to user; prompts: [A]pprove / [E]dit / [C]ancel
4. On approval, switches to full ReAct execution using the plan as additional context
5. Agent checks off steps as it completes them (using the think tool to track progress)

Implementation sketch:

• Add mode: "react" | "plan" to Agent.run()
• In plan mode, wrap tool execution with a read-only guard (deny write, edit, bash that writes)
• Add /plan to the slash command registry in repl.ts
• The plan output is injected as a skill-like synthetic context block before the execution phase

When to auto-suggest planner mode:
Consider heuristics to automatically suggest /plan when:

• The user's request contains words like "refactor", "migrate", "redesign", "replace all"
• The request is longer than ~100 words
• The request mentions multiple files/modules

This can be a simple keyword match in repl.ts that prints a suggestion: 💡 This looks like a complex task — run /plan first to review a step-by-step approach before making changes.

---

Summary of proposed changes

#	Change	Complexity	Impact
1	Tool output middle-truncation (20k chars, save to tmp)	Small	High
2	Max iterations guard (default 50) + stuck detection	Small	High
3	Git context snapshot at session start	Small	High
4	Built-in think tool	Small	Medium
5	Mid-loop system-reminder injection	Small	Medium
6	Planner mode (/plan command)	Medium	High
7	Context compaction via LLM summarization	Large	Medium

Suggested implementation order: 3 → 1 → 2 → 4 → 5 → 6 → 7

[zjshen14]

Review: Thoughts on Issue #19

Great issue — well-researched with solid competitive analysis. Here are my thoughts on each proposal, including some implementation concerns and suggestions.

---

✅ 1. Tool output truncation — Agree, with a tweak

Middle-truncation is the right call. The 30/70 head/tail split is well-reasoned — errors tend to land at the bottom.

One thing to watch: the "save full output to tmp file" mechanism needs to be wired into the agent's awareness. If you just silently save the file, the model won't know to read it. The truncation message itself ([... N lines truncated — full output saved to {path} ...]) becomes critical context. Make sure this message is part of the tool result, not just a stderr side-effect.

Also consider: tool output truncation should happen in the executor, not in the tool implementations themselves. This keeps tools simple and the truncation policy centralized. A single truncateOutput(result: string, maxChars: number): string utility in the executor is clean.

---

✅ 2. Max iterations guard — Strongly agree

This is the single most important safety feature missing today. The stuck-loop detection (same tool + same args 3× consecutively) is especially valuable — it catches the most common failure mode (model retrying a failing read or bash call verbatim).

Implementation note: the stuck detection should compare serialized args (JSON.stringify(call.args)), not object identity. And the counter should reset whenever the tool name or args change.

Default of 50 is reasonable. Claude Code's recommendation of 30 for production is worth noting in the --help text.

---

✅ 3. Git context injection — Agree, already implemented

I see this is actually already implemented in src/agent/prompt.ts — the getGitContext() function and the {GIT_CONTEXT} placeholder are both present. Nice work. Is this issue outdated on this point, or is there something additional needed beyond what's already landed?

---

⚠️ 4. think tool — Agree in principle, but consider alternatives

The think tool is a well-known pattern (Anthropic's own research validates it). However, there's a tension: if the model you're using already supports native thinking/reasoning (Gemini's thinking mode, Claude's extended thinking), a think tool is redundant and actually wastes a tool-call round-trip. The model's native thinking is cheaper and faster.

My suggestion:

• For models with native thinking (Gemini Flash Thinking, Claude with extended thinking): skip the think tool, rely on native reasoning
• For models without native thinking: register the think tool

This could be a simple check in createDefaultRegistry() based on the model name. Or, pragmatically, just always register it and let the model decide — it's a no-op anyway, so the cost is just one extra tool definition in the schema.

---

⚠️ 5. Mid-loop system reminders — Cautious agreement

This is effective but fragile. The risk is that reminder content becomes a maintenance burden — every time you change a rule in the system prompt, you have to remember to update the reminder too.

Suggestion: rather than hardcoding reminder text, extract the key rules as a constant array that both the system prompt and the reminder share. Something like:

const CORE_RULES = [
  "commit only when explicitly asked",
  "prefer targeted edits over full rewrites",
  "run tests after changes",
];

Then the reminder is just [reminder: ${CORE_RULES.join("; ")}] and it's always in sync.

Also: every 5 rounds is arbitrary. Consider making this configurable or tying it to a heuristic (e.g., only inject after tool calls that modify files, not after reads).

---

✅ 6. Planner mode — Strong agree, with a note on scope

This is the highest-impact item on the list. The read-only planning pass is the key insight — it prevents the model from making changes before the user has reviewed the approach.

One concern: the "read-only guard" on bash is tricky. You can't reliably detect whether a bash command is read-only without actually parsing it (is curl read-only? git stash? npm install?).

A simpler approach that Cline uses: in plan mode, don't expose write tools at all. Only register read, glob, grep, and think in the tool definitions for the planning pass. The model literally cannot call write, edit, or bash because they're not in the schema. This is foolproof and requires zero command parsing.

---

⚠️ 7. Context compaction — Agree, but deprioritize

Using the LLM to summarize old context is the "right" long-term answer, but it has real costs:

• Extra API call per compaction (latency + money)
• Summary quality varies — if the model forgets a key file path or decision, the agent will repeat work
• Hard to test and debug

Given that items 1-6 collectively reduce context pressure significantly (truncation alone is huge), I'd push this to v2. The current slice pruning + the tool-pair-safe fix from issue #2 is good enough for now.

---

Suggested implementation order (revised)

I'd reorder slightly from the proposal:

Priority	Item	Rationale
1	#2 Max iterations + stuck detection	Safety-critical, prevents runaway costs
2	#1 Tool output truncation	Biggest context-window win
3	#4 Think tool	Small, easy, improves reasoning quality
4	#6 Planner mode	Highest user-facing impact, but larger scope
5	#5 Mid-loop reminders	Nice-to-have, low effort
6	#7 Context compaction	Defer to v2

Note: #3 (git context) appears to already be implemented.

Overall this is a solid roadmap. The combination of max-iterations + truncation + planner mode would bring OpenCLI's agent loop quality close to the state of the art.

[zjshen14]

One extra architectural pass after comparing the proposal to the current code:

• #3 looks already landed: getGitContext() exists in src/agent/prompt.ts, and ContextManager.getSystemInstruction() injects {GIT_CONTEXT} at session start.
• For #1, I would avoid blanket truncation of read results. read already supports offset/limit and returns line-numbered source in src/tools/file/read.ts; if the executor middle-truncates that output, the agent can lose the exact span it needs for later edit calls. I would start by truncating noisy tools like bash (and maybe grep/glob) while keeping file reads paginated instead.
• For #6, planner mode probably belongs above the ReAct loop rather than inside it. Agent.run() in src/agent/core.ts is currently a clean single-purpose loop; adding mode: "react" | "plan" there risks mixing planning UI / approval flow with core orchestration. A cleaner shape is: create a restricted read-only registry, run a planning pass, then inject the approved plan as extra context into a normal execution agent.
• On #4, Anthropic updated its think-tool guidance on December 15, 2025 to recommend extended thinking instead in most cases, so I would make this provider-aware or defer it behind #1 / #2 unless we see real evidence that reasoning quality is the current bottleneck.

If I were sequencing this from the current codebase, I'd still do #2 first, then #1, then #6.

[zjshen14]

Thanks for the thorough review — both sets of comments are sharp and I'm incorporating them.

Key changes to the plan

#20 (git context) — Already landed in commit 4f3bdc3. Closed.

#21 (tool output truncation) — Agreed on scoping this to bash only (and optionally grep/glob). The second reviewer is right that middle-truncating read output would break edit calls that depend on exact line spans. Updating the issue accordingly.

#22 (max iterations + stuck detection) — Moving this to the top of the queue. Both reviewers flagged it as the most important safety fix. Stuck detection will compare JSON.stringify({ name, args }) and reset on any change.

#23 (think tool) — Making it provider-aware: skip registration for models with native thinking support (Gemini thinking variants, Claude extended thinking). Will defer behind #21 and #22.

#25 (planner mode) — revised architecture — The second reviewer's point is exactly right. Agent.run() should stay a clean single-purpose loop. The revised design:

1. /plan creates a restricted read-only ToolRegistry containing only read, glob, grep (no bash, write, edit)
2. Runs a separate Agent instance with that registry — no mode flag needed inside core.ts
3. Collects the plan output, renders it, prompts [A]pprove / [E]dit / [C]ancel
4. On approval: injects the plan as a synthetic context block and runs a normal Agent with the full registry

This lives entirely in repl.ts (or a new src/cli/planner.ts), not in core.ts.

#26 (context compaction) — Agreed, defer to v2. Items 1–5 reduce context pressure enough that compaction isn't urgent.

Revised implementation order

#	Item	Status
#20	Git context injection	✅ Done
#22	Max iterations + stuck detection	Next
#21	Tool output truncation (bash/grep/glob only)	After #22
#25	Planner mode (above the loop, not inside it)	After #21
#23	Think tool (provider-aware)	After #25
#24	Mid-loop system reminders	After #23
#26	Context compaction	Defer to v2

[zjshen14]

Status Update

4 of 7 proposed items have been implemented:

#	Item	Status
1	Tool output middle-truncation (20k chars, head/tail split)	✅ Shipped
2	Max iterations guard (default 50) + stuck-loop detection (3× threshold)	✅ Shipped
3	Git context snapshot at session start	✅ Shipped
4	Built-in think tool (conditional — skipped for models with native thinking)	✅ Shipped (#23)
5	Mid-loop system-reminder injection	❌ Tracked in #24
6	Planner mode (/plan command)	❌ Tracked in #25
7	Context compaction via LLM summarization	❌ Tracked in #26

Keeping this issue open as a tracking umbrella until #24, #25, #26 are resolved.

[zjshen14]

Progress update — all sub-tasks complete except #26

Status

Issue	Feature	Status
#20	Git context snapshot at session start	✅ Closed — getGitContext() in prompt.ts, {GIT_CONTEXT} in system instruction
#21	Middle-truncate tool outputs	✅ Closed — truncateOutput() in executor.ts; 30/70 head/tail split; full output saved to SESSION_TMP; configurable via OPENCLI_MAX_TOOL_OUTPUT
#22	Max iterations guard + stuck-loop detection	✅ Closed — maxTurns (default 50), --max-turns CLI flag, 3-identical-call stuck detection
#23	Built-in think tool	✅ Closed — implemented by Codex/Antigravity; skipped for native-thinking models (Gemini 2.5+/3.x)
#24	Mid-loop system reminders	✅ Closed — event-driven (not turn-based): fires based on which tools ran; appended to last tool result
#25	Planner mode	✅ Closed — /plan <task> in REPL, --plan flag on opencli run; read-only pass with @clack/prompts Approve/Edit/Cancel; defence-in-depth (tool list filtered + executor readOnly guard)
#26	Context compaction	🔲 Open — still to implement

Notes on design decisions

#24 — Event-driven vs. turn-based reminders: Original proposal was "every 5 turns". Implemented as event-driven instead: reminders fire only when relevant (e.g. after edit/write → "run tests"; after bash with git → "never commit without explicit request"). This avoids noise on turns where the reminder isn't actionable and removes the magic-number maintenance burden.

#25 — Bash blocked entirely in plan mode: The sub-task proposal allowed bash with "read-only validation". After researching how Claude Code (allowlist of specific binaries), Cline (full bash allowed), and Aider (no bash in plan) handle this, I blocked bash entirely. read/glob/grep cover 95% of exploration needs, and reliably validating bash as read-only is hard (subshells, redirects, find -exec). Can revisit with a bash allowlist in a follow-up.

#25 — Plan prompt synthesis: The plan system prompt is based on research into Claude Code, Cline, Aider, and OpenHands plan modes — 4-step process (Understand → Explore → Design → Plan), mandatory - [ ] checklist output with file paths in every step, and ⚠️ risk flagging for unverified assumptions (a gap none of the four had filled).

Remaining: #26 context compaction

This is the one piece left. It's larger than the others — requires an LLM call during context pressure, not just a local computation. Suggest implementing behind a --compaction flag as originally proposed.