cc-viewer 1.6.182 → 1.6.183

package/concepts/en/Tool-EnterWorktree.md

@@ -1,56 +1,44 @@
 # EnterWorktree
 
-## Definition
+Creates an isolated Git worktree on a new branch, or switches the session into an existing worktree of the current repository, so that parallel or experimental work can proceed without touching the primary checkout.
 
-Creates an isolated git worktree and switches the current session into it. Only used when the user explicitly asks to work in a worktree.
-
-## Parameters
-
-| Name | Type | Required | Description |
-|---|---|---|---|
-| name | string | No | A name for the worktree. If not provided, a random name is generated. |
-
-## Use Cases
-
-**Good for:**
-- The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree")
-
-**Not good for:**
-- The user asks to create/switch branches — use git commands instead
-- The user asks to fix a bug or work on a feature — use normal git workflow unless they specifically mention worktrees
-
-## Notes
+## When to Use
 
-- Must be in a git repository, or have WorktreeCreate/WorktreeRemove hooks configured
-- Must not already be in a worktree
+- The user explicitly says "worktree" — for example "start a worktree", "create a worktree", or "work in a worktree".
+- Project instructions in `CLAUDE.md` or persistent memory direct you to use a worktree for the current task.
+- You want to continue a task that was previously set up as a worktree (pass `path` to re-enter it).
+- Multiple experimental branches need to coexist on disk without constant checkout churn.
+- A long-running task should be insulated from unrelated edits in the main working tree.
 
-## Original Text
+## Parameters
 
-<textarea readonly>Use this tool ONLY when the user explicitly asks to work in a worktree. This tool creates an isolated git worktree and switches the current session into it.
+- `name` (string, optional): A name for a new worktree directory. Each `/`-separated segment may contain only letters, digits, dots, underscores, and dashes; the full string is capped at 64 characters. If omitted and `path` is also omitted, a random name is generated. Mutually exclusive with `path`.
+- `path` (string, optional): The filesystem path of an existing worktree of the current repository to switch into. Must appear in `git worktree list` for this repo; paths that are not registered worktrees of the current repo are rejected. Mutually exclusive with `name`.
 
-## When to Use
+## Examples
 
-- The user explicitly says "worktree" (e.g., "start a worktree", "work in a worktree", "create a worktree", "use a worktree")
+### Example 1: Create a new worktree with a descriptive name
 
-## When NOT to Use
+```
+EnterWorktree(name="feat/okta-sso")
+```
 
-- The user asks to create a branch, switch branches, or work on a different branch — use git commands instead
-- The user asks to fix a bug or work on a feature — use normal git workflow unless they specifically mention worktrees
-- Never use this tool unless the user explicitly mentions "worktree"
+Creates `.claude/worktrees/feat/okta-sso` on a new branch based on `HEAD`, then switches the session's working directory into it. All subsequent file edits and shell commands operate inside that worktree until you exit.
 
-## Requirements
+### Example 2: Re-enter an existing worktree
 
-- Must be in a git repository, OR have WorktreeCreate/WorktreeRemove hooks configured in settings.json
-- Must not already be in a worktree
+```
+EnterWorktree(path="/Users/me/repo/.claude/worktrees/feat/okta-sso")
+```
 
-## Behavior
+Resumes work in a previously created worktree. Because you entered it via `path`, `ExitWorktree` will not delete it automatically — leaving with `action: "keep"` simply returns to the original directory.
 
-- In a git repository: creates a new git worktree inside `.claude/worktrees/` with a new branch based on HEAD
-- Outside a git repository: delegates to WorktreeCreate/WorktreeRemove hooks for VCS-agnostic isolation
-- Switches the session's working directory to the new worktree
-- On session exit, the user will be prompted to keep or remove the worktree
-
-## Parameters
+## Notes
 
