cc-viewer 1.6.182 → 1.6.183

package/concepts/en/Tool-Bash.md

@@ -1,167 +1,39 @@
 # Bash
 
-## Definition
+Runs a shell command inside a persistent working directory and returns its stdout/stderr. Best reserved for operations that no dedicated Claude Code tool can express, such as running git, npm, docker, or build scripts.
 
-Executes shell commands with optional timeout settings. The working directory persists between commands, but shell state (environment variables, etc.) does not persist.
+## When to Use
 
-## Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `command` | string | Yes | The bash command to execute |
-| `description` | string | No | A short description of the command |
-| `timeout` | number | No | Timeout in milliseconds, max 600000, default 120000 |
-| `run_in_background` | boolean | No | Whether to run in the background |
-
-## Use Cases
-
-**Good for:**
-- git operations (commit, push, branch, etc.)
-- npm/yarn and other package management commands
-- docker operations
-- Compilation and build commands
-- Listing directory contents (`ls`)
-- Other system commands that require shell execution
-
-**Not good for:**
-- Reading files — use Read instead
-- Searching for filenames — use Glob instead
-- Searching file contents — use Grep instead
-- Editing files — use Edit instead
-- Writing files — use Write instead
-- Outputting information to the user — output directly in the response text
-- Long-running processes (dev server, watch mode) — recommend the user run them manually
-
-## Notes
-
-- Paths containing spaces must be wrapped in double quotes
-- Output exceeding 30000 characters will be truncated
-- Background commands retrieve results via TaskOutput
-- Use absolute paths whenever possible, avoid `cd`
-- Independent commands can invoke multiple Bash calls in parallel
-- Dependent commands should be chained with `&&`
-- The shell environment is initialized from the user's profile (bash or zsh)
-
-## Original Text
-
-<textarea readonly>Executes a given bash command and returns its output.
-
-The working directory persists between commands, but shell state does not. The shell environment is initialized from the user's profile (bash or zsh).
+- Executing git operations (`git status`, `git diff`, `git commit`, `gh pr create`)
+- Running package managers and build tools (`npm install`, `npm run build`, `pytest`, `cargo build`)
+- Launching long-running processes (dev servers, watchers) in the background with `run_in_background`
+- Invoking domain-specific CLIs (`docker`, `terraform`, `kubectl`, `gh`) that have no built-in equivalent
+- Chaining dependent steps together with `&&` when ordering matters
 
