#17240: feat: add /plan directive for read-only analysis mode
agents
stale
size: M
Cluster:
Error Handling in Agent Tools
## Summary
Adds `/plan` directive for read-only analysis mode, inspired by Claude Code and Gemini CLI plan modes.
**Closes #17084**
## Changes
### Directive
- `/plan on` — Enable plan mode (read-only tools only)
- `/plan off` — Disable plan mode (restore default tools)
- `/plan` — Show current status
### Tool Profile
Plan mode restricts to read-only tools:
- `read`, `web_search`, `web_fetch`
- `memory_search`, `memory_get`
- `session_status`, `sessions_list`, `sessions_history`
- `image`
### System Prompt
When plan mode is active, injects guidance based on Claude Code/Gemini CLI research:
- Emphasizes read-only constraint
- Provides workflow: Explore → Plan → Ask
- Includes "Asking Good Questions" guidance
## Testing
- Added plan profile tests (5 tests)
- Added directive parsing tests (invalid level, colon variant)
- All existing tests pass
## Future Considerations (not in this PR)
- Whether `browser` (snapshot-only) should be in plan profile
- Whether subagents should inherit plan mode
- System event notification on plan mode toggle
## Review Notes
-[x] Local validation (pnpm build && pnpm check && pnpm test) and manally tests
-[x] Focused scope (one change/theme per PR): only add /plan feature with minimal scope
-[x] Clear "what" + "why" in description
-[x] AI-assistance transparency (if used): Yes, implementation drafted with AI, manually reviewed and tested

<!-- greptile_comment -->
<h3>Greptile Summary</h3>
This PR adds a `/plan` directive that enables read-only analysis mode, restricting tools to a read-only subset (`read`, `web_search`, `web_fetch`, `memory_search`, `memory_get`, `session_status`, `sessions_list`, `sessions_history`, `image`). When plan mode is enabled via `/plan on`, it injects custom system prompt guidance and switches the tool profile to `"plan"`, which enforces the tool restrictions. The implementation properly threads `sessionToolProfile` through the agent execution pipeline and includes comprehensive test coverage.
Key changes:
- Added `PlanLevel` type and normalization in `thinking.ts`
- Added `extractPlanDirective()` for parsing `/plan [on|off]` directives
- Added `"plan"` tool profile to `tool-policy.ts` with read-only tool allowlist
- Wired `sessionToolProfile` through execution params and tool selection
- Injects plan mode guidance into system prompt when active
- Saves/restores previous `toolProfile` when toggling plan mode on/off
- Added 7 new tests covering plan directive parsing and tool profile validation
Issues found:
- **Critical**: Missing `currentPlanLevel` parameter prevents `/plan` status queries from working
- **Critical**: Inconsistent `previousToolProfile` handling between two code paths causes incorrect tool profile restoration in some scenarios
<h3>Confidence Score: 2/5</h3>
- This PR has critical bugs that will cause runtime failures
- Two critical logical errors were found: (1) the `/plan` status query won't work because `currentPlanLevel` is never passed to the handler, and (2) the tool profile restoration logic is inconsistent between two code paths, which will cause incorrect behavior when toggling plan mode off in certain scenarios. Both issues need to be fixed before merging.
- Pay close attention to `src/auto-reply/reply/get-reply-directives-apply.ts` and `src/auto-reply/reply/directive-handling.persist.ts`
<sub>Last reviewed commit: 9e034f7</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#21648: feat: execution plan governance plugin
by nayname · 2026-02-20
72.6%
#10189: fix: resolve file_path param in tool display for read/write tools
by Yida-Dev · 2026-02-06
72.6%
#16064: feat: add contact-based tool permissions with verification
by jamiequint · 2026-02-14
72.5%
#18992: fix: suppress spurious tool error warnings for read-only exec commands
by Phineas1500 · 2026-02-17
72.2%
#19094: Fix empty tool_call_id and function names in provider transcript pa...
by yxshee · 2026-02-17
70.9%
#23783: Tools: add strict allowlist mode and fail closed on unknown entries
by bmendonca3 · 2026-02-22
70.6%
#10998: fix(agents): pass session thinking/reasoning levels to session_stat...
by wony2 · 2026-02-07
70.4%
#21136: fix(security): harden agent autonomy controls
by novalis133 · 2026-02-19
70.2%
#7044: feat: Add local model tool calling support
by jokelord · 2026-02-02
70.1%
#21285: fix(auto-reply): parse toolCall read paths in post-compaction audit
by Jackten · 2026-02-19
70.1%