-- `name` (optional): A name for the worktree. If not provided, a random name is generated.
-</textarea>
+- Do not call `EnterWorktree` unless the user has explicitly asked or project instructions require it. Ordinary branch-switching or bug-fix requests should use normal Git commands, not worktrees.
+- When invoked inside a Git repository, the tool creates a worktree under `.claude/worktrees/` and registers a new branch based on `HEAD`. Outside a Git repository, it delegates to configured `WorktreeCreate` / `WorktreeRemove` hooks in `settings.json` for VCS-agnostic isolation.
+- Only one worktree session is active at a time. The tool refuses to run if you are already inside a worktree session; exit first with `ExitWorktree`.
+- Use `ExitWorktree` to leave mid-session. If the session ends while still inside a newly created worktree, the user is prompted to keep or remove it.
+- Worktrees entered by `path` are considered external — `ExitWorktree` with `action: "remove"` will not delete them. This is a safety rail to protect worktrees the user manages manually.
+- A new worktree inherits the current branch's contents but has an independent working directory and index. Staged and unstaged changes in the main checkout are not visible inside the worktree.
+- Naming tip: prefix with the kind of work (`feat/`, `fix/`, `spike/`) so multiple concurrent worktrees are easy to distinguish in `git worktree list`.

package/concepts/en/Tool-ExitPlanMode.md

@@ -1,62 +1,42 @@
 # ExitPlanMode
 
-## Definition
+Submits the implementation plan that was drafted during plan mode for user approval, and — if approved — transitions the session out of plan mode so that edits can begin.
 
-Exits plan mode and submits the plan for user approval. The plan content is read from a previously written plan file.
+## When to Use
 
-## Parameters
-
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `allowedPrompts` | array | No | List of permission descriptions required for the implementation plan |
-
-Each element in the `allowedPrompts` array:
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `tool` | enum | Yes | The applicable tool, currently only supports `Bash` |
-| `prompt` | string | Yes | Semantic description of the operation (e.g., "run tests", "install dependencies") |
-
-## Use Cases
-
-**Good for:**
-- The plan is complete in plan mode and ready for user approval
-- Only for implementation tasks that require writing code
+- A plan written during `EnterPlanMode` is complete and ready for review.
+- The task is implementation-focused (code or config changes), not pure research, so an explicit plan is appropriate.
+- All prerequisite reading and analysis has been done; no further investigation is needed before the user decides.
+- The assistant has enumerated concrete file paths, functions, and steps — not just goals.
+- The user has asked to see the plan, or the plan-mode workflow is about to hand off to edit tools.
 
-**Not good for:**
-- Pure research/exploration tasks — no need to exit plan mode
-- Asking the user "Is the plan okay?" — that is exactly what this tool does, do not use AskUserQuestion for that
-
-## Notes
+## Parameters
 
-- This tool does not accept plan content as a parameter — it reads from a previously written plan file
-- The user will see the plan file content for approval
-- Do not use AskUserQuestion to ask "Is the plan okay?" before calling this tool, as that would be redundant
-- Do not mention "the plan" in questions, since the user cannot see the plan content before ExitPlanMode
+- `allowedPrompts` (array, optional): Prompts that the user may type on the approval screen to auto-approve or alter the plan. Each element specifies a scoped permission (for example, an operation name and the tool it applies to). Leave unset to use the default approval flow.
 
-## Original Text
+## Examples
 
-<textarea readonly>Use this tool when you are in plan mode and have finished writing your plan to the plan file and are ready for user approval.
+### Example 1: Standard submission
 
-## How This Tool Works
-- You should have already written your plan to the plan file specified in the plan mode system message
-- This tool does NOT take the plan content as a parameter - it will read the plan from the file you wrote
-- This tool simply signals that you're done planning and ready for the user to review and approve
-- The user will see the contents of your plan file when they review it
+After investigating an authentication refactor inside plan mode and writing the plan file to disk, the assistant calls `ExitPlanMode` with no arguments. The harness reads the plan from its canonical location, displays it to the user, and waits for approval or rejection.
 
-## When to Use This Tool
-IMPORTANT: Only use this tool when the task requires planning the implementation steps of a task that requires writing code. For research tasks where you're gathering information, searching files, reading files or in general trying to understand the codebase - do NOT use this tool.
+### Example 2: Pre-approved quick actions
 