-IMPORTANT: Avoid using this tool to run `find`, `grep`, `cat`, `head`, `tail`, `sed`, `awk`, or `echo` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
-
- - File search: Use Glob (NOT find or ls)
- - Content search: Use Grep (NOT grep or rg)
- - Read files: Use Read (NOT cat/head/tail)
- - Edit files: Use Edit (NOT sed/awk)
- - Write files: Use Write (NOT echo >/cat <<EOF)
- - Communication: Output text directly (NOT echo/printf)
-While the Bash tool can do similar things, it’s better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
-
-# Instructions
- - If your command will create new directories or files, first use this tool to run `ls` to verify the parent directory exists and is the correct location.
- - Always quote file paths that contain spaces with double quotes in your command (e.g., cd "path with spaces/file.txt")
- - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of `cd`. You may use `cd` if the User explicitly requests it.
- - You may specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). By default, your command will timeout after 120000ms (2 minutes).
- - You can use the `run_in_background` parameter to run the command in the background. Only use this if you don't need the result immediately and are OK being notified when the command completes later. You do not need to check the output right away - you'll be notified when it finishes. You do not need to use '&' at the end of the command when using this parameter.
- - Write a clear, concise description of what your command does. For simple commands, keep it brief (5-10 words). For complex commands (piped commands, obscure flags, or anything hard to understand at a glance), include enough context so that the user can understand what your command will do.
- - When issuing multiple commands:
-  - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message. Example: if you need to run "git status" and "git diff", send a single message with two Bash tool calls in parallel.
-  - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them together.
-  - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail.
-  - DO NOT use newlines to separate commands (newlines are ok in quoted strings).
- - For git commands:
-  - Prefer to create a new commit rather than amending an existing commit.
-  - Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
-  - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
- - Avoid unnecessary `sleep` commands:
-  - Do not sleep between commands that can run immediately — just run them.
-  - If your command is long running and you would like to be notified when it finishes – simply run your command using `run_in_background`. There is no need to sleep in this case.
-  - Do not retry failing commands in a sleep loop — diagnose the root cause or consider an alternative approach.
-  - If waiting for a background task you started with `run_in_background`, you will be notified when it completes — do not poll.
-  - If you must poll an external process, use a check command (e.g. `gh run view`) rather than sleeping first.
-  - If you must sleep, keep the duration short (1-5 seconds) to avoid blocking the user.
-
-# Committing changes with git
-
-Only create commits when requested by the user. If unclear, ask first. When the user asks you to create a new git commit, follow these steps carefully:
-
-Git Safety Protocol:
-- NEVER update the git config
-- NEVER run destructive git commands (push --force, reset --hard, checkout ., restore ., clean -f, branch -D) unless the user explicitly requests these actions. Taking unauthorized destructive actions is unhelpful and can result in lost work, so it's best to ONLY run these commands when given direct instructions 
-- NEVER skip hooks (--no-verify, --no-gpg-sign, etc) unless the user explicitly requests it
-- NEVER run force push to main/master, warn the user if they request it
-- CRITICAL: Always create NEW commits rather than amending, unless the user explicitly requests a git amend. When a pre-commit hook fails, the commit did NOT happen — so --amend would modify the PREVIOUS commit, which may result in destroying work or losing previous changes. Instead, after hook failure, fix the issue, re-stage, and create a NEW commit
-- When staging files, prefer adding specific files by name rather than using "git add -A" or "git add .", which can accidentally include sensitive files (.env, credentials) or large binaries
-- NEVER commit changes unless the user explicitly asks you to. It is VERY IMPORTANT to only commit when explicitly asked, otherwise the user will feel that you are being too proactive
-
-1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel, each using the Bash tool:
-  - Run a git status command to see all untracked files. IMPORTANT: Never use the -uall flag as it can cause memory issues on large repos.
-  - Run a git diff command to see both staged and unstaged changes that will be committed.
-  - Run a git log command to see recent commit messages, so that you can follow this repository's commit message style.
-2. Analyze all staged changes (both previously staged and newly added) and draft a commit message:
-  - Summarize the nature of the changes (eg. new feature, enhancement to an existing feature, bug fix, refactoring, test, docs, etc.). Ensure the message accurately reflects the changes and their purpose (i.e. "add" means a wholly new feature, "update" means an enhancement to an existing feature, "fix" means a bug fix, etc.).
-  - Do not commit files that likely contain secrets (.env, credentials.json, etc). Warn the user if they specifically request to commit those files
-  - Draft a concise (1-2 sentences) commit message that focuses on the "why" rather than the "what"
-  - Ensure it accurately reflects the changes and their purpose
-3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands:
-   - Add relevant untracked files to the staging area.
-   - Create the commit with a message ending with:
-   Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
-   - Run git status after the commit completes to verify success.
-   Note: git status depends on the commit completing, so run it sequentially after the commit.
-4. If the commit fails due to pre-commit hook: fix the issue and create a NEW commit
-
-Important notes:
-- NEVER run additional commands to read or explore code, besides git bash commands
-- NEVER use the TodoWrite or Agent tools
-- DO NOT push to the remote repository unless the user explicitly asks you to do so
-- IMPORTANT: Never use git commands with the -i flag (like git rebase -i or git add -i) since they require interactive input which is not supported.
-- IMPORTANT: Do not use --no-edit with git rebase commands, as the --no-edit flag is not a valid option for git rebase.
-- If there are no changes to commit (i.e., no untracked files and no modifications), do not create an empty commit
-- In order to ensure good formatting, ALWAYS pass the commit message via a HEREDOC, a la this example:
-<example>
-git commit -m "$(cat <<'EOF'
-   Commit message here.
-
-   Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
-   EOF
-   )"
-</example>
+## Parameters
 
