One read of Claude Code CLIclaude-code-20261027T203701Z
7 pages moved out of 228 read.
Pages moved
7
significant first
Pages read
228
in this capture
Captured
20:37 UTC
Corpus hash
90cc09798049
corpus-hash
What this read moved
1-7 of 7changelog Changed · +55 / -0 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 6
66
77Run `claude --version` to check your installed version.
88
9**2.1.312**
10
11October 27, 2026
12
13**Added**
14
15* Added `oidc.user_id_claim` to the Claude apps gateway, to identify people by an id\_token claim other than `sub`, such as Microsoft Entra ID's `oid`
16* Added click to send: in fullscreen, clicking the "to send now" hint under a queued message sends it right away, as its key does
17* \[Cloud sessions] Added an effort level to the model picker when you create or edit a routine that runs in the cloud
18* \[Cloud sessions] Added a Bash editor with colors, line numbers and a Copy button to the setup script box in cloud environment settings
19
20**Changed**
21
22* Changed Bedrock, Vertex, Foundry and Mantle to use the shorter system prompt for model names Claude Code doesn't recognize, such as custom deployment names and inference profile ARNs, even when they front Sonnet or Haiku; set `CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT=0` to keep the full prompt
23* Changed automatic model switches after a flagged message to also cover model names Claude Code doesn't recognize, such as custom deployment names; set `CLAUDE_CODE_DISABLE_REFUSAL_FALLBACK=1` to turn them off
24* Changed usage limit messages to call the 5-hour window the "5-hour limit" instead of the "session limit"
25* Changed cloud sessions started from the CLI to get their names and branch names from the server
26* Changed prompt and agent hooks to run at most 24 at a time per session, sub-agents included, plus at most 12 that have waited longer than their event's timeout; a `timeout` under 1 second now counts as 1 second
27* Changed a subagent's `autoCompactWindow` to lower the window set by `CLAUDE_CODE_AUTO_COMPACT_WINDOW`, where it had no effect before; it still never raises that window
28* Changed OpenTelemetry `mcp_server.name` to report the real name of fixed-URL remote MCP servers declared by plugins from the official Anthropic marketplace, instead of `custom`
29* Changed Claude Code to stop sending the `claude_code.safety_event` OpenTelemetry event
30* \[VSCode] Changed usage limit resets to show a clock time ("Resets at 3:10 PM") and to say "5-hour limit"
31
32**Improved**
33
34* Improved the prompt's effort indicator: a change made mid-task now says it may wait for your next message, and the note clears when it no longer applies
35* Improved WebFetch errors in cloud sessions: a host that does not resolve is now explained as possibly outside the allowed network domains, so Claude names the host to allow
36* \[Cloud sessions] Improved the step shown when Claude adds a repository to a cloud session: opening it now shows a short table of what happened instead of raw JSON
37* \[Claude Tag] Improved Claude Tag's retry notice in Slack to name the model in use, or say rate limits were hit, instead of a generic API error
38
39**22 bug fixes**
40
41* Fixed managed settings and organization policy not being fetched for the rest of the session after signing in from the VS Code extension
42* Fixed Claude overwriting a very large CLAUDE.md, rules file or @-included file in a subdirectory after seeing only its start; Write now asks Claude to read it all or edit in place
43* Fixed per-directory and `paths:` skills not being found after a Bash `cd` deeper into a git repository
44* Fixed a rare case where the first reply after resuming a session in the terminal could be missing the next time the session was resumed
45* Fixed a command with an invalid name stopping all commands from loading, which could leave `claude -p` with no output
46* Fixed the Read tool sometimes failing on PDF pages with "pdftoppm failed: Could not write image" when the clean-up of old session files ran at the same time
47* Fixed the spinner, OpenTelemetry `effort` values and transcripts naming a newly picked effort level during a task before the model applied it; they now show the level in force
48* Fixed the `/model` and `/effort` cache warning saying the re-read waits for your next message; a change made while Claude is working can trigger it sooner
49* Fixed some sessions showing as waiting on you when the last message only mentioned items waiting on you mid-sentence
50* Fixed agent view restoring input text on the next launch after it was cleared with Ctrl+C just before exiting
51* Fixed agent view reopening in shell mode after exiting with Ctrl+D from an empty `!` input
52* Fixed vim mode `d`, `c` and `y` with a `gj` or `gk` count larger than the lines left deleting or copying text; like Vim, they now only move the cursor
53* Fixed `/verify` showing a long description meant for Claude in `/help` and the `/` command menu instead of a short one
54* \[VSCode] Fixed sessions ending on a bare exit code when your organization's settings couldn't be loaded or were refused at startup; the tab now says why and offers Retry or Sign in again
55* \[Cloud sessions] Fixed resending an unchanged message after a failed send in a cloud session sometimes running it twice
56* \[Cloud sessions] Fixed a failed cloud environment creation showing its error only as a toast outside the open dialog; it now appears inside the dialog
57* \[Cloud sessions] Fixed Edit in a routine's menu on the Routines page going to the routine's page without opening its edit dialog
58* \[Remote Control] Fixed an unarchived Remote Control session showing as working until a computer reconnected; it now shows as idle
59* \[Claude Tag] Fixed a Claude Tag channel's on/off switch and agent settings falling back to workspace defaults when an older private Slack channel goes public and gets a new ID
60* \[Claude Tag] Fixed Claude in Slack not replying in channels whose environment has network access set to None
61* \[Claude Tag] Fixed Claude in Slack sometimes posting a file in the wrong thread when it was answering in another thread of the same channel
62* \[Code Review] Fixed Code Review reviewing an outdated commit, or none at all, when GitHub delivered a push event late; it now reviews the pull request's current commit
63
964**2.1.311**
1065
1166October 26, 2026
from line 2114
20592114* Fixed the Artifact tool so that publishing a page no longer lets Claude overwrite its source file without re-reading it when Claude's earlier read was cut short or the file had changed since
20602115* Fixed auto mode skipping its classifier for Artifact tool asset uploads and reads of someone else's artifact when you had approved that artifact earlier in another permission mode
20612116* Fixed a misleading "core.worktree is set" error from `/ultrareview` when the project folder briefly could not be read
2062* Fixed `/ultrareview` on macOS and Linux failing to upload the working tree from a git worktree whose per-worktree config sets `core.longpaths`
2063* Fixed the Artifact tool sometimes reporting a publish as a conflict with another session after retrying a temporary server error, when the first attempt had actually succeeded
2064* Fixed `/ultrareview` uploads including uncommitted changes to credential files whose name has a colon before the extension, such as `server:8443.key`
2065* Fixed a rare auth failure when two sessions recover a login refresh lock left by a crashed process at the same time
2066* Fixed the PowerShell tool's permission check skipping deny and ask rules, and caching that failure for later checks, when its command parser failed to start (for example when the machine was out of memory)
2067* Fixed `/ultrareview` uploads on macOS and Linux running slowly on some unusual file names, and their credential-file check missing file or folder names with many backup or editor marks
2068* Fixed a cancelled shell command or hook still starting, and running to its end, when the cancel arrived while it was being set up
2069* Fixed vim mode: after editing in the external editor (Ctrl+G), `x` or `r` in NORMAL mode no longer breaks a pasted-text placeholder at the end of the prompt
2070* Fixed responses blocked by the API's output content filter being re-sent and retried, sometimes for minutes, instead of showing the filter's error right away
2071* Fixed plugins silently skipping a bundled `.mcpb` MCP server that still needs configuration: `/plugin`, the install message and `claude plugin install` now say so and point to Configure
2072* Fixed compacting or resuming a session failing, opening without its history, or crashing when its saved transcript holds a compaction marker or loop wakeup entry with missing or malformed fields
2073* WSL: Fixed `/ultrareview` refusing to upload a checkout on a Linux volume when a changed file's name has a colon or ends in a dot or space
2074* Fixed `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` re-running a turn that had ended at `--max-turns`
2075* Fixed sign-in that could wait forever after the browser showed success
2076* Windows: Fixed `/ultrareview` uploading a linked worktree of a repository rooted at your home folder in some cases
2077* Fixed cloud sessions reporting the uploads folder as missing before any file had been uploaded
2078* Fixed a reply sent from `claude agents` to a background session waiting on a permission prompt sometimes approving the pending command
2079* Fixed `claude attach`, `logs`, `stop`, `respawn` and `rm` starting a new session with the command name as its prompt when options came before it, such as from a shell alias
2080* Fixed `claude mcp list` leaving out WebSocket (`ws`) MCP servers; each is now listed with its URL and health status
2081* Fixed `claude mcp get` showing no Type, Command, Args, or Environment for stdio servers whose config entry omits the `type` field
2082* Fixed `.claude/settings.local.json` allow rules being held back outside a git repository when git's trace2 output is configured
2083* Fixed the `/claude-api` eval runner scaffold and report builder writing through a symlink or hard link planted at an output file
2084* Fixed the `/claude-api` eval runner scaffold counting responses cut off at `max_tokens` in the score averages; they are now marked truncated and counted separately
2085* Fixed ` ` showing as literal text in the terminal when a reply uses it to indent text, such as row labels in a markdown table
2086* Fixed a brief freeze (up to a second) partway through long sessions outside fullscreen mode, which came back after `/clear` or `/compact`
2087* Fixed an approved Edit never going through when its target is a device, such as a file symlinked to /dev/null, and the approval came from the IDE diff view or changed the edit
2088* Fixed a failing API request being retried up to 21 times when streaming kept failing; the non-streaming fallback now shares the request's retry budget instead of getting a fresh set of retries
2089* \[VSCode] Fixed pressing Enter after typing a slash command running an unrelated menu item picked by fuzzy match, or doing nothing
2090* \[VSCode] Fixed an open agent transcript losing the agent's newer messages during a long session
2091* \[VSCode] Fixed a message that quotes a Claude Code or IDE tag losing the rest of its text in the chat
2092* \[VSCode] Fixed a message sent while Claude was working disappearing from the conversation after the session was reopened
2093* \[VSCode] Fixed the session list's Web tab showing the previous account's sessions after an account switch
2094* \[VSCode] Fixed restored tabs re-running an interrupted turn when VS Code was started with `CLAUDE_CODE_RESUME_INTERRUPTED_TURN` set, even with Continue After Reload off
2095* \[VSCode] Fixed Escape stopping the running turn instead of closing the command menu after clicking one of its rows
2096* \[VSCode] Fixed opening Past conversations replacing a live conversation with its saved copy
2097* \[VSCode] Fixed a Claude tab reloaded after an extension restart staying blank instead of saying how to recover
2098* \[VSCode] Fixed opening a conversation that is already open in another window or app starting a second copy of it without warning; it now asks first
2099* \[VSCode] Fixed a hook's reason for blocking or stopping a prompt disappearing after a window reload
2100* \[VSCode] Fixed tabs stuck on a conversation that can't be resumed: the error now says so and offers to start a new conversation
2101* \[VSCode] Fixed every file Read, Write and Edit stalling for ten minutes and then being skipped when the editor stops responding to the extension's automatic save before the tool runs
2102* \[VSCode] Fixed the agent map labeling a sub-agent with the session's model instead of the model it actually ran on (e.g. under `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` or an agent's own `model`)
2103* \[VSCode] Fixed uninstalling a plugin from the
2117* Fixed `/ultrar
plugins/mods/events Changed · +13 / -10 lines
from line 311
311311
312312### Change or refuse a settings read
313313
314A `settings.read` hook runs on a mod's read and on Claude Code's own read:
314Use a `settings.read` hook to change or refuse a settings read, either a mod's or Claude Code's own:
315315
316316* **A mod's read**: a mod calls [`$.settings.read`](https://code.claude.com/docs/en/plugins/mods/api#read-one-source-or-one-key).
317* **Claude Code's own read**: Claude Code builds the session's merged settings. This read repeats when settings or the loaded plugins change.
317* **Claude Code's own read**: your hook first runs when Claude Code merges the session's settings, after the session's mods have loaded. Your hook runs again when settings or loaded plugins change.
318318
319Before you rely on either read, check the guard and your version:
319Check which mods get this event and your Claude Code version:
320320
321321* **The built-in guard**: with managed settings, or with a Team or Enterprise [`/login`](https://code.claude.com/docs/en/authentication#authentication-precedence) as the session's credential, the [built-in guard](https://code.claude.com/docs/en/plugins/mods/admin.md#know-what-happens-by-default) can skip this hook in a mod you install or load with `--plugin-dir`. To check, search the [debug log](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#read-the-debug-log) for `settings.read bypassed by cc-plugin-sec-default`. If a line with that text names your mod, ask your organization's administrator to [install the mod as one of the organization's mods](https://code.claude.com/docs/en/plugins/mods/admin.md#install-your-organizations-mods).
322322* **The version**: the event firing on Claude Code's own read, and the `e.layers` field, require Claude Code v2.1.304 or later.
from line 332
332332
333333#### Tell Claude Code's own read from a mod's read
334334
335On [Claude Code's own read](#settings-read-hook), [`next.origin`](https://code.claude.com/docs/en/plugins/mods/reference#the-hook-function) is `{ plugin: 'engine', tier: 'core' }`, and on a mod's read `next.origin.plugin` is the calling mod's name.
335Check [`next.origin`](https://code.claude.com/docs/en/plugins/mods/reference#the-hook-function):
336336
337* **Claude Code's own read**: `{ plugin: 'engine', tier: 'core' }`
338* **A mod's read**: `plugin` is the calling mod's name
339
337340#### What a `settings.read` hook can return
338341
339Your hook can return [`next(e)`](https://code.claude.com/docs/en/plugins/mods/reference#the-hook-function)'s result unchanged, a `{ value }` of its own, or `{ deny: reason }`. On [Claude Code's own read](#settings-read-hook) and a mod's read, a `{ value }` replaces what the read gives and `{ deny: reason }` refuses the read:
342Return [`next(e)`](#settings-read-next)'s result unchanged to leave the read as it is, or return one of these:
340343
341| Return | On Claude Code's own read | On a mod's read |
344| Return | On [Claude Code's own read](#settings-read-hook) | On a mod's read |
342345| :- | :- | :- |
343| `{ value }` | For each key you change, what you return replaces that key's whole value in the session's merged settings, if it [fits the key's schema](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#settings-read-key-refused) | That mod's call resolves to your `value`, or to the `key` it asked for taken from your `value`, so return a whole object and not an array |
346| `{ value }` | For each key changed, you replace its whole value in the session's merged settings, if yours [fits the key's schema](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#settings-read-key-refused) | That mod's call resolves to your `value`, or to the `key` it asked for taken from your `value`, so return a whole object and not an array |
344347| `{ deny: reason }` | The session keeps the settings as they were merged before any hook answered, and the [debug log records your `reason`](https://code.claude.com/docs/en/plugins/mods/troubleshoot#settings-read-refused) | That mod's call rejects with `<calling mod>: $.settings.read: <reason>` |
345348
346349On Claude Code's own read, build your `{ value }` from [`next(e)`'s `value`](#settings-read-next), since a key you leave out is unset. Where Claude Code reads a key such as `env` from each source separately, changing it in your `value` [has no effect](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#settings-read-key-no-effect).
from line 372
369372})
370373```
371374
372On Claude Code's own read, if your hook returns a value outside the key's schema, such as a string, that key alone keeps the value merged before any hook answered. The debug log then says [`the answer for <key> is no value the key can hold`](https://code.claude.com/docs/en/plugins/mods/troubleshoot#settings-read-key-refused). If your value fits and the key still doesn't change, see [why a returned key has no effect](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#settings-read-key-no-effect).
375On Claude Code's own read, if your hook returns a value outside the key's schema, such as a string, that key alone keeps the value merged before any hook answered. The debug log then says [`the answer for <key> is no value the key can hold`](https://code.claude.com/docs/en/plugins/mods/troubleshoot#settings-read-key-refused). If your value fits and the key still doesn't change, see [why a key doesn't take effect](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#settings-read-key-no-effect).
373376
374377### Handle the settings hook events
375378
plugins/mods/gallery Changed · +8 / -8 lines
from line 242
242242
243243### `Input`
244244
245An `Input` is a text field that runs `onSubmit` when the user presses Enter. It holds one line unless you give it `rows`:
245An `Input` is a text field that holds one line by default and runs `onSubmit` when the user presses Enter:
246246
247247```javascript theme={null}
248248Input({
from line 267
267267
268268
269269
270Add `rows` for a field that holds several lines, such as a note or a commit message:
270Set `rows` to 2 or more for a field that holds several lines, such as a note or a commit message:
271271
272272```javascript theme={null}
273273Input({
from line 279
279279})
280280```
281281
282Whatever the field holds, it takes that many rows, up to the height of the pane or band it's drawn in. Longer text scrolls inside it.
282The terminal and the Desktop app draw the rows. In the VS Code extension, the field holds one line. `rows` requires Claude Code v2.1.301 or later. On earlier versions the field holds one line.
283283
284* Enter still submits. In the terminal, the user starts a new line by typing a backslash and then pressing Enter, or by pressing Shift+Enter where [the terminal emulator supports it](https://code.claude.com/docs/en/terminal-config.md#enter-multiline-prompts). Those are the same keys as in the prompt.
285* Up and Down move between the field's rows. From its first and last row they move to the control before or after.
286* `onSubmit` and `onInput` receive the whole text with its lines joined by `\n`.
284The field takes up the number of rows you set, even when it's empty, up to the height of the pane or band it's drawn in. While the field has focus, longer text scrolls inside it.
287285
288The terminal and the Desktop app draw the rows. In the VS Code extension, the field holds one line.
286* In the terminal, Enter still submits. There, the user starts a new line by typing a backslash and then pressing Enter, or by pressing Shift+Enter where [the terminal emulator supports it](https://code.claude.com/docs/en/terminal-config.md#enter-multiline-prompts). Those are the same keys as in the prompt.
287* In the terminal, Up and Down move between the field's rows. From its first and last row they move to the control before or after.
288* `onSubmit` and `onInput` receive the whole text with its lines joined by `\n`.
289289
290290### `Select`
291291
plugins/mods/reference Changed · +23 / -10 lines
from line 106
106106
107107### Commands and configuration
108108
109Command and configuration events fire when a command runs or is listed, when a `/config` row is shown or changed, and on a settings read:
110
111109| Event | Fires when | A hook can return |
112110| :- | :- | :- |
113111| [`command.run`](https://code.claude.com/docs/en/plugins/mods/api#add-a-command) | A command is about to run | `{ text }`, `{}`, or `next(e)` |
from line 112
114112| `command.describe` | Once for each command, for the command list | `{ description, argumentHint, isHidden }` |
115113| `config.set` | A `/config` row is about to change | `next({ ...e, value })` or `{ deny: reason }` |
116114| `config.describe` | Once for each `/config` row | `{ label, description, isHidden }` |
117| [`settings.read`](https://code.claude.com/docs/en/plugins/mods/events#settings-read-hook) | A mod calls [`$.settings.read`](https://code.claude.com/docs/en/plugins/mods/api#reach-files-processes-and-the-network), or Claude Code builds the session's merged settings | `next(e)`, `{ value }`, or `{ deny: reason }` |
115| [`settings.read`](https://code.claude.com/docs/en/plugins/mods/events#settings-read-hook) | A mod calls [`$.settings.read`](https://code.claude.com/docs/en/plugins/mods/api#reach-files-processes-and-the-network), or Claude Code builds the session's merged settings. Requires Claude Code v2.1.304 or later on Claude Code's own read and for `e.layers` | `next(e)`, `{ value }`, or `{ deny: reason }` |
118116
119117#### `e.layers` and `e.source` on `settings.read`
120118
121119* **`e.layers`**: one `{ source, settings }` object for each source in use that holds settings, lowest [precedence](https://code.claude.com/docs/en/settings.md#settings-precedence) first. See [What a `settings.read` hook receives](https://code.claude.com/docs/en/plugins/mods/events#settings-read-receives).
122* **`e.source`**: the one source a mod asked for, as in `$.settings.read({ source: 'policy' })`. Absent on Claude Code's own read and on any other read of the merged settings
120* **`e.source`**: the one source a mod asked for, as in `$.settings.read({ source: 'policy' })`. Absent on Claude Code's own read and on a read of the merged settings
123121
124On `settings.read`, the event firing on Claude Code's own read and the `e.layers` field require Claude Code v2.1.304 or later. For when the hook runs and what the hook can return, with an example, see [Change or refuse a settings read](https://code.claude.com/docs/en/plugins/mods/events.md#settings-read-hook).
125
126122### Turns
127123
128124Turn events follow one answer from start to finish, including each request to the model within it:
from line 263
267263| :- | :- | :-: | :-: | :-: |
268264| [`Box`](https://code.claude.com/docs/en/plugins/mods/interface#build-a-tree-from-elements) | `key`, flex layout, [`gap`, `padding`, `margin`](#box-spacing-steps), `width`, `height`, `minWidth`, `minHeight`, [`borderStyle`](#box-border-styles), `borderColor`, `borderDimColor`, `backgroundColor`, `position`, `top`, `left`, `right`, `bottom`, `overflow`, `display`, `hover` | ✓ | ✓ | ✓ |
269265| [`Text`](https://code.claude.com/docs/en/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, [`bold`](#text-bold), `italic`, `underline`, `strikethrough`, `dimColor`, `inverse`, `wrap`, [`size`, `weight`, `mono`, `tabular`](#text-typography), `hover` | ✓ | ✓ | ✓ |
270| [`Button`](https://code.claude.com/docs/en/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action`, `hover` | ✓ | ✓ | ✓ |
266| [`Button`](https://code.claude.com/docs/en/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `children`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action`, `variant`, `role`, `hover` | ✓ | ✓ | ✓ |
271267| [`Link`](https://code.claude.com/docs/en/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. See [Limits](#limits). | ✓ | ✓ | ✓ |
272268| [`Code`](https://code.claude.com/docs/en/plugins/mods/gallery#show-code-and-changes) | `source`, `language`, `path`, `startLine`, `format`, `wrap` | ✓ | ✓ | ✓ |
273269| `Markdown` | `text`, `key`, `dimColor`, `onLinkPress`, `pressableLinks` | ✓ | ✓ | ✓ |
from line 280
284280* **Digit hotkeys on the band**: a digit `hotkey` on a button in the band also fires when the user types that digit alone into an empty prompt and pauses
285281* **A collapsed band**: while the band is [collapsed](https://code.claude.com/docs/en/plugins/mods/interface.md#when-the-user-collapses-the-band), neither an `action` binding nor a hotkey presses a button in it
286282* **Two buttons on one hotkey**: when two buttons in one drawing name the same `hotkey`, the later one gets it
283* **`variant`**: `primary` or `secondary`, and any other value throws. In the terminal, a `primary` button draws in the accent color unless it's `plain`.
284* **`role`**: `dismiss` marks a close button, and any other value throws. Do the closing in your `onPress`. In a band that holds text and a row of buttons, the Desktop app can draw the row's first `dismiss` button as its own close control. The terminal draws the button as it would without `role`.
287285
286A `Button` can hold `children` in place of a `label`:
287
288* **What children can be**: strings and `Text` elements, such as a name followed by a dim detail or a colored chip. Claude Code refuses any other element inside a `Button`.
289* **Naming the button**: the `label` names the button and defaults to the text of its children. Give a button with children other than one string a `key` or a `label`.
290* **In the terminal**: the children draw where the label would be, and a press anywhere on them counts as one press, so you can make each row of a list a single button
291* **In the Desktop app and the VS Code extension**: the button draws its `label`
292
293> [!NOTE]
294>
295> A `Button` with children other than a single string requires Claude Code v2.1.295 or later.
296
288297`autoFocus` accepts only `true` on any control, so omit the prop to leave it off.
289298
290299The VS Code extension ignores some element props and draws the element as if you had left them out:
from line 300
291300
292301* **`Box`**: `position` with its `top`, `left`, `right`, and `bottom`, `alignSelf`, `borderDimColor`, and `hover`
293302* **`Text`**: `size`, `mono`, `tabular`, and `hover`
294* **`Button`**: `hotkey`, `plain`, `autoFocus`, `action`, and `hover`, so the user presses a button there with a click, or with Enter once it has focus
303* **`Button`**: `hotkey`, `plain`, `autoFocus`, `action`, and `hover`, so the user presses a button there with a click, or with Enter once it has focus. The extension also ignores `variant` and `role`.
295304* **`Code`**: `language`, `path`, `startLine`, `format`, and `wrap`, so code draws without colors or line numbers, and a `format: 'diff'` block shows the diff's raw text
296* **`Input` and `Select`**: `autoFocus`
305* **`Input` and `Select`**: `autoFocus`, and `rows` on an `Input`
297306* **`Svg`**: `isInteractive`
298307
299308### `Box` border styles
from line 369
360369| A `.catch` handler's execution time | 1 second |
361370| All `session.end` hooks together | As long as the [SessionEnd hook budget](https://code.claude.com/docs/en/hooks.md#sessionend-input), 1.5 seconds unless you change it, counted from when your settings `SessionEnd` hooks finish |
362371| `$.process.run` timeout | 30 seconds by default, 10 minutes at most |
372| `$.process.run` `stdout` and `stderr` | 4 MiB each. `isStdoutTruncated` or `isStderrTruncated` is `true` when one was cut. |
363373| `$.model.complete` `maxTokens` | 1024 by default, up to 64,000 or the model's output limit |
364374| `$.fs.read` and `$.fs.write` | 4 MiB for one file |
365375| A `$.http.fetch` request body | 4 MiB, counted in characters. A call with a larger body rejects. |
from line 387
377387| `$.store` | 4 MiB of JSON in total |
378388| `$.session.messages()` | The newest 4,096 entries |
379389| `$.ui.invalidate('ui.render')` redraws | Throttled to 10 a second, or 30 in the terminal for the visible pane, the expanded band, and the hint line under the prompt. Calls that come sooner are coalesced. |
380| `$.ui.toast` | Shown for 4 seconds unless you pass `{ timeoutMs }` |
390| `$.ui.toast` | Shown for 4 seconds unless you pass `{ timeoutMs }`. In the [classic renderer](https://code.claude.com/docs/en/fullscreen.md#enable-fullscreen-rendering), a mod's newer toast can [take the place of its older one](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear) that's showing or waiting to show. |
381391| A pane opened without the user asking | Placed from 144 terminal columns, 110 after they've opened it once |
392| Nesting depth of a mods API call's arguments | 28,000 levels. Past that, the call rejects with a message ending `nesting deeper than 28000 levels is not supported`. Requires Claude Code v2.1.299 or later. |
393| Nesting depth of a changed event passed to `next`, outside [async generator hooks](#events) such as one on `turn.step` | 28,000 levels. Past that, `next` rejects with a message ending `nesting deeper than 28000 levels is not supported`. Requires Claude Code v2.1.299 or later. |
394| Nesting depth of a hook's return value, outside `ui.render`, `ui.resolve`, and async generator hooks | 28,000 levels. Past that, the hook's result is refused, and [the notice that reports it](https://code.claude.com/docs/en/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing) includes `nesting deeper than 28000 levels is not supported`. Requires Claude Code v2.1.299 or later. |
382395| Scopes, such as functions, blocks, and loops, nested inside one another in one file of a hooks module | 2,000 |
383396| Command, tool, subagent type, and pane names | Letters, digits, `_`, and `-`, up to 64 characters |
384397| One `claude plugin test` test | 5 seconds unless the test sets `timeoutMs` |
plugins/mods/troubleshoot Changed · +18 / -11 lines
from line 337
337337
338338### A key your `settings.read` hook returns doesn't take effect
339339
340Returned `env` entries don't become environment variables. Returned `allow`, `ask`, and `deny` rules aren't checked on tool calls. Set those in a [settings file](https://code.claude.com/docs/en/settings.md), or call [`$.env.set`](https://code.claude.com/docs/en/plugins/mods/api#reach-files-processes-and-the-network) for environment variables.
340If you return permission rules or `env` on [Claude Code's own read](https://code.claude.com/docs/en/plugins/mods/events.md#settings-read-hook), the rules aren't checked on tool calls and the `env` entries don't become environment variables. Use a [settings file](https://code.claude.com/docs/en/settings.md) for both, or [`$.env.set`](https://code.claude.com/docs/en/plugins/mods/api#reach-files-processes-and-the-network) for `env`.
341341
342342For another key, check [which mods get `settings.read` and from which version](https://code.claude.com/docs/en/plugins/mods/events#settings-read-hook), then search the [debug log](#read-the-debug-log) for `settings.read` and look for one of these lines:
343343
from line 345
345345| :- | :- |
346346| `settings.read hook skipped`, after your mod's name | Your hook failed. [Fix the error the line reports](#hook-skipped). |
347347| `settings.read bypassed by cc-plugin-sec-default`, on a line that names your mod ahead of it | The [built-in guard](https://code.claude.com/docs/en/plugins/mods/admin.md#know-what-happens-by-default) skipped your hook. Ask your organization's administrator to [install the mod as one of the organization's mods](https://code.claude.com/docs/en/plugins/mods/admin.md#install-your-organizations-mods). |
348| `settings.read: the answer for <key> is no value the key can hold` | The returned value doesn't fit the key's schema. [Return one it allows](#settings-read-key-refused). |
348| `settings.read: the answer for <key> is no value the key can hold` | Claude Code refused the value a hook returned for that key. The hook may be yours or another mod's. Follow [the step for your case](#settings-read-key-refused). |
349349| `settings.read: the merge never settles for <key>` | The keys the line names keep the settings sources' values. Set them in a settings file. |
350| `answered settings.read without next()`, after a mod's name | Relevant only if that mod [runs before yours](https://code.claude.com/docs/en/plugins/mods/events.md#the-order-mods-run-in). Then your hook didn't run on that read. [Turn that mod off](https://code.claude.com/docs/en/plugins/mods/overview.md#turn-mods-on-or-off), or if your organization deployed it, ask its administrator to. |
351| `settings.read: refused to the engine` | The read was refused, so no hook's `{ value }` applied. [Find what refused it](#settings-read-refused). |
350| `answered settings.read without next()`, after a mod's name | Your hook is affected if the named mod [runs before yours](https://code.claude.com/docs/en/plugins/mods/events.md#the-order-mods-run-in). Then your hook didn't run on that read. [Turn that mod off](https://code.claude.com/docs/en/plugins/mods/overview.md#turn-mods-on-or-off), or if your organization deployed it, ask its administrator to. |
351| `settings.read: refused to the engine` | Your value didn't apply because Claude Code's own read was refused. [Find what refused it](#settings-read-refused). |
352352
353353If no line explains the key, check the mods that run before yours for a `settings.read` hook that [changes the key](https://code.claude.com/docs/en/plugins/mods/events.md#settings-read-example). Turn that mod off, or ask your organization's administrator to. If no hook does, set the key in a settings file.
354354
355355### `the answer for <key> is no value the key can hold`
356356
357This [debug log](#read-the-debug-log) line means Claude Code refused the value your [`settings.read`](https://code.claude.com/docs/en/plugins/mods/events#settings-read-hook) hook returned for the named key, and that key alone:
357This [debug log](#read-the-debug-log) line means Claude Code refused the value a [`settings.read`](https://code.claude.com/docs/en/plugins/mods/events#settings-read-hook) hook returned for the named key, and that key alone:
358358
359359```text theme={null}
360360settings.read: the answer for <key> is no value the key can hold; the settings' own value stands
361361```
362362
363The value you returned for the named key didn't fit that key's schema, for example by type or by range. Return a value that the key's [settings reference](https://code.claude.com/docs/en/settings-reference.md) entry allows. While your value doesn't fit, the key keeps the value merged from the settings sources before any hook answered. The line calls it the settings' own value.
363The value returned for the named key didn't fit that key's schema, for example by type or by range.
364364
365* **Your value doesn't fit the key's schema**: return one the key's [settings reference](https://code.claude.com/docs/en/settings-reference.md) entry allows.
366* **Your value fits**: the value that doesn't fit came from another mod's `settings.read` hook. To find that mod, follow [the steps to turn off mods one at a time](#settings-read-refused). Search each new log for this line instead of `refused to the engine`.
367
368While the value doesn't fit, the key keeps the value merged from the settings sources before any hook answered. The line calls it the settings' own value.
369
365370### `settings.read: refused to the engine`
366371
367This [debug log](#read-the-debug-log) line means [Claude Code's own read](https://code.claude.com/docs/en/plugins/mods/events.md#settings-read-hook) was refused, so no hook's `{ value }` applied, yours included. When a `settings.read` hook refuses that read with [`{ deny: reason }`](https://code.claude.com/docs/en/plugins/mods/events#settings-read-returns), the line carries that hook's reason:
372You see this line in the [debug log](#read-the-debug-log) when [Claude Code's own read](https://code.claude.com/docs/en/plugins/mods/events.md#settings-read-hook) is refused, and Claude Code drops every hook's value. When a `settings.read` hook refuses that read with [`{ deny: reason }`](https://code.claude.com/docs/en/plugins/mods/events#settings-read-returns), the line carries that hook's reason:
368373
369374```text theme={null}
370375settings.read: refused to the engine (engine: $.settings.read: <reason>); the settings' own values stand
371376```
372377
373Search your own hook's code for the `<reason>` text:
378Search your code for the reason in the parentheses:
374379
375380* **Your code has it**: your hook refused the read. Make it return `{ value }` when [`next.origin`](https://code.claude.com/docs/en/plugins/mods/events#settings-read-origin) shows Claude Code's own read.
376* **Your code doesn't have it**: [turn off](https://code.claude.com/docs/en/plugins/mods/overview.md#turn-mods-on-or-off) your other mods one at a time. After each, rerun this session's command from your shell with one `--debug-file` on a new path, and search that file for `refused to the engine`. If the line is there, turn off the next mod. If not, the last mod you turned off refused the read, so keep it off.
381* **Your code doesn't have it**: [turn off](https://code.claude.com/docs/en/plugins/mods/overview.md#turn-mods-on-or-off) your other mods one at a time. If your organization deployed a mod, ask its administrator to turn it off. After each:
382 1. Start the session from your shell with `claude --debug-file ./settings-read-2.log`, followed by the flags it started with. Use a new path each time.
383 2. Search that file for `refused to the engine`. If the line is there, turn off the next mod. If not, the last mod you turned off refused the read, so keep it off.
377384
378With no other mod left, use a [settings file](https://code.claude.com/docs/en/settings.md) for the keys your hook returns. Its values hold while the read is refused.
385If the line stays with no other mod left, set the keys your hook returns in a [settings file](https://code.claude.com/docs/en/settings.md). Its values hold while the read is refused.
379386
380387## Read the debug log
381388
errors 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/interface Changed · +2 / -2 lines
from line 417
417417Note: Type a note and press Enter
418418```
419419
420Add `rows` to let the field hold several lines. Enter still submits, and a backslash before Enter starts a new line, as does Shift+Enter where [the terminal supports it](https://code.claude.com/docs/en/terminal-config.md#enter-multiline-prompts). The gallery shows [a field with `rows`](https://code.claude.com/docs/en/plugins/mods/gallery#input).
420Set `rows` to 2 or more for [a field that holds several lines](https://code.claude.com/docs/en/plugins/mods/gallery.md#input).
421421
422422The [interface gallery](https://code.claude.com/docs/en/plugins/mods/gallery.md) has samples and screenshots of most elements. This table lists every element:
423423
from line 542
542542| Key | What it does |
543543| :- | :- |
544544| Tab | Moves to the next control |
545| Up and Down | Move between controls while your drawing fits. When the pane or band has more rows than it can show, they scroll it. In an `Input`, they [move between the field's rows](https://code.claude.com/docs/en/plugins/mods/gallery.md#input) first. |
545| Up and Down | Move between controls while your drawing fits. When the pane or band has more rows than it can show, they scroll it. In an `Input` in the terminal, they [move between the field's rows](https://code.claude.com/docs/en/plugins/mods/gallery.md#input), and from its first or last row they move to the control before or after it. |
546546| Enter | Presses the focused `Button`, submits the focused `Input`, or picks in a `Select` |
547547| A button's hotkey | Presses that button. While an `Input` has the focus, every printable key goes to the field. |
548548| Page Up, Page Down, Home, and End | Scroll your pane or band when it has more rows than it can show |