-## Before Using This Tool
-Ensure your plan is complete and unambiguous:
-- If you have unresolved questions about requirements or approach, use AskUserQuestion first (in earlier phases)
-- Once your plan is finalized, use THIS tool to request approval
+```
+ExitPlanMode(allowedPrompts=[
+  {"tool": "Bash", "prompt": "run tests"},
+  {"tool": "Bash", "prompt": "install dependencies"}
+])
+```
 
-**Important:** Do NOT use AskUserQuestion to ask "Is this plan okay?" or "Should I proceed?" - that's exactly what THIS tool does. ExitPlanMode inherently requests user approval of your plan.
+Lets the user grant permission up front for routine follow-up commands, so the assistant does not need to pause for each permission prompt during implementation.
 
-## Examples
+## Notes
 
-1. Initial task: "Search for and understand the implementation of vim mode in the codebase" - Do not use the exit plan mode tool because you are not planning the implementation steps of a task.
-2. Initial task: "Help me implement yank mode for vim" - Use the exit plan mode tool after you have finished planning the implementation steps of the task.
-3. Initial task: "Add a new feature to handle user authentication" - If unsure about auth method (OAuth, JWT, etc.), use AskUserQuestion first, then use exit plan mode tool after clarifying the approach.
-</textarea>
+- `ExitPlanMode` only makes sense for implementation-style work. If the user's request is a research or explanation task with no file changes, answer directly instead — do not route through plan mode just to exit it.
+- The plan must already be written to disk before calling this tool. `ExitPlanMode` does not accept the plan body as a parameter; it reads from the path the harness expects.
+- If the user rejects the plan, you return to plan mode. Revise based on the feedback and submit again; do not start editing files while the plan is unapproved.
+- Approval grants permission to leave plan mode and use mutating tools (`Edit`, `Write`, `Bash`, and so on) for the scope described in the plan. Expanding scope afterwards requires a new plan or explicit user consent.
+- Do not use `AskUserQuestion` to ask "does this plan look good?" before calling this tool — requesting plan approval is exactly what `ExitPlanMode` does, and the user cannot see the plan until it is submitted.
+- Keep the plan minimal and actionable. A reviewer should be able to skim it in under a minute and understand exactly what will change.
+- If you realize mid-implementation that the plan was wrong, stop and report back to the user rather than silently deviating. Re-entering plan mode is a valid next step.

package/concepts/en/Tool-ExitWorktree.md

@@ -0,0 +1,41 @@
+# ExitWorktree
+
+Exit a worktree session previously created by `EnterWorktree` and return the session to the original working directory. This tool only operates on worktrees created by `EnterWorktree` in the current session; it is a no-op if no such session is active.
+
+## When to Use
+
+- You have finished work in an isolated worktree and want to return to the main working directory.
+- You completed a task in a feature branch worktree and want to clean up the branch and directory after merging.
+- You want to preserve the worktree for later and simply return to the original directory without deleting anything.
+- You want to abandon an experimental or throwaway branch without keeping any of its artifacts on disk.
+- You need to start fresh with a new `EnterWorktree` call, which requires exiting the current one first.
+
+## Parameters
+
+- `action` (string, required): `"keep"` leaves the worktree directory and branch intact on disk so you can return to them later; `"remove"` deletes both the worktree directory and its branch, performing a clean exit.
+- `discard_changes` (boolean, optional, default `false`): Only meaningful when `action` is `"remove"`. If the worktree contains uncommitted files or commits that are not on the original branch, the tool refuses to remove it unless `discard_changes` is set to `true`. The error response lists the specific changes so you can confirm with the user before re-invoking.
+
+## Examples
+
+### Example 1: clean exit after merging changes
+
+After finishing work in a worktree and merging the branch into main, call `ExitWorktree` with `action: "remove"` to delete the worktree directory and branch, and return to the original working directory.
+
+```
+ExitWorktree(action: "remove")
+```
+
+### Example 2: discard a throwaway worktree with uncommitted experimental code
+
+If a worktree contains experimental uncommitted changes that should be discarded entirely, first attempt `action: "remove"`. The tool will refuse and list the uncommitted changes. After confirming with the user that the changes can be discarded, re-invoke with `discard_changes: true`.
+
+```
+ExitWorktree(action: "remove", discard_changes: true)
+```
+
+## Notes
+
+- This tool only operates on worktrees created by `EnterWorktree` within the current session. It will not affect worktrees created with `git worktree add`, worktrees from previous sessions, or the plain working directory if `EnterWorktree` was never called — in those cases the tool is a no-op.
+- `action: "remove"` refuses to proceed if the worktree has uncommitted changes or commits not present on the original branch, unless `discard_changes: true` is explicitly provided. Always confirm with the user before setting `discard_changes: true`, as the data cannot be recovered.
+- If a tmux session was attached to the worktree: on `remove` it is killed; on `keep` it is left running, and its name is returned so the user can reattach later.
+- After `ExitWorktree` completes, `EnterWorktree` can be called again to start a fresh worktree session.