-# Creating pull requests
-Use the gh command via the Bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases. If given a Github URL use the gh command to get the information needed.
+- `command` (string, required): The exact shell command to execute.
+- `description` (string, required): A short, active-voice summary (5-10 words for simple commands; more context for piped or obscure ones).
+- `timeout` (number, optional): Timeout in milliseconds, up to `600000` (10 minutes). Defaults to `120000` (2 minutes).
+- `run_in_background` (boolean, optional): When `true`, the command runs detached and you receive a notification on completion. Do not append `&` yourself.
 
-IMPORTANT: When the user asks you to create a pull request, follow these steps carefully:
+## Examples
 
-1. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following bash commands in parallel using the Bash tool, in order to understand the current state of the branch since it diverged from the main branch:
-   - Run a git status command to see all untracked files (never use -uall flag)
-   - Run a git diff command to see both staged and unstaged changes that will be committed
-   - Check if the current branch tracks a remote branch and is up to date with the remote, so you know if you need to push to the remote
-   - Run a git log command and `git diff [base-branch]...HEAD` to understand the full commit history for the current branch (from the time it diverged from the base branch)
-2. Analyze all changes that will be included in the pull request, making sure to look at all relevant commits (NOT just the latest commit, but ALL commits that will be included in the pull request!!!), and draft a pull request title and summary:
-   - Keep the PR title short (under 70 characters)
-   - Use the description/body for details, not the title
-3. You can call multiple tools in a single response. When multiple independent pieces of information are requested and all commands are likely to succeed, run multiple tool calls in parallel for optimal performance. run the following commands in parallel:
-   - Create new branch if needed
-   - Push to remote with -u flag if needed
-   - Create PR using gh pr create with the format below. Use a HEREDOC to pass the body to ensure correct formatting.
-<example>
-gh pr create --title "the pr title" --body "$(cat <<'EOF'
-## Summary
-<1-3 bullet points>
+### Example 1: Inspect repo state before committing
+Issue `git status` and `git diff --stat` as two parallel `Bash` calls in the same message to gather context quickly, then assemble the commit in a follow-up call.
 
-## Test plan
-[Bulleted markdown checklist of TODOs for testing the pull request...]
+### Example 2: Chain dependent build steps
+Use a single call such as `npm ci && npm run build && npm test` so each step only runs after the previous one succeeds. Use `;` only if you intentionally want later steps to run even after failures.
 
-🤖 Generated with [Claude Code](https://claude.com/claude-code)
-EOF
-)"
-</example>
+### Example 3: Long-running dev server
+Invoke `npm run dev` with `run_in_background: true`. You will be notified when it exits. Do not poll with `sleep` loops; diagnose failures instead of retrying blindly.
 
-Important:
-- DO NOT use the TodoWrite or Agent tools
-- Return the PR URL when you're done, so the user can see it
+## Notes
 
-# Other common operations
-- View comments on a Github PR: gh api repos/foo/bar/pulls/123/comments</textarea>
+- The working directory persists between calls, but shell state (exported variables, shell functions, aliases) does not. Prefer absolute paths and avoid `cd` unless the user asks for it.
+- Prefer dedicated tools over piped shell equivalents: `Glob` instead of `find`/`ls`, `Grep` instead of `grep`/`rg`, `Read` instead of `cat`/`head`/`tail`, `Edit` instead of `sed`/`awk`, `Write` instead of `echo >` or heredocs, and plain assistant text instead of `echo`/`printf` for user-facing output.
+- Quote any path that contains spaces with double quotes (for example `"/Users/me/My Project/file.txt"`).
+- For independent commands, make multiple `Bash` tool calls in parallel within a single message. Only chain with `&&` when one command depends on another.
+- Output over 30000 characters is truncated. When capturing large logs, redirect to a file and then read it with the `Read` tool.
+- Never use interactive flags such as `git rebase -i` or `git add -i`; they cannot receive input through this tool.
+- Do not skip git hooks (`--no-verify`, `--no-gpg-sign`) or perform destructive operations (`reset --hard`, `push --force`, `clean -f`) unless the user explicitly requests them.

