Home Docs Claude Code CLI

One capture · claude-code

One read of Claude Code CLIclaude-code-20261106T043702Z

5 pages moved out of 228 read.

Pages moved 5 significant first

Pages read 228 in this capture

Captured 6 Nov 2026 04:37 UTC

Corpus hash b271cd858c90 corpus-hash

What this read moved

1-5 of 5

desktop-scheduled-tasks Changed · +3 / -3 lines

from line 156

156156

157157## Permissions for scheduled tasks

158158

159Each task has its own permission mode, which you set when creating or editing the task. Allow rules from `~/.claude/settings.json` also apply to scheduled task sessions. If a task runs in [Manual mode](https://code.claude.com/docs/en/desktop.md#choose-a-permission-mode) and needs to run a tool it doesn't have permission for, the run stalls until you approve it. To approve it, [find the run's session](#find-a-runs-session) and answer the permission prompt there.

159Each task has its own [permission mode](https://code.claude.com/docs/en/desktop.md#choose-a-permission-mode), which you set when creating or editing the task. Allow rules from `~/.claude/settings.json` also apply to scheduled task sessions. When a run is stalled on a permission prompt, [find the run's session](#find-a-runs-session) and answer the prompt there.

160160

161To avoid stalls, click **Run now** after creating a task, watch for permission prompts, and select "always allow" for each one. Future runs of that task auto-approve the same tools without prompting. You can review and revoke these approvals from the task's detail page.

161To avoid stalls, click **Run now** after creating a task, watch for permission prompts, and select "always allow" for each one. Future runs skip most of those prompts. You can review and revoke these approvals from the task's detail page. If you select "always allow" on a file edit in the task's folder, only that session moves to **Accept edits**, so set the task's permission mode to **Accept edits**.

162162

163163MCP tools marked [`requiresUserInteraction`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool) prompt on every call and don't offer an always-allow option. Runs that call these tools stall each time.

164164

from line 175

175175

176176You can also list, create, edit, and pause tasks by asking Claude in any Desktop session. For example, "pause my dependency-audit task" or "show me my scheduled tasks." To delete a task, use the **Delete** button on its detail page.

177177

178A scheduled task can also modify its own schedule or prompt from within a running session using the `update_scheduled_task` MCP tool. This lets a task reschedule itself based on what it finds, for example, rescheduling a code review to run earlier when it detects a release branch has been created.

178To let a task change its own schedule or prompt with the `update_scheduled_task` MCP tool, click **Run now** and approve the call each time.

179179

180180To edit a task's prompt on disk, open `~/.claude/scheduled-tasks/<task-name>/SKILL.md` (or under [`CLAUDE_CONFIG_DIR`](https://code.claude.com/docs/en/env-vars) if set). The file uses YAML frontmatter for `name` and `description`, with the prompt as the body. Changes take effect on the next run. Schedule, folder, model, and enabled state are not in this file: change them through the Edit form or ask Claude.

181181

hooks Changed · +25 / -7 lines

#### Match Monitor commands #### PreCompact output

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

from line 66

6666

6767> [tab] macOS/Linux

6868>

69> The `matcher` narrows to Bash tool calls and the `if` condition narrows further to Bash subcommands matching `rm *`, so `block-rm.sh` only spawns when both filters match:

69> The `matcher` narrows to Bash tool calls and [Monitor commands](#match-monitor-commands), and the `if` condition narrows further to Bash subcommands matching `rm *`, so `block-rm.sh` only spawns when both filters match:

7070>

7171> ```json theme={null}

7272> {

from line 112

112112

113113> [tab] Windows (PowerShell)

114114>

115> The matcher `Bash|PowerShell` covers the [PowerShell tool](#powershell) as well as Bash. A single `if` rule matches only one tool's calls, so each tool gets its own handler: the first narrows to Bash subcommands matching `rm *`, the second to PowerShell commands matching `Remove-Item *`. Both run the same script through `powershell.exe`:

115> The matcher `Bash|PowerShell` covers the [PowerShell tool](#powershell) as well as Bash. A single `if` rule names one tool, so each tool gets its own handler: the first narrows to Bash subcommands matching `rm *`, the second to PowerShell commands matching `Remove-Item *`. Both run the same script through `powershell.exe`:

116116>

117117> ```json theme={null}

118118> {

from line 221

221221Hooks are defined in JSON settings files. The configuration has three levels of nesting:

222222

2232231. Choose a [hook event](#hook-events) to respond to, like `PreToolUse` or `Stop`

2242. Add a [matcher group](#matcher-patterns) to filter when it fires, like "only for the Bash tool"

2242. Add a [matcher group](#matcher-patterns) to filter when it fires, like "for the Bash tool"

2252253. Define one or more [hook handlers](#hook-handler-fields) to run when matched

226226

227227See [How a hook resolves](#how-a-hook-resolves) above for a complete walkthrough with an annotated example.

from line 273

273273| Matcher value | Evaluated as | Example |

274274| :- | :- | :- |

275275| `"*"`, `""`, or omitted | Match all | fires on every occurrence of the event |

276| Only letters, digits, `_`, `-`, spaces, `,`, and `\|` | Exact string, or list of exact strings separated by `\|` or `,` with optional surrounding whitespace | `Bash` matches only the Bash tool; `Edit\|Write` and `Edit, Write` each match either tool exactly; `code-reviewer` matches only that agent type |

276| Only letters, digits, `_`, `-`, spaces, `,`, and `\|` | Exact string, or list of exact strings separated by `\|` or `,` with optional surrounding whitespace | `Bash` matches the Bash tool, and on `PreToolUse` and `PermissionRequest` also [Monitor commands](#match-monitor-commands); `Edit\|Write` and `Edit, Write` each match either tool exactly; `code-reviewer` matches only that agent type |

277277| Contains any other character | JavaScript regular expression, unanchored | `^Notebook` matches any tool whose name starts with `Notebook`; `mcp__memory__.*` matches every tool from the `memory` server |

278278

279279A matcher on the regular-expression path is tested with JavaScript's `RegExp.prototype.test`, which succeeds on a match anywhere in the value. `Edit.*` matches both `Edit` and `NotebookEdit`; wrap the pattern in `^` and `$`, as in `^Edit$`, when you need a whole-string match.

from line 381

381381}

382382```

383383

384#### Match Monitor commands

385

386A [`PreToolUse`](#pretooluse) or [`PermissionRequest`](#permissionrequest) hook with a `Bash` matcher also runs on shell commands Claude starts with the [Monitor tool](https://code.claude.com/docs/en/tools-reference.md#monitor-tool), but its `allow` and [`updatedInput`](#pretooluse-decision-control) have no effect on them. Requires Claude Code v2.1.314 or later. Matchers such as `Bash|PowerShell`, `^Bash$`, and `Bash.*` are `Bash` matchers too. A hook with a `Bash` matcher doesn't run for a [WebSocket watch](https://code.claude.com/docs/en/tools-reference.md#websocket-source), and a `PostToolUse` hook with one doesn't run for Monitor.

387

388A hook that runs for a Monitor command can deny it or have Claude Code ask you about it. To allow or rewrite the command, switch from a `Bash` matcher to one that includes Monitor:

389

390* **Matcher that includes Monitor**: with a matcher such as `Bash|Monitor` or `.*`, or with no matcher, the hook gets the Monitor call's own input, and `allow` and `updatedInput` apply. In [`if`](#common-fields), name Monitor, as in `Monitor(tail *)`, which matches by [the rules `Bash(tail *)` follows](#bash-if-matching). If its `if` names Bash, the hook still gets the Monitor call's input, but `allow` and `updatedInput` have no effect

391* **`Bash` matcher**: the hook gets a Bash call. In `if`, name Bash, as in `Bash(tail *)`. The hook doesn't run if its `if` names Monitor

392

384393### Hook handler fields

385394

386395Each object in the inner `hooks` array is a hook handler: the shell command, HTTP endpoint, MCP tool, LLM prompt, or agent that runs when the matcher matches. There are five types:

from line 816

807816* **Two or more lines that each parse as JSON on their own, the first starting with `{` and the last ending with `}`**: plain text when no line is a JSON output object that sets a field. When one line is, the output is a parse failure, so print that object with nothing else on stdout.

808817* **Anything else that starts with `{` and ends with `}` but isn't valid JSON**: a parse failure.

809818

810For most events, Claude Code writes stdout to the debug log and doesn't show it in the transcript. The exceptions are `UserPromptSubmit`, `UserPromptExpansion`, `SessionStart`, and `PostModelSwitch`, where Claude Code adds plain-text stdout as context that Claude can see and act on. On those events, Claude Code doesn't add stdout it failed to parse.

819For most events, Claude Code writes stdout to the debug log and doesn't show it in the transcript. On these events, your stdout reaches Claude or the compaction summary:

811820

821* **`UserPromptSubmit`, `UserPromptExpansion`, `SessionStart`, and `PostModelSwitch`**: Claude Code adds plain-text stdout as context that Claude can see and act on. It doesn't add stdout it failed to parse.

822* **`PreCompact`**: your stdout becomes [instructions for the compaction summary](#precompact-output)

823

812824Claude never sees stderr from a hook that exits 0. To read it yourself on events such as `PreToolUse`, enable [debug logging](#debug-hooks). To surface a warning to Claude from a `PostToolUse` or `PostToolUseFailure` hook, exit 2 instead so [Claude sees the stderr](#exit-code-2-behavior-per-event) even though the tool already ran.

813825

814826#### Exit code 2

from line 1058

10461058A hook's `additionalContext`, `systemMessage`, and `initialUserMessage` strings, and its plain stdout, are capped at 10,000 characters:

10471059

10481060* **Scope**: Claude Code measures each string on its own, even when several hooks run for the same event. For JSON output, each field is measured separately; plain stdout is measured whole.

1049* **Over the limit**: Claude Code saves the output to a file in the session directory and replaces it with the file path and a preview of up to the first 2,000 characters. A large valid Bash result is handled the same way, described under [Output limits](https://code.claude.com/docs/en/tools-reference.md#output-limits). Unlike that Bash ceiling, this cap has no setting or environment variable to raise it.

1061* **Over the limit**: except for [PreCompact stdout](#precompact-output), Claude Code saves the output to a file in the session directory. It replaces the output with the file path and a preview of up to the first 2,000 characters. A large valid Bash result is handled the same way, described under [Output limits](https://code.claude.com/docs/en/tools-reference.md#output-limits). Unlike that Bash ceiling, this cap has no setting or environment variable to raise it.

10501062* **Reading the file**: Claude Code doesn't ask Claude to read the file, so keep anything Claude must always see within the cap.

10511063

10521064The JSON object supports three kinds of fields:

from line 1962

19501962

19511963#### PreToolUse decision control

19521964

1953`PreToolUse` hooks can control whether a tool call proceeds. Unlike other hooks that use a top-level `decision` field, PreToolUse returns its decision inside a `hookSpecificOutput` object. This gives it richer control: four outcomes (allow, deny, ask, or defer) plus the ability to modify tool input before execution.

1965`PreToolUse` hooks can control whether a tool call proceeds. Unlike other hooks that use a top-level `decision` field, PreToolUse returns its decision inside a `hookSpecificOutput` object. This gives it richer control: four outcomes (allow, deny, ask, or defer) plus the ability to modify tool input before execution. To allow or rewrite a Monitor command, see [Match Monitor commands](#match-monitor-commands).

19541966

19551967| Field | Description |

19561968| :- | :- |

from line 2156

21442156| `message` | For `"deny"` only: tells Claude why the permission was denied |

21452157| `interrupt` | For `"deny"` only: if `true`, stops Claude |

21462158

2159To allow or rewrite a Monitor command, see [Match Monitor commands](#match-monitor-commands).

2160

21472161A hook that exits 2 without a `decision` object leaves the permission flow unchanged, and its stderr is discarded. To grant or deny the request, return the `decision` object.

21482162

21492163```json theme={null}

from line 3337

33233337}

33243338```

33253339

3340#### PreCompact output

3341

3342When a PreCompact hook exits 0 and doesn't block, Claude Code uses its stdout as instructions for the compaction summary. Keep that stdout under 10,000 characters per hook. Claude Code cuts longer output at the cap and appends a marker.

3343

33263344### PostCompact

33273345

33283346Runs after Claude Code completes a compact operation. Use this event to react to the new compacted state, for example to log the generated summary or update external state. Claude Code discards a PostCompact hook's `systemMessage` and `continue` fields.

from line 3758

37403758> ]

37413759> }

37423760> }

3743> ```

3744>

3745> Save this script to `.claude/hooks/answer-project-key.sh` in your project and make it executable with `chmod +x`:

3746>

3747> ```bash theme={null}

3748> #!/bin/bash

3749> input=$(cat)

3750> fields=$(jq -c '.requested_schema.properties // {} | keys' <<<"$input")

3751>

3752> if [ "$fields" = '["project_key"]' ]; then

3753> jq -n '{hookSpecificOutput: {hookEventName: "Elicitation", action: "accept", content: {project_key: "DOCS"}}}'

3754> fi

3755> ```

3756

3757> [tab] Windows (PowerShell)

3758>

3759> Register a command hook that runs the script through PowerShell, with the server name as the matcher:

3760>

3761> ```json theme={null}

3762> {

3763> "hooks": {

3764> "Elicitation": [

3765> {

3766> "matcher": "issue-tracker",

3767> "hooks": [

3768> {

3769> "type": "command",

3770> "command": "powershell.exe",

3771> "args": [

3772> "-NoProfile",

3773> "-ExecutionPolicy",

3774> "Bypass",

3775> "-File",

3776> "${CLAUDE_PROJECT_DIR}/.claude/hooks/answer-project-key.ps1"

3777> ]

3778> }

3779> ]

3780> }

3781> ]

3782> }

3783> }

3784> ```

3785>

3786> Save this script to `.claude/hooks/answer-project-key.ps1` in your project:

3787>

3788> ```powershell theme={null}

3789> $request = [Console]::In.ReadToEnd() | ConvertFrom-Json

3790> $fields = @($request.requested_schema.properties.PSObject.Properties.Name)

3791>

3792> if ($fields.Count -eq 1 -and $fields[0] -eq 'project_key') {

3793> @{

3794> hookSpecificOutput = @{

3795> hookEventName = "Elicitation"

3796> action = "accept"

3797> content = @{ project_key = "DOCS" }

3798> }

3799> } | ConvertTo-Json -Depth 3

3800> }

3801> ```

3802

3803To confirm the hook works, start Claude Code with `claude --debug` and give Claude a task that makes the server ask for the project key. No dialog appears, and the [debug log](#debug-hooks) has a line that ends with `Elicitation resolved by hook: {"action":"accept","content":{"project_key":"DOCS"}}`.

3804

3805### ElicitationResult

3806

3807Runs after a user responds to an MCP elicitation. Hooks can observe, modify, or block the response before it is sent back to the MCP server.

3808

3809When an [Elicitation](#elicitation) hook answers a request, Claude Code sends that answer to the server without running ElicitationResu

model-config Changed · +10 / -1 lines

#### Subagents switch or fail without asking

from line 562

562562* If both models flag the same request, you can edit the prompt and retry, or start a new session.

563563* In [cloud sessions](https://code.claude.com/docs/en/claude-code-on-the-web.md) on the mobile app, editing and retrying is not supported. Switch models, or continue the session from a desktop browser or the desktop app.

564564* In [non-interactive mode](https://code.claude.com/docs/en/cli-reference.md#cli-flags) and SDK integrations that can't show the prompt, a flagged request ends the turn with a refusal instead.

565* In a [subagent](https://code.claude.com/docs/en/sub-agents.md), Claude Code doesn't show the prompt, and a flagged request that would switch models re-runs on the fallback model.

565* In a subagent that Claude starts with the [Agent tool](https://code.claude.com/docs/en/tools-reference.md#agent-tool-behavior), Claude Code doesn't pause to ask, and the subagent fails instead of switching models. See [Subagents switch or fail without asking](#subagents-switch-or-fail-without-asking).

566566* When the fallback target is blocked by [`availableModels`](#restrict-model-selection), Claude Code doesn't show the prompt. The flagged request ends with the refusal, the same as automatic fallback when the target is blocked.

567

568#### Subagents switch or fail without asking

569

570In a built-in or custom [subagent](https://code.claude.com/docs/en/sub-agents.md) that Claude starts with the [Agent tool](https://code.claude.com/docs/en/tools-reference.md#agent-tool-behavior), Claude Code doesn't [pause to ask](#ask-before-switching) at a flagged request. If a fallback model is available, the request re-runs on it or the subagent fails, according to your **Switch models when a message is flagged** choice in `/config`:

571

572* **Switch automatically**, or no choice yet: the request re-runs on the fallback model, and your session's model is unchanged

573* **Ask each time**: the subagent fails with [`Agent terminated early due to an API error`](https://code.claude.com/docs/en/errors#agent-terminated-early-due-to-an-api-error) and the refusal message. Claude receives that error and decides what to do about the unfinished task. To let subagents switch models, choose **Switch automatically**. Your main conversation then switches without asking too.

574

575When no fallback model is available, the subagent fails the same way with either choice. Before v2.1.318, a subagent's flagged request re-ran on an available fallback model whichever you chose.

567576

568577#### Enable fallback on Bedrock, Agent Platform, and Foundry

569578

agent-sdk/hooks Changed · +1 / -1 lines

from line 222

224224

225Use the `matcher` pattern to target specific tools whenever possible. A matcher with `'Bash'` only runs for Bash commands, while omitting the pattern runs your callbacks for every occurrence of the event.

225Use the `matcher` pattern to target specific tools whenever possible. With a `'Bash'` matcher, your callbacks run for Bash commands. On Claude Code v2.1.314 or later, they also run on `PreToolUse` and `PermissionRequest` for Monitor commands, which they [can deny but not approve](https://code.claude.com/docs/en/hooks.md#match-monitor-commands). With no matcher, they run for every occurrence of the event.

226226

227227### Callback functions

228228

agent-sdk/python Changed · +1 / -1 lines

from line 2513

25132513

25142514### Hook Usage Example

25152515

2516This example registers two hooks: one that blocks dangerous Bash commands like `rm -rf /`, and another that logs all tool usage for auditing. The security hook only runs on Bash commands (via the `matcher`), while the logging hook runs on all tools.

2516This example registers two hooks: one that blocks dangerous Bash commands like `rm -rf /`, and another that logs all tool usage for auditing. With its [`Bash` matcher](https://code.claude.com/docs/en/agent-sdk/hooks#matchers), the security hook runs on Bash tool calls. The logging hook has no matcher, so it runs on every tool call.

25172517

25182518```python theme={null}

25192519import asyncio