package/concepts/en/Tool-Glob.md

@@ -1,39 +1,35 @@
 # Glob
 
-## Definition
+Matches filenames against a glob pattern and returns the paths sorted by most recent modification time first. Optimized for locating files quickly in codebases of any size without shelling out to `find`.
 
-A fast file pattern matching tool that works with any codebase size. Returns matching file paths sorted by modification time.
+## When to Use
 
-## Parameters
+- Enumerating every file of a specific extension (for example, all `*.ts` files under `src`)
+- Discovering configuration or fixture files by naming convention (`**/jest.config.*`, `**/*.test.tsx`)
+- Narrowing a search surface before running a targeted `Grep`
+- Checking whether a file already exists at a known pattern before calling `Write`
+- Finding recently touched files by relying on the modification-time ordering
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `pattern` | string | Yes | Glob pattern (e.g., `**/*.js`, `src/**/*.ts`) |
-| `path` | string | No | Search directory, defaults to the current working directory. Do not pass "undefined" or "null" |
+## Parameters
 
-## Use Cases
+- `pattern` (string, required): The glob expression to match. Supports `*` for single-segment wildcards, `**` for recursive matches, and `{a,b}` for alternatives, for example `src/**/*.{ts,tsx}`.
+- `path` (string, optional): Directory in which to run the search. Must be a valid directory path when provided. Omit the field entirely to search the current working directory. Do not pass the strings `"undefined"` or `"null"`.
 
-**Good for:**
-- Finding files by filename pattern
-- Finding all files of a specific type (e.g., all `.tsx` files)
-- Locating files first when searching for a specific class definition (e.g., `class Foo`)
-- Multiple Glob calls can be issued in parallel within a single message
+## Examples
 
-**Not good for:**
-- Searching file contents — use Grep instead
-- Open-ended exploration requiring multiple rounds of searching — use Task (Explore type) instead
+### Example 1: Every TypeScript source file
+Call `Glob` with `pattern: "src/**/*.ts"`. The result is a mtime-sorted list, so the most recently edited files appear first, which is useful for focusing on hot spots.
 
-## Notes
+### Example 2: Locate a class definition candidate
+When you suspect a class lives in a file whose name you do not know, search with `pattern: "**/*UserService*"` to narrow the candidates, then follow up with `Read` or `Grep`.
 
-- Supports standard glob syntax: `*` matches single level, `**` matches multiple levels, `{}` matches alternatives
-- Results are sorted by modification time
-- Preferred over the `find` command in Bash
+### Example 3: Parallel discovery before a larger task
+In a single message, issue multiple `Glob` calls (for example one for `**/*.test.ts` and one for `**/fixtures/**`) so both run in parallel and their results can be correlated.
 
-## Original Text
+## Notes
 
-<textarea readonly>- Fast file pattern matching tool that works with any codebase size
-- Supports glob patterns like "**/*.js" or "src/**/*.ts"
-- Returns matching file paths sorted by modification time
-- Use this tool when you need to find files by name patterns
-- When you are doing an open ended search that may require multiple rounds of globbing and grepping, use the Agent tool instead
-- You can call multiple tools in a single response. It is always better to speculatively perform multiple searches in parallel if they are potentially useful.</textarea>
+- Results are ordered by file modification time (newest first), not alphabetically. Sort downstream if you need stable ordering.
+- Patterns are evaluated by the tool, not by the shell; you do not need to quote or escape them as you would on the command line.
+- For open-ended exploration that requires multiple rounds of searching and reasoning, delegate to an `Agent` with the Explore agent type instead of chaining many `Glob` calls.
+- Prefer `Glob` over `Bash` invocations of `find` or `ls` for filename discovery; it handles permissions consistently and returns structured output.
+- When looking for content inside files rather than filenames, use `Grep` instead.