package/concepts/en/Tool-CronCreate.md

@@ -0,0 +1,57 @@
+# CronCreate
+
+Schedule a prompt to be enqueued at a future time, either once or on a recurring basis. Uses standard 5-field cron syntax in the user's local timezone — no timezone conversion required.
+
+## When to Use
+
+- **One-shot reminders**: When a user asks to be reminded at a specific future time ("remind me at 3pm tomorrow"). Set `recurring: false` so the task fires once then is automatically deleted.
+- **Recurring schedules**: When a user wants something to happen repeatedly ("every weekday at 9am", "every 30 minutes"). The default `recurring: true` covers this case.
+- **Autonomous agent loops**: When building a workflow that needs to re-prompt itself on a schedule — for example, a daily digest or a periodic status check.
+- **Durable tasks**: When the schedule must survive a session restart. Pass `durable: true` to write the task to `.claude/scheduled_tasks.json`.
+- **Approximate-time requests**: When the user says "around 9am" or "hourly", choose an off-minute value (e.g. `57 8 * * *` or `7 * * * *`) to avoid clustering with other users at :00 or :30.
+
+## Parameters
+
+- `cron` (string, required): A 5-field cron expression in the user's local timezone. Fields are `minute hour day-of-month month day-of-week`. Example: `"0 9 * * 1-5"` means 9:00am Monday–Friday.
+- `prompt` (string, required): The prompt text to enqueue when the cron fires. This is the exact message that will be submitted to the REPL at the scheduled time.
+- `recurring` (boolean, optional, default `true`): When `true`, the job runs on every matching cron interval and auto-expires after 7 days. When `false`, the job fires exactly once then is automatically deleted — use this for one-shot reminders.
+- `durable` (boolean, optional, default `false`): When `false`, the schedule lives only in memory and is lost when the session ends. When `true`, the task is persisted to `.claude/scheduled_tasks.json` and survives restarts.
+
+## Examples
+
+### Example 1: one-shot reminder
+
+User says: "Remind me to send the weekly report tomorrow at 2:30pm." Assuming tomorrow is the 21st of April:
+
+```json
+{
+  "cron": "30 14 21 4 *",
+  "prompt": "Reminder: send the weekly report now.",
+  "recurring": false,
+  "durable": true
+}
+```
+
+`recurring: false` ensures the task deletes itself after firing. `durable: true` keeps it alive across any restarts before then.
+
+### Example 2: recurring weekday morning task
+
+User says: "Every weekday morning, summarize my open GitHub issues."
+
+```json
+{
+  "cron": "3 9 * * 1-5",
+  "prompt": "Summarize all open GitHub issues assigned to me.",
+  "recurring": true,
+  "durable": true
+}
+```
+
+Minute `3` instead of `0` avoids the :00 fleet-load spike. The job auto-expires after 7 days.
+
+## Notes
+
+- **7-day auto-expiry**: Recurring jobs fire for at most 7 days, then are deleted automatically. If you need a longer-running schedule, recreate it before it expires.
+- **Fires only when idle**: `CronCreate` enqueues the prompt only when the REPL is not processing another query. If the REPL is busy at fire time, the prompt waits until the current query finishes.
+- **Avoid :00 and :30 marks**: For approximate-time requests, deliberately choose off-minute values to spread system load. Reserve exact :00/:30 only for when the user specifies that precise minute.
+- **No timezone conversion**: The cron expression is interpreted directly in the user's local timezone. There is no need to convert to UTC or any other zone.

