feat: add Plan mode for read-only code analysis and planning

[atsushi-ishibashi]

Summary

This PR introduces a new Plan mode - a read-only mode specifically designed for code analysis and implementation planning without making any code modifications.

Background

Currently, Claude Code operates in modes that can modify code directly. However, there are scenarios where users want Claude to:

• Analyze and understand a codebase without making changes
• Create detailed implementation plans before actual coding
• Investigate bugs and provide analysis without immediate fixes
• Review architecture and suggest improvements

Having a dedicated read-only mode ensures safer interactions when modification is not desired and provides focused analysis capabilities.

What's Changed

Core Features

• New Plan Mode (src/modes/plan/): Read-only mode with restricted tool access
  • Only allows: Read, Grep, LS, Glob
  • Blocks all modification tools: Edit, Write, MultiEdit, etc.
  • Specialized prompt for analysis-focused tasks

Use Cases

1. Implementation Planning: Create detailed plans before coding
2. Bug Investigation: Analyze root causes without modifying code
3. Code Reviews: Provide feedback and improvement suggestions, not for pull requests, but for the existing codebase.
4. Architecture Analysis: Understand and document existing structures

[ashwin-ant]

@atsushi-ishibashi please check out our announcement about breaking changes in 1.0: https://github.com/anthropics/claude-code-action/discussions. User-facing modes like this will not be part of the design anymore.

[atsushi-ishibashi]

@ashwin-ant thanks! It seems that what this PR was trying to do can be achieved using prompt input.

[atsushi-ishibashi]

@ashwin-ant @km-anthropic
Congrats on the v1 release! 🎉
I wanted to get your thoughts because I’m wondering if what I was trying to do in that PR might not be achievable with v1.

Here’s what I’d like to do:
•Use GitHub Context to construct the prompt (similar to Tag Mode), and also perform tasks like downloading files.
•Insert a custom, investigation-oriented prompt instead of the implementation-oriented prompt used in Tag Mode. Using CLAUDE.md doesn’t work here, and I don’t want the Tag Mode prompt included in the context.

From my understanding, Agent Mode does allow customizing the prompt, but it doesn’t bring in the GitHub Context.

Thanks.

[ashwin-ant]

@atsushi-ishibashi we'll be looking into ways to expose the file download stuff outside of tag mode. In the meantime, you can include general github context in a workflow by doing something like:

prompt: "Prompt text ... ${{ github.repository }}/pulls/${{ github.event.pull_request.number }}" # or similar

You can also use slash commands to avoid having a large prompt in a yml file:

prompt: "/some-custom-command ${{ github.repository }}/pulls/${{ github.event.pull_request.number }}"

[atsushi-ishibashi]

@ashwin-ant
I had understood from reading docs/custom-automation that it’s possible to construct GitHub Context like this: Prompt text ... ${{ github.repository }}/pulls/${{ github.event.pull_request.number }}
But the file download part seems tricky 🤔

we’ll be looking into ways to expose the file download stuff outside of tag mode

That sounds great! If we had that, I think I could do what I want. I can take a first pass at implementing this if that helps👍

[ashwin-ant]

The way we're likely to expose it is via environment variables that we provide to Claude, so that they can be referenced in slash commands via Bash command execution: https://docs.anthropic.com/en/docs/claude-code/slash-commands#bash-command-execution. If you're open to taking that on, go for it. cc @km-anthropic for thoughts