package/concepts/en/Tool-Grep.md

@@ -1,57 +1,46 @@
 # Grep
 
-## Definition
+Searches file contents using the ripgrep engine. Offers full regular expression support, file-type filtering, and three output modes so you can trade precision for compactness.
 
-A powerful content search tool based on ripgrep. Supports regular expressions, file type filtering, and multiple output modes.
+## When to Use
+
+- Locating every call site of a function or every reference to an identifier
+- Checking whether a string or error message appears anywhere in the codebase
+- Counting occurrences of a pattern to gauge impact before refactoring
+- Narrowing a search to a file type (`type: "ts"`) or glob (`glob: "**/*.tsx"`)
+- Pulling cross-line matches such as multi-line struct definitions or JSX blocks with `multiline: true`
 
 ## Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `pattern` | string | Yes | Regular expression search pattern |
-| `path` | string | No | Search path (file or directory), defaults to current working directory |
-| `glob` | string | No | Filename filter (e.g., `*.js`, `*.{ts,tsx}`) |
-| `type` | string | No | File type filter (e.g., `js`, `py`, `rust`), more efficient than glob |
-| `output_mode` | enum | No | Output mode: `files_with_matches` (default), `content`, `count` |
-| `-i` | boolean | No | Case-insensitive search |
-| `-n` | boolean | No | Show line numbers (content mode only), default true |
-| `-A` | number | No | Number of lines to show after a match |
-| `-B` | number | No | Number of lines to show before a match |
-| `-C` / `context` | number | No | Number of lines to show before and after a match |
-| `head_limit` | number | No | Limit the number of output entries, default 0 (unlimited) |
-| `offset` | number | No | Skip the first N results |
-| `multiline` | boolean | No | Enable multiline matching mode, default false |
-
-## Use Cases
-
-**Good for:**
-- Searching for specific strings or patterns in the codebase
-- Finding where functions/variables are used
-- Filtering search results by file type
-- Counting the number of matches
-
-**Not good for:**
-- Finding files by filename — use Glob instead
-- Open-ended exploration requiring multiple rounds of searching — use Task (Explore type) instead
+- `pattern` (string, required): The regular expression to search for. Uses ripgrep syntax, so literal braces need escaping (for example `interface\{\}` to find `interface{}`).
+- `path` (string, optional): File or directory to search. Defaults to the current working directory.
+- `glob` (string, optional): Filename filter such as `*.js` or `*.{ts,tsx}`.
+- `type` (string, optional): File-type shortcut such as `js`, `py`, `rust`, `go`. More efficient than `glob` for standard languages.
+- `output_mode` (enum, optional): `files_with_matches` (default, returns paths only), `content` (returns matching lines), or `count` (returns match tallies).
+- `-i` (boolean, optional): Case-insensitive matching.
+- `-n` (boolean, optional): Include line numbers in `content` mode. Defaults to `true`.
+- `-A` (number, optional): Lines of context to show after each match (requires `content` mode).
+- `-B` (number, optional): Lines of context before each match (requires `content` mode).
+- `-C` / `context` (number, optional): Lines of context on both sides of each match.
+- `multiline` (boolean, optional): Allow patterns to span newlines (`.` matches `\n`). Defaults to `false`.
+- `head_limit` (number, optional): Limit returned lines, file paths, or count entries. Defaults to 250; pass `0` for unlimited (use sparingly).
+- `offset` (number, optional): Skip the first N results before applying `head_limit`. Defaults to `0`.
+
+## Examples
+
+### Example 1: Find all call sites of a function
+Set `pattern: "registerHandler\\("`, `output_mode: "content"`, and `-C: 2` to see the surrounding lines of each call.
+
+### Example 2: Count matches across a type
+Set `pattern: "TODO"`, `type: "py"`, and `output_mode: "count"` to see per-file TODO totals across Python sources.
+
+### Example 3: Multiline struct match
+Use `pattern: "struct Config \\{[\\s\\S]*?version"` with `multiline: true` to capture a field declared several lines into a Go struct.
 
 ## Notes
 