package/concepts/en/Tool-CronDelete.md

@@ -0,0 +1,43 @@
+# CronDelete
+
+Cancel a cron job previously scheduled with `CronCreate`. Removes it from the in-memory session store immediately; has no effect if the job was already auto-deleted (one-shot jobs are removed after firing, recurring jobs expire after 7 days).
+
+## When to Use
+
+- A user asks to stop a recurring scheduled task before its 7-day auto-expiry.
+- A one-shot job is no longer needed and should be cancelled before it fires.
+- You need to change the schedule for an existing job — delete it with `CronDelete`, then recreate it with `CronCreate` using the new expression.
+- Cleaning up multiple stale jobs to keep the session store tidy.
+
+## Parameters
+
+- `id` (string, required): The job ID returned by `CronCreate` when the job was first created. This value must match exactly; there is no fuzzy or name-based lookup.
+
+## Examples
+
+### Example 1: cancel a running recurring job
+
+A recurring job was created earlier with ID `"cron_abc123"`. The user asks to stop it.
+
+```
+CronDelete({ id: "cron_abc123" })
+```
+
+The job is removed from the session store and will not fire again.
+
+### Example 2: remove a stale one-shot before it fires
+
+A one-shot job with ID `"cron_xyz789"` was scheduled to run in 30 minutes, but the user has decided it is no longer needed.
+
+```
+CronDelete({ id: "cron_xyz789" })
+```
+
+The job is cancelled. No action will be taken when the original trigger time arrives.
+
+## Notes
+
+- The `id` must be obtained from the return value of `CronCreate`. There is no way to look up a job by description or callback — store the ID if you may need to cancel later.
+- If the job has already been auto-deleted (fired as a one-shot, or reached the 7-day recurring expiry), calling `CronDelete` with that ID is a no-op and will not produce an error.
+- `CronDelete` only affects the current in-memory session. If the runtime does not persist cron state across restarts, scheduled jobs are lost on restart regardless of whether `CronDelete` was called.
+- There is no bulk-delete operation; cancel each job individually using its own `id`.

package/concepts/en/Tool-CronList.md

@@ -0,0 +1,30 @@
+# CronList
+
+List all cron jobs scheduled via `CronCreate` in the current session. Returns a summary of each active cron including its `id`, cron expression, abbreviated `prompt`, `recurring` flag, `durable` flag, and next scheduled fire time.
+
+## When to Use
+
+- Audit what jobs are currently scheduled before making changes or ending a session.
+- Find the correct `id` of a job before calling `CronDelete` to remove it.
+- Debug why an expected job never fired by confirming it exists and checking its next fire time.
+- Confirm that a one-shot (non-recurring) job has not yet fired and is still pending.
+
+## Parameters
+
+None.
+
+## Examples
+
+### Example 1: audit all scheduled jobs
+
+Call `CronList` with no arguments to retrieve the full list of active cron jobs. The response includes each job's `id`, the cron expression defining its schedule, a truncated version of the `prompt` it will execute, whether it is `recurring`, whether it is `durable` across restarts, and the next time it is scheduled to fire.
+
+### Example 2: locate the id of a specific recurring task
+
+If you created multiple cron jobs and need to delete one specific recurring task, call `CronList` first. Scan the returned list for the job whose `prompt` summary and cron expression match the task you want to remove. Copy its `id` and pass it to `CronDelete`.
+
+## Notes
+
+- Only jobs created in the current session are listed unless they were created with `durable: true`, which allows them to persist across session restarts.
+- The `prompt` field in the summary is truncated; it shows only the beginning of the full prompt text, not the complete instruction.
+- One-shot jobs (where `recurring` is `false`) that have already fired are automatically deleted and will no longer appear in the list.

package/concepts/en/Tool-Edit.md

@@ -1,46 +1,38 @@
 # Edit
 
