docs: Claude Code v2.1.310 - plugin marketplaces fetch only the git submodules plugins use, fast mode cache costs reworked, Claude Tag runners need python3

content/en/docs/claude-code/agent-sdk/typescript.md

@@ -1830,13 +1830,17 @@ Claude Code omits the field in these cases:
 * Turns that answer no message of yours, or answer a message you sent without a `uuid`
 * Results that answer no message you sent, such as the zeroed result after a crashed worker process
 
+When a [`UserPromptSubmit`](https://code.claude.com/docs/en/hooks#userpromptsubmit) hook blocks a message that starts its own turn, or stops it with `continue: false`, you still get a result for that message. It's a success result with `is_error: false` and `num_turns: 0`, its `result` is the [block message](https://code.claude.com/docs/en/hooks.md#what-a-blocked-prompt-leaves-behind) or [stop message](https://code.claude.com/docs/en/hooks.md#json-output), and it echoes the message's `uuid` under the same rules as any other result. The result has no `terminal_reason`, and nothing on it besides the `result` text says a hook ended the turn. A message that a hook blocks while another turn is running may get no result: see [`user_message_uuids`](#user_message_uuids).
+
 #### `user_message_uuids`
 
 The `uuid`s of every message you sent that Claude Code answered in this turn. When you send several messages close together, Claude Code can merge them into one turn, and `user_message_uuid` then names only the last of them. To match the reply to any of the merged messages, look for that message's `uuid` anywhere in this list. Requires Agent SDK v0.3.259 or later.
 
 Claude Code sets the list together with `user_message_uuid` on each reply frame that carries that field and on the result. For the full set of turn frames that echo the answered message's `uuid`, and the version each requires, see [`user_message_uuid`](#user_message_uuid). The list always contains `user_message_uuid` and holds at most 64 entries.
 
-When Claude Code picks up a regular message you sent while a turn was running, it adds that message's `uuid` to the result's list.
+When Claude Code picks up a regular message you sent while a turn was running, it adds that message's `uuid` to the result's list. When a [`UserPromptSubmit`](https://code.claude.com/docs/en/hooks#userpromptsubmit) hook blocks the message at pickup, Claude Code drops it instead: the message never reaches Claude and isn't kept for a later turn. You get no result for it, and its `uuid` appears in no result's list. If a hook can block messages, set a timeout on waiting for a result that lists a message you sent while a turn was running.
+
+That holds when the hook's output is a block alone. If the output sets `continue: false`, even beside `decision: "block"`, or the hook is a prompt hook that answers [`ok: false`](https://code.claude.com/docs/en/hooks#response-schema) without `continueOnBlock: true`, Claude Code stops the message instead of dropping it. The message waits for its own turn, you get a result for it, and its text stays in the conversation, so Claude sees it on the next turn.
 
 When a first reply or result carries `user_message_uuid` without the list, it came from an earlier Claude Code version, so fall back to the single field.
 

content/en/docs/claude-code/claude-apps-gateway-spend-limits.md

@@ -98,7 +98,7 @@ Each display needs a minimum Claude Code version on the developer's machine and
 
 The warnings and the percentage come from the `anthropic-ratelimit-unified-*` headers, which the gateway adds to each successful `/v1/messages` response for a developer who has a cap. The headers always describe the developer's own cap: the gateway strips the upstream provider's rate-limit headers, which describe your shared quota, and never forwards them.
 
-The spend a developer sees is the gateway's own [estimate](#how-requests-are-priced), the same figure it enforces the cap with, and not an amount from your provider's bill. Claude Code reads the dollar amounts with a separate request to the gateway. If you set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` on developers' machines, as [Compliance posture](https://code.claude.com/docs/en/claude-apps-gateway-deploy.md#compliance-posture) suggests, Claude Code skips that request. With that variable set, or with a gateway server older than v2.1.284, the bar and the status line stay percentage-only.
+The spend a developer sees is the gateway's own [estimate](#how-requests-are-priced), the same figure it enforces the cap with. It isn't an amount from your provider's bill. Claude Code reads the dollar amounts with a separate request to the gateway, which it sends even if you set `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` on developers' machines. Before v2.1.295, Claude Code skipped that request when the variable was set, and `/usage` and the status line showed the percentage and the reset date, with no dollar amounts.
 
 ## Admin API reference
 

content/en/docs/claude-code/fast-mode.md

@@ -80,7 +80,7 @@ Fast mode has higher per-token pricing than standard Opus:
 
 Fast mode pricing is flat across the full 1M token context window. For the standard Opus rate to compare against, see the [Claude pricing reference](https://platform.claude.com/docs/en/about-claude/pricing).
 
-The first time you enable fast mode in a conversation, you pay the full fast mode uncached input token price for the entire conversation context. The deeper into a conversation you are, the more this costs, so the charge is smallest when you enable fast mode at the start. The cost applies once per conversation, so toggling fast mode off and on again later doesn't repeat it. For the mechanism, see [how fast mode interacts with the prompt cache](https://code.claude.com/docs/en/prompt-caching.md#turning-on-fast-mode).
+The first time you enable fast mode in a conversation, you pay the full fast mode uncached input token price for the entire conversation context. The deeper into a conversation you are, the more this costs, so the charge is smallest when you enable fast mode at the start. Fast mode and standard speed keep [separate caches](https://code.claude.com/docs/en/prompt-caching.md#turning-on-fast-mode), so each later switch reads part or all of the conversation uncached again.
 
 ### See where fast mode spend appears
 

content/en/docs/claude-code/hooks.md

@@ -4086,7 +4086,7 @@ Claude Code delivers an async hook's results only while the session runs:
 
 When an async hook fires, Claude Code starts the hook process and immediately continues without waiting for it to finish. The hook receives the same JSON input via stdin as a synchronous hook.
 
-After the background process exits, Claude Code delivers the `additionalContext` and `systemMessage` fields from the hook's JSON response to Claude on the next conversation turn. Unlike a synchronous hook's `systemMessage`, neither field is shown to you.
+After the background process exits, Claude Code delivers the `additionalContext` and `systemMessage` fields from the hook's JSON response to Claude on the next conversation turn, except for [repeated `SessionStart` output](#limitations). Unlike a synchronous hook's `systemMessage`, neither field is shown to you.
 
 Print the JSON response alone on stdout or on one line of its own:
 
@@ -4154,6 +4154,7 @@ Async hooks have additional constraints compared to synchronous hooks:
 
 * Hook output is delivered on the next conversation turn. If the session is idle, the response waits until the next user interaction. Exception: an `asyncRewake` hook that exits with code 2 wakes Claude immediately even when the session is idle.
 * Each execution creates a separate background process.
+* An async `SessionStart` hook runs every time the event fires. Claude Code skips the hook's output when the `additionalContext` and `systemMessage` text matches what Claude last received from that hook, unless a synchronous `SessionStart` hook has added other text since. Claude Code delivers the text when it changes, and again the next time the hook runs after a compaction or `/clear`. Before v2.1.295, Claude Code added the same text to the conversation again on every resume.
 
 ## Security considerations
 

content/en/docs/claude-code/plugin-marketplaces.md

@@ -148,6 +148,19 @@ A marketplace plugin has an entry `name` in `marketplace.json` and a `name` in i
 
 When the two names differ and someone installs by the manifest name, Claude Code reports `Plugin "<manifest-name>" not found in marketplace "<marketplace>"`. Keep the two names the same. For more on how Claude Code uses the two names, see [Plugin loading reference](https://code.claude.com/docs/en/plugins/loading.md#find-where-a-plugin-came-from).
 
+### Keep unused submodules out of the clone
+
+When someone adds your marketplace, Claude Code clones the repository and fetches only the git submodules that hold plugin files. Requires Claude Code v2.1.295 or later.
+
+You decide which submodules Claude Code fetches by where you put each plugin:
+
+* **A plugin in a subdirectory**: Claude Code fetches the submodules inside the plugin's directory and a submodule that contains it. Put a submodule your plugin needs inside the plugin's directory, and keep one it doesn't need outside
+* **A plugin at the marketplace root**: Claude Code fetches every submodule in the repository as soon as one of the plugin's files refers to a path inside any of them. If your repository has a large submodule that only your build uses, move the plugin into a subdirectory
+
+If a plugin at the root runs a file from a submodule, write the file's path out in the plugin's hook or server configuration, such as `${CLAUDE_PLUGIN_ROOT}/vendor/tool/run.sh`. Claude Code reads those paths to find out whether the plugin needs the submodules. It can't see a path that a script builds while it runs.
+
+For the full rule, see [Git submodules in the marketplace repository](https://code.claude.com/docs/en/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository).
+
 ## Choose a plugin source
 
 Each plugin entry in `marketplace.json` has a `source` that tells Claude Code where to fetch that one plugin. Pick the source by where the plugin's files are stored. The table lists the sources most marketplace owners use.

content/en/docs/claude-code/plugins/create-marketplace.md

@@ -148,6 +148,19 @@ A marketplace plugin has an entry `name` in `marketplace.json` and a `name` in i
 
 When the two names differ and someone installs by the manifest name, Claude Code reports `Plugin "<manifest-name>" not found in marketplace "<marketplace>"`. Keep the two names the same. For more on how Claude Code uses the two names, see [Plugin loading reference](https://code.claude.com/docs/en/plugins/loading.md#find-where-a-plugin-came-from).
 
+### Keep unused submodules out of the clone
+
+When someone adds your marketplace, Claude Code clones the repository and fetches only the git submodules that hold plugin files. Requires Claude Code v2.1.295 or later.
+
+You decide which submodules Claude Code fetches by where you put each plugin:
+
+* **A plugin in a subdirectory**: Claude Code fetches the submodules inside the plugin's directory and a submodule that contains it. Put a submodule your plugin needs inside the plugin's directory, and keep one it doesn't need outside
+* **A plugin at the marketplace root**: Claude Code fetches every submodule in the repository as soon as one of the plugin's files refers to a path inside any of them. If your repository has a large submodule that only your build uses, move the plugin into a subdirectory
+
+If a plugin at the root runs a file from a submodule, write the file's path out in the plugin's hook or server configuration, such as `${CLAUDE_PLUGIN_ROOT}/vendor/tool/run.sh`. Claude Code reads those paths to find out whether the plugin needs the submodules. It can't see a path that a script builds while it runs.
+
+For the full rule, see [Git submodules in the marketplace repository](https://code.claude.com/docs/en/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository).
+
 ## Choose a plugin source
 
 Each plugin entry in `marketplace.json` has a `source` that tells Claude Code where to fetch that one plugin. Pick the source by where the plugin's files are stored. The table lists the sources most marketplace owners use.

content/en/docs/claude-code/plugins/marketplace-reference.md

@@ -172,6 +172,36 @@ A relative path resolves only when Claude Code has the marketplace's files, so c
 * **`url`**: Claude Code fetches only `marketplace.json`, so relative paths can't resolve. Give each plugin an object source instead, such as `github` or `git-subdir`.
 * **`settings`**: relative paths are rejected outright.
 
+#### Git submodules in the marketplace repository
+
+When Claude Code clones a marketplace repository, it fetches only the git submodules that hold plugin files. Requires Claude Code v2.1.295 or later.
+
+Earlier versions fetch every submodule, nested ones included. If the repository has a large submodule, Claude Code can then run past the [clone timeout](https://code.claude.com/docs/en/plugins/troubleshooting.md#git-clone-timed-out-after-120s) while fetching it.
+
+For a plugin in a subdirectory, such as `./plugins/formatter`, Claude Code fetches a submodule in these cases:
+
+* **The plugin is inside the submodule**: the submodule is the plugin's directory or a directory above it
+* **The submodule is inside the plugin**: the submodule is anywhere under the plugin's directory
+* **A symbolic link points into the submodule**: a link committed to the repository has its target in the submodule
+
+A plugin at the marketplace root, with `"source": "./"`, gets every submodule in the repository or none of them. Claude Code fetches every submodule when one of these points into any submodule:
+
+* **A component directory**: a directory at the root that holds plugin components, such as `skills/`, `hooks/`, or `bin/`
+* **A path in the plugin's configuration**: a path in the plugin's marketplace entry, in its `plugin.json`, or in a config file such as `.mcp.json` or `hooks/hooks.json`
+* **A symbolic link**: a link committed to the repository
+* **Text in the plugin's files**: a submodule's path, such as `vendor/tool`, written in a config file or in a file under a component directory
+
+When none of them does, Claude Code fetches no submodule for that plugin. A repository that is both a project and a plugin often has submodules that only the project's build uses, and this rule leaves them out.
+
+Claude Code also fetches every submodule where it can't tell which ones hold plugin files, such as:
+
+* **A `SKILL.md` at the root**: the whole repository is then one skill's directory
+* **A file Claude Code can't read**: the marketplace file, one of the plugin's config files, or `.gitmodules`
+
+If you add a marketplace with `--sparse`, or its source sets `sparsePaths`, Claude Code checks out only the directories named there and fetches no submodule. Earlier versions do the same.
+
+To keep a submodule your plugins don't use out of the clone, see [Keep unused submodules out of the clone](https://code.claude.com/docs/en/plugins/create-marketplace.md#keep-unused-submodules-out-of-the-clone).
+
 #### Bare names under pluginRoot
 
 A bare name is a single directory name with no `/`, such as `"formatter"`. To write bare names instead of `./` paths, set [`metadata.pluginRoot`](#top-level-fields) to the directory they resolve under. With `"pluginRoot": "./plugins"`, `"source": "formatter"` resolves to `./plugins/formatter`. Requires Claude Code v2.1.239 or later.

content/en/docs/claude-code/plugins/troubleshooting.md

@@ -318,6 +318,8 @@ Then retry in the same shell.
 
 If the repository is a monorepo, limit the checkout to the directories you name with `claude plugin marketplace add <source> --sparse <paths>`.
 
+If the repository has large git submodules, update Claude Code. On v2.1.295 and later, Claude Code fetches only the [submodules that hold plugin files](https://code.claude.com/docs/en/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository). Earlier versions fetch every submodule, which can use up the 120 seconds on its own.
+
 ### Marketplace updates keep failing offline
 
 You work in an environment where the marketplace's git host is unreachable, and every session repeats a failed refresh in the background. Your existing checkout of the marketplace stays in place and startup isn't delayed.
@@ -1090,6 +1092,14 @@ When a user adds a URL-based marketplace, Claude Code downloads only the `market
 
 Alternatively, host the marketplace in a git repository and tell users to add it with the repository URL. For a git source, Claude Code clones the whole repository, so relative paths resolve. Source types are on the [marketplace reference](https://code.claude.com/docs/en/plugins/marketplace-reference.md).
 
+### A root plugin's files from a git submodule are missing after install
+
+Your plugin is at the marketplace root and runs or reads a file from a git submodule of the repository. After install, the submodule's directory is empty. Before v2.1.295, Claude Code fetched every submodule, so the directory was populated.
+
+When Claude Code clones your marketplace, it fetches only the [submodules that hold plugin files](https://code.claude.com/docs/en/plugins/marketplace-reference.md#git-submodules-in-the-marketplace-repository). For a plugin at the root, it decides by reading the paths in the plugin's configuration and the text of the plugin's files. It can't see a path that a script builds while it runs.
+
+Write a path into the submodule out in full where Claude Code can read it, such as `${CLAUDE_PLUGIN_ROOT}/vendor/tool/run.sh` in a hook command. Claude Code then fetches every submodule in the repository for that plugin.
+
 ### Marketplace validation errors
 
 You ran `claude plugin validate .` from your marketplace directory and it reported errors or warnings on the marketplace file itself.