-- Uses ripgrep syntax (not grep); special characters like braces need escaping
-- `files_with_matches` mode returns only file paths, most efficient
-- `content` mode returns matching line content, supports context lines
-- Multiline matching requires setting `multiline: true`
-- Always prefer the Grep tool over `grep` or `rg` commands in Bash
-
-## Original Text
-
-<textarea readonly>A powerful search tool built on ripgrep
-
-  Usage:
-  - ALWAYS use Grep for search tasks. NEVER invoke `grep` or `rg` as a Bash command. The Grep tool has been optimized for correct permissions and access.
-  - Supports full regex syntax (e.g., "log.*Error", "function\s+\w+")
-  - Filter files with glob parameter (e.g., "*.js", "**/*.tsx") or type parameter (e.g., "js", "py", "rust")
-  - Output modes: "content" shows matching lines, "files_with_matches" shows only file paths (default), "count" shows match counts
-  - Use Agent tool for open-ended searches requiring multiple rounds
-  - Pattern syntax: Uses ripgrep (not grep) - literal braces need escaping (use `interface\{\}` to find `interface{}` in Go code)
-  - Multiline matching: By default patterns match within single lines only. For cross-line patterns like `struct \{[\s\S]*?field`, use `multiline: true`
-</textarea>
+- Always prefer `Grep` over running `grep` or `rg` through `Bash`; the tool is optimized for correct permissions and structured output.
+- Default output mode is `files_with_matches`, which is cheapest. Switch to `content` only when you need to see the lines themselves.
+- Context flags (`-A`, `-B`, `-C`) are ignored unless `output_mode` is `content`.
+- Large result sets burn context tokens. Use `head_limit`, `offset`, or tighter `glob`/`type` filters to stay focused.
+- For filename discovery, use `Glob` instead; for open-ended investigations across many rounds, dispatch an `Agent` with the Explore agent.

package/concepts/en/Tool-Monitor.md

@@ -0,0 +1,50 @@
+# Monitor
+
+Start a background monitor that streams events from a long-running script. Each stdout line becomes a notification — keep working while events arrive in chat.
+
+## When to Use
+
+- Tailing a log file for errors, warnings, or crash signatures while a deployment runs
+- Polling a remote API, PR, or CI pipeline every 30 seconds for new status events
+- Watching a filesystem directory or build output for changes as they happen
+- Waiting for a specific condition across many iterations (e.g., a training step milestone or a queue draining)
+- **Not** for simple "wait until done" — use `Bash` with `run_in_background` for that; it emits one completion notification when the process exits
+
+## Parameters
+
+- `command` (string, required): The shell command or script to run. Each line written to stdout becomes a separate notification event. The monitor ends when the process exits.
+- `description` (string, required): A short human-readable label shown in every notification. Be specific — "errors in deploy.log" is better than "watching logs". This label is how you identify which monitor fired.
+- `timeout_ms` (number, default `300000`, max `3600000`): Kill deadline in milliseconds. After this duration the process is terminated. Ignored when `persistent: true`.
+- `persistent` (boolean, default `false`): When `true`, the monitor runs for the lifetime of the session with no timeout. Stop it explicitly with `TaskStop`.
+
+## Examples
+
+### Example 1: Tail a log file for errors and crashes
+
+This example covers terminal states: success marker, traceback, common error keywords, OOM kill, and unexpected process death.
+
+```bash
+tail -F /var/log/deploy.log | grep -E --line-buffered \
+  "deployed|Traceback|Error|FAILED|assert|Killed|OOM"
+```
+
+Use `grep --line-buffered` in every pipe. Without it the operating system buffers output in 4 KB blocks and events can be delayed by minutes. The alternation pattern covers both the happy path (`deployed`) and failure paths (`Traceback`, `Error`, `FAILED`, `Killed`, `OOM`). A monitor that only watches for success stays silent through a crash — silence looks identical to "still running".
+
+### Example 2: Poll a remote API every 30 seconds for new events
+
+```bash
+while true; do
+  curl -sf "https://api.example.com/status" || true
+  sleep 30
+done | grep --line-buffered -E "completed|failed|error"
+```
+
+`|| true` prevents a transient network failure from killing the loop. Poll intervals of 30 seconds or more are appropriate for remote APIs to avoid rate limits. Adjust the grep pattern to capture both success and failure responses so silence cannot mask an API-side error.
+
+## Notes
+
+- **Always use `grep --line-buffered` in pipes.** Without it, pipe buffering delays events by minutes because the OS accumulates output until a 4 KB block fills. `--line-buffered` forces a flush after every line.
+- **Filter must cover both success and failure signatures.** A monitor watching only for the success marker goes silent on a crash, hang, or unexpected exit. Widen the alternation: include `Error`, `Traceback`, `FAILED`, `Killed`, `OOM`, and similar terminal-state markers alongside the success keyword.
+- **Poll intervals: 30 seconds or more for remote APIs.** Tight polling loops on external services risk rate-limit errors or bans. For local filesystem or process checks, 0.5–1 second is appropriate.
+- **Use `persistent: true` for session-lifetime monitors.** The default `timeout_ms` of 300 000 ms (5 minutes) terminates the process. For monitors that should run until you explicitly stop them, set `persistent: true` and call `TaskStop` when done.
+- **Auto-stop on event flood.** Every stdout line is a conversation message. If the filter is too broad and produces too many events, the monitor is automatically stopped. Restart with a tighter `grep` pattern. Lines arriving within 200 ms are batched into a single notification.

