Plan mode

Plan mode makes IsonForge research-only. The agent reads files, searches the codebase, fetches docs, builds a TodoWrite plan, and proposes - but it cannot write, edit, or run bash.

Use for:

• Complex refactors where you want to see the plan before any code moves.
• Unfamiliar codebases - let IsonForge explore + summarize first.
• High-stakes changes where a wrong patch is expensive.

Enter plan mode

Three ways:

At startup:

isonforge --permission-mode plan "refactor auth/session.py to use redis"

Mid-session, hard enforcement:

Press Shift+Tab until the status line shows plan. This applies server-enforced filtering.

Mid-session, prompt-only guidance:

/plan on

This adds plan-mode instructions to the system prompt for the current turn but does not strip tools server-side. The model is told not to mutate but technically could. Use the Shift+Tab cycle or --permission-mode plan for the hard guarantee.

What works in plan mode

• read_file
• search_files
• list_files
• glob
• web_search
• web_fetch
• task_explore (sub-agent, read-only)
• task_research (sub-agent, read-only)
• todo_write (for the plan itself)
• Workspace read tools (workspace_list, workspace_read in Web Forge)

What's blocked

The server strips these from the tool list before the model sees them. Calls won't even attempt:

• write_file
• edit_file
• bash (no shell execution at all)
• bash_output, kill_shell
• workspace_write, workspace_edit (Web Forge)
• Any MCP tool that hasn't been explicitly allowlisted

The plan output

IsonForge writes the plan via todo_write (or as inline markdown). A typical output:

Goal: Refactor session storage from in-memory Map to Redis.

Plan:
1. Read current session implementation
   - src/auth/session.py (constructor, store, retrieve, delete)
   - tests/auth/test_session.py (8 tests)
2. Add redis-py dependency
   - poetry add redis (or pip install)
3. Replace the storage backend
   - Keep the existing interface (set/get/del with TTL)
   - Connection from env var REDIS_URL
   - Retry + fallback to in-memory on connection failure
4. Update tests
   - Use fakeredis for unit tests
   - Add integration test with real redis (skip if no REDIS_URL)
5. Migration note
   - Existing sessions invalidate on deploy. Document in CHANGELOG.

Risks:
- Connection pooling not handled - if traffic spikes, may want a pool config.
- TTL behavior differs subtly between in-memory expiry and redis EXPIRE.
- Tests will need docker compose for integration.

Reply "apply" or "gas" to switch to execution.

Switch to execution

After reviewing:

gas

or:

apply

IsonForge switches to default (or whatever your previous mode was) and begins executing the plan.

If you want to keep iterating on the plan:

> the redis fallback is wrong - retry should just fail loud

The agent updates the plan without mutating anything.

Plan mode vs Skills with disable-model-invocation

Both stop the model from acting unprompted, but they're different:

• Plan mode is a session-wide gate on mutating tools.
• disable-model-invocation: true on a specific Skill prevents the model from suggesting that skill, but doesn't restrict tool calls.

Use plan mode for "let me see what you're going to do before you do it." Use disable-model-invocation for "only I get to invoke this specific workflow."

Web Forge plan mode

In Web Forge, plan mode is a toggle in the UI (/plan slash also works). It does the same server-enforced tool filtering. The plan shows in the TodoWrite sidebar.

Best practices

• Use plan for unfamiliar code. A 30-second plan beats a 5-minute revert.
• Don't skip review on big plans. If the agent proposes editing 12 files, read carefully before gas.
• Switch modes per turn. Plan to gather, switch off to execute, switch back to plan for the next chunk.
• Pair with /checkpoint. Even after switching out of plan mode, take a checkpoint before the agent starts changing files.