explanation of hook

Here is a detailed explanation of this hook's use case.

### High-Level Use Case

The primary use case of this hook is **to automatically make "Plan Mode" more powerful and efficient by default.**

It achieves this by ensuring that whenever a user is in the read-only "Plan Mode", their prompts are automatically handled by the specialized, fast, and efficient `Plan` subagent without the user needing to remember to invoke it manually.

---

### How It Works: Step-by-Step

1.  **Trigger Event**: The hook is configured in `settings.json` to run on the `UserPromptSubmit` event. This means the script executes *after* you type a prompt and press Enter, but *before* Claude starts processing it.

2.  **Mode Check**: The Python script (`prepend_plan_agent.py`) first checks if the current `permission_mode` is `"plan"`. If you are in any other mode (like `default` or `acceptEdits`), the script does nothing.

3.  **Prompt Modification**: If you are in "Plan Mode", the script takes your prompt (e.g., `"show me all API endpoints"`) and automatically prepends it with `@agent-Plan`.

4.  **Returning the New Prompt**: The script then returns a JSON object to Claude Code, instructing it to replace your original prompt with the new, modified one (e.g., `"@agent-Plan show me all API endpoints"`).

5.  **Subagent Invocation**: Claude Code receives this modified prompt and, seeing the `@agent-Plan` trigger, delegates the task to the built-in `Plan` subagent.

### The "Why": Solving a User Experience Problem

From the changelog you provided (version 2.0.28), we know that Claude Code introduced a new, specialized `Plan` subagent.

> **Plan**: Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns..., search code for keywords..., or answer questions about the codebase...

This subagent is optimized for the exact kind of read-only exploration that "Plan Mode" is designed for.

*   **The Problem:** Without this hook, a user in Plan Mode would have to remember to manually type `@agent-Plan` before every single query to get the best performance. Forgetting to do so would mean the general-purpose agent handles the request, which might be slower or less efficient for exploration tasks.

*   **The Solution (This Hook):** This hook automates that best practice. It creates a seamless experience where **Plan Mode is automatically powered by the Plan subagent**. The user can just focus on their questions, and the system ensures the best tool is used for the job behind the scenes.

### Practical Example

**Without the Hook:**

1.  You enable Plan Mode (`Shift+Tab`).
2.  You type: `find all files that import the 'requests' library`.
3.  The main Claude agent processes this, searching the codebase.
4.  To get better performance, you have to remember to type: `@agent-Plan find all files that import the 'requests' library`.

**With the Hook:**

1.  You enable Plan Mode (`Shift+Tab`).
2.  You type: `find all files that import the 'requests' library`.
3.  The hook intercepts this, automatically changes it to `"@agent-Plan find all files that import the 'requests' library"`.
4.  The specialized, faster `Plan` subagent immediately takes over, giving you a more efficient result.

In short, this hook is a quality-of-life improvement that links the **"Plan Mode" feature** directly to the **`Plan` subagent**, making the experience smarter and more intuitive for the user.