-## Definition
+Performs an exact string replacement inside an existing file. It is the preferred way to modify files because only the diff is transmitted, keeping edits precise and auditable.
 
-Edits files via exact string replacement. Replaces `old_string` with `new_string` in the file.
+## When to Use
 
-## Parameters
+- Fixing a bug in a single function without rewriting the surrounding file
+- Updating a configuration value, version string, or import path
+- Renaming a symbol across a file with `replace_all`
+- Inserting a block near an anchor (expand `old_string` to include nearby context, then provide the replacement)
+- Applying small, well-scoped edits as part of a multi-step refactor
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `file_path` | string | Yes | Absolute path of the file to modify |
-| `old_string` | string | Yes | The original text to replace |
-| `new_string` | string | Yes | The new replacement text (must differ from old_string) |
-| `replace_all` | boolean | No | Whether to replace all matches, default `false` |
+## Parameters
 
-## Use Cases
+- `file_path` (string, required): Absolute path of the file to modify.
+- `old_string` (string, required): The exact text to search for. Must match character-for-character, including whitespace and indentation.
+- `new_string` (string, required): The replacement text. Must differ from `old_string`.
+- `replace_all` (boolean, optional): When `true`, replaces every occurrence of `old_string`. Defaults to `false`, which requires the match to be unique.
 
-**Good for:**
-- Modifying specific code sections in existing files
-- Fixing bugs, updating logic
-- Renaming variables (with `replace_all: true`)
-- Any scenario requiring precise file content modification
+## Examples
 
-**Not good for:**
-- Creating new files — use Write instead
-- Large-scale rewrites — may need Write to overwrite the entire file
+### Example 1: Fix a single call site
+Set `old_string` to the exact line `const port = 3000;` and `new_string` to `const port = process.env.PORT ?? 3000;`. The match is unique so `replace_all` can stay at its default.
 
-## Notes
+### Example 2: Rename a symbol across a file
+To rename `getUser` to `fetchUser` everywhere in `api.ts`, set `old_string: "getUser"`, `new_string: "fetchUser"`, and `replace_all: true`.
 
-- You must first read the file via Read before using this tool, otherwise it will error
-- `old_string` must be unique in the file, otherwise the edit fails. If not unique, provide more context to make it unique, or use `replace_all`
-- When editing text, preserve the original indentation (tabs/spaces); do not include the line number prefix from Read output
-- Prefer editing existing files over creating new ones
-- `new_string` must differ from `old_string`
+### Example 3: Disambiguate a repeated snippet
+If `return null;` appears in several branches, widen `old_string` to include surrounding context (for example the preceding `if` line) so the match is unique. Otherwise the tool errors out rather than guess.
 
-## Original Text
-
-<textarea readonly>Performs exact string replacements in files.
+## Notes
 
-Usage:
-- You must use your `Read` tool at least once in the conversation before editing. This tool will error if you attempt an edit without reading the file. 
-- When editing text from Read tool output, ensure you preserve the exact indentation (tabs/spaces) as it appears AFTER the line number prefix. The line number prefix format is: spaces + line number + tab. Everything after that tab is the actual file content to match. Never include any part of the line number prefix in the old_string or new_string.
-- ALWAYS prefer editing existing files in the codebase. NEVER write new files unless explicitly required.
-- Only use emojis if the user explicitly requests it. Avoid adding emojis to files unless asked.
-- The edit will FAIL if `old_string` is not unique in the file. Either provide a larger string with more surrounding context to make it unique or use `replace_all` to change every instance of `old_string`.
-- Use `replace_all` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.</textarea>
+- You must call `Read` on the file at least once in the current session before `Edit` will accept changes. Line-number prefixes from `Read` output are not part of the file content; do not include them in `old_string` or `new_string`.
+- Whitespace must match exactly. Pay attention to tabs versus spaces and trailing spaces, especially in YAML, Makefiles, and Python.
+- If `old_string` is not unique and `replace_all` is `false`, the edit fails. Either expand the context or enable `replace_all`.
+- Prefer `Edit` over `Write` whenever the file already exists; `Write` overwrites the entire file and loses unrelated content if you are not careful.
+- For multiple unrelated edits in the same file, issue several `Edit` calls in sequence rather than one large, fragile replacement.
+- Avoid introducing emoji, marketing copy, or unrequested documentation blocks when editing source files.

