One read of Claude Code CLIclaude-code-20261024T143701Z
9 pages moved out of 228 read.
Pages moved
9
significant first
Pages read
228
in this capture
Captured
14:37 UTC
Corpus hash
05021c2dc424
corpus-hash
What this read moved
1-9 of 9claude-apps-gateway Changed · +8 / -6 lines
from line 454
454454
455455#### How hook and skill keys in parent settings take effect
456456
457If you pass `disableAllHooks: true` as a parent setting through the Agent SDK's `managedSettings` option, not every hook stops. Your [SDK hook callbacks](https://code.claude.com/docs/en/agent-sdk/hooks.md) still run, and so do the administrator's hooks, which your application can't switch off.
457Keys your application passes in the Agent SDK's [`managedSettings`](https://code.claude.com/docs/en/agent-sdk/typescript#options) option are parent settings. On a machine where an administrator deploys managed settings, Claude Code ignores parent settings unless the administrator [lets an embedding host add policy](https://code.claude.com/docs/en/managed-settings.md#let-an-embedding-host-add-policy).
458458
459On a machine where an administrator deploys managed settings, Claude Code ignores parent settings unless the administrator [lets an embedding host add policy](https://code.claude.com/docs/en/managed-settings.md#let-an-embedding-host-add-policy).
459If you pass [`disableAllHooks: true`](https://code.claude.com/docs/en/settings-reference#disableallhooks) in `managedSettings`:
460460
461* **Stop**: user, project, and local hooks, plus hooks declared in agent frontmatter or in the SDK's [`settings` option](https://code.claude.com/docs/en/agent-sdk/typescript#options).
462* **Keep running**: your application's [SDK hook callbacks](https://code.claude.com/docs/en/agent-sdk/hooks.md) and an administrator's hooks from managed settings. Your application can't turn the administrator's hooks off.
463
461464| What you pass | What happens |
462465| :- | :- |
463| `disableAllHooks: true` | Treated as `allowManagedHooksOnly: true`, so the hooks listed as [blocked under `allowManagedHooksOnly`](https://code.claude.com/docs/en/settings-reference#what-runs-under-allowmanagedhooksonly) stop, and so do hooks in the SDK's [`settings` option](https://code.claude.com/docs/en/agent-sdk/typescript#options). |
464| [`disableSkillShellExecution: true`](https://code.claude.com/docs/en/settings-reference#disableskillshellexecution) | Takes effect. |
466| `hooks`, or `allowedHttpHookUrls` or `httpHookAllowedEnvVars` with entries | Claude Code ignores the key. Use the SDK `settings` option instead. |
465467| `allowedHttpHookUrls: []` | Takes effect unless the administrator defines `hooks` or enables a plugin. No HTTP hook runs, except for URLs another settings source lists. |
466468| `httpHookAllowedEnvVars: []` | Takes effect unless the administrator defines `hooks` or enables a plugin. HTTP hook headers can include only environment variables another settings source lists. |
467| `allowedHttpHookUrls` or `httpHookAllowedEnvVars` with entries | Claude Code ignores it, since merging would widen an administrator's list. Use the SDK `settings` option instead. |
469| [`disableSkillShellExecution: true`](https://code.claude.com/docs/en/settings-reference#disableskillshellexecution) | Takes effect. |
468470
469471Passing these keys in `managedSettings` requires Claude Code v2.1.309 or later, or TypeScript Agent SDK v0.3.309 or later.
470472
errors Changed · +3 / -4 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.
hooks Changed · +5 / -7 lines
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 957
957957blocking because Git Bash wasn't found, so only exit code 0 or 2 counts as this hook's verdict.
958958```
959959
960To find out why the hook failed, check the [debug log](#debug-hooks). Pick the fix that matches your hook:
960Without Git Bash, any exit code other than 0 or 2 from that hook counts as a [failure](#block-the-action-when-a-hook-fails), even when it prints JSON that doesn't deny the call. To find out why the hook failed, check the [debug log](#debug-hooks). Then pick the fix that matches your hook:
961961
962* **The action should go ahead when the hook fails**: add [`"onFailure": "continue"`](#block-the-action-when-a-hook-fails) to the hook
963* **The hook is written for Bash**: a [shell-form](#exec-form-and-shell-form) hook with no `shell` set runs in PowerShell when Git Bash isn't installed, where a script written for Bash may not run as written. Install [Git for Windows](https://git-scm.com/downloads/win), or set [`CLAUDE_CODE_GIT_BASH_PATH`](https://code.claude.com/docs/en/env-vars) if Git Bash is installed where Claude Code doesn't find it, then start a new session
962* **The call should go ahead when the hook fails**: add [`"onFailure": "continue"`](#block-the-action-when-a-hook-fails) to the hook
963* **The hook exits 1 to warn but must block when it crashes**: with `"onFailure": "continue"`, the call goes ahead on exit code 1, warning or crash alike. Add `"onFailure": "block"` instead, and have the script exit 0 where it warns, so those calls go ahead. To still show the warning on `PreToolUse`, print it to stdout as the [`systemMessage`](#json-output) field of one JSON object.
964* **The hook is written for Bash**: without Git Bash, a [shell-form](#exec-form-and-shell-form) hook with no `shell` set runs in PowerShell, where it can fail. Install [Git for Windows](https://git-scm.com/downloads/win), or set [`CLAUDE_CODE_GIT_BASH_PATH`](https://code.claude.com/docs/en/env-vars) if Git Bash is installed where Claude Code doesn't find it. Then start a new session.
964965* **The hook runs one `.exe`, not a `.cmd` or `.bat` file**: put the program in `command` and its arguments in `args` to use exec form, and add `"onFailure": "block"`. Claude Code then starts the program with no shell. Without `"onFailure": "block"`, the call can go ahead when the program fails, is missing, or times out
965* **The hook exits 1 to warn but must block when it crashes**: with `"onFailure": "continue"`, the call goes ahead on exit code 1, warning or crash alike. Add `"onFailure": "block"` instead, and end the script with exit code 0 where it warns, so those calls go ahead. To show the warning on `PreToolUse` after exit code 0, print it to stdout in the [`systemMessage`](#json-output) field of one JSON object
966966* **A PowerShell guard hook that must block on failure**: with `onFailure` unset, it stops doing so once Git for Windows is installed and Claude Code finds Git Bash. Add `"onFailure": "block"` so a failure or a timeout blocks the call with or without Git Bash. Also set `"shell": "powershell"` so the hook keeps running in PowerShell from then on instead of in Git Bash
967967
968For a hook that shows this error, any exit code other than 0 or 2 counts as a [failure](#block-the-action-when-a-hook-fails), even when the hook prints JSON that doesn't deny the call.
969
970968Before v2.1.309, the message read `blocking because Git Bash wasn't found and this hook doesn't set "shell" to "powershell", so only exit code 0 or 2 counts as its verdict.`
971969
972970#### Exit code 2 behavior per event
from line 3918
39203918| Field | Required | Description |
39213919| :- | :- | :- |
39223920| `type` | yes | Must be `"prompt"` |
3923| `prompt` | yes | The prompt text to send to the LLM. U
3921| `prompt` | yes | The prompt text to send to the LLM. Use `$ARGUMENTS` as a placeholder for the hook input JSON. If `$ARGUMENTS`
self-hosted-environments-configuration Changed · +20 / -0 lines
#### Fix `Argument list too long` at session start
from line 85
8585* **Pass them through**: end the wrapper with `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"`, which forwards the file flags along with every other argument. Don't drop or rewrite them. If a session loses a prompt file flag, it runs without the instructions the control plane sent for it.
8686* **On a runner at v2.1.281 or later, a file flag you append replaces the server's, never adds to it**: each prompt file flag takes a single value and Claude Code keeps the last occurrence, so if you append `--append-system-prompt-file <path>` after `"$@"`, your file's contents replace the server's appended instructions. To add instructions on top of the server's, put them in the runner image's `CLAUDE.md`, which the runner [seeds into every session's user-level config](#how-each-session’s-config-is-assembled).
8787
88#### Fix `Argument list too long` at session start
89
90On Linux, if you join the control plane's prompt and your own text into one `--append-system-prompt` argument, the runner logs a line like this once the argument reaches 128 KB:
91
92```text theme={null}
93Session <id> finished: failed — reason: child exited 126: /opt/wrapper.sh: line 9: /usr/local/bin/claude: Argument list too long
94```
95
96Linux limits each single argument to 32 memory pages, or 128 KB with the usual 4 KB pages. The figure from `getconf ARG_MAX`, often 2 MB, is a separate limit on all arguments and the environment together.
97
98On Claude Code v2.1.283 or later, leave the file flags in `"$@"` and pass only your own text as `--append-system-prompt`. Claude Code [uses both](https://code.claude.com/docs/en/cli-reference.md#system-prompt-flags), the control plane's prompt first and then your own text:
99
100```bash theme={null}
101exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@" --append-system-prompt "$(cat /opt/team-instructions.md)"
102```
103
104On Linux, if your own text reaches 128 KB, move it to the runner image's `CLAUDE.md`, because it's still one argument.
105
106On v2.1.281 or v2.1.282, that command exits with `Cannot use both --append-system-prompt and --append-system-prompt-file`. On earlier versions, your text replaces the control plane's prompt with no error. On any of them, update first, or move your own text to `CLAUDE.md`.
107
88108### Provision credentials scoped to the session creator
89109
90110Use the `decode-token` subcommand to read claims from the session JWT. It reads the token from an argument, from `CLAUDE_CODE_SESSION_ACCESS_TOKEN`, or from stdin, in that order; see [Verify the token inside the session](https://code.claude.com/docs/en/self-hosted-environments-identity.md#verify-the-token-inside-the-session) for what it checks. The example below decodes the creator identity, exchanges it for short-lived AWS credentials, and execs into Claude Code:
self-hosted-environments-reference Changed · +5 / -5 lines
from line 250
250250 annotations:
251251 summary: "Runners are running mixed versions"
252252 - alert: ClaudeRunnerInitErrorsHigh
253 expr: increase(claude_code_self_hosted_runner_session_init_errors_total[10m]) > 3
253 expr: sum by (namespace) (increase(claude_code_self_hosted_runner_session_init_errors_total[10m])) > 3
254254 for: 5m
255255 labels: {severity: warning}
256256 annotations:
257 summary: "Runner {{ $labels.pod }}: >3 session init failures in 10m (checkout hook / git / token / pre-init crash)"
257 summary: "Sessions are failing before init (checkout hook / git / token / pre-init crash)"
258258 - alert: ClaudeRunnerPollErrors
259259 expr: sum by (pod) (rate(claude_code_self_hosted_runner_poll_errors_total[5m])) > 0
260260 for: 2m
from line 262
262262 annotations:
263263 summary: "Runner {{ $labels.pod }}: PollWork failing ({{ $value | humanize }}/s over 5m)"
264264 - alert: ClaudeRunnerSessionStartHookErrors
265 expr: increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m]) > 3
265 expr: sum by (namespace) (increase(claude_code_self_hosted_runner_session_start_hook_errors_total[10m])) > 3
266266 for: 5m
267267 labels: {severity: warning}
268268 annotations:
269 summary: "Runner {{ $labels.pod }}: >3 SessionStart hook failures in 10m"
269 summary: "SessionStart hooks are failing"
270270
271271 - name: claude-code-self-hosted-orchestrator
272272 rules:
from line 283
283283 annotations:
284284 summary: "Orchestrator {{ $labels.pod }} has not polled in >90s (poll loop waits on hook execution)"
285285 - alert: ClaudeOrchestratorCircuitBroken
286 expr: claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions > 0
286 expr: max by (namespace) (claude_code_self_hosted_orchestrator_queue_circuit_broken_sessions and on (instance) max_over_time(claude_code_self_hosted_orchestrator_connected[2m]) == 1) > 0
287287 for: 1m
288288 labels: {severity: critical}
289289 annotations:
claude-tag Changed · +1 / -1 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.
plugins/mods/troubleshoot Changed · +1 / -1 lines
from line 102
102102
103103Code in the hooks module is nested too deeply, or its chain of imports is too long, for Claude Code to load it. The line starts with the mod's name and `hooks module did not load:`, then gives a file's name and this reason.
104104
105Look through that file and the files reached through its imports for the most deeply nested part and rewrite it to nest less, or shorten the chain of imports. If you installed the mod and didn't write it, ask its author to.
105In that file and the files its imports reach, find the most deeply nested code and rewrite it to nest less, or shorten the chain of imports. If you didn't write the mod, ask its author to fix it.
106106
107107### `the parser stopped` or `the engine ran out of stack loading the file`
108108
settings-reference Changed · +2 / -2 lines
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 3466
34663466
34673467Hostname matching is case-insensitive and treats `hooks.example.com.`, with the trailing dot that marks a fully qualified domain name, the same as `hooks.example.com`, which is how DNS treats them. The allowlist applies to hooks from every source, including managed settings.
34683468
3469In the Agent SDK's `managedSettings` option, Claude Code ignores this key when its list has entries, so pass the list in the SDK's `settings` option instead. See [what each value does in parent settings](https://code.claude.com/docs/en/claude-apps-gateway#how-hook-and-skill-keys-in-parent-settings-take-effect).
3469In the Agent SDK's `managedSettings` option, Claude Code ignores a list with entries, so pass it in the SDK's [`settings` option](https://code.claude.com/docs/en/agent-sdk/typescript#options) instead. See [what an empty list does in parent settings](https://code.claude.com/docs/en/claude-apps-gateway#how-hook-and-skill-keys-in-parent-settings-take-effect).
34703470
34713471### `allowManagedHooksOnly`
34723472
from line 3476
34763476* **Type**: Boolean
34773477 * `true`: only managed hooks run, plus Agent SDK hooks and hooks from plugins your managed settings force-enable. See [What runs under `allowManagedHooksOnly`](#what-runs-under-allowmanagedhooksonly)
34783478 * `false`: hooks from every settings scope and plugin run
3479* **Default**: unset, so hooks from every settings scope and plugin run
3480
3481```json managed-settings.json theme=
3479* **Default**: unset, so hooks from every settings scope and pl
ultrareview Changed · +2 / -2 lines
from line 172
172172The subcommand exits with one of three codes:
173173
174174* **0**: the review completed, with or without findings
175* **1**: the review failed to launch or was stopped before it finished, the cloud session errored, or the timeout elapsed. The code is also 1 when the [folder isn't trusted](#trust-the-folder-before-the-review-runs), including when you answer `n` or press Ctrl-C at the trust question.
175* **1**: the review failed to launch or was stopped before it finished, the cloud session errored, or the timeout elapsed. The code is also 1 when the [folder isn't trusted](#trust-the-folder-before-the-review-runs), including when you answer `n`, press Enter, or press Ctrl-C at the trust question.
176176* **130**: you pressed Ctrl-C while the subcommand was launching the review, waiting for the findings, or sending the `--post` comment, rather than at the trust question
177177
178178If the subcommand exits before the findings arrive, they never reach your terminal. The review may still be running in the cloud. Running the subcommand again starts a new review rather than resuming that one, and the new review [uses a free run or bills as usage credits](#pricing-and-free-runs).
from line 194
194194claude ultrareview 1234 --trust-workspace
195195```
196196
197To review an untrusted pull request, run `claude ultrareview <PR number> --trust-workspace` from a branch you trust. Unlike `y`, the flag saves nothing. The PR is [cloned in the cloud](#review-a-pull-request), so you don't need its branch locally.
197To review an untrusted pull request, run `claude ultrareview <PR number> --trust-workspace` from a branch you trust. The PR is [cloned in the cloud](#review-a-pull-request), so you don't need its branch locally.
198198
199199## How ultrareview compares to /code-review
200200