package/concepts/en/Tool-NotebookEdit.md

@@ -1,33 +1,39 @@
 # NotebookEdit
 
-## Definition
+Modifies a single cell in a Jupyter notebook (`.ipynb`). Supports replacing a cell's source, inserting a new cell, or deleting an existing cell while preserving the rest of the notebook structure.
 
-Replaces, inserts, or deletes specific cells in a Jupyter notebook (.ipynb file).
+## When to Use
+
+- Fixing or updating a code cell in an analysis notebook without rewriting the entire file
+- Swapping out a markdown cell to improve narrative or add documentation
+- Inserting a new code or markdown cell at a known position in an existing notebook
+- Removing an obsolete or broken cell so downstream cells no longer depend on it
+- Preparing a reproducible notebook by iterating on cells one at a time
 
 ## Parameters
 
-| Parameter | Type | Required | Description |
-|-----------|------|----------|-------------|
-| `notebook_path` | string | Yes | Absolute path of the notebook file |
-| `new_source` | string | Yes | New content for the cell |
-| `cell_id` | string | No | ID of the cell to edit. In insert mode, the new cell is inserted after this ID |
-| `cell_type` | enum | No | Cell type: `code` or `markdown`. Required in insert mode |
-| `edit_mode` | enum | No | Edit mode: `replace` (default), `insert`, `delete` |
+- `notebook_path` (string, required): Absolute path to the `.ipynb` file. Relative paths are rejected.
+- `new_source` (string, required): The new cell source. For `replace` and `insert` it becomes the cell body; for `delete` it is ignored but still required by the schema.
+- `cell_id` (string, optional): ID of the target cell. In `replace` and `delete` modes, the tool acts on this cell. In `insert` mode, the new cell is inserted immediately after the cell with this ID; omit it to insert at the top of the notebook.
+- `cell_type` (enum, optional): Either `code` or `markdown`. Required when `edit_mode` is `insert`. When omitted during `replace`, the existing cell's type is preserved.
+- `edit_mode` (enum, optional): `replace` (default), `insert`, or `delete`.
 
-## Use Cases
+## Examples
 
-**Good for:**
-- Modifying code or markdown cells in a Jupyter notebook
-- Adding new cells to a notebook
-- Deleting cells from a notebook
+### Example 1: Replace a buggy code cell
+Call `NotebookEdit` with `notebook_path` set to the absolute path, `cell_id` set to the target cell's ID, and `new_source` containing the corrected Python code. Leave `edit_mode` at its default `replace`.
 
-## Notes
+### Example 2: Insert a markdown explanation
+To add a markdown cell right after an existing `setup` cell, set `edit_mode: "insert"`, `cell_type: "markdown"`, `cell_id` to the setup cell's ID, and put the narrative in `new_source`.
 