package/concepts/en/Tool-EnterPlanMode.md

@@ -1,128 +1,35 @@
 # EnterPlanMode
 
-## Definition
+Switches the session into plan mode, a read-only exploration phase in which the assistant investigates the codebase and drafts a concrete implementation plan for the user to approve before any files are modified.
 
-Switches Claude Code into plan mode for exploring the codebase and designing an implementation plan before execution.
+## When to Use
 
-## Parameters
-
-No parameters.
-
-## Use Cases
-
-**Good for:**
-- New feature implementation — requires architectural decisions
-- Multiple viable approaches exist — requires user selection
-- Code changes affect existing behavior or structure
-- Multi-file changes — potentially involving 2-3 or more files
-- Requirements are unclear — need to explore first to understand scope
-- User preferences matter — implementation can go in multiple reasonable directions
-
-**Not good for:**
-- Single-line or few-line fixes (typos, obvious bugs)
-- The user has given very specific instructions
-- Pure research/exploration tasks — use Task (Explore type) instead
-
-## Behavior in Plan Mode
-
-After entering plan mode, Claude Code will:
-1. Use Glob, Grep, and Read tools to deeply explore the codebase
-2. Understand existing patterns and architecture
-3. Design an implementation plan
-4. Submit the plan for user approval
-5. Use AskUserQuestion if clarification is needed
-6. Exit via ExitPlanMode when the plan is ready
-
-## Notes
-
-- This tool requires user consent to enter plan mode
-- When unsure whether planning is needed, lean toward planning — aligning upfront is better than rework
-
-## Original Text
-
-<textarea readonly>Use this tool proactively when you're about to start a non-trivial implementation task. Getting user sign-off on your approach before writing code prevents wasted effort and ensures alignment. This tool transitions you into plan mode where you can explore the codebase and design an implementation approach for user approval.
-
-## When to Use This Tool
-
-**Prefer using EnterPlanMode** for implementation tasks unless they're simple. Use it when ANY of these conditions apply:
-
-1. **New Feature Implementation**: Adding meaningful new functionality
-   - Example: "Add a logout button" - where should it go? What should happen on click?
-   - Example: "Add form validation" - what rules? What error messages?
+- The user asks for a non-trivial change that spans multiple files or subsystems.
+- Requirements are ambiguous and the assistant needs to read code before committing to an approach.
+- A refactor, migration, or dependency upgrade is proposed and the blast radius is unclear.
+- The user explicitly says "plan this", "let's plan first", or requests a design review.
+- Risk is high enough that moving straight to edits could waste work or damage state.
 
-2. **Multiple Valid Approaches**: The task can be solved in several different ways
-   - Example: "Add caching to the API" - could use Redis, in-memory, file-based, etc.
-   - Example: "Improve performance" - many optimization strategies possible
-
-3. **Code Modifications**: Changes that affect existing behavior or structure
-   - Example: "Update the login flow" - what exactly should change?
-   - Example: "Refactor this component" - what's the target architecture?
-
-4. **Architectural Decisions**: The task requires choosing between patterns or technologies
-   - Example: "Add real-time updates" - WebSockets vs SSE vs polling
-   - Example: "Implement state management" - Redux vs Context vs custom solution
-
-5. **Multi-File Changes**: The task will likely touch more than 2-3 files
-   - Example: "Refactor the authentication system"
-   - Example: "Add a new API endpoint with tests"
-
-6. **Unclear Requirements**: You need to explore before understanding the full scope
-   - Example: "Make the app faster" - need to profile and identify bottlenecks
-   - Example: "Fix the bug in checkout" - need to investigate root cause
-
-7. **User Preferences Matter**: The implementation could reasonably go multiple ways
-   - If you would use AskUserQuestion to clarify the approach, use EnterPlanMode instead
-   - Plan mode lets you explore first, then present options with context
-
-## When NOT to Use This Tool
-
-Only skip EnterPlanMode for simple tasks:
-- Single-line or few-line fixes (typos, obvious bugs, small tweaks)
-- Adding a single function with clear requirements
-- Tasks where the user has given very specific, detailed instructions
-- Pure research/exploration tasks (use the Agent tool with explore agent instead)
-
-## What Happens in Plan Mode
+## Parameters
 
