Plugin API: clear context and restart with file

Use case

Building iterative dev loop plugins (like rl) where the workflow has two distinct phases:

1. Planning — design/spec/plan discussion with the user, producing a structured task file
2. Execution — iterative implementation loop with review gates

Claude Code's built-in plan mode handles this perfectly: plan in restricted mode, save plan.md, clear context, restart with the plan as seed. But plugins can't replicate the "clear context and restart" step — there's no hook or API for it.

Current workaround

Write the plan to disk (.rl/prompt.md), rely on natural compaction to compress the planning conversation, and use the stop hook's reason field to inject the plan as a fresh directive. This works but the planning context stays in the window competing with execution context.

The cleanest alternative today is telling users to start a new claude session manually, which breaks the flow.

Proposed API

A plugin-accessible method to clear conversation context and restart with a new prompt, similar to what plan mode does internally:

// From a hook callback
return { clearContext: true, prompt: "Read .rl/prompt.md and execute the task." };

// Or as a standalone API in the Agent SDK
await queryHandle.clearContext({ prompt: "..." });

This would enable plugins to build multi-phase workflows (plan → execute, research → implement, etc.) with clean context boundaries between phases.

Alternatives considered

• Session forking (forkSession) — keeps old context, doesn't help
• Compaction — happens automatically but doesn't clear, just compresses
• Stop hook reason injection — injects a directive but old context remains
• Manual new session — works but breaks the flow

Context

• Plugin: 0xbigboss/rl — iterative dev loops with Codex review gates
• The PreCompact and SessionStart hook events exist but can't inject files or clear context