-- `cell_number` is 0-indexed
-- `insert` mode inserts a new cell at the specified position
-- `delete` mode deletes the cell at the specified position
-- The path must be an absolute path
+### Example 3: Delete a stale cell
+Set `edit_mode: "delete"` and supply the `cell_id` of the cell to remove. Provide any string for `new_source`; it is not applied.
 
-## Original Text
+## Notes
 
-<textarea readonly>Completely replaces the contents of a specific cell in a Jupyter notebook (.ipynb file) with new source. Jupyter notebooks are interactive documents that combine code, text, and visualizations, commonly used for data analysis and scientific computing. The notebook_path parameter must be an absolute path, not a relative path. The cell_number is 0-indexed. Use edit_mode=insert to add a new cell at the index specified by cell_number. Use edit_mode=delete to delete the cell at the index specified by cell_number.</textarea>
+- Always pass an absolute path. `NotebookEdit` does not resolve relative paths against the working directory.
+- The tool rewrites only the targeted cell; execution counts, outputs, and metadata for unrelated cells remain untouched.
+- Inserting without a `cell_id` places the new cell at the very beginning of the notebook.
+- `cell_type` is mandatory for inserts. For replaces, omit it unless you explicitly want to convert a code cell into markdown or vice versa.
+- To inspect cells and grab their IDs, use the `Read` tool on the notebook first; it returns the cells with their content and outputs.
+- Use regular `Edit` for plain source files; `NotebookEdit` is specific to `.ipynb` JSON and understands its cell structure.

package/concepts/en/Tool-PushNotification.md

@@ -0,0 +1,48 @@
+# PushNotification
+
+Sends a desktop notification from the current Claude Code session. If Remote Control is connected, it also pushes to the user's phone, pulling their attention back from wherever they are.
+
+## When to Use
+
+- A long-running task finished while the user was likely away from the terminal
+- A build, test run, or deployment completed and the result is ready to review
+- You have reached a decision point that requires user input before work can continue
+- An error or blocker has surfaced that you cannot resolve autonomously
+- The user explicitly asked to be notified when a specific task or condition is met
+
+## When NOT to Use
+
+Do not send a notification for routine progress updates mid-task, or to confirm you have answered a question the user clearly just asked and is still watching. Do not notify when a short task completes — if the user submitted it and is waiting, a notification adds no value and erodes trust for future ones. Err strongly toward not sending one.
+
+## Parameters
+
+- `message` (string, required): the notification body. Keep under 200 characters; mobile operating systems truncate longer strings. Lead with what the user would act on: "build failed: 2 auth tests" is more useful than "task complete."
+- `status` (string, required): always set to `"proactive"`. This is a fixed marker and does not change.
+
+## Examples
+
+### Example 1: notifying on completion of a long analysis
+
+A repository-wide dependency audit was requested and took several minutes to run. The user stepped away. When the report is ready:
+
+```
+message: "Dependency audit done: 3 high-severity CVEs found in lodash, axios, jsonwebtoken. Report at audit-report.txt"
+status: "proactive"
+```
+
+### Example 2: flagging a decision point during autonomous work
+
+During a multi-step refactor, you discover that two modules have conflicting interfaces and cannot be merged without a design decision:
+
+```
+message: "Refactor paused: AuthService and UserService have conflicting token interfaces. Need your call before continuing."
+status: "proactive"
+```
+
+## Notes
+
+- Err toward **not** sending. The notification interrupts the user regardless of what they are doing. Treat it as a cost that must be justified by the value of the information.
+- Lead with actionable content. The first words should tell the user what happened and what, if anything, they need to do — not a generic status label.
+- Keep `message` under 200 characters. Mobile operating systems will truncate longer strings, cutting off the most important part if it appears at the end.
+- If the result indicates the push was not sent because Remote Control is not connected, that is expected behavior. No retry or follow-up action is needed; the desktop notification still fires locally.
+- Avoid notification spam. If you send notifications frequently for minor events, the user will start ignoring them. Reserve this tool for moments where there is a real chance the user has walked away and will want to know the result now.