-In plan mode, you'll:
-1. Thoroughly explore the codebase using Glob, Grep, and Read tools
-2. Understand existing patterns and architecture
-3. Design an implementation approach
-4. Present your plan to the user for approval
-5. Use AskUserQuestion if you need to clarify approaches
-6. Exit plan mode with ExitPlanMode when ready to implement
+None. `EnterPlanMode` takes no arguments — invoke it with an empty parameter object.
 
 ## Examples
 
-### GOOD - Use EnterPlanMode:
-User: "Add user authentication to the app"
-- Requires architectural decisions (session vs JWT, where to store tokens, middleware structure)
-
-User: "Optimize the database queries"
-- Multiple approaches possible, need to profile first, significant impact
-
-User: "Implement dark mode"
-- Architectural decision on theme system, affects many components
+### Example 1: Large feature request
 
-User: "Add a delete button to the user profile"
-- Seems simple but involves: where to place it, confirmation dialog, API call, error handling, state updates
+The user asks: "Add SSO via Okta to the admin panel." The assistant calls `EnterPlanMode`, then spends several turns reading auth middleware, session storage, route guards, and existing login UI. It writes a plan describing required changes, migration steps, and test coverage, then submits via `ExitPlanMode` for approval.
 
-User: "Update the error handling in the API"
-- Affects multiple files, user should approve the approach
+### Example 2: Risky refactor
 
-### BAD - Don't use EnterPlanMode:
-User: "Fix the typo in the README"
-- Straightforward, no planning needed
+The user says: "Convert the REST controllers to tRPC." The assistant enters plan mode, surveys each controller, catalogs the public contract, lists rollout phases (shim, dual-read, cutover), and proposes a sequencing plan before touching any file.
 
-User: "Add a console.log to debug this function"
-- Simple, obvious implementation
-
-User: "What files handle routing?"
-- Research task, not implementation planning
-
-## Important Notes
+## Notes
 
-- This tool REQUIRES user approval - they must consent to entering plan mode
-- If unsure whether to use it, err on the side of planning - it's better to get alignment upfront than to redo work
-- Users appreciate being consulted before significant changes are made to their codebase
-</textarea>
+- Plan mode is read-only by contract. While inside it, the assistant must not run `Edit`, `Write`, `NotebookEdit`, or any mutating shell command. Use `Read`, `Grep`, `Glob`, and non-destructive `Bash` commands only.
+- Do not enter plan mode for trivial one-liner edits, pure research questions, or tasks where the user has already specified the change in full detail. The overhead hurts more than it helps.
+- Under Auto mode, plan mode is discouraged unless the user explicitly requests it — Auto mode prefers action over up-front planning.
+- Use plan mode to reduce course-corrections on expensive work. A five-minute plan often saves an hour of misdirected edits.
+- Once in plan mode, focus investigation on the parts of the system that will actually change. Avoid exhaustive tours of the repository unrelated to the task at hand.
+- The plan itself should be written to disk at the path the harness expects so that `ExitPlanMode` can submit it. The plan should contain concrete file paths, function names, and verification steps, not vague intent.
+- The user may reject the plan and ask for revisions. Iterate inside plan mode until the plan is accepted; only then exit.