Documentation — Spybara

agent-sdk/agent-loop.md +395 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Как работает цикл агента

7> Поймите жизненный цикл сообщений, выполнение инструментов, контекстное окно и архитектуру, которые питают ваших агентов SDK.

9Agent SDK позволяет встроить автономный цикл агента Claude Code в ваши собственные приложения. SDK — это отдельный пакет, который дает вам программный контроль над инструментами, разрешениями, ограничениями затрат и выводом. Вам не нужно устанавливать Claude Code CLI для его использования.

11Когда вы запускаете агента, SDK запускает тот же [цикл выполнения, который питает Claude Code](/ru/how-claude-code-works#the-agentic-loop): Claude оценивает ваш запрос, вызывает инструменты для выполнения действий, получает результаты и повторяет до завершения задачи. На этой странице объясняется, что происходит внутри этого цикла, чтобы вы могли эффективно создавать, отлаживать и оптимизировать своих агентов.

13## Цикл с первого взгляда

15Каждая сессия агента следует одному и тому же циклу:

17<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-loop-diagram.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=192e1bd6c8a2950a16e5ee0b94e27e26" alt="Цикл агента: запрос входит, Claude оценивает, ветвится на вызовы инструментов или финальный ответ" width="680" height="150" data-path="images/agent-loop-diagram.svg" />

191. **Получить запрос.** Claude получает ваш запрос вместе с системным запросом, определениями инструментов и историей разговора. SDK выдает [`SystemMessage`](#message-types) с подтипом `"init"`, содержащий метаданные сессии.

202. **Оценить и ответить.** Claude оценивает текущее состояние и определяет, как действовать дальше. Он может ответить текстом, запросить один или несколько вызовов инструментов или оба варианта. SDK выдает [`AssistantMessage`](#message-types), содержащее текст и любые запросы вызовов инструментов.

213. **Выполнить инструменты.** SDK запускает каждый запрошенный инструмент и собирает результаты. Каждый набор результатов инструментов возвращается Claude для следующего решения. Вы можете использовать [hooks](/ru/agent-sdk/hooks) для перехвата, изменения или блокировки вызовов инструментов перед их выполнением.

224. **Повторить.** Шаги 2 и 3 повторяются как цикл. Каждый полный цикл — это один ход. Claude продолжает вызывать инструменты и обрабатывать результаты до тех пор, пока не выдаст ответ без вызовов инструментов.

235. **Вернуть результат.** SDK выдает финальное [`AssistantMessage`](#message-types) с текстовым ответом (без вызовов инструментов), за которым следует [`ResultMessage`](#message-types) с финальным текстом, использованием токенов, стоимостью и ID сессии.

25Быстрый вопрос («какие файлы здесь?») может занять один или два хода вызова `Glob` и ответа с результатами. Сложная задача («рефакторить модуль аутентификации и обновить тесты») может связать десятки вызовов инструментов на протяжении многих ходов, читая файлы, редактируя код и запуская тесты, при этом Claude корректирует свой подход на основе каждого результата.

27## Ходы и сообщения

29Ход — это один цикл внутри цикла: Claude выдает выход, который включает вызовы инструментов, SDK выполняет эти инструменты, и результаты автоматически возвращаются Claude. Это происходит без возврата управления вашему коду. Ходы продолжаются до тех пор, пока Claude не выдаст выход без вызовов инструментов, после чего цикл заканчивается и доставляется финальный результат.

31Рассмотрим, как может выглядеть полная сессия для запроса «Исправить неудачные тесты в auth.ts».

33Сначала SDK отправляет ваш запрос Claude и выдает [`SystemMessage`](#message-types) с метаданными сессии. Затем начинается цикл:

351. **Ход 1:** Claude вызывает `Bash` для запуска `npm test`. SDK выдает [`AssistantMessage`](#message-types) с вызовом инструмента, выполняет команду, затем выдает [`UserMessage`](#message-types) с выводом (три ошибки).

362. **Ход 2:** Claude вызывает `Read` на `auth.ts` и `auth.test.ts`. SDK возвращает содержимое файлов и выдает `AssistantMessage`.

373. **Ход 3:** Claude вызывает `Edit` для исправления `auth.ts`, затем вызывает `Bash` для повторного запуска `npm test`. Все три теста проходят. SDK выдает `AssistantMessage`.

384. **Финальный ход:** Claude выдает текстовый ответ без вызовов инструментов: «Исправлена ошибка аутентификации, все три теста теперь проходят.» SDK выдает финальное `AssistantMessage` с этим текстом, затем [`ResultMessage`](#message-types) с тем же текстом плюс стоимость и использование.

40Это было четыре хода: три с вызовами инструментов, один финальный текстовый ответ.

42Вы можете ограничить цикл с помощью `max_turns` / `maxTurns`, который считает только ходы с использованием инструментов. Например, `max_turns=2` в цикле выше остановился бы перед шагом редактирования. Вы также можете использовать `max_budget_usd` / `maxBudgetUsd` для ограничения ходов на основе порога расходов.

44Без ограничений цикл работает до тех пор, пока Claude не закончит самостоятельно, что хорошо для хорошо определенных задач, но может работать долго на открытых запросах («улучшить этот кодовую базу»). Установка бюджета — хороший стандарт для производственных агентов. См. [Ходы и бюджет](#turns-and-budget) ниже для справки по опциям.

46## Типы сообщений

48По мере выполнения цикла SDK выдает поток сообщений. Каждое сообщение имеет тип, который говорит вам, на каком этапе цикла оно пришло. Пять основных типов:

50* **`SystemMessage`:** события жизненного цикла сессии. Поле `subtype` их различает: `"init"` — это первое сообщение (метаданные сессии), а `"compact_boundary"` срабатывает после [компактирования](#automatic-compaction). В TypeScript граница компактирования — это собственный тип [`SDKCompactBoundaryMessage`](/ru/agent-sdk/typescript#sdkcompactboundarymessage) вместо подтипа `SDKSystemMessage`.

51* **`AssistantMessage`:** выдается после каждого ответа Claude, включая финальный текстовый. Содержит блоки текстового содержимого и блоки вызовов инструментов из этого хода.

52* **`UserMessage`:** выдается после каждого выполнения инструмента с результатом инструмента, отправленным обратно Claude. Также выдается для любых пользовательских входов, которые вы транслируете в середине цикла.

53* **`StreamEvent`:** выдается только при включении частичных сообщений. Содержит необработанные события потоковой передачи API (дельты текста, фрагменты входных данных инструмента). См. [Потоковые ответы](/ru/agent-sdk/streaming-output).

54* **`ResultMessage`:** отмечает конец цикла агента. Содержит финальный текстовый результат, использование токенов, стоимость и ID сессии. Проверьте поле `subtype`, чтобы определить, успешна ли задача или достигнут ли лимит. Небольшое количество завершающих системных событий, таких как `prompt_suggestion`, может прибыть после него, поэтому итерируйте поток до завершения, а не прерывайте на результате. См. [Обработать результат](#handle-the-result).

56Эти пять типов охватывают полный жизненный цикл цикла агента в обоих SDK. TypeScript SDK также выдает дополнительные события наблюдаемости (события hooks, прогресс инструмента, ограничения скорости, уведомления задач), которые предоставляют дополнительные детали, но не требуются для управления циклом. См. [справку по типам сообщений Python](/ru/agent-sdk/python#message-types) и [справку по типам сообщений TypeScript](/ru/agent-sdk/typescript#message-types) для полных списков.

58### Обработать сообщения

60Какие сообщения вы обрабатываете, зависит от того, что вы создаете:

62* **Только финальные результаты:** обработайте `ResultMessage`, чтобы получить выход, стоимость и то, успешна ли задача или достигнут ли лимит.

63* **Обновления прогресса:** обработайте `AssistantMessage`, чтобы увидеть, что делает Claude на каждом ходу, включая какие инструменты он вызвал.

64* **Прямая потоковая передача:** включите частичные сообщения (`include_partial_messages` в Python, `includePartialMessages` в TypeScript), чтобы получить сообщения `StreamEvent` в реальном времени. См. [Потоковые ответы в реальном времени](/ru/agent-sdk/streaming-output).

66Как вы проверяете типы сообщений, зависит от SDK:

68* **Python:** проверьте типы сообщений с помощью `isinstance()` для классов, импортированных из `claude_agent_sdk` (например, `isinstance(message, ResultMessage)`).

69* **TypeScript:** проверьте строковое поле `type` (например, `message.type === "result"`). `AssistantMessage` и `UserMessage` оборачивают необработанное сообщение API в поле `.message`, поэтому блоки содержимого находятся в `message.message.content`, а не в `message.content`.

71<Accordion title="Пример: Проверить типы сообщений и обработать результаты">

72 <CodeGroup>

73 ```python Python theme={null}

74 from claude_agent_sdk import query, AssistantMessage, ResultMessage

76 async for message in query(prompt="Summarize this project"):

77 if isinstance(message, AssistantMessage):

78 print(f"Turn completed: {len(message.content)} content blocks")

79 if isinstance(message, ResultMessage):

80 if message.subtype == "success":

81 print(message.result)

82 else:

83 print(f"Stopped: {message.subtype}")

84 ```

86 ```typescript TypeScript theme={null}

87 import { query } from "@anthropic-ai/claude-agent-sdk";

89 for await (const message of query({ prompt: "Summarize this project" })) {

90 if (message.type === "assistant") {

91 console.log(`Turn completed: ${message.message.content.length} content blocks`);

92 }

93 if (message.type === "result") {

94 if (message.subtype === "success") {

95 console.log(message.result);

96 } else {

97 console.log(`Stopped: ${message.subtype}`);

98 }

99 }

100 }

101 ```

102 </CodeGroup>

103</Accordion>

104

105## Выполнение инструментов

106

107Инструменты дают вашему агенту возможность действовать. Без инструментов Claude может только отвечать текстом. С инструментами Claude может читать файлы, запускать команды, искать код и взаимодействовать с внешними сервисами.

108

109### Встроенные инструменты

110

111SDK включает те же инструменты, которые питают Claude Code:

112

113| Категория | Инструменты | Что они делают |

114| :--------------------- | :----------------------------------------------- | :---------------------------------------------------------------------------------------------- |

115| **Операции с файлами** | `Read`, `Edit`, `Write` | Читать, изменять и создавать файлы |

116| **Поиск** | `Glob`, `Grep` | Найти файлы по шаблону, искать содержимое с помощью regex |

117| **Выполнение** | `Bash` | Запускать команды оболочки, скрипты, операции git |

118| **Веб** | `WebSearch`, `WebFetch` | Искать в веб, получать и анализировать страницы |

119| **Обнаружение** | `ToolSearch` | Динамически находить и загружать инструменты по требованию вместо предварительной загрузки всех |

120| **Оркестрация** | `Agent`, `Skill`, `AskUserQuestion`, `TodoWrite` | Порождать подагентов, вызывать skills, спрашивать пользователя, отслеживать задачи |

121

122Помимо встроенных инструментов, вы можете:

123

124* **Подключить внешние сервисы** с помощью [MCP servers](/ru/agent-sdk/mcp) (базы данных, браузеры, API)

125* **Определить пользовательские инструменты** с помощью [пользовательских обработчиков инструментов](/ru/agent-sdk/custom-tools)

126* **Загрузить skills проекта** через [источники настроек](/ru/agent-sdk/claude-code-features) для повторно используемых рабочих процессов

127

128### Разрешения инструментов

129

130Claude определяет, какие инструменты вызывать на основе задачи, но вы контролируете, разрешено ли выполнение этих вызовов. Вы можете автоматически одобрить определенные инструменты, полностью заблокировать другие или требовать одобрения для всего. Три опции работают вместе, чтобы определить, что работает:

131

132* **`allowed_tools` / `allowedTools`** автоматически одобряет перечисленные инструменты. Агент только для чтения с `["Read", "Glob", "Grep"]` в списке разрешенных инструментов запускает эти инструменты без подсказок. Инструменты, не указанные в списке, все еще доступны, но требуют разрешения.

133* **`disallowed_tools` / `disallowedTools`** блокирует перечисленные инструменты, независимо от других настроек. См. [Разрешения](/ru/agent-sdk/permissions) для порядка, в котором правила проверяются перед запуском инструмента.

134* **`permission_mode` / `permissionMode`** контролирует, что происходит с инструментами, которые не охватываются правилами разрешения или запрета. См. [Режим разрешения](#permission-mode) для доступных режимов.

135

136Вы также можете ограничить отдельные инструменты правилами, такими как `"Bash(npm *)"`, чтобы разрешить только определенные команды. См. [Разрешения](/ru/agent-sdk/permissions) для полного синтаксиса правил.

137

138Когда инструмент отклоняется, Claude получает сообщение об отклонении как результат инструмента и обычно пытается использовать другой подход или сообщает, что не может продолжить.

139

140### Параллельное выполнение инструментов

141

142Когда Claude запрашивает несколько вызовов инструментов в одном ходе, оба SDK могут запускать их одновременно или последовательно в зависимости от инструмента. Инструменты только для чтения (такие как `Read`, `Glob`, `Grep` и MCP инструменты, отмеченные как только для чтения) могут работать одновременно. Инструменты, которые изменяют состояние (такие как `Edit`, `Write` и `Bash`), работают последовательно, чтобы избежать конфликтов.

143

144Пользовательские инструменты по умолчанию работают последовательно. Чтобы включить параллельное выполнение для пользовательского инструмента, установите `readOnlyHint` в его аннотациях. Оба SDK [TypeScript](/ru/agent-sdk/typescript#tool) и [Python](/ru/agent-sdk/python#tool) используют это имя поля из MCP SDK.

145

146## Контролировать, как работает цикл

147

148Вы можете ограничить количество ходов, которые делает цикл, сколько он стоит, насколько глубоко Claude рассуждает, и требуют ли инструменты одобрения перед запуском. Все это поля на [`ClaudeAgentOptions`](/ru/agent-sdk/python#claudeagentoptions) (Python) / [`Options`](/ru/agent-sdk/typescript#options) (TypeScript).

149

150### Ходы и бюджет

151

152| Опция | Что она контролирует | По умолчанию |

153| :--------------------------------------------------- | :------------------------------------------ | :-------------- |

154| Максимум ходов (`max_turns` / `maxTurns`) | Максимум раундов использования инструментов | Без ограничений |

155| Максимум бюджета (`max_budget_usd` / `maxBudgetUsd`) | Максимальная стоимость перед остановкой | Без ограничений |

156

157Когда достигается любой лимит, SDK возвращает `ResultMessage` с соответствующим подтипом ошибки (`error_max_turns` или `error_max_budget_usd`). См. [Обработать результат](#handle-the-result) для того, как проверить эти подтипы, и [`ClaudeAgentOptions`](/ru/agent-sdk/python#claudeagentoptions) / [`Options`](/ru/agent-sdk/typescript#options) для синтаксиса.

158

159### Уровень усилий

160

161Опция `effort` контролирует, сколько рассуждений применяет Claude. Более низкие уровни усилий используют меньше токенов за ход и снижают стоимость. Не все модели поддерживают параметр effort. См. [Effort](https://platform.claude.com/docs/en/build-with-claude/effort) для того, какие модели его поддерживают.

162

163| Уровень | Поведение | Хорошо для |

164| :--------- | :-------------------------------------- | :-------------------------------------------------------- |

165| `"low"` | Минимальное рассуждение, быстрые ответы | Поиск файлов, список каталогов |

166| `"medium"` | Сбалансированное рассуждение | Обычные редактирования, стандартные задачи |

167| `"high"` | Тщательный анализ | Рефакторинг, отладка |

168| `"xhigh"` | Расширенная глубина рассуждения | Задачи кодирования и агентские; рекомендуется на Opus 4.7 |

169| `"max"` | Максимальная глубина рассуждения | Многошаговые проблемы, требующие глубокого анализа |

170

171Если вы не установите `effort`, Python SDK оставляет параметр неустановленным и полагается на поведение модели по умолчанию. TypeScript SDK по умолчанию использует `"high"`.

172

173<Note>

174 `effort` обменивает задержку и стоимость токена на глубину рассуждения в каждом ответе. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) — это отдельная функция, которая выдает видимые блоки цепочки мыслей в выводе. Они независимы: вы можете установить `effort: "low"` с включенным extended thinking или `effort: "max"` без него.

175</Note>

176

177Используйте более низкие усилия для агентов, выполняющих простые, хорошо определенные задачи (такие как список файлов или запуск одного grep), чтобы снизить стоимость и задержку. Установите `effort` в опциях верхнего уровня `query()` для всей сессии или для каждого подагента с полем `effort` на [`AgentDefinition`](/ru/agent-sdk/subagents#agentdefinition-configuration), чтобы переопределить уровень сессии.

178

179### Режим разрешения

180

181Опция режима разрешения (`permission_mode` в Python, `permissionMode` в TypeScript) контролирует, просит ли агент одобрения перед использованием инструментов:

182

183| Режим | Поведение |

184| :--------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

185| `"default"` | Инструменты, не охватываемые правилами разрешения, запускают ваш обратный вызов одобрения; отсутствие обратного вызова означает отклонение |

186| `"acceptEdits"` | Автоматически одобряет редактирование файлов и общие команды файловой системы (`mkdir`, `touch`, `mv`, `cp` и т. д.); другие команды Bash следуют правилам по умолчанию |

187| `"plan"` | Инструменты только для чтения работают; Claude исследует и выдает план без редактирования ваших исходных файлов |

188| `"dontAsk"` | Никогда не подсказывает. Инструменты, предварительно одобренные [правилами разрешения](/ru/settings#permission-settings), работают, все остальное отклоняется |

189| `"auto"` (только TypeScript) | Использует классификатор модели для одобрения или отклонения каждого вызова инструмента. См. [Режим Auto](/ru/permission-modes#eliminate-prompts-with-auto-mode) для доступности и поведения |

190| `"bypassPermissions"` | Запускает все разрешенные инструменты без запроса. Не может использоваться при запуске от root на Unix. Используйте только в изолированных окружениях, где действия агента не могут повлиять на системы, которые вам важны |

191

192Для интерактивных приложений используйте `"default"` с обратным вызовом одобрения инструмента для отображения подсказок одобрения. Для автономных агентов на машине разработки используйте `"acceptEdits"`, чтобы автоматически одобрить редактирование файлов и общие команды файловой системы (`mkdir`, `touch`, `mv`, `cp` и т. д.), при этом все еще ограничивая другие команды `Bash` правилами разрешения. Зарезервируйте `"bypassPermissions"` для CI, контейнеров или других изолированных окружений. См. [Разрешения](/ru/agent-sdk/permissions) для полных деталей.

193

194### Модель

195

196Если вы не установите `model`, SDK использует значение по умолчанию Claude Code, которое зависит от вашего метода аутентификации и подписки. Установите его явно (например, `model="claude-sonnet-4-6"`), чтобы закрепить определенную модель или использовать меньшую модель для более быстрых и дешевых агентов. См. [models](https://platform.claude.com/docs/en/about-claude/models) для доступных ID.

197

198## Контекстное окно

199

200Контекстное окно — это общее количество информации, доступной Claude во время сессии. Оно не сбрасывается между ходами в пределах сессии. Все накапливается: системный запрос, определения инструментов, история разговора, входные данные инструментов и выходные данные инструментов. Содержимое, которое остается неизменным на протяжении ходов (системный запрос, определения инструментов, CLAUDE.md), автоматически [кэшируется в запросе](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), что снижает стоимость и задержку для повторяющихся префиксов.

201

202### Что потребляет контекст

203

204Вот как каждый компонент влияет на контекст в SDK:

205

206| Источник | Когда он загружается | Влияние |

207| :--------------------------- | :-------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

208| **Системный запрос** | Каждый запрос | Небольшая фиксированная стоимость, всегда присутствует |

209| **CLAUDE.md файлы** | Начало сессии, через [`settingSources`](/ru/agent-sdk/claude-code-features) | Полное содержимое в каждом запросе (но кэшировано в запросе, поэтому только первый запрос платит полную стоимость) |

210| **Определения инструментов** | Каждый запрос | Каждый инструмент добавляет свою схему; используйте [поиск инструментов MCP](/ru/agent-sdk/mcp#mcp-tool-search) для загрузки инструментов по требованию вместо всех сразу |

211| **История разговора** | Накапливается на протяжении ходов | Растет с каждым ходом: запросы, ответы, входные данные инструментов, выходные данные инструментов |

212| **Описания skills** | Начало сессии, через источники настроек | Короткие резюме; полное содержимое загружается только при вызове |

213

214Большие выходные данные инструментов потребляют значительный контекст. Чтение большого файла или запуск команды с подробным выводом может использовать тысячи токенов в одном ходе. Контекст накапливается на протяжении ходов, поэтому более длительные сессии с множеством вызовов инструментов накапливают значительно больше контекста, чем короткие.

215

216### Автоматическое компактирование

217

218Когда контекстное окно приближается к своему лимиту, SDK автоматически компактирует разговор: он суммирует более старую историю, чтобы освободить место, сохраняя ваши самые последние обмены и ключевые решения нетронутыми. SDK выдает сообщение с `type: "system"` и `subtype: "compact_boundary"` в потоке, когда это происходит (в Python это `SystemMessage`; в TypeScript это отдельный тип `SDKCompactBoundaryMessage`).

219

220Компактирование заменяет более старые сообщения резюме, поэтому конкретные инструкции с начала разговора могут не сохраниться. Постоянные правила должны находиться в CLAUDE.md (загружаемые через [`settingSources`](/ru/agent-sdk/claude-code-features)), а не в начальном запросе, потому что содержимое CLAUDE.md повторно вводится в каждом запросе.

221

222Вы можете настроить поведение компактирования несколькими способами:

223

224* **Инструкции по суммированию в CLAUDE.md:** Компактор читает ваш CLAUDE.md как любой другой контекст, поэтому вы можете включить раздел, рассказывающий ему, что сохранить при суммировании. Заголовок раздела свободной формы (не волшебная строка); компактор совпадает по намерению.

225* **Hook `PreCompact`:** Запустите пользовательскую логику перед компактированием, например для архивирования полной транскрипции. Hook получает поле `trigger` (`manual` или `auto`). См. [hooks](/ru/agent-sdk/hooks).

226* **Ручное компактирование:** Отправьте `/compact` как строку запроса для запуска компактирования по требованию. (Slash commands, отправленные таким образом, — это входные данные SDK, а не только ярлыки CLI. См. [slash commands в SDK](/ru/agent-sdk/slash-commands).)

227

228<Accordion title="Пример: Инструкции по суммированию в CLAUDE.md">

229 Добавьте раздел в CLAUDE.md вашего проекта, рассказывающий компактору, что сохранить. Имя заголовка не является специальным; используйте любой четкий ярлык.

230

231 ```markdown CLAUDE.md theme={null}

232 # Summary instructions

233

234 When summarizing this conversation, always preserve:

235 - The current task objective and acceptance criteria

236 - File paths that have been read or modified

237 - Test results and error messages

238 - Decisions made and the reasoning behind them

239 ```

240</Accordion>

241

242### Держите контекст эффективным

243

244Несколько стратегий для долгоживущих агентов:

245

246* **Используйте подагентов для подзадач.** Каждый подагент начинает со свежего разговора (без предыдущей истории сообщений, хотя он загружает свой собственный системный запрос и контекст уровня проекта, такой как CLAUDE.md). Он не видит ходы родителя, и только его финальный ответ возвращается родителю как результат инструмента. Контекст основного агента растет на эту резюме, а не на полную транскрипцию подзадачи. См. [Что наследуют подагенты](/ru/agent-sdk/subagents#what-subagents-inherit) для деталей.

247* **Будьте избирательны с инструментами.** Каждое определение инструмента занимает место контекста. Используйте поле `tools` на [`AgentDefinition`](/ru/agent-sdk/subagents#agentdefinition-configuration) для ограничения подагентов минимальным набором, который им нужен, и используйте [поиск инструментов MCP](/ru/agent-sdk/mcp#mcp-tool-search) для загрузки инструментов по требованию вместо предварительной загрузки всех.

248* **Следите за стоимостью MCP сервера.** Каждый MCP сервер добавляет все свои схемы инструментов в каждый запрос. Несколько серверов с множеством инструментов могут потребить значительный контекст перед тем, как агент выполнит какую-либо работу. Инструмент `ToolSearch` может помочь, загружая инструменты по требованию вместо предварительной загрузки всех. См. [поиск инструментов MCP](/ru/agent-sdk/mcp#mcp-tool-search) для конфигурации.

249* **Используйте более низкие усилия для обычных задач.** Установите [effort](#effort-level) на `"low"` для агентов, которым нужно только читать файлы или список каталогов. Это снижает использование токенов и стоимость.

250

251Для подробного разбора стоимости контекста для каждой функции см. [Понять стоимость контекста](/ru/features-overview#understand-context-costs).

252

253## Сессии и непрерывность

254

255Каждое взаимодействие с SDK создает или продолжает сессию. Захватите ID сессии из `ResultMessage.session_id` (доступно в обоих SDK) для возобновления позже. TypeScript SDK также выставляет его как прямое поле на инициализирующем `SystemMessage`; в Python он вложен в `SystemMessage.data`.

256

257Когда вы возобновляете, полный контекст из предыдущих ходов восстанавливается: файлы, которые были прочитаны, анализ, который был выполнен, и действия, которые были предприняты. Вы также можете разветвить сессию, чтобы ветвиться в другой подход без изменения оригинала.

258

259См. [Управление сессией](/ru/agent-sdk/sessions) для полного руководства по возобновлению, продолжению и разветвлению паттернов.

260

261<Note>

262 В Python `ClaudeSDKClient` автоматически обрабатывает ID сессий на протяжении нескольких вызовов. См. [справку Python SDK](/ru/agent-sdk/python#choosing-between-query-and-claudesdkclient) для деталей.

263</Note>

264

265## Обработать результат

266

267Когда цикл заканчивается, `ResultMessage` говорит вам, что произошло, и дает вам выход. Поле `subtype` (доступно в обоих SDK) — это основной способ проверить состояние завершения.

268

269| Подтип результата | Что произошло | Поле `result` доступно? |

270| :------------------------------------ | :------------------------------------------------------------------------------- | :---------------------: |

271| `success` | Claude нормально завершил задачу | Да |

272| `error_max_turns` | Достигнут лимит `maxTurns` перед завершением | Нет |

273| `error_max_budget_usd` | Достигнут лимит `maxBudgetUsd` перед завершением | Нет |

274| `error_during_execution` | Ошибка прервала цикл (например, отказ API или отмененный запрос) | Нет |

275| `error_max_structured_output_retries` | Валидация структурированного выхода не прошла после настроенного лимита повторов | Нет |

276

277Поле `result` (финальный текстовый выход) присутствует только в варианте `success`, поэтому всегда проверяйте подтип перед его чтением. Все подтипы результатов содержат `total_cost_usd`, `usage`, `num_turns` и `session_id`, поэтому вы можете отслеживать стоимость и возобновлять даже после ошибок. В Python `total_cost_usd` и `usage` типизированы как опциональные и могут быть `None` на некоторых путях ошибок, поэтому охраняйте перед форматированием. См. [Отслеживание стоимости и использования](/ru/agent-sdk/cost-tracking) для деталей по интерпретации полей `usage`.

278

279Результат также включает поле `stop_reason` (`string | null` в TypeScript, `str | None` в Python), указывающее, почему модель остановила генерацию на своем финальном ходе. Общие значения — `end_turn` (модель закончила нормально), `max_tokens` (достигнут лимит выходных токенов) и `refusal` (модель отклонила запрос). На подтипах результатов ошибок `stop_reason` содержит значение из последнего ответа помощника перед завершением цикла. Для обнаружения отклонений проверьте `stop_reason === "refusal"` (TypeScript) или `stop_reason == "refusal"` (Python). См. [`SDKResultMessage`](/ru/agent-sdk/typescript#sdkresultmessage) (TypeScript) или [`ResultMessage`](/ru/agent-sdk/python#resultmessage) (Python) для полного типа.

280

281## Hooks

282

283[Hooks](/ru/agent-sdk/hooks) — это обратные вызовы, которые срабатывают в определенных точках цикла: перед запуском инструмента, после его возврата, когда агент заканчивает, и так далее. Некоторые часто используемые hooks:

284

285| Hook | Когда он срабатывает | Общие использования |

286| :------------------------------- | :----------------------------------------- | :------------------------------------------------------- |

287| `PreToolUse` | Перед выполнением инструмента | Валидировать входные данные, блокировать опасные команды |

288| `PostToolUse` | После возврата инструмента | Аудировать выходные данные, запускать побочные эффекты |

289| `UserPromptSubmit` | Когда запрос отправляется | Вводить дополнительный контекст в запросы |

290| `Stop` | Когда агент заканчивает | Валидировать результат, сохранять состояние сессии |

291| `SubagentStart` / `SubagentStop` | Когда подагент порождается или завершается | Отслеживать и агрегировать результаты параллельных задач |

292| `PreCompact` | Перед компактированием контекста | Архивировать полную транскрипцию перед суммированием |

293

294Hooks работают в процессе вашего приложения, а не внутри контекстного окна агента, поэтому они не потребляют контекст. Hooks также могут короткозамкнуть цикл: hook `PreToolUse`, который отклоняет вызов инструмента, предотвращает его выполнение, и Claude получает сообщение об отклонении вместо этого.

295

296Оба SDK поддерживают все события выше. TypeScript SDK включает дополнительные события, которые Python еще не поддерживает. См. [Контролировать выполнение с помощью hooks](/ru/agent-sdk/hooks) для полного списка событий, доступности для каждого SDK и полного API обратного вызова.

297

298## Собрать все вместе

299

300Этот пример объединяет ключевые концепции с этой страницы в одного агента, который исправляет неудачные тесты. Он конфигурирует агента с разрешенными инструментами (автоматически одобренными, поэтому агент работает автономно), настройками проекта и ограничениями безопасности на ходы и усилия рассуждения. По мере выполнения цикла он захватывает ID сессии для потенциального возобновления, обрабатывает финальный результат и выводит общую стоимость.

301

302<CodeGroup>

303 ```python Python theme={null}

304 import asyncio

305 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

306

307

308 async def run_agent():

309 session_id = None

310

311 async for message in query(

312 prompt="Find and fix the bug causing test failures in the auth module",

313 options=ClaudeAgentOptions(

314 allowed_tools=[

315 "Read",

316 "Edit",

317 "Bash",

318 "Glob",

319 "Grep",

320 ], # Listing tools here auto-approves them (no prompting)

321 setting_sources=[

322 "project"

323 ], # Load CLAUDE.md, skills, hooks from current directory

324 max_turns=30, # Prevent runaway sessions

325 effort="high", # Thorough reasoning for complex debugging

326 ),

327 ):

328 # Handle the final result

329 if isinstance(message, ResultMessage):

330 session_id = message.session_id # Save for potential resumption

331

332 if message.subtype == "success":

333 print(f"Done: {message.result}")

334 elif message.subtype == "error_max_turns":

335 # Agent ran out of turns. Resume with a higher limit.

336 print(f"Hit turn limit. Resume session {session_id} to continue.")

337 elif message.subtype == "error_max_budget_usd":

338 print("Hit budget limit.")

339 else:

340 print(f"Stopped: {message.subtype}")

341 if message.total_cost_usd is not None:

342 print(f"Cost: ${message.total_cost_usd:.4f}")

343

344

345 asyncio.run(run_agent())

346 ```

347

348 ```typescript TypeScript theme={null}

349 import { query } from "@anthropic-ai/claude-agent-sdk";

350

351 let sessionId: string | undefined;

352

353 for await (const message of query({

354 prompt: "Find and fix the bug causing test failures in the auth module",

355 options: {

356 allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)

357 settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory

358 maxTurns: 30, // Prevent runaway sessions

359 effort: "high" // Thorough reasoning for complex debugging

360 }

361 })) {

362 // Save the session ID to resume later if needed

363 if (message.type === "system" && message.subtype === "init") {

364 sessionId = message.session_id;

365 }

366

367 // Handle the final result

368 if (message.type === "result") {

369 if (message.subtype === "success") {

370 console.log(`Done: ${message.result}`);

371 } else if (message.subtype === "error_max_turns") {

372 // Agent ran out of turns. Resume with a higher limit.

373 console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);

374 } else if (message.subtype === "error_max_budget_usd") {

375 console.log("Hit budget limit.");

376 } else {

377 console.log(`Stopped: ${message.subtype}`);

378 }

379 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);

380 }

381 }

382 ```

383</CodeGroup>

384

385## Следующие шаги

386

387Теперь, когда вы понимаете цикл, вот куда идти в зависимости от того, что вы создаете:

388

389* **Еще не запустили агента?** Начните с [quickstart](/ru/agent-sdk/quickstart), чтобы установить SDK и увидеть полный пример, работающий от начала до конца.

390* **Готовы подключиться к вашему проекту?** [Загрузите CLAUDE.md, skills и hooks файловой системы](/ru/agent-sdk/claude-code-features), чтобы агент автоматически следовал соглашениям вашего проекта.

391* **Создаете интерактивный UI?** Включите [потоковую передачу](/ru/agent-sdk/streaming-output), чтобы показать живой текст и вызовы инструментов по мере выполнения цикла.

392* **Нужен более плотный контроль над тем, что может делать агент?** Заблокируйте доступ к инструментам с помощью [разрешений](/ru/agent-sdk/permissions) и используйте [hooks](/ru/agent-sdk/hooks) для аудита, блокировки или преобразования вызовов инструментов перед их выполнением.

393* **Запускаете долгие или дорогие задачи?** Перенесите изолированную работу на [подагентов](/ru/agent-sdk/subagents), чтобы держать ваш основной контекст стройным.

394

395Для более широкой концептуальной картины цикла агента (не специфичной для SDK) см. [Как работает Claude Code](/ru/how-claude-code-works).

agent-sdk/hooks.md +11 −11

Details

236Ваш callback возвращает объект с двумя категориями полей:236Ваш callback возвращает объект с двумя категориями полей:

237 237

238* **Поля верхнего уровня** контролируют разговор: `systemMessage` внедряет сообщение в разговор, видимое модели, и `continue` (`continue_` в Python) определяет, продолжает ли агент работать после этого hook.238* **Поля верхнего уровня** контролируют разговор: `systemMessage` внедряет сообщение в разговор, видимое модели, и `continue` (`continue_` в Python) определяет, продолжает ли агент работать после этого hook.

239* **`hookSpecificOutput`** контролирует текущую операцию. Поля внутри зависят от типа события hook. Для hooks `PreToolUse` здесь вы устанавливаете `permissionDecision` (`"allow"`, `"deny"` или `"ask"`), `permissionDecisionReason` и `updatedInput`. В TypeScript SDK `permissionDecision` также принимает `"defer"` для завершения запроса и [возобновления позже](/ru/hooks#defer-a-tool-call-for-later); это значение недоступно в Python SDK. Для hooks `PostToolUse` вы можете установить `additionalContext` для добавления информации к результату инструмента.239* **`hookSpecificOutput`** контролирует текущую операцию. Поля внутри зависят от типа события hook. Для hooks `PreToolUse` здесь вы устанавливаете `permissionDecision` (`"allow"`, `"deny"` или `"ask"`), `permissionDecisionReason` и `updatedInput`. В TypeScript SDK `permissionDecision` также принимает `"defer"` для завершения запроса и [возобновления позже](/ru/hooks#defer-a-tool-call-for-later); это значение недоступно в Python SDK. Для hooks `PostToolUse` вы можете установить `additionalContext` для добавления информации к результату инструмента, или `updatedToolOutput` для полной замены выходных данных инструмента перед тем, как Claude их увидит.

240 240

241Возвращайте `{}` для разрешения операции без изменений. SDK callback hooks используют тот же формат вывода JSON, что и [hooks команд shell Claude Code](/ru/hooks#json-output), который документирует каждое поле и опцию, специфичную для события. Для определений типов SDK см. справочники [TypeScript](/ru/agent-sdk/typescript#sync-hook-json-output) и [Python](/ru/agent-sdk/python#sync-hook-json-output) SDK.241Возвращайте `{}` для разрешения операции без изменений. SDK callback hooks используют тот же формат вывода JSON, что и [hooks команд shell Claude Code](/ru/hooks#json-output), который документирует каждое поле и опцию, специфичную для события. Для определений типов SDK см. справочники [TypeScript](/ru/agent-sdk/typescript#sync-hook-json-output) и [Python](/ru/agent-sdk/python#sync-hook-json-output) SDK.

242 242

417 ```417 ```

418</CodeGroup>418</CodeGroup>

419 419

420### Цепочка нескольких hooks420### Регистрация нескольких hooks

421 421

422Hooks выполняются в порядке, в котором они появляются в массиве. Держите каждый hook сосредоточенным на одной ответственности и цепляйте несколько hooks для сложной логики:422Когда событие срабатывает, все соответствующие hooks выполняются параллельно. Для решений о разрешениях побеждает наиболее ограничивающий результат: одно `deny` блокирует вызов инструмента независимо от того, что возвращают другие hooks. Поскольку порядок завершения недетерминирован, напишите каждый hook так, чтобы он действовал независимо, а не полагаясь на то, что другой hook уже выполнился.

423

424Пример ниже регистрирует три независимые проверки для каждого вызова инструмента:

423 425

424<CodeGroup>426<CodeGroup>

425 ```python Python theme={null}427 ```python Python theme={null}

426 options = ClaudeAgentOptions(428 options = ClaudeAgentOptions(

427 hooks={429 hooks={

428 "PreToolUse": [430 "PreToolUse": [

429 HookMatcher(hooks=[rate_limiter]), # First: check rate limits431 HookMatcher(hooks=[authorization_check]),

430 HookMatcher(hooks=[authorization_check]), # Second: verify permissions432 HookMatcher(hooks=[input_validator]),

431 HookMatcher(hooks=[input_sanitizer]), # Third: sanitize inputs433 HookMatcher(hooks=[audit_logger]),

432 HookMatcher(hooks=[audit_logger]), # Last: log the action

433 ]434 ]

434 }435 }

435 )436 )

439 const options = {440 const options = {

440 hooks: {441 hooks: {

441 PreToolUse: [442 PreToolUse: [

442 { hooks: [rateLimiter] }, // First: check rate limits443 { hooks: [authorizationCheck] },

443 { hooks: [authorizationCheck] }, // Second: verify permissions444 { hooks: [inputValidator] },

444 { hooks: [inputSanitizer] }, // Third: sanitize inputs445 { hooks: [auditLogger] }

445 { hooks: [auditLogger] } // Last: log the action

446 ]446 ]

447 }447 }

448 };448 };

agent-sdk/migration-guide.md +289 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Миграция на Claude Agent SDK

7> Руководство по миграции Claude Code TypeScript и Python SDK на Claude Agent SDK

9## Обзор

11Claude Code SDK был переименован в **Claude Agent SDK**, и его документация была переорганизована. Это изменение отражает более широкие возможности SDK для создания AI-агентов, выходящих за рамки только задач кодирования.

13## Что изменилось

15| Аспект | Старое | Новое |

16| :---------------------------- | :-------------------------- | :------------------------------- |

17| **Имя пакета (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |

18| **Python пакет** | `claude-code-sdk` | `claude-agent-sdk` |

19| **Расположение документации** | Claude Code документация | API Guide → Agent SDK раздел |

21<Note>

22 **Изменения в документации:** Документация Agent SDK переместилась из Claude Code документации в API Guide в отдельный раздел [Agent SDK](/ru/agent-sdk/overview). Документация Claude Code теперь сосредоточена на инструменте CLI и функциях автоматизации.

23</Note>

25## Шаги миграции

27### Для проектов TypeScript/JavaScript

29**1. Удалите старый пакет:**

31```bash theme={null}

32npm uninstall @anthropic-ai/claude-code

33```

35**2. Установите новый пакет:**

37```bash theme={null}

38npm install @anthropic-ai/claude-agent-sdk

39```

41**3. Обновите ваши импорты:**

43Измените все импорты с `@anthropic-ai/claude-code` на `@anthropic-ai/claude-agent-sdk`:

45```typescript theme={null}

46// До

47import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

49// После

50import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

51```

53**4. Обновите зависимости в package.json:**

55Если у вас есть пакет в вашем `package.json`, обновите его:

57До:

59```json theme={null}

60{

61 "dependencies": {

62 "@anthropic-ai/claude-code": "^0.0.42"

63 }

64}

65```

67После:

69```json theme={null}

70{

71 "dependencies": {

72 "@anthropic-ai/claude-agent-sdk": "^0.2.0"

73 }

74}

75```

77Вот и всё! Никаких других изменений кода не требуется.

79### Для Python проектов

81**1. Удалите старый пакет:**

83```bash theme={null}

84pip uninstall claude-code-sdk

85```

87**2. Установите новый пакет:**

89```bash theme={null}

90pip install claude-agent-sdk

91```

93**3. Обновите ваши импорты:**

95Измените все импорты с `claude_code_sdk` на `claude_agent_sdk`:

97```python theme={null}

98# До

99from claude_code_sdk import query, ClaudeCodeOptions

100

101# После

102from claude_agent_sdk import query, ClaudeAgentOptions

103```

104

105**4. Обновите имена типов:**

106

107Измените `ClaudeCodeOptions` на `ClaudeAgentOptions`:

108

109```python theme={null}

110# До

111from claude_code_sdk import query, ClaudeCodeOptions

112

113options = ClaudeCodeOptions(model="claude-opus-4-7")

114

115# После

116from claude_agent_sdk import query, ClaudeAgentOptions

117

118options = ClaudeAgentOptions(model="claude-opus-4-7")

119```

120

121**5. Просмотрите [критические изменения](#breaking-changes)**

122

123Внесите необходимые изменения в код для завершения миграции.

124

125## Критические изменения

126

127<Warning>

128 Для улучшения изоляции и явной конфигурации Claude Agent SDK v0.1.0 вводит критические изменения для пользователей, переходящих с Claude Code SDK. Внимательно просмотрите этот раздел перед миграцией.

129</Warning>

130

131### Python: ClaudeCodeOptions переименован в ClaudeAgentOptions

132

133**Что изменилось:** Тип Python SDK `ClaudeCodeOptions` был переименован в `ClaudeAgentOptions`.

134

135**Миграция:**

136

137```python theme={null}

138# ДО (claude-code-sdk)

139from claude_code_sdk import query, ClaudeCodeOptions

140

141options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

142

143# ПОСЛЕ (claude-agent-sdk)

144from claude_agent_sdk import query, ClaudeAgentOptions

145

146options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

147```

148

149**Почему это изменилось:** Имя типа теперь соответствует брендингу "Claude Agent SDK" и обеспечивает согласованность в соглашениях об именовании SDK.

150

151### Системный промпт больше не используется по умолчанию

152

153**Что изменилось:** SDK больше не использует системный промпт Claude Code по умолчанию.

154

155**Миграция:**

156

157<CodeGroup>

158 ```typescript TypeScript theme={null}

159 // ДО (v0.0.x) - Использовал системный промпт Claude Code по умолчанию

160 const result = query({ prompt: "Hello" });

161

162 // ПОСЛЕ (v0.1.0) - Использует минимальный системный промпт по умолчанию

163 // Чтобы получить старое поведение, явно запросите предустановку Claude Code:

164 const result = query({

165 prompt: "Hello",

166 options: {

167 systemPrompt: { type: "preset", preset: "claude_code" }

168 }

169 });

170

171 // Или используйте пользовательский системный промпт:

172 const result = query({

173 prompt: "Hello",

174 options: {

175 systemPrompt: "You are a helpful coding assistant"

176 }

177 });

178 ```

179

180 ```python Python theme={null}

181 # ДО (v0.0.x) - Использовал системный промпт Claude Code по умолчанию

182 async for message in query(prompt="Hello"):

183 print(message)

184

185 # ПОСЛЕ (v0.1.0) - Использует минимальный системный промпт по умолчанию

186 # Чтобы получить старое поведение, явно запросите предустановку Claude Code:

187 from claude_agent_sdk import query, ClaudeAgentOptions

188

189 async for message in query(

190 prompt="Hello",

191 options=ClaudeAgentOptions(

192 system_prompt={"type": "preset", "preset": "claude_code"} # Используйте предустановку

193 ),

194 ):

195 print(message)

196

197 # Или используйте пользовательский системный промпт:

198 async for message in query(

199 prompt="Hello",

200 options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),

201 ):

202 print(message)

203 ```

204</CodeGroup>

205

206**Почему это изменилось:** Обеспечивает лучший контроль и изоляцию для приложений SDK. Теперь вы можете создавать агентов с пользовательским поведением без наследования инструкций, ориентированных на CLI Claude Code.

207

208### Значения по умолчанию для источников настроек

209

210Это значение по умолчанию было кратко изменено в v0.1.0, а затем восстановлено, поэтому никаких действий по миграции не требуется.

211

212**Текущее поведение:** Пропуск `settingSources` в `query()` загружает пользовательские, проектные и локальные настройки файловой системы, соответствуя CLI. Это включает `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, файлы CLAUDE.md и пользовательские команды.

213

214Для запуска в изоляции от настроек файловой системы передайте пустой массив:

215

216<CodeGroup>

217 ```typescript TypeScript theme={null}

218 const result = query({

219 prompt: "Hello",

220 options: {

221 settingSources: [] // Настройки файловой системы не загружаются

222 }

223 });

224

225 // Или загрузите только определённые источники:

226 const result = query({

227 prompt: "Hello",

228 options: {

229 settingSources: ["project"] // Только настройки проекта

230 }

231 });

232 ```

233

234 ```python Python theme={null}

235 from claude_agent_sdk import query, ClaudeAgentOptions

236

237 async for message in query(

238 prompt="Hello",

239 options=ClaudeAgentOptions(setting_sources=[]), # Настройки файловой системы не загружаются

240 ):

241 print(message)

242

243 # Или загрузите только определённые источники:

244 async for message in query(

245 prompt="Hello",

246 options=ClaudeAgentOptions(

247 setting_sources=["project"] # Только настройки проекта

248 ),

249 ):

250 print(message)

251 ```

252</CodeGroup>

253

254Изоляция особенно важна для конвейеров CI/CD, развёрнутых приложений, тестовых сред и многопользовательских систем, где локальные настройки не должны просачиваться.

255

256<Note>

257 SDK v0.1.0 кратко использовал значение по умолчанию без загруженных настроек; это было восстановлено в последующих выпусках. Python SDK 0.1.59 и более ранние версии обрабатывали пустой список так же, как пропуск опции, поэтому обновитесь перед использованием `setting_sources=[]`. Смотрите [Что settingSources не контролирует](/ru/agent-sdk/claude-code-features#what-settingsources-does-not-control) для входных данных, которые читаются даже когда `settingSources` равен `[]`.

258</Note>

259

260## Почему переименование?

261

262Claude Code SDK был первоначально разработан для задач кодирования, но он превратился в мощную платформу для создания всех типов AI-агентов. Новое имя "Claude Agent SDK" лучше отражает его возможности:

263

264* Создание бизнес-агентов (помощники по правовым вопросам, финансовые консультанты, поддержка клиентов)

265* Создание специализированных агентов кодирования (боты SRE, рецензенты безопасности, агенты проверки кода)

266* Разработка пользовательских агентов для любой области с использованием инструментов, интеграции MCP и многого другого

267

268## Получение помощи

269

270Если вы столкнулись с какими-либо проблемами во время миграции:

271

272**Для TypeScript/JavaScript:**

273

2741. Проверьте, что все импорты обновлены для использования `@anthropic-ai/claude-agent-sdk`

2752. Убедитесь, что ваш package.json содержит новое имя пакета

2763. Запустите `npm install`, чтобы убедиться, что зависимости обновлены

277

278**Для Python:**

279

2801. Проверьте, что все импорты обновлены для использования `claude_agent_sdk`

2812. Убедитесь, что ваш requirements.txt или pyproject.toml содержит новое имя пакета

2823. Запустите `pip install claude-agent-sdk`, чтобы убедиться, что пакет установлен

283

284## Следующие шаги

285

286* Изучите [Обзор Agent SDK](/ru/agent-sdk/overview), чтобы узнать о доступных функциях

287* Ознакомьтесь со [Справочником TypeScript SDK](/ru/agent-sdk/typescript) для подробной документации API

288* Просмотрите [Справочник Python SDK](/ru/agent-sdk/python) для документации, специфичной для Python

289* Узнайте о [Пользовательских инструментах](/ru/agent-sdk/custom-tools) и [Интеграции MCP](/ru/agent-sdk/mcp)

agent-sdk/permissions.md +242 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Настройка разрешений

7> Контролируйте использование инструментов вашим агентом с помощью режимов разрешений, hooks и декларативных правил allow/deny.

9Claude Agent SDK предоставляет элементы управления разрешениями для управления использованием инструментов Claude. Используйте режимы разрешений и правила для определения того, что разрешено автоматически, и callback [`canUseTool`](/ru/agent-sdk/user-input) для обработки всего остального во время выполнения.

11<Note>

12 На этой странице рассматриваются режимы разрешений и правила. Чтобы создать интерактивные потоки утверждения, где пользователи одобряют или отклоняют запросы инструментов во время выполнения, см. [Обработка утверждений и ввода пользователя](/ru/agent-sdk/user-input).

13</Note>

15## Как оцениваются разрешения

17Когда Claude запрашивает инструмент, SDK проверяет разрешения в следующем порядке:

19<Steps>

20 <Step title="Hooks">

21 Сначала запустите [hooks](/ru/agent-sdk/hooks). Hook может отклонить вызов полностью или передать его дальше. Hook, который возвращает `allow`, не пропускает правила deny и ask ниже; они оцениваются независимо от результата hook.

22 </Step>

24 <Step title="Правила deny">

25 Проверьте правила `deny` (из `disallowed_tools` и [settings.json](/ru/settings#permission-settings)). Если правило deny совпадает, инструмент блокируется, даже в режиме `bypassPermissions`.

26 </Step>

28 <Step title="Режим разрешений">

29 Примените активный [режим разрешений](#permission-modes). `bypassPermissions` одобряет всё, что достигает этого шага. `acceptEdits` одобряет операции с файлами. Другие режимы проходят дальше.

30 </Step>

32 <Step title="Правила allow">

33 Проверьте правила `allow` (из `allowed_tools` и settings.json). Если правило совпадает, инструмент одобрен.

34 </Step>

36 <Step title="Callback canUseTool">

37 Если не разрешено ни одним из вышеперечисленных, вызовите ваш callback [`canUseTool`](/ru/agent-sdk/user-input) для принятия решения. В режиме `dontAsk` этот шаг пропускается и инструмент отклоняется.

38 </Step>

39</Steps>

41<img src="https://mintcdn.com/claude-code/FEspvVUyRuaWjm0s/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=FEspvVUyRuaWjm0s&q=85&s=a1759b0cf4541281a9fdd8f5348228e8" alt="Диаграмма потока оценки разрешений" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

43На этой странице основное внимание уделяется **правилам allow и deny** и **режимам разрешений**. Для других шагов:

45* **Hooks:** запустите пользовательский код для разрешения, отклонения или изменения запросов инструментов. См. [Управление выполнением с помощью hooks](/ru/agent-sdk/hooks).

46* **Callback canUseTool:** запросите у пользователей утверждение во время выполнения. См. [Обработка утверждений и ввода пользователя](/ru/agent-sdk/user-input).

48## Правила allow и deny

50`allowed_tools` и `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) добавляют записи в списки правил allow и deny в потоке оценки выше. Они контролируют, одобрен ли вызов инструмента, а не доступен ли инструмент для Claude.

52| Опция | Эффект |

53| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ |

54| `allowed_tools=["Read", "Grep"]` | `Read` и `Grep` автоматически одобрены. Инструменты, не указанные здесь, всё ещё существуют и переходят к режиму разрешений и `canUseTool`. |

55| `disallowed_tools=["Bash"]` | `Bash` всегда отклоняется. Правила deny проверяются первыми и действуют в каждом режиме разрешений, включая `bypassPermissions`. |

57Для заблокированного агента объедините `allowedTools` с `permissionMode: "dontAsk"`. Указанные инструменты одобрены; всё остальное отклоняется полностью вместо запроса:

59```typescript theme={null}

60const options = {

61 allowedTools: ["Read", "Glob", "Grep"],

62 permissionMode: "dontAsk"

63};

64```

66<Warning>

67 **`allowed_tools` не ограничивает `bypassPermissions`.** `allowed_tools` только предварительно одобряет указанные вами инструменты. Неуказанные инструменты не совпадают ни с одним правилом allow и переходят к режиму разрешений, где `bypassPermissions` их одобряет. Установка `allowed_tools=["Read"]` вместе с `permission_mode="bypassPermissions"` всё ещё одобряет каждый инструмент, включая `Bash`, `Write` и `Edit`. Если вам нужен `bypassPermissions`, но вы хотите заблокировать определённые инструменты, используйте `disallowed_tools`.

68</Warning>

70Вы также можете настроить правила allow, deny и ask декларативно в `.claude/settings.json`. Эти правила читаются, когда включен источник параметра `project`, что происходит для параметров `query()` по умолчанию. Если вы явно установите `setting_sources` (TypeScript: `settingSources`), включите `"project"`, чтобы они применялись. См. [Параметры разрешений](/ru/settings#permission-settings) для синтаксиса правил.

72## Режимы разрешений

74Режимы разрешений обеспечивают глобальный контроль над использованием инструментов Claude. Вы можете установить режим разрешений при вызове `query()` или изменить его динамически во время сеансов потоковой передачи.

76### Доступные режимы

78SDK поддерживает эти режимы разрешений:

80| Режим | Описание | Поведение инструмента |

81| :------------------------- | :-------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------ |

82| `default` | Стандартное поведение разрешений | Без автоматических одобрений; несовпадающие инструменты запускают ваш callback `canUseTool` |

83| `dontAsk` | Отклонение вместо запроса | Всё, что не предварительно одобрено `allowed_tools` или правилами, отклоняется; `canUseTool` никогда не вызывается |

84| `acceptEdits` | Автоматическое принятие редактирования файлов | Редактирование файлов и [операции с файловой системой](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv` и т. д.) автоматически одобрены |

85| `bypassPermissions` | Обход всех проверок разрешений | Все инструменты работают без запросов разрешений (используйте с осторожностью) |

86| `plan` | Режим планирования | Инструменты только для чтения работают; Claude анализирует и планирует без редактирования исходных файлов |

87| `auto` (только TypeScript) | Одобрения, классифицированные моделью | Классификатор модели одобряет или отклоняет каждый вызов инструмента. См. [Режим Auto](/ru/permission-modes#eliminate-prompts-with-auto-mode) для доступности |

89<Warning>

90 **Наследование подагентом:** Когда родитель использует `bypassPermissions`, `acceptEdits` или `auto`, все подагенты наследуют этот режим и он не может быть переопределён для каждого подагента. Подагенты могут иметь различные системные подсказки и менее ограниченное поведение, чем ваш основной агент, поэтому наследование `bypassPermissions` предоставляет им полный автономный доступ к системе без каких-либо запросов утверждения.

91</Warning>

93### Установка режима разрешений

95Вы можете установить режим разрешений один раз при запуске запроса или изменить его динамически во время активного сеанса.

97<Tabs>

98 <Tab title="При запросе">

99 Передайте `permission_mode` (Python) или `permissionMode` (TypeScript) при создании запроса. Этот режим применяется для всего сеанса, если не изменён динамически.

100

101 <CodeGroup>

102 ```python Python theme={null}

103 import asyncio

104 from claude_agent_sdk import query, ClaudeAgentOptions

105

106

107 async def main():

108 async for message in query(

109 prompt="Help me refactor this code",

110 options=ClaudeAgentOptions(

111 permission_mode="default", # Установите режим здесь

112 ),

113 ):

114 if hasattr(message, "result"):

115 print(message.result)

116

117

118 asyncio.run(main())

119 ```

120

121 ```typescript TypeScript theme={null}

122 import { query } from "@anthropic-ai/claude-agent-sdk";

123

124 async function main() {

125 for await (const message of query({

126 prompt: "Help me refactor this code",

127 options: {

128 permissionMode: "default" // Установите режим здесь

129 }

130 })) {

131 if ("result" in message) {

132 console.log(message.result);

133 }

134 }

135 }

136

137 main();

138 ```

139 </CodeGroup>

140 </Tab>

141

142 <Tab title="Во время потоковой передачи">

143 Вызовите `set_permission_mode()` (Python) или `setPermissionMode()` (TypeScript) для изменения режима в середине сеанса. Новый режим вступает в силу немедленно для всех последующих запросов инструментов. Это позволяет вам начать с ограничительного режима и ослабить разрешения по мере развития доверия, например переключиться на `acceptEdits` после проверки первоначального подхода Claude.

144

145 <CodeGroup>

146 ```python Python theme={null}

147 import asyncio

148 from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

149

150

151 async def main():

152 async with ClaudeSDKClient(

153 options=ClaudeAgentOptions(

154 permission_mode="default", # Начните в режиме по умолчанию

155 )

156 ) as client:

157 await client.query("Help me refactor this code")

158

159 # Измените режим динамически в середине сеанса

160 await client.set_permission_mode("acceptEdits")

161

162 # Обработайте сообщения с новым режимом разрешений

163 async for message in client.receive_response():

164 if hasattr(message, "result"):

165 print(message.result)

166

167

168 asyncio.run(main())

169 ```

170

171 ```typescript TypeScript theme={null}

172 import { query } from "@anthropic-ai/claude-agent-sdk";

173

174 async function main() {

175 const q = query({

176 prompt: "Help me refactor this code",

177 options: {

178 permissionMode: "default" // Начните в режиме по умолчанию

179 }

180 });

181

182 // Измените режим динамически в середине сеанса

183 await q.setPermissionMode("acceptEdits");

184

185 // Обработайте сообщения с новым режимом разрешений

186 for await (const message of q) {

187 if ("result" in message) {

188 console.log(message.result);

189 }

190 }

191 }

192

193 main();

194 ```

195 </CodeGroup>

196 </Tab>

197</Tabs>

198

199### Детали режимов

200

201#### Режим принятия редактирования (`acceptEdits`)

202

203Автоматически одобряет операции с файлами, чтобы Claude мог редактировать код без запроса. Другие инструменты (например, команды Bash, которые не являются операциями с файловой системой) по-прежнему требуют обычных разрешений.

204

205**Автоматически одобренные операции:**

206

207* Редактирование файлов (инструменты Edit, Write)

208* Команды файловой системы: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`

209

210Оба применяются только к путям внутри рабочего каталога или `additionalDirectories`. Пути вне этой области и записи в защищённые пути по-прежнему запрашивают разрешение.

211

212**Используйте, когда:** вы доверяете редактированию Claude и хотите более быстрой итерации, например во время прототипирования или при работе в изолированном каталоге.

213

214#### Режим без запроса (`dontAsk`)

215

216Преобразует любой запрос разрешения в отклонение. Инструменты, предварительно одобренные `allowed_tools`, правилами allow в `settings.json` или hook, работают нормально. Всё остальное отклоняется без вызова `canUseTool`.

217

218**Используйте, когда:** вы хотите фиксированную, явную поверхность инструментов для автономного агента и предпочитаете жёсткое отклонение молчаливому полаганию на отсутствие `canUseTool`.

219

220#### Режим обхода разрешений (`bypassPermissions`)

221

222Автоматически одобряет все использования инструментов без запросов. Hooks всё ещё выполняются и могут блокировать операции при необходимости.

223

224<Warning>

225 Используйте с крайней осторожностью. Claude имеет полный доступ к системе в этом режиме. Используйте только в контролируемых средах, где вы доверяете всем возможным операциям.

226

227 `allowed_tools` не ограничивает этот режим. Каждый инструмент одобрен, а не только те, которые вы указали. Правила deny (`disallowed_tools`), явные правила `ask` и hooks оцениваются перед проверкой режима и всё ещё могут заблокировать инструмент.

228</Warning>

229

230#### Режим планирования (`plan`)

231

232Ограничивает Claude инструментами только для чтения. Claude может читать файлы и запускать команды оболочки только для чтения для изучения кодовой базы, но не редактирует исходные файлы. Claude может использовать `AskUserQuestion` для уточнения требований перед завершением плана. См. [Обработка утверждений и ввода пользователя](/ru/agent-sdk/user-input#handle-clarifying-questions) для обработки этих запросов.

233

234**Используйте, когда:** вы хотите, чтобы Claude предложил изменения без их выполнения, например при проверке кода или когда вам нужно одобрить изменения перед их внесением.

235

236## Связанные ресурсы

237

238Для других шагов в потоке оценки разрешений:

239

240* [Обработка утверждений и ввода пользователя](/ru/agent-sdk/user-input): интерактивные запросы утверждения и уточняющие вопросы

241* [Руководство по hooks](/ru/agent-sdk/hooks): запуск пользовательского кода в ключевых точках жизненного цикла агента

242* [Правила разрешений](/ru/settings#permission-settings): декларативные правила allow/deny в `settings.json`

agent-sdk/python.md +39 −37

Details

113#### Параметры113#### Параметры

114 114

115| Параметр | Тип | Описание |115| Параметр | Тип | Описание |

116| :------------- | :----------------------------------------------- | :------------------------------------------------------------------------------ |116| :------------- | :---------------------------------------------- | :------------------------------------------------------------------------------ |

117| `name` | `str` | Уникальный идентификатор инструмента |117| `name` | `str` | Уникальный идентификатор инструмента |

118| `description` | `str` | Понятное описание того, что делает инструмент |118| `description` | `str` | Понятное описание того, что делает инструмент |

121 121

122#### Варианты схемы ввода122#### Варианты схемы ввода

123 123

250#### Параметры250#### Параметры

251 251

252| Параметр | Тип | По умолчанию | Описание |252| Параметр | Тип | По умолчанию | Описание |

253| :------------------ | :------------ | :----------- | :------------------------------------------------------------------------------------------ |253| :------------------ | :------------ | :----------- | :------------------------------------------------------------------------------------------- |

257 257

258#### Тип возвращаемого значения: `SDKSessionInfo`258#### Тип возвращаемого значения: `SDKSessionInfo`

259 259

269| `cwd` | `str \| None` | Рабочий каталог для сеанса |269| `cwd` | `str \| None` | Рабочий каталог для сеанса |

270| `tag` | `str \| None` | Тег сеанса, установленный пользователем (см. [`tag_session()`](#tag-session)) |270| `tag` | `str \| None` | Тег сеанса, установленный пользователем (см. [`tag_session()`](#tag_session)) |

272 272

273#### Пример273#### Пример

345 345

346Возвращает [`SDKSessionInfo`](#return-type-sdk-session-info) или `None`, если сеанс не найден.346Возвращает [`SDKSessionInfo`](#return-type-sdksessioninfo) или `None`, если сеанс не найден.

347 347

348#### Пример348#### Пример

349 349

381 381

382#### Пример382#### Пример

383 383

384Переименуйте самый последний сеанс, чтобы его было легче найти позже. Новое название появляется в [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) при последующих чтениях.384Переименуйте самый последний сеанс, чтобы его было легче найти позже. Новое название появляется в [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo) при последующих чтениях.

385 385

386```python theme={null}386```python theme={null}

387from claude_agent_sdk import list_sessions, rename_session387from claude_agent_sdk import list_sessions, rename_session

478| `rewind_files(user_message_id)` | Восстановите файлы в их состояние в указанном пользовательском сообщении. Требует `enable_file_checkpointing=True`. См. [File checkpointing](/ru/agent-sdk/file-checkpointing) |478| `rewind_files(user_message_id)` | Восстановите файлы в их состояние в указанном пользовательском сообщении. Требует `enable_file_checkpointing=True`. См. [File checkpointing](/ru/agent-sdk/file-checkpointing) |

479| `get_mcp_status()` | Получите статус всех настроенных MCP servers. Возвращает [`McpStatusResponse`](#mcp-status-response) |479| `get_mcp_status()` | Получите статус всех настроенных MCP servers. Возвращает [`McpStatusResponse`](#mcpstatusresponse) |

481| `toggle_mcp_server(server_name, enabled)` | Включите или отключите MCP server в середине сеанса. Отключение удаляет его инструменты |481| `toggle_mcp_server(server_name, enabled)` | Включите или отключите MCP server в середине сеанса. Отключение удаляет его инструменты |

482| `stop_task(task_id)` | Остановите выполняющуюся фоновую задачу. [`TaskNotificationMessage`](#task-notification-message) со статусом `"stopped"` следует в потоке сообщений |482| `stop_task(task_id)` | Остановите выполняющуюся фоновую задачу. [`TaskNotificationMessage`](#tasknotificationmessage) со статусом `"stopped"` следует в потоке сообщений |

485 485

791 effort: Literal["low", "medium", "high", "max"] | None = None791 effort: Literal["low", "medium", "high", "max"] | None = None

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None793 session_store: SessionStore | None = None

794 session_store_flush: SessionStoreFlushMode = "batched"

794```795```

795 796

796| Свойство | Тип | По умолчанию | Описание |797| Свойство | Тип | По умолчанию | Описание |

797| :---------------------------- | :------------------------------------------------------------------------------------- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |798| :---------------------------- | :------------------------------------------------------------------------------------ | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Конфигурация инструментов. Используйте `{"type": "preset", "preset": "claude_code"}` для инструментов Claude Code по умолчанию |799| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Конфигурация инструментов. Используйте `{"type": "preset", "preset": "claude_code"}` для инструментов Claude Code по умолчанию |

799| `allowed_tools` | `list[str]` | `[]` | Инструменты для автоматического одобрения без запроса. Это не ограничивает Claude только этими инструментами; неуказанные инструменты переходят к `permission_mode` и `can_use_tool`. Используйте `disallowed_tools` для блокировки инструментов. См. [Permissions](/ru/agent-sdk/permissions#allow-and-deny-rules) |800| `allowed_tools` | `list[str]` | `[]` | Инструменты для автоматического одобрения без запроса. Это не ограничивает Claude только этими инструментами; неуказанные инструменты переходят к `permission_mode` и `can_use_tool`. Используйте `disallowed_tools` для блокировки инструментов. См. [Permissions](/ru/agent-sdk/permissions#allow-and-deny-rules) |

800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Конфигурация системной подсказки. Передайте строку для пользовательской подсказки или используйте `{"type": "preset", "preset": "claude_code"}` для системной подсказки Claude Code. Добавьте `"append"` для расширения предустановки |801| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Конфигурация системной подсказки. Передайте строку для пользовательской подсказки или используйте `{"type": "preset", "preset": "claude_code"}` для системной подсказки Claude Code. Добавьте `"append"` для расширения предустановки |

812| `output_format` | `dict[str, Any] \| None` | `None` | Формат вывода для структурированных ответов (например, `{"type": "json_schema", "schema": {...}}`). См. [Structured outputs](/ru/agent-sdk/structured-outputs) для деталей |813| `output_format` | `dict[str, Any] \| None` | `None` | Формат вывода для структурированных ответов (например, `{"type": "json_schema", "schema": {...}}`). См. [Structured outputs](/ru/agent-sdk/structured-outputs) для деталей |

814| `cwd` | `str \| Path \| None` | `None` | Текущий рабочий каталог |815| `cwd` | `str \| Path \| None` | `None` | Текущий рабочий каталог |

831| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Контролируйте, какие параметры файловой системы загружать. Передайте `[]` для отключения пользовательских, проектных и локальных параметров. Управляемые параметры политики загружаются независимо. См. [Use Claude Code features](/ru/agent-sdk/claude-code-features#what-settingsources-does-not-control) |832| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Контролируйте, какие параметры файловой системы загружать. Передайте `[]` для отключения пользовательских, проектных и локальных параметров. Управляемые параметры политики загружаются независимо. См. [Use Claude Code features](/ru/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

835| `session_store` | [`SessionStore`](/ru/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | Зеркалируйте стенограммы сеансов во внешний бэкэнд, чтобы любой хост мог их возобновить. См. [Persist sessions to external storage](/ru/agent-sdk/session-storage) |836| `session_store` | [`SessionStore`](/ru/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Зеркалируйте стенограммы сеансов во внешний бэкэнд, чтобы любой хост мог их возобновить. См. [Persist sessions to external storage](/ru/agent-sdk/session-storage) |

837| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Когда сбрасывать записи зеркальной стенограммы в `session_store`. `"batched"` сбрасывает один раз за ход или когда буфер заполняется; `"eager"` запускает фоновый сброс после каждого кадра. Игнорируется, когда `session_store` равен `None` |

836 838

837### `OutputFormat`839### `OutputFormat`

838 840

1031| `maxTurns` | Нет | Максимальное количество агентских ходов перед остановкой агента |1033| `maxTurns` | Нет | Максимальное количество агентских ходов перед остановкой агента |

1032| `background` | Нет | Запустите этого агента как неблокирующую фоновую задачу при вызове |1034| `background` | Нет | Запустите этого агента как неблокирующую фоновую задачу при вызове |

1033| `effort` | Нет | Уровень усилий рассуждения для этого агента. Принимает именованный уровень или целое число |1035| `effort` | Нет | Уровень усилий рассуждения для этого агента. Принимает именованный уровень или целое число |

1034| `permissionMode` | Нет | Режим разрешений для выполнения инструментов в этом агенте. См. [`PermissionMode`](#permission-mode) |1036| `permissionMode` | Нет | Режим разрешений для выполнения инструментов в этом агенте. См. [`PermissionMode`](#permissionmode) |

1035 1037

1036<Note>1038<Note>

1037 Имена полей `AgentDefinition` используют camelCase, такие как `disallowedTools`, `permissionMode` и `maxTurns`. Эти имена напрямую соответствуют формату проводки, общему с TypeScript SDK. Это отличается от `ClaudeAgentOptions`, который использует Python snake\_case для эквивалентных полей верхнего уровня, таких как `disallowed_tools` и `permission_mode`. Поскольку `AgentDefinition` является dataclass, передача ключевого слова snake\_case вызывает `TypeError` во время конструирования.1039 Имена полей `AgentDefinition` используют camelCase, такие как `disallowedTools`, `permissionMode` и `maxTurns`. Эти имена напрямую соответствуют формату проводки, общему с TypeScript SDK. Это отличается от `ClaudeAgentOptions`, который использует Python snake\_case для эквивалентных полей верхнего уровня, таких как `disallowed_tools` и `permission_mode`. Поскольку `AgentDefinition` является dataclass, передача ключевого слова snake\_case вызывает `TypeError` во время конструирования.

1045PermissionMode = Literal[1047PermissionMode = Literal[

1046 "default", # Standard permission behavior1048 "default", # Standard permission behavior

1047 "acceptEdits", # Auto-accept file edits1049 "acceptEdits", # Auto-accept file edits

1048 "plan", # Planning mode - no execution1050 "plan", # Planning mode - read-only tools only

1049 "dontAsk", # Deny anything not pre-approved instead of prompting1051 "dontAsk", # Deny anything not pre-approved instead of prompting

1050 "bypassPermissions", # Bypass all permission checks (use with caution)1052 "bypassPermissions", # Bypass all permission checks (use with caution)

1051]1053]

1081```1083```

1082 1084

1083| Поле | Тип | Описание |1085| Поле | Тип | Описание |

1084| :------------ | :----------------------- | :------------------------------------------------------- |1086| :------------ | :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1086| `suggestions` | `list[PermissionUpdate]` | Предложения обновления разрешений из CLI |1088| `suggestions` | `list[PermissionUpdate]` | Предложения обновления разрешений из CLI. Подсказки Bash включают предложение с назначением `localSettings`, поэтому возврат его в `updated_permissions` записывает правило в `.claude/settings.local.json` и сохраняется между сеансами. |

1087 1089

1088### `PermissionResult`1090### `PermissionResult`

1089 1091

1289 1291

1290### `McpServerStatusConfig`1292### `McpServerStatusConfig`

1291 1293

1292Конфигурация MCP server, как сообщается [`get_mcp_status()`](#methods). Это объединение всех вариантов транспорта [`McpServerConfig`](#mcp-server-config) плюс вариант `claudeai-proxy` только для вывода для servers, проксированных через claude.ai.1294Конфигурация MCP server, как сообщается [`get_mcp_status()`](#methods). Это объединение всех вариантов транспорта [`McpServerConfig`](#mcpserverconfig) плюс вариант `claudeai-proxy` только для вывода для servers, проксированных через claude.ai.

1293 1295

1294```python theme={null}1296```python theme={null}

1295McpServerStatusConfig = (1297McpServerStatusConfig = (

1301)1303)

1302```1304```

1303 1305

1304`McpSdkServerConfigStatus` - это сериализуемая форма [`McpSdkServerConfig`](#mcp-sdk-server-config) с только полями `type` (`"sdk"`) и `name` (`str`); встроенный `instance` опущен. `McpClaudeAIProxyServerConfig` имеет поля `type` (`"claudeai-proxy"`), `url` (`str`) и `id` (`str`).1306`McpSdkServerConfigStatus` - это сериализуемая форма [`McpSdkServerConfig`](#mcpsdkserverconfig) с только полями `type` (`"sdk"`) и `name` (`str`); встроенный `instance` опущен. `McpClaudeAIProxyServerConfig` имеет поля `type` (`"claudeai-proxy"`), `url` (`str`) и `id` (`str`).

1305 1307

1306### `McpStatusResponse`1308### `McpStatusResponse`

1307 1309

1314 1316

1315### `McpServerStatus`1317### `McpServerStatus`

1316 1318

1317Статус подключенного MCP server, содержащийся в [`McpStatusResponse`](#mcp-status-response).1319Статус подключенного MCP server, содержащийся в [`McpStatusResponse`](#mcpstatusresponse).

1318 1320

1319```python theme={null}1321```python theme={null}

1320class McpServerStatus(TypedDict):1322class McpServerStatus(TypedDict):

1328```1330```

1329 1331

1330| Поле | Тип | Описание |1332| Поле | Тип | Описание |

1331| :----------- | :----------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1333| :----------- | :-------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1332| `name` | `str` | Имя сервера |1334| `name` | `str` | Имя сервера |

1333| `status` | `str` | Один из `"connected"`, `"failed"`, `"needs-auth"`, `"pending"` или `"disabled"` |1335| `status` | `str` | Один из `"connected"`, `"failed"`, `"needs-auth"`, `"pending"` или `"disabled"` |

1334| `serverInfo` | `dict` (опционально) | Имя и версия сервера (`{"name": str, "version": str}`) |1336| `serverInfo` | `dict` (опционально) | Имя и версия сервера (`{"name": str, "version": str}`) |

1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (опционально) | Конфигурация сервера. Та же форма, что и [`McpServerConfig`](#mcp-server-config) (stdio, SSE, HTTP или SDK), плюс вариант `claudeai-proxy` для servers, подключенных через claude.ai |1338| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (опционально) | Конфигурация сервера. Та же форма, что и [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP или SDK), плюс вариант `claudeai-proxy` для servers, подключенных через claude.ai |

1339 1341

1416```1418```

1417 1419

1418| Поле | Тип | Описание |1420| Поле | Тип | Описание |

1419| :------------------- | :------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------- |1421| :------------------- | :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------- |

1421| `model` | `str` | Модель, которая создала ответ |1423| `model` | `str` | Модель, которая создала ответ |

1426 1428

1427### `AssistantMessageError`1429### `AssistantMessageError`

1481| `cache_creation_input_tokens` | `int` | Токены, используемые для создания новых записей кэша. |1483| `cache_creation_input_tokens` | `int` | Токены, используемые для создания новых записей кэша. |

1482| `cache_read_input_tokens` | `int` | Токены, прочитанные из существующих записей кэша. |1484| `cache_read_input_tokens` | `int` | Токены, прочитанные из существующих записей кэша. |

1483 1485

1484Словарь `model_usage` отображает имена моделей на использование для каждой модели. Внутренние ключи словаря используют camelCase, потому что значение передается без изменений из базового процесса CLI, соответствуя типу TypeScript [`ModelUsage`](/ru/agent-sdk/typescript#model-usage):1486Словарь `model_usage` отображает имена моделей на использование для каждой модели. Внутренние ключи словаря используют camelCase, потому что значение передается без изменений из базового процесса CLI, соответствуя типу TypeScript [`ModelUsage`](/ru/agent-sdk/typescript#modelusage):

1485 1487

1486| Ключ | Тип | Описание |1488| Ключ | Тип | Описание |

1487| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |1489| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1527```1529```

1528 1530

1529| Поле | Тип | Описание |1531| Поле | Тип | Описание |

1530| :---------------- | :---------------------------------- | :------------------------------------- |1532| :---------------- | :-------------------------------- | :------------------------------------- |

1532| `uuid` | `str` | Уникальный идентификатор события |1534| `uuid` | `str` | Уникальный идентификатор события |

1533| `session_id` | `str` | Идентификатор сеанса |1535| `session_id` | `str` | Идентификатор сеанса |

1534 1536

1535### `RateLimitInfo`1537### `RateLimitInfo`

1536 1538

1537Состояние ограничения скорости, переносимое [`RateLimitEvent`](#rate-limit-event).1539Состояние ограничения скорости, переносимое [`RateLimitEvent`](#ratelimitevent).

1538 1540

1539```python theme={null}1541```python theme={null}

1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]1542RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]

1812 1814

1813Параметры:1815Параметры:

1814 1816

1815* `input`: Строго типизированный ввод hooks с дискриминированными объединениями на основе `hook_event_name` (см. [`HookInput`](#hook-input))1817* `input`: Строго типизированный ввод hooks с дискриминированными объединениями на основе `hook_event_name` (см. [`HookInput`](#hookinput))

1816* `tool_use_id`: Дополнительный идентификатор использования инструмента (для hooks, связанных с инструментами)1818* `tool_use_id`: Дополнительный идентификатор использования инструмента (для hooks, связанных с инструментами)

1817* `context`: Контекст hooks с дополнительной информацией1819* `context`: Контекст hooks с дополнительной информацией

1818 1820

1819Возвращает [`HookJSONOutput`](#hook-json-output), который может содержать:1821Возвращает [`HookJSONOutput`](#hookjsonoutput), который может содержать:

1820 1822

1821* `decision`: `"block"` для блокировки действия1823* `decision`: `"block"` для блокировки действия

1822* `systemMessage`: Системное сообщение для добавления в стенограмму1824* `systemMessage`: Системное сообщение для добавления в стенограмму

3109```3111```

3110 3112

3111| Свойство | Тип | По умолчанию | Описание |3113| Свойство | Тип | По умолчанию | Описание |

3112| :-------------------------- | :------------------------------------------------------ | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3114| :-------------------------- | :---------------------------------------------------- | :----------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3116| `allowUnsandboxedCommands` | `bool` | `True` | Разрешить модели запрашивать выполнение команд вне sandbox. Когда `True`, модель может установить `dangerouslyDisableSandbox` в входе инструмента, что переходит к [системе разрешений](#permissions-fallback-for-unsandboxed-commands) |3118| `allowUnsandboxedCommands` | `bool` | `True` | Разрешить модели запрашивать выполнение команд вне sandbox. Когда `True`, модель может установить `dangerouslyDisableSandbox` в входе инструмента, что переходит к [системе разрешений](#permissions-fallback-for-unsandboxed-commands) |

3120 3122

3121#### Пример использования3123#### Пример использования

agent-sdk/streaming-output.md +396 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Потоковая передача ответов в реальном времени

7> Получайте ответы в реальном времени от Agent SDK по мере поступления текста и вызовов инструментов

9По умолчанию Agent SDK выдает полные объекты `AssistantMessage` после того, как Claude завершит генерацию каждого ответа. Чтобы получать добавочные обновления по мере генерации текста и вызовов инструментов, включите потоковую передачу частичных сообщений, установив `include_partial_messages` (Python) или `includePartialMessages` (TypeScript) в значение `true` в ваших параметрах.

11<Tip>

12 На этой странице рассматривается потоковая передача выходных данных (получение токенов в реальном времени). Для режимов ввода (как вы отправляете сообщения), см. [Отправка сообщений агентам](/ru/agent-sdk/streaming-vs-single-mode). Вы также можете [передавать ответы потоком с помощью Agent SDK через CLI](/ru/headless).

13</Tip>

15## Включение потоковой передачи выходных данных

17Чтобы включить потоковую передачу, установите `include_partial_messages` (Python) или `includePartialMessages` (TypeScript) в значение `true` в ваших параметрах. Это заставляет SDK выдавать сообщения `StreamEvent`, содержащие необработанные события API по мере их поступления, в дополнение к обычным `AssistantMessage` и `ResultMessage`.

19Ваш код затем должен:

211. Проверить тип каждого сообщения, чтобы отличить `StreamEvent` от других типов сообщений

222. Для `StreamEvent` извлечь поле `event` и проверить его `type`

233. Искать события `content_block_delta`, где `delta.type` — это `text_delta`, которые содержат фактические текстовые фрагменты

25Пример ниже включает потоковую передачу и выводит текстовые фрагменты по мере их поступления. Обратите внимание на вложенные проверки типов: сначала для `StreamEvent`, затем для `content_block_delta`, затем для `text_delta`:

27<CodeGroup>

28 ```python Python theme={null}

29 from claude_agent_sdk import query, ClaudeAgentOptions

30 from claude_agent_sdk.types import StreamEvent

31 import asyncio

34 async def stream_response():

35 options = ClaudeAgentOptions(

36 include_partial_messages=True,

37 allowed_tools=["Bash", "Read"],

38 )

40 async for message in query(prompt="List the files in my project", options=options):

41 if isinstance(message, StreamEvent):

42 event = message.event

43 if event.get("type") == "content_block_delta":

44 delta = event.get("delta", {})

45 if delta.get("type") == "text_delta":

46 print(delta.get("text", ""), end="", flush=True)

49 asyncio.run(stream_response())

50 ```

52 ```typescript TypeScript theme={null}

53 import { query } from "@anthropic-ai/claude-agent-sdk";

55 for await (const message of query({

56 prompt: "List the files in my project",

57 options: {

58 includePartialMessages: true,

59 allowedTools: ["Bash", "Read"]

60 }

61 })) {

62 if (message.type === "stream_event") {

63 const event = message.event;

64 if (event.type === "content_block_delta") {

65 if (event.delta.type === "text_delta") {

66 process.stdout.write(event.delta.text);

67 }

68 }

69 }

70 }

71 ```

72</CodeGroup>

74## Справочник StreamEvent

76Когда включены частичные сообщения, вы получаете необработанные события потоковой передачи Claude API, завернутые в объект. Тип имеет разные имена в каждом SDK:

78* **Python**: `StreamEvent` (импортируется из `claude_agent_sdk.types`)

79* **TypeScript**: `SDKPartialAssistantMessage` с `type: 'stream_event'`

81Оба содержат необработанные события Claude API, а не накопленный текст. Вам нужно самостоятельно извлекать и накапливать текстовые дельты. Вот структура каждого типа:

83<CodeGroup>

84 ```python Python theme={null}

85 @dataclass

86 class StreamEvent:

87 uuid: str # Unique identifier for this event

88 session_id: str # Session identifier

89 event: dict[str, Any] # The raw Claude API stream event

90 parent_tool_use_id: str | None # Parent tool ID if from a subagent

91 ```

93 ```typescript TypeScript theme={null}

94 type SDKPartialAssistantMessage = {

95 type: "stream_event";

96 event: BetaRawMessageStreamEvent; // From Anthropic SDK

97 parent_tool_use_id: string | null;

98 uuid: UUID;

99 session_id: string;

100 };

101 ```

102</CodeGroup>

103

104Поле `event` содержит необработанное событие потоковой передачи из [Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types). Распространенные типы событий включают:

105

106| Тип события | Описание |

107| :-------------------- | :-------------------------------------------------------------------- |

108| `message_start` | Начало нового сообщения |

109| `content_block_start` | Начало нового блока содержимого (текст или использование инструмента) |

110| `content_block_delta` | Добавочное обновление содержимого |

111| `content_block_stop` | Конец блока содержимого |

112| `message_delta` | Обновления на уровне сообщения (причина остановки, использование) |

113| `message_stop` | Конец сообщения |

114

115## Поток сообщений

116

117С включенными частичными сообщениями вы получаете сообщения в этом порядке:

118

119```text theme={null}

120StreamEvent (message_start)

121StreamEvent (content_block_start) - text block

122StreamEvent (content_block_delta) - text chunks...

123StreamEvent (content_block_stop)

124StreamEvent (content_block_start) - tool_use block

125StreamEvent (content_block_delta) - tool input chunks...

126StreamEvent (content_block_stop)

127StreamEvent (message_delta)

128StreamEvent (message_stop)

129AssistantMessage - complete message with all content

130... tool executes ...

131... more streaming events for next turn ...

132ResultMessage - final result

133```

134

135Без включенных частичных сообщений (`include_partial_messages` в Python, `includePartialMessages` в TypeScript) вы получаете все типы сообщений, кроме `StreamEvent`. Распространенные типы включают `SystemMessage` (инициализация сеанса), `AssistantMessage` (полные ответы), `ResultMessage` (финальный результат) и компактное граничное сообщение, указывающее на то, когда история разговора была сжата (`SDKCompactBoundaryMessage` в TypeScript; `SystemMessage` с подтипом `"compact_boundary"` в Python).

136

137## Потоковая передача текстовых ответов

138

139Чтобы отобразить текст по мере его генерации, ищите события `content_block_delta`, где `delta.type` — это `text_delta`. Они содержат добавочные текстовые фрагменты. Пример ниже выводит каждый фрагмент по мере его поступления:

140

141<CodeGroup>

142 ```python Python theme={null}

143 from claude_agent_sdk import query, ClaudeAgentOptions

144 from claude_agent_sdk.types import StreamEvent

145 import asyncio

146

147

148 async def stream_text():

149 options = ClaudeAgentOptions(include_partial_messages=True)

150

151 async for message in query(prompt="Explain how databases work", options=options):

152 if isinstance(message, StreamEvent):

153 event = message.event

154 if event.get("type") == "content_block_delta":

155 delta = event.get("delta", {})

156 if delta.get("type") == "text_delta":

157 # Print each text chunk as it arrives

158 print(delta.get("text", ""), end="", flush=True)

159

160 print() # Final newline

161

162

163 asyncio.run(stream_text())

164 ```

165

166 ```typescript TypeScript theme={null}

167 import { query } from "@anthropic-ai/claude-agent-sdk";

168

169 for await (const message of query({

170 prompt: "Explain how databases work",

171 options: { includePartialMessages: true }

172 })) {

173 if (message.type === "stream_event") {

174 const event = message.event;

175 if (event.type === "content_block_delta" && event.delta.type === "text_delta") {

176 process.stdout.write(event.delta.text);

177 }

178 }

179 }

180

181 console.log(); // Final newline

182 ```

183</CodeGroup>

184

185## Потоковая передача вызовов инструментов

186

187Вызовы инструментов также передаются потоком добавочно. Вы можете отследить, когда инструменты начинают работу, получить их входные данные по мере их генерации и увидеть, когда они завершаются. Пример ниже отслеживает текущий вызываемый инструмент и накапливает входные данные JSON по мере их поступления. Он использует три типа событий:

188

189* `content_block_start`: инструмент начинает работу

190* `content_block_delta` с `input_json_delta`: поступают фрагменты входных данных

191* `content_block_stop`: вызов инструмента завершен

192

193<CodeGroup>

194 ```python Python theme={null}

195 from claude_agent_sdk import query, ClaudeAgentOptions

196 from claude_agent_sdk.types import StreamEvent

197 import asyncio

198

199

200 async def stream_tool_calls():

201 options = ClaudeAgentOptions(

202 include_partial_messages=True,

203 allowed_tools=["Read", "Bash"],

204 )

205

206 # Track the current tool and accumulate its input JSON

207 current_tool = None

208 tool_input = ""

209

210 async for message in query(prompt="Read the README.md file", options=options):

211 if isinstance(message, StreamEvent):

212 event = message.event

213 event_type = event.get("type")

214

215 if event_type == "content_block_start":

216 # New tool call is starting

217 content_block = event.get("content_block", {})

218 if content_block.get("type") == "tool_use":

219 current_tool = content_block.get("name")

220 tool_input = ""

221 print(f"Starting tool: {current_tool}")

222

223 elif event_type == "content_block_delta":

224 delta = event.get("delta", {})

225 if delta.get("type") == "input_json_delta":

226 # Accumulate JSON input as it streams in

227 chunk = delta.get("partial_json", "")

228 tool_input += chunk

229 print(f" Input chunk: {chunk}")

230

231 elif event_type == "content_block_stop":

232 # Tool call complete - show final input

233 if current_tool:

234 print(f"Tool {current_tool} called with: {tool_input}")

235 current_tool = None

236

237

238 asyncio.run(stream_tool_calls())

239 ```

240

241 ```typescript TypeScript theme={null}

242 import { query } from "@anthropic-ai/claude-agent-sdk";

243

244 // Track the current tool and accumulate its input JSON

245 let currentTool: string | null = null;

246 let toolInput = "";

247

248 for await (const message of query({

249 prompt: "Read the README.md file",

250 options: {

251 includePartialMessages: true,

252 allowedTools: ["Read", "Bash"]

253 }

254 })) {

255 if (message.type === "stream_event") {

256 const event = message.event;

257

258 if (event.type === "content_block_start") {

259 // New tool call is starting

260 if (event.content_block.type === "tool_use") {

261 currentTool = event.content_block.name;

262 toolInput = "";

263 console.log(`Starting tool: ${currentTool}`);

264 }

265 } else if (event.type === "content_block_delta") {

266 if (event.delta.type === "input_json_delta") {

267 // Accumulate JSON input as it streams in

268 const chunk = event.delta.partial_json;

269 toolInput += chunk;

270 console.log(` Input chunk: ${chunk}`);

271 }

272 } else if (event.type === "content_block_stop") {

273 // Tool call complete - show final input

274 if (currentTool) {

275 console.log(`Tool ${currentTool} called with: ${toolInput}`);

276 currentTool = null;

277 }

278 }

279 }

280 }

281 ```

282</CodeGroup>

283

284## Создание пользовательского интерфейса потоковой передачи

285

286Этот пример объединяет потоковую передачу текста и инструментов в единый пользовательский интерфейс. Он отслеживает, выполняет ли агент в настоящее время инструмент (используя флаг `in_tool`), чтобы показать индикаторы состояния, такие как `[Using Read...]`, пока работают инструменты. Текст передается потоком нормально, когда инструмент не используется, а завершение инструмента вызывает сообщение "done". Этот паттерн полезен для интерфейсов чата, которым нужно показывать прогресс во время многошаговых задач агента.

287

288<CodeGroup>

289 ```python Python theme={null}

290 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

291 from claude_agent_sdk.types import StreamEvent

292 import asyncio

293 import sys

294

295

296 async def streaming_ui():

297 options = ClaudeAgentOptions(

298 include_partial_messages=True,

299 allowed_tools=["Read", "Bash", "Grep"],

300 )

301

302 # Track whether we're currently in a tool call

303 in_tool = False

304

305 async for message in query(

306 prompt="Find all TODO comments in the codebase", options=options

307 ):

308 if isinstance(message, StreamEvent):

309 event = message.event

310 event_type = event.get("type")

311

312 if event_type == "content_block_start":

313 content_block = event.get("content_block", {})

314 if content_block.get("type") == "tool_use":

315 # Tool call is starting - show status indicator

316 tool_name = content_block.get("name")

317 print(f"\n[Using {tool_name}...]", end="", flush=True)

318 in_tool = True

319

320 elif event_type == "content_block_delta":

321 delta = event.get("delta", {})

322 # Only stream text when not executing a tool

323 if delta.get("type") == "text_delta" and not in_tool:

324 sys.stdout.write(delta.get("text", ""))

325 sys.stdout.flush()

326

327 elif event_type == "content_block_stop":

328 if in_tool:

329 # Tool call finished

330 print(" done", flush=True)

331 in_tool = False

332

333 elif isinstance(message, ResultMessage):

334 # Agent finished all work

335 print(f"\n\n--- Complete ---")

336

337

338 asyncio.run(streaming_ui())

339 ```

340

341 ```typescript TypeScript theme={null}

342 import { query } from "@anthropic-ai/claude-agent-sdk";

343

344 // Track whether we're currently in a tool call

345 let inTool = false;

346

347 for await (const message of query({

348 prompt: "Find all TODO comments in the codebase",

349 options: {

350 includePartialMessages: true,

351 allowedTools: ["Read", "Bash", "Grep"]

352 }

353 })) {

354 if (message.type === "stream_event") {

355 const event = message.event;

356

357 if (event.type === "content_block_start") {

358 if (event.content_block.type === "tool_use") {

359 // Tool call is starting - show status indicator

360 process.stdout.write(`\n[Using ${event.content_block.name}...]`);

361 inTool = true;

362 }

363 } else if (event.type === "content_block_delta") {

364 // Only stream text when not executing a tool

365 if (event.delta.type === "text_delta" && !inTool) {

366 process.stdout.write(event.delta.text);

367 }

368 } else if (event.type === "content_block_stop") {

369 if (inTool) {

370 // Tool call finished

371 console.log(" done");

372 inTool = false;

373 }

374 }

375 } else if (message.type === "result") {

376 // Agent finished all work

377 console.log("\n\n--- Complete ---");

378 }

379 }

380 ```

381</CodeGroup>

382

383## Известные ограничения

384

385Некоторые функции SDK несовместимы с потоковой передачей:

386

387* **Extended thinking**: когда вы явно устанавливаете `max_thinking_tokens` (Python) или `maxThinkingTokens` (TypeScript), сообщения `StreamEvent` не выдаются. Вы будете получать только полные сообщения после каждого хода. Обратите внимание, что мышление отключено по умолчанию в SDK, поэтому потоковая передача работает, если вы его не включите.

388* **Structured output**: результат JSON появляется только в финальном `ResultMessage.structured_output`, а не как потоковые дельты. Подробнее см. в разделе [структурированные выходные данные](/ru/agent-sdk/structured-outputs).

389

390## Следующие шаги

391

392Теперь, когда вы можете передавать текст и вызовы инструментов потоком в реальном времени, изучите эти связанные темы:

393

394* [Интерактивные и одноразовые запросы](/ru/agent-sdk/streaming-vs-single-mode): выберите режим ввода для вашего случая использования

395* [Структурированные выходные данные](/ru/agent-sdk/structured-outputs): получайте типизированные ответы JSON от агента

396* [Разрешения](/ru/agent-sdk/permissions): контролируйте, какие инструменты может использовать агент

agent-sdk/todo-tracking.md +189 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Списки задач

7> Отслеживайте и отображайте задачи с помощью Claude Agent SDK для организованного управления задачами

9Отслеживание задач предоставляет структурированный способ управления задачами и отображения прогресса пользователям. Claude Agent SDK включает встроенную функциональность задач, которая помогает организовать сложные рабочие процессы и держать пользователей в курсе хода выполнения задач.

11### Жизненный цикл задач

13Задачи следуют предсказуемому жизненному циклу:

151. **Созданы** как `pending` при выявлении задач

162. **Активированы** в `in_progress` при начале работы

173. **Завершены** при успешном завершении задачи

184. **Удалены** при завершении всех задач в группе

20### Когда используются задачи

22SDK автоматически создает задачи для:

24* **Сложных многошаговых задач**, требующих 3 или более отдельных действий

25* **Списков задач, предоставленных пользователем**, когда упоминаются несколько элементов

26* **Нетривиальных операций**, которые выигрывают от отслеживания прогресса

27* **Явных запросов**, когда пользователи просят организовать задачи

29## Примеры

31### Мониторинг изменений задач

33<CodeGroup>

34 ```typescript TypeScript theme={null}

35 import { query } from "@anthropic-ai/claude-agent-sdk";

37 for await (const message of query({

38 prompt: "Optimize my React app performance and track progress with todos",

39 options: { maxTurns: 15 }

40 })) {

41 // Todo updates are reflected in the message stream

42 if (message.type === "assistant") {

43 for (const block of message.message.content) {

44 if (block.type === "tool_use" && block.name === "TodoWrite") {

45 const todos = block.input.todos;

47 console.log("Todo Status Update:");

48 todos.forEach((todo, index) => {

49 const status =

50 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

51 console.log(`${index + 1}. ${status} ${todo.content}`);

52 });

53 }

54 }

55 }

56 }

57 ```

59 ```python Python theme={null}

60 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

62 async for message in query(

63 prompt="Optimize my React app performance and track progress with todos",

64 options=ClaudeAgentOptions(max_turns=15),

65 ):

66 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):

68 for block in message.content:

69 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

70 todos = block.input["todos"]

72 print("Todo Status Update:")

73 for i, todo in enumerate(todos):

74 status = (

75 "✅"

76 if todo["status"] == "completed"

77 else "🔧"

78 if todo["status"] == "in_progress"

79 else "❌"

80 )

81 print(f"{i + 1}. {status} {todo['content']}")

82 ```

83</CodeGroup>

85### Отображение прогресса в реальном времени

87<CodeGroup>

88 ```typescript TypeScript theme={null}

89 import { query } from "@anthropic-ai/claude-agent-sdk";

91 class TodoTracker {

92 private todos: any[] = [];

94 displayProgress() {

95 if (this.todos.length === 0) return;

97 const completed = this.todos.filter((t) => t.status === "completed").length;

98 const inProgress = this.todos.filter((t) => t.status === "in_progress").length;

99 const total = this.todos.length;

100

101 console.log(`\nProgress: ${completed}/${total} completed`);

102 console.log(`Currently working on: ${inProgress} task(s)\n`);

103

104 this.todos.forEach((todo, index) => {

105 const icon =

106 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

107 const text = todo.status === "in_progress" ? todo.activeForm : todo.content;

108 console.log(`${index + 1}. ${icon} ${text}`);

109 });

110 }

111

112 async trackQuery(prompt: string) {

113 for await (const message of query({

114 prompt,

115 options: { maxTurns: 20 }

116 })) {

117 if (message.type === "assistant") {

118 for (const block of message.message.content) {

119 if (block.type === "tool_use" && block.name === "TodoWrite") {

120 this.todos = block.input.todos;

121 this.displayProgress();

122 }

123 }

124 }

125 }

126 }

127 }

128

129 // Usage

130 const tracker = new TodoTracker();

131 await tracker.trackQuery("Build a complete authentication system with todos");

132 ```

133

134 ```python Python theme={null}

135 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

136 from typing import List, Dict

137

138

139 class TodoTracker:

140 def __init__(self):

141 self.todos: List[Dict] = []

142

143 def display_progress(self):

144 if not self.todos:

145 return

146

147 completed = len([t for t in self.todos if t["status"] == "completed"])

148 in_progress = len([t for t in self.todos if t["status"] == "in_progress"])

149 total = len(self.todos)

150

151 print(f"\nProgress: {completed}/{total} completed")

152 print(f"Currently working on: {in_progress} task(s)\n")

153

154 for i, todo in enumerate(self.todos):

155 icon = (

156 "✅"

157 if todo["status"] == "completed"

158 else "🔧"

159 if todo["status"] == "in_progress"

160 else "❌"

161 )

162 text = (

163 todo["activeForm"]

164 if todo["status"] == "in_progress"

165 else todo["content"]

166 )

167 print(f"{i + 1}. {icon} {text}")

168

169 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):

171 if isinstance(message, AssistantMessage):

172 for block in message.content:

173 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

174 self.todos = block.input["todos"]

175 self.display_progress()

176

177

178 # Usage

179 tracker = TodoTracker()

180 await tracker.track_query("Build a complete authentication system with todos")

181 ```

182</CodeGroup>

183

184## Связанная документация

185

186* [Справочник TypeScript SDK](/ru/agent-sdk/typescript)

187* [Справочник Python SDK](/ru/agent-sdk/python)

188* [Потоковая передача в сравнении с одиночным режимом](/ru/agent-sdk/streaming-vs-single-mode)

189* [Пользовательские инструменты](/ru/agent-sdk/custom-tools)

agent-sdk/typescript.md +32 −32

Details

41#### Параметры41#### Параметры

42 42

43| Параметр | Тип | Описание |43| Параметр | Тип | Описание |

~~44| :-------- | :---------------------------------------------------------------- | :----------------------------------------------------------------------------------- |~~44| :-------- | :--------------------------------------------------------------- | :----------------------------------------------------------------------------------- |

47 47

48#### Возвращаемое значение48#### Возвращаемое значение

49 49

~~50Возвращает объект [`Query`](#query-object), который расширяет `AsyncGenerator<`[`SDKMessage`](#sdk-message)`, void>` дополнительными методами.~~50Возвращает объект [`Query`](#query-object), который расширяет `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` дополнительными методами.

51 51

52### `startup()`52### `startup()`

53 53

54Предварительно разогревает подпроцесс CLI, запуская его и завершая инициализационное рукопожатие до того, как запрос будет доступен. Возвращённый дескриптор [`WarmQuery`](#warm-query) принимает запрос позже и записывает его в уже готовый процесс, поэтому первый вызов `query()` разрешается без затрат на запуск подпроцесса и инициализацию в строке.54Предварительно разогревает подпроцесс CLI, запуская его и завершая инициализационное рукопожатие до того, как запрос будет доступен. Возвращённый дескриптор [`WarmQuery`](#warmquery) принимает запрос позже и записывает его в уже готовый процесс, поэтому первый вызов `query()` разрешается без затрат на запуск подпроцесса и инициализацию в строке.

55 55

56```typescript theme={null}56```typescript theme={null}

57function startup(params?: {57function startup(params?: {

69 69

70#### Возвращаемое значение70#### Возвращаемое значение

71 71

72Возвращает `Promise<`[`WarmQuery`](#warm-query)`>`, который разрешается после того, как подпроцесс запущен и завершил инициализационное рукопожатие.72Возвращает `Promise<`[`WarmQuery`](#warmquery)`>`, который разрешается после того, как подпроцесс запущен и завершил инициализационное рукопожатие.

73 73

74#### Пример74#### Пример

75 75

104#### Параметры104#### Параметры

105 105

106| Параметр | Тип | Описание |106| Параметр | Тип | Описание |

107| :------------ | :------------------------------------------------------------------ | :-------------------------------------------------------------------------------- |107| :------------ | :---------------------------------------------------------------- | :-------------------------------------------------------------------------------- |

112| `extras` | `{ annotations?: `[`ToolAnnotations`](#tool-annotations)` }` | Опциональные аннотации MCP tool, предоставляющие поведенческие подсказки клиентам |112| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | Опциональные аннотации MCP tool, предоставляющие поведенческие подсказки клиентам |

113 113

114#### `ToolAnnotations`114#### `ToolAnnotations`

115 115

191 191

192#### Пример192#### Пример

272 272

273Возвращает [`SDKSessionInfo`](#return-type-sdk-session-info) или `undefined`, если сессия не найдена.273Возвращает [`SDKSessionInfo`](#return-type-sdksessioninfo) или `undefined`, если сессия не найдена.

274 274

275### `renameSession()`275### `renameSession()`

276 276

328| `allowedTools` | `string[]` | `[]` | Tools для автоматического одобрения без запроса. Это не ограничивает Claude только этими tools; неперечисленные tools переходят к `permissionMode` и `canUseTool`. Используйте `disallowedTools` для блокировки tools. См. [Разрешения](/ru/agent-sdk/permissions#allow-and-deny-rules) |328| `allowedTools` | `string[]` | `[]` | Tools для автоматического одобрения без запроса. Это не ограничивает Claude только этими tools; неперечисленные tools переходят к `permissionMode` и `canUseTool`. Используйте `disallowedTools` для блокировки tools. См. [Разрешения](/ru/agent-sdk/permissions#allow-and-deny-rules) |

341| `extraArgs` | `Record<string, string \| null>` | `{}` | Дополнительные аргументы |341| `extraArgs` | `Record<string, string \| null>` | `{}` | Дополнительные аргументы |

344| `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | Обратные вызовы hooks для событий |344| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Обратные вызовы hooks для событий |

346| `maxBudgetUsd` | `number` | `undefined` | Остановите запрос, когда оценка стоимости на стороне клиента достигнет этого значения USD. Сравнивается с той же оценкой, что и `total_cost_usd`; см. [Отслеживание стоимости и использования](/ru/agent-sdk/cost-tracking) для предостережений точности |346| `maxBudgetUsd` | `number` | `undefined` | Остановите запрос, когда оценка стоимости на стороне клиента достигнет этого значения USD. Сравнивается с той же оценкой, что и `total_cost_usd`; см. [Отслеживание стоимости и использования](/ru/agent-sdk/cost-tracking) для предостережений точности |

349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | Конфигурации MCP серверов |349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Конфигурации MCP серверов |

351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Определите формат вывода для результатов агента. См. [Структурированные выводы](/ru/agent-sdk/structured-outputs) для деталей |351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Определите формат вывода для результатов агента. См. [Структурированные выводы](/ru/agent-sdk/structured-outputs) для деталей |

352| `pathToClaudeCodeExecutable` | `string` | Автоопределение из встроенного нативного бинарного файла | Путь к исполняемому файлу Claude Code. Требуется только если опциональные зависимости были пропущены при установке или ваша платформа не в поддерживаемом наборе |352| `pathToClaudeCodeExecutable` | `string` | Автоопределение из встроенного нативного бинарного файла | Путь к исполняемому файлу Claude Code. Требуется только если опциональные зависимости были пропущены при установке или ваша платформа не в поддерживаемом наборе |

362| `sessionStore` | [`SessionStore`](/ru/agent-sdk/session-storage#the-session-store-interface) | `undefined` | Зеркалируйте транскрипты сессий на внешний бэкенд, чтобы любой хост мог их возобновить. См. [Сохранение сессий на внешнее хранилище](/ru/agent-sdk/session-storage) |362| `sessionStore` | [`SessionStore`](/ru/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Зеркалируйте транскрипты сессий на внешний бэкенд, чтобы любой хост мог их возобновить. См. [Сохранение сессий на внешнее хранилище](/ru/agent-sdk/session-storage) |

363| `settingSources` | [`SettingSource`](#setting-source)`[]` | Значения по умолчанию CLI (все источники) | Контролируйте, какие настройки файловой системы загружать. Передайте `[]` для отключения пользовательских, проектных и локальных настроек. Управляемые политикой настройки загружаются независимо. См. [Используйте функции Claude Code](/ru/agent-sdk/claude-code-features#what-settingsources-does-not-control) |363| `settingSources` | [`SettingSource`](#settingsource)`[]` | Значения по умолчанию CLI (все источники) | Контролируйте, какие настройки файловой системы загружать. Передайте `[]` для отключения пользовательских, проектных и локальных настроек. Управляемые политикой настройки загружаются независимо. См. [Используйте функции Claude Code](/ru/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Пользовательская функция для запуска процесса Claude Code. Используйте для запуска Claude Code на ВМ, контейнерах или удалённых окружениях |364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Пользовательская функция для запуска процесса Claude Code. Используйте для запуска Claude Code на ВМ, контейнерах или удалённых окружениях |

367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (минимальный запрос) | Конфигурация системного запроса. Передайте строку для пользовательского запроса или `{ type: 'preset', preset: 'claude_code' }` для использования системного запроса Claude Code. При использовании формы объекта preset добавьте `append` для расширения его дополнительными инструкциями и установите `excludeDynamicSections: true` для перемещения контекста для каждой сессии в первое пользовательское сообщение для [лучшего переиспользования prompt-cache на разных машинах](/ru/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (минимальный запрос) | Конфигурация системного запроса. Передайте строку для пользовательского запроса или `{ type: 'preset', preset: 'claude_code' }` для использования системного запроса Claude Code. При использовании формы объекта preset добавьте `append` для расширения его дополнительными инструкциями и установите `excludeDynamicSections: true` для перемещения контекста для каждой сессии в первое пользовательское сообщение для [лучшего переиспользования prompt-cache на разных машинах](/ru/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

368| `thinking` | [`ThinkingConfig`](#thinking-config) | `{ type: 'adaptive' }` для поддерживаемых моделей | Контролирует поведение мышления/рассуждения Claude. См. [`ThinkingConfig`](#thinking-config) для опций |368| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` для поддерживаемых моделей | Контролирует поведение мышления/рассуждения Claude. См. [`ThinkingConfig`](#thinkingconfig) для опций |

370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Конфигурация tool. Передайте массив имён tool или используйте preset для получения встроенных tools Claude Code |370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Конфигурация tool. Передайте массив имён tool или используйте preset для получения встроенных tools Claude Code |

371 371

372### `Query` объект372### `Query` объект

410| `initializationResult()` | Возвращает полный результат инициализации, включая поддерживаемые команды, модели, информацию об учётной записи и конфигурацию стиля вывода |410| `initializationResult()` | Возвращает полный результат инициализации, включая поддерживаемые команды, модели, информацию об учётной записи и конфигурацию стиля вывода |

493| `background` | Нет | Запустите этого агента как неблокирующую фоновую задачу при вызове |493| `background` | Нет | Запустите этого агента как неблокирующую фоновую задачу при вызове |

494| `memory` | Нет | Источник памяти для этого агента: `'user'`, `'project'` или `'local'` |494| `memory` | Нет | Источник памяти для этого агента: `'user'`, `'project'` или `'local'` |

495| `effort` | Нет | Уровень усилий рассуждения для этого агента. Принимает именованный уровень или целое число |495| `effort` | Нет | Уровень усилий рассуждения для этого агента. Принимает именованный уровень или целое число |

496| `permissionMode` | Нет | Режим разрешения для выполнения tool в этом агенте. См. [`PermissionMode`](#permission-mode) |496| `permissionMode` | Нет | Режим разрешения для выполнения tool в этом агенте. См. [`PermissionMode`](#permissionmode) |

497| `criticalSystemReminder_EXPERIMENTAL` | Нет | Экспериментально: Критическое напоминание, добавленное в системный запрос |497| `criticalSystemReminder_EXPERIMENTAL` | Нет | Экспериментально: Критическое напоминание, добавленное в системный запрос |

498 498

499### `AgentMcpServerSpec`499### `AgentMcpServerSpec`

626 | "default" // Стандартное поведение разрешения626 | "default" // Стандартное поведение разрешения

627 | "acceptEdits" // Автоматически принимайте редактирования файлов627 | "acceptEdits" // Автоматически принимайте редактирования файлов

628 | "bypassPermissions" // Обойдите все проверки разрешения628 | "bypassPermissions" // Обойдите все проверки разрешения

629 | "plan" // Режим планирования - без выполнения629 | "plan" // Режим планирования - только инструменты чтения

630 | "dontAsk" // Не запрашивайте разрешения, отклоняйте, если не предварительно одобрено630 | "dontAsk" // Не запрашивайте разрешения, отклоняйте, если не предварительно одобрено

631 | "auto"; // Используйте классификатор модели для одобрения или отклонения каждого вызова tool631 | "auto"; // Используйте классификатор модели для одобрения или отклонения каждого вызова tool

632```632```

651```651```

652 652

653| Опция | Тип | Описание |653| Опция | Тип | Описание |

654| :--------------- | :------------------------------------------- | :------------------------------------------------------------------------------------------ |654| :--------------- | :------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

656| `suggestions` | [`PermissionUpdate`](#permission-update)`[]` | Предложенные обновления разрешения, чтобы пользователь не был запрошен снова для этого tool |656| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Предложенные обновления разрешения, чтобы пользователь не был запрошен снова для этого tool. Запросы Bash включают предложение с назначением `localSettings` [destination](#permissionupdatedestination), поэтому возврат его в `updatedPermissions` записывает правило в `.claude/settings.local.json` и сохраняется между сессиями. |

2379 | McpClaudeAIProxyServerConfig;2379 | McpClaudeAIProxyServerConfig;

2380```2380```

2381 2381

2382См. [`McpServerConfig`](#mcp-server-config) для деталей по каждому типу транспорта.2382См. [`McpServerConfig`](#mcpserverconfig) для деталей по каждому типу транспорта.

2383 2383

2384### `AccountInfo`2384### `AccountInfo`

2385 2385

2825```2825```

2826 2826

2827| Свойство | Тип | По умолчанию | Описание |2827| Свойство | Тип | По умолчанию | Описание |

2828| :-------------------------- | :------------------------------------------------------ | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2828| :-------------------------- | :---------------------------------------------------- | :----------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2832| `allowUnsandboxedCommands` | `boolean` | `true` | Разрешите модели запрашивать выполнение команд вне sandbox. Когда `true`, модель может установить `dangerouslyDisableSandbox` в входных данных tool, что переходит к [системе разрешений](#permissions-fallback-for-unsandboxed-commands) |2832| `allowUnsandboxedCommands` | `boolean` | `true` | Разрешите модели запрашивать выполнение команд вне sandbox. Когда `true`, модель может установить `dangerouslyDisableSandbox` в входных данных tool, что переходит к [системе разрешений](#permissions-fallback-for-unsandboxed-commands) |

2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Карта категорий нарушений на паттерны для игнорирования (например, `{ file: ['/tmp/*'], network: ['localhost'] }`) |2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Карта категорий нарушений на паттерны для игнорирования (например, `{ file: ['/tmp/*'], network: ['localhost'] }`) |

2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Конфигурация пользовательского бинарного файла ripgrep для окружений sandbox |2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Конфигурация пользовательского бинарного файла ripgrep для окружений sandbox |

data-usage.md +1 −1

Details

67 67

68На диаграмме ниже показано, как Claude Code подключается к внешним сервисам во время установки и нормальной работы. Сплошные линии указывают на обязательные соединения, а пунктирные линии представляют дополнительные или инициированные пользователем потоки данных.68На диаграмме ниже показано, как Claude Code подключается к внешним сервисам во время установки и нормальной работы. Сплошные линии указывают на обязательные соединения, а пунктирные линии представляют дополнительные или инициированные пользователем потоки данных.

69 69

70<img src="https://mintcdn.com/claude-code/YcBW2H7CArGcduPb/images/claude-code-data-flow.svg?fit=max&auto=format&n=YcBW2H7CArGcduPb&q=85&s=b600a89f84fc86f9ff7be00a466c0635" alt="Диаграмма, показывающая внешние соединения Claude Code: установка/обновление подключается к серверу распределения, а запросы пользователя подключаются к сервисам Anthropic, включая Console auth, public-api, и опционально Statsig, Sentry и отчёты об ошибках" width="720" height="520" data-path="images/claude-code-data-flow.svg" />70<img src="https://mintcdn.com/claude-code/RcOyXc06Ja8cuvMZ/images/claude-code-data-flow.svg?fit=max&auto=format&n=RcOyXc06Ja8cuvMZ&q=85&s=b5be40abf333defe984993af89546c19" alt="Диаграмма, показывающая внешние соединения Claude Code: установка/обновление подключается к серверу распределения, а запросы пользователя подключаются к сервисам Anthropic, включая Console auth, public-api, и опционально Statsig, Sentry и отчёты об ошибках" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

71 71

72Claude Code работает локально. Для взаимодействия с LLM Claude Code отправляет данные по сети. Эти данные включают все подсказки пользователя и выходные данные модели, зашифрованные при передаче через TLS 1.2+. Claude Code совместим с большинством популярных VPN и прокси LLM.72Claude Code работает локально. Для взаимодействия с LLM Claude Code отправляет данные по сети. Эти данные включают все подсказки пользователя и выходные данные модели, зашифрованные при передаче через TLS 1.2+. Claude Code совместим с большинством популярных VPN и прокси LLM.

73 73

desktop.md +5 −3

Details

282 282

283### Работа параллельно с сеансами283### Работа параллельно с сеансами

284 284

285Нажмите **+ New session** в боковой панели, или нажмите **Cmd+N** на macOS или **Ctrl+N** на Windows, чтобы работать над несколькими задачами параллельно. Нажмите **Ctrl+Tab** и **Ctrl+Shift+Tab**, чтобы циклически переходить через сеансы в боковой панели. Для Git-репозиториев каждый сеанс получает свою собственную изолированную копию вашего проекта, используя [Git Worktrees](/ru/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), поэтому изменения в одном сеансе не влияют на другие сеансы до тех пор, пока вы их не зафиксируете.285Нажмите **+ New session** в боковой панели, или нажмите **Cmd+N** на macOS или **Ctrl+N** на Windows, чтобы работать над несколькими задачами параллельно. Нажмите **Ctrl+Tab** и **Ctrl+Shift+Tab**, чтобы циклически переходить через сеансы в боковой панели. Для Git-репозиториев каждый сеанс получает свою собственную изолированную копию вашего проекта, используя [Git Worktrees](/ru/worktrees), поэтому изменения в одном сеансе не влияют на другие сеансы до тех пор, пока вы их не зафиксируете.

286

287Чтобы просмотреть два сеанса одновременно, удерживайте **Cmd** на macOS или **Ctrl** на Windows и нажмите на сеанс в боковой панели. Сеанс откроется во втором панели рядом с тем, который у вас уже открыт. Пока разделение активно, нажатие на другой сеанс в боковой панели заменяет ту панель, которая имеет фокус. Нажмите **Cmd+\\** на macOS или **Ctrl+\\** на Windows, чтобы закрыть панель с фокусом и вернуться к одному сеансу.

286 288

287Worktrees хранятся в `<project-root>/.claude/worktrees/` по умолчанию. Вы можете изменить это на пользовательский каталог в Settings → Claude Code под "Worktree location". Вы также можете установить префикс ветви, который добавляется в начало каждого имени ветви worktree, что полезно для организации веток, созданных Claude. Чтобы удалить worktree после завершения, наведите курсор на сеанс в боковой панели и нажмите значок архива. Чтобы сеансы архивировали себя, когда их pull request объединяется или закрывается, включите **Auto-archive after PR merge or close** в Settings → Claude Code. Auto-archive применяется только к локальным сеансам, которые завершили работу.289Worktrees хранятся в `<project-root>/.claude/worktrees/` по умолчанию. Вы можете изменить это на пользовательский каталог в Settings → Claude Code под "Worktree location". Вы также можете установить префикс ветви, который добавляется в начало каждого имени ветви worktree, что полезно для организации веток, созданных Claude. Чтобы удалить worktree после завершения, наведите курсор на сеанс в боковой панели и нажмите значок архива. Чтобы сеансы архивировали себя, когда их pull request объединяется или закрывается, включите **Auto-archive after PR merge or close** в Settings → Claude Code. Auto-archive применяется только к локальным сеансам, которые завершили работу.

288 290

289Чтобы включить gitignored файлы, такие как `.env`, в новые worktrees, создайте [`.worktreeinclude` файл](/ru/common-workflows#copy-gitignored-files-to-worktrees) в корне вашего проекта.291Чтобы включить gitignored файлы, такие как `.env`, в новые worktrees, создайте [`.worktreeinclude` файл](/ru/worktrees#copy-gitignored-files-into-worktrees) в корне вашего проекта.

290 292

291<Note>293<Note>

292 Изоляция сеанса требует [Git](https://git-scm.com/downloads). На большинстве Mac Git включен по умолчанию. Запустите `git --version` в Terminal для проверки. На Windows Git требуется для работы вкладки Code: [загрузите Git для Windows](https://git-scm.com/downloads/win), установите его и перезагрузите приложение. Если вы столкнулись с ошибками Git, попросите Claude в [вкладке Cowork](https://claude.com/product/cowork) помочь вам устранить неполадки вашей установки.294 Изоляция сеанса требует [Git](https://git-scm.com/downloads). На большинстве Mac Git включен по умолчанию. Запустите `git --version` в Terminal для проверки. На Windows Git требуется для работы вкладки Code: [загрузите Git для Windows](https://git-scm.com/downloads/win), установите его и перезагрузите приложение. Если вы столкнулись с ошибками Git, попросите Claude в [вкладке Cowork](https://claude.com/product/cowork) помочь вам устранить неполадки вашей установки.

516 518

517Чтобы установить переменные окружения для локальных сеансов и dev-серверов на любой платформе, откройте раскрывающийся список окружения в поле подсказки, наведите курсор на **Local** и нажмите значок шестерёнки, чтобы открыть локальный редактор окружения. Переменные, которые вы сохраняете здесь, хранятся в зашифрованном виде на вашей машине и применяются к каждому локальному сеансу и серверу предпросмотра, который вы запускаете. Вы также можете добавить переменные к ключу `env` в вашем файле `~/.claude/settings.json`, хотя они достигают только сеансов Claude, а не dev-серверов. См. [переменные окружения](/ru/env-vars) для полного списка поддерживаемых переменных.519Чтобы установить переменные окружения для локальных сеансов и dev-серверов на любой платформе, откройте раскрывающийся список окружения в поле подсказки, наведите курсор на **Local** и нажмите значок шестерёнки, чтобы открыть локальный редактор окружения. Переменные, которые вы сохраняете здесь, хранятся в зашифрованном виде на вашей машине и применяются к каждому локальному сеансу и серверу предпросмотра, который вы запускаете. Вы также можете добавить переменные к ключу `env` в вашем файле `~/.claude/settings.json`, хотя они достигают только сеансов Claude, а не dev-серверов. См. [переменные окружения](/ru/env-vars) для полного списка поддерживаемых переменных.

518 520

519[Extended thinking](/ru/common-workflows#use-extended-thinking-thinking-mode) включен по умолчанию, что улучшает производительность на сложных задачах рассуждения, но использует дополнительные токены. Чтобы полностью отключить thinking, установите `MAX_THINKING_TOKENS` на `0` в локальном редакторе окружения. На моделях с [адаптивным рассуждением](/ru/model-config#adjust-effort-level) любое другое значение `MAX_THINKING_TOKENS` игнорируется, потому что адаптивное рассуждение контролирует глубину thinking вместо этого. На Opus 4.6 и Sonnet 4.6 установите `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` на `1`, чтобы использовать фиксированный бюджет thinking; Opus 4.7 всегда использует адаптивное рассуждение и не имеет режима фиксированного бюджета.521[Extended thinking](/ru/model-config#extended-thinking) включен по умолчанию, что улучшает производительность на сложных задачах рассуждения, но использует дополнительные токены. Чтобы полностью отключить thinking, установите `MAX_THINKING_TOKENS` на `0` в локальном редакторе окружения. На моделях с [адаптивным рассуждением](/ru/model-config#adjust-effort-level) любое другое значение `MAX_THINKING_TOKENS` игнорируется, потому что адаптивное рассуждение контролирует глубину thinking вместо этого. На Opus 4.6 и Sonnet 4.6 установите `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` на `1`, чтобы использовать фиксированный бюджет thinking; Opus 4.7 всегда использует адаптивное рассуждение и не имеет режима фиксированного бюджета.

520 522

521### Удалённые сеансы523### Удалённые сеансы

522 524

features-overview.md +49 −12

Details

12 Информацию о том, как работает основной цикл агента, см. в разделе [How Claude Code works](/ru/how-claude-code-works).12 Информацию о том, как работает основной цикл агента, см. в разделе [How Claude Code works](/ru/how-claude-code-works).

13</Note>13</Note>

14 14

15**Новичок в Claude Code?** Начните с [CLAUDE.md](/ru/memory) для соглашений проекта. Добавляйте другие расширения по мере необходимости.15**Новичок в Claude Code?** Начните с [CLAUDE.md](/ru/memory) для соглашений проекта, затем добавляйте другие расширения [по мере возникновения конкретных триггеров](#build-your-setup-over-time).

16 16

17## Обзор17## Обзор

18 18

23* **[MCP](/ru/mcp)** подключает Claude к внешним сервисам и инструментам23* **[MCP](/ru/mcp)** подключает Claude к внешним сервисам и инструментам

24* **[Subagents](/ru/sub-agents)** запускают свои собственные циклы в изолированном контексте, возвращая резюме24* **[Subagents](/ru/sub-agents)** запускают свои собственные циклы в изолированном контексте, возвращая резюме

25* **[Agent teams](/ru/agent-teams)** координируют несколько независимых сессий с общими задачами и обменом сообщениями между участниками25* **[Agent teams](/ru/agent-teams)** координируют несколько независимых сессий с общими задачами и обменом сообщениями между участниками

~~26* **[Hooks](/ru/hooks)** работают полностью вне цикла как детерминированные скрипты~~26* **[Hooks](/ru/hooks-guide)** срабатывают при событиях жизненного цикла и могут запустить скрипт, HTTP запрос, prompt или subagent

27* **[Plugins](/ru/plugins)** и **[marketplaces](/ru/plugin-marketplaces)** упаковывают и распространяют эти функции27* **[Plugins](/ru/plugins)** и **[marketplaces](/ru/plugin-marketplaces)** упаковывают и распространяют эти функции

28 28

29[Skills](/ru/skills) — это наиболее гибкое расширение. Skill — это файл markdown, содержащий знания, рабочие процессы или инструкции. Вы можете вызывать skills с помощью команды типа `/deploy`, или Claude может загружать их автоматически, когда они релевантны. Skills могут работать в вашем текущем разговоре или в изолированном контексте через subagents.29[Skills](/ru/skills) — это наиболее гибкое расширение. Skill — это файл markdown, содержащий знания, рабочие процессы или инструкции. Вы можете вызывать skills с помощью команды типа `/deploy`, или Claude может загружать их автоматически, когда они релевантны. Skills могут работать в вашем текущем разговоре или в изолированном контексте через subagents.

39| **Subagent** | Изолированный контекст выполнения, который возвращает обобщённые результаты | Изоляция контекста, параллельные задачи, специализированные работники | Задача исследования, которая читает много файлов, но возвращает только ключевые выводы |39| **Subagent** | Изолированный контекст выполнения, который возвращает обобщённые результаты | Изоляция контекста, параллельные задачи, специализированные работники | Задача исследования, которая читает много файлов, но возвращает только ключевые выводы |

40| **[Agent teams](/ru/agent-teams)** | Координируют несколько независимых сессий Claude Code | Параллельное исследование, разработка новых функций, отладка с конкурирующими гипотезами | Запустите рецензентов для одновременной проверки безопасности, производительности и тестов |40| **[Agent teams](/ru/agent-teams)** | Координируют несколько независимых сессий Claude Code | Параллельное исследование, разработка новых функций, отладка с конкурирующими гипотезами | Запустите рецензентов для одновременной проверки безопасности, производительности и тестов |

41| **MCP** | Подключение к внешним сервисам | Внешние данные или действия | Запрос к вашей базе данных, отправка в Slack, управление браузером |41| **MCP** | Подключение к внешним сервисам | Внешние данные или действия | Запрос к вашей базе данных, отправка в Slack, управление браузером |

43 43

44**[Plugins](/ru/plugins)** — это уровень упаковки. Plugin объединяет skills, hooks, subagents и MCP servers в единый устанавливаемый модуль. Plugin skills имеют пространство имён (например, `/my-plugin:review`), поэтому несколько plugins могут сосуществовать. Используйте plugins, когда вы хотите переиспользовать одну и ту же настройку в нескольких репозиториях или распространять другим через **[marketplace](/ru/plugin-marketplaces)**.44**[Plugins](/ru/plugins)** — это уровень упаковки. Plugin объединяет skills, hooks, subagents и MCP servers в единый устанавливаемый модуль. Plugin skills имеют пространство имён (например, `/my-plugin:review`), поэтому несколько plugins могут сосуществовать. Используйте plugins, когда вы хотите переиспользовать одну и ту же настройку в нескольких репозиториях или распространять другим через **[marketplace](/ru/plugin-marketplaces)**.

45 45

46### Сформируйте вашу настройку со временем

48Вам не нужно настраивать всё заранее. Каждая функция имеет узнаваемый триггер, и большинство команд добавляют их примерно в таком порядке:

50| Триггер | Добавить |

51| :--------------------------------------------------------------------------------------- | :--------------------------------------------------------- |

52| Claude дважды неправильно применяет соглашение или команду | Добавьте в [CLAUDE.md](/ru/memory) |

53| Вы постоянно вводите один и тот же prompt для начала задачи | Сохраните как вызываемый пользователем [skill](/ru/skills) |

54| Вы вставляете один и тот же playbook или многошаговую процедуру в чат в третий раз | Захватите как [skill](/ru/skills) |

55| Вы постоянно копируете данные из вкладки браузера, которую Claude не видит | Подключите эту систему как [MCP server](/ru/mcp) |

56| Побочная задача заполняет ваш разговор выводом, на который вы больше не будете ссылаться | Маршрутизируйте через [subagent](/ru/sub-agents) |

57| Вы хотите, чтобы что-то происходило каждый раз без запроса | Напишите [hook](/ru/hooks-guide) |

58| Второй репозиторий нуждается в одной и той же настройке | Упакуйте как [plugin](/ru/plugins) |

60Те же триггеры говорят вам, когда обновлять то, что у вас уже есть. Повторяющаяся ошибка или повторяющийся комментарий рецензии — это редактирование CLAUDE.md, а не одноразовое исправление в чате. Рабочий процесс, который вы постоянно подправляете вручную, — это skill, который нуждается в другой редакции.

46### Сравните похожие функции62### Сравните похожие функции

47 63

48Некоторые функции могут казаться похожими. Вот как их различить.64Некоторые функции могут казаться похожими. Вот как их различить.

55 * **Subagents** — это изолированные работники, которые работают отдельно от вашего основного разговора71 * **Subagents** — это изолированные работники, которые работают отдельно от вашего основного разговора

56 72

~~58 | ------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------- |~~74 | --------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------- |

77 | **[Влияние на окно контекста](/ru/context-window)** | Добавляется в ваше основное окно | Использует отдельное окно со своими входными и выходными токенами |

62 79

63 **Skills могут быть справочными или действенными.** Справочные skills предоставляют знания, которые Claude использует на протяжении вашей сессии (например, ваше руководство по стилю API). Action skills говорят Claude сделать что-то конкретное (например, `/deploy`, который запускает ваш рабочий процесс развёртывания).80 **Skills могут быть справочными или действенными.** Справочные skills предоставляют знания, которые Claude использует на протяжении вашей сессии (например, ваше руководство по стилю API). Action skills говорят Claude сделать что-то конкретное (например, `/deploy`, который запускает ваш рабочий процесс развёртывания).

142 159

143 Пример: MCP server подключает Claude к вашей базе данных. Skill учит Claude вашу модель данных, общие шаблоны запросов и какие таблицы использовать для разных задач.160 Пример: MCP server подключает Claude к вашей базе данных. Skill учит Claude вашу модель данных, общие шаблоны запросов и какие таблицы использовать для разных задач.

144 </Tab>161 </Tab>

162

163 <Tab title="Hook vs Skill">

164 Hook срабатывает при событии жизненного цикла; skill загружается в контекст для применения Claude.

165

166 | Аспект | Hook | Skill |

167 | ----------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |

168 | **Запускает** | Команду shell, HTTP запрос, LLM prompt или subagent | Инструкции, которые Claude читает и следует им |

169 | **Запущено** | [События жизненного цикла](/ru/hooks#hook-events) такие как `PostToolUse` или `SessionStart` | Вы вводите `/<name>`, или Claude сопоставляет описание с вашей задачей |

170 | **Детерминизм** | Всегда срабатывает при своём событии; триггер гарантирован | Claude интерпретирует инструкции; результат может варьироваться |

171 | **Стоимость контекста** | Ноль, если hook не возвращает вывод | Описание загружается каждую сессию; полный контент загружается при использовании |

172 | **Лучше всего для** | Линтинг после редактирования, блокирование небезопасных команд, логирование, уведомления | Рабочие процессы, которые нуждаются в рассуждении, справочный материал, многошаговые задачи |

173

174 **Используйте hook**, когда действие должно происходить одинаково каждый раз и не нуждается в размышлении Claude. Например: форматирование при сохранении, отклонение `rm -rf /`, отправка сообщения Slack при завершении сессии.

175

176 **Используйте skill**, когда Claude должен решить, как применить шаги, или когда контент — это знание, а не скрипт. Например: контрольный список `/release`, ваше руководство по стилю API, playbook отладки.

177

178 **Поместите guardrails в hooks.** Инструкция типа "никогда не редактируйте `.env`" в CLAUDE.md или skill — это запрос, а не гарантия. Hook `PreToolUse`, который блокирует редактирование, — это принуждение. Если правило должно выполняться каждый раз, сделайте его hook, а не инструкцию prompt.

179

180 **Вывод Hook попадает в контекст.** Hook `PostToolUse`, который запускает ваш linter, возвращает результаты как текст, который читает Claude; skill `/fix-lint` говорит Claude, как их разрешить.

181 </Tab>

145</Tabs>182</Tabs>

146 183

147### Поймите, как функции слоятся184### Поймите, как функции слоятся

168 205

169## Поймите стоимость контекста206## Поймите стоимость контекста

170 207

171Каждая функция, которую вы добавляете, потребляет часть контекста Claude. Слишком много может заполнить ваше окно контекста, но это также может добавить шум, который делает Claude менее эффективным; skills могут не срабатывать правильно, или Claude может потерять из виду ваши соглашения. Понимание этих компромиссов помогает вам построить эффективную настройку.208Каждая функция, которую вы добавляете, потребляет часть контекста Claude. Слишком много может заполнить ваше окно контекста, но это также может добавить шум, который делает Claude менее эффективным; skills могут не срабатывать правильно, или Claude может потерять из виду ваши соглашения. Понимание этих компромиссов помогает вам построить эффективную настройку. Для интерактивного представления того, как эти функции объединяются в работающей сессии, см. [Explore the context window](/ru/context-window).

172 209

173### Стоимость контекста по функциям210### Стоимость контекста по функциям

174 211

178| --------------- | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------- |215| --------------- | --------------------------------- | --------------------------------------------------- | ----------------------------------------------------- |

184 221

188 225

189Каждая функция загружается в разные точки вашей сессии. Вкладки ниже объясняют, когда загружается каждая и что входит в контекст.226Каждая функция загружается в разные точки вашей сессии. Вкладки ниже объясняют, когда загружается каждая и что входит в контекст.

190 227

191<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Загрузка контекста: CLAUDE.md и MCP загружаются в начале сессии и остаются в каждом запросе. Skills загружают описания в начале, полный контент при вызове. Subagents получают изолированный контекст. Hooks работают внешне." width="720" height="410" data-path="images/context-loading.svg" />228<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Загрузка контекста: CLAUDE.md загружается в начале сессии и остаётся в каждом запросе. Имена инструментов MCP загружаются в начале с полными схемами отложенными до использования. Skills загружают описания в начале, полный контент при вызове. Subagents получают изолированный контекст. Hooks работают внешне." width="720" height="410" data-path="images/context-loading.svg" />

192 229

193<Tabs>230<Tabs>

194 <Tab title="CLAUDE.md">231 <Tab title="CLAUDE.md">

202 </Tab>239 </Tab>

203 240

204 <Tab title="Skills">241 <Tab title="Skills">

205 Skills — это дополнительные возможности в наборе инструментов Claude. Они могут быть справочным материалом (например, руководство по стилю API) или вызываемыми рабочими процессами, которые вы запускаете с помощью `/<name>` (например, `/deploy`). Claude Code поставляется с [встроенными skills](/ru/skills#bundled-skills) типа `/simplify`, `/batch` и `/debug`, которые работают из коробки. Вы также можете создавать свои собственные. Claude использует skills, когда это уместно, или вы можете вызвать один напрямую.242 Skills — это дополнительные возможности в наборе инструментов Claude. Они могут быть справочным материалом (например, руководство по стилю API) или вызываемыми рабочими процессами, которые вы запускаете с помощью `/<name>` (например, `/deploy`). Claude Code поставляется с [встроенными skills](/ru/commands) типа `/simplify`, `/batch` и `/debug`, которые работают из коробки. Вы также можете создавать свои собственные. Claude использует skills, когда это уместно, или вы можете вызвать один напрямую.

206 243

207 **Когда:** Зависит от конфигурации skill. По умолчанию описания загружаются в начале сессии, а полный контент загружается при использовании. Для skills только пользователя (`disable-model-invocation: true`) ничего не загружается до тех пор, пока вы их не вызовете.244 **Когда:** Зависит от конфигурации skill. По умолчанию описания загружаются в начале сессии, а полный контент загружается при использовании. Для skills только пользователя (`disable-model-invocation: true`) ничего не загружается до тех пор, пока вы их не вызовете.

208 245

220 <Tab title="MCP servers">257 <Tab title="MCP servers">

221 **Когда:** Начало сессии.258 **Когда:** Начало сессии.

222 259

223 **Что загружается:** Все определения инструментов и JSON схемы из подключённых серверов.260 **Что загружается:** Имена инструментов из подключённых серверов. Полные JSON схемы остаются отложенными до тех пор, пока Claude не нуждается в конкретном инструменте.

224 261

225 **Стоимость контекста:** [Tool search](/ru/mcp#scale-with-mcp-tool-search) (включён по умолчанию) загружает MCP инструменты до 10% контекста и откладывает остальное до необходимости.262 **Стоимость контекста:** [Tool search](/ru/mcp#scale-with-mcp-tool-search) включён по умолчанию, поэтому неиспользуемые MCP инструменты потребляют минимальный контекст.

226 263

227 **Примечание о надёжности:** MCP подключения могут молча отказать в середине сессии. Если сервер отключится, его инструменты исчезнут без предупреждения. Claude может попытаться использовать инструмент, который больше не существует. Если вы заметили, что Claude не может использовать MCP инструмент, который он раньше мог использовать, проверьте подключение с помощью `/mcp`.264 **Примечание о надёжности:** MCP подключения могут молча отказать в середине сессии. Если сервер отключится, его инструменты исчезнут без предупреждения. Claude может попытаться использовать инструмент, который больше не существует. Если вы заметили, что Claude не может использовать MCP инструмент, который он раньше мог использовать, проверьте подключение с помощью `/mcp`.

228 265

245 </Tab>282 </Tab>

246 283

247 <Tab title="Hooks">284 <Tab title="Hooks">

248 **Когда:** При срабатывании. Hooks срабатывают при определённых событиях жизненного цикла, таких как выполнение инструмента, границы сессии, отправка prompt, запросы разрешений и компактирование. Полный список см. в разделе [Hooks](/ru/hooks).285 **Когда:** При срабатывании. Hooks срабатывают при определённых событиях жизненного цикла, таких как выполнение инструмента, границы сессии, отправка prompt, запросы разрешений и компактирование. Подробный список см. в разделе [Hooks](/ru/hooks).

249 286

250 **Что загружается:** Ничего по умолчанию. Hooks работают как внешние скрипты.287 **Что загружается:** Ничего по умолчанию. Hooks работают вне основного разговора.

251 288

252 **Стоимость контекста:** Ноль, если hook не возвращает вывод, который добавляется как сообщения в ваш разговор.289 **Стоимость контекста:** Ноль, если hook не возвращает вывод, который добавляется как сообщения в ваш разговор.

253 290

hooks.md +8 −8

Details

970Чтобы заблокировать подсказку, верните JSON объект с `decision`, установленным на `"block"`:970Чтобы заблокировать подсказку, верните JSON объект с `decision`, установленным на `"block"`:

971 971

972| Поле | Описание |972| Поле | Описание |

973| :------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------ |973| :------------------ | :---------------------------------------------------------------------------------------------------------------------------- |

974| `decision` | `"block"` предотвращает обработку подсказки и стирает её из контекста. Опустите, чтобы разрешить подсказке продолжаться |974| `decision` | `"block"` предотвращает обработку подсказки и стирает её из контекста. Опустите, чтобы разрешить подсказке продолжаться |

976| `additionalContext` | Строка, добавленная в контекст Claude наряду с отправленной подсказкой. См. [Add context for Claude](#add-context-for-claude) |976| `additionalContext` | Строка, добавленная в контекст Claude наряду с отправленной подсказкой. См. [Add context for Claude](#add-context-for-claude) |

977| `sessionTitle` | Устанавливает название сеанса, тот же эффект, что и `/rename`. Используйте для автоматического именования сеансов на основе содержимого подсказки |977| `sessionTitle` | Устанавливает название сеанса. Используйте для автоматического именования сеансов на основе содержимого подсказки |

978 978

979```json theme={null}979```json theme={null}

980{980{

1357Hooks `PostToolUse` могут предоставить обратную связь Claude после выполнения инструмента. В дополнение к [JSON полям выхода](#json-output), доступным для всех hooks, ваш скрипт hook может вернуть эти поля, специфичные для события:1357Hooks `PostToolUse` могут предоставить обратную связь Claude после выполнения инструмента. В дополнение к [JSON полям выхода](#json-output), доступным для всех hooks, ваш скрипт hook может вернуть эти поля, специфичные для события:

1358 1358

1359| Поле | Описание |1359| Поле | Описание |

1360| :--------------------- | :---------------------------------------------------------------------------------------------------------------------------------------- |1360| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- |

1361| `decision` | `"block"` предлагает Claude с `reason`. Опустите, чтобы разрешить действию продолжаться |1361| `decision` | `"block"` добавляет `reason` рядом с результатом инструмента. Claude всё ещё видит исходный выход; чтобы заменить его, используйте `updatedToolOutput` |

1363| `additionalContext` | Строка, добавленная в контекст Claude наряду с результатом инструмента. См. [Add context for Claude](#add-context-for-claude) |1363| `additionalContext` | Строка, добавленная в контекст Claude наряду с результатом инструмента. См. [Add context for Claude](#add-context-for-claude) |

1364| `updatedToolOutput` | Заменяет выход инструмента предоставленным значением перед отправкой Claude. Значение должно соответствовать форме выхода инструмента |1364| `updatedToolOutput` | Заменяет выход инструмента предоставленным значением перед отправкой Claude. Значение должно соответствовать форме выхода инструмента |

2020 2020

2021Когда вы запускаете `claude --worktree` или [subagent использует `isolation: "worktree"`](/ru/sub-agents#choose-the-subagent-scope), Claude Code создаёт изолированную рабочую копию, используя `git worktree`. Если вы настроите hook WorktreeCreate, он заменяет поведение git по умолчанию, позволяя вам использовать другую систему контроля версий, такую как SVN, Perforce или Mercurial.2021Когда вы запускаете `claude --worktree` или [subagent использует `isolation: "worktree"`](/ru/sub-agents#choose-the-subagent-scope), Claude Code создаёт изолированную рабочую копию, используя `git worktree`. Если вы настроите hook WorktreeCreate, он заменяет поведение git по умолчанию, позволяя вам использовать другую систему контроля версий, такую как SVN, Perforce или Mercurial.

2022 2022

2023Потому что hook заменяет поведение по умолчанию полностью, [`.worktreeinclude`](/ru/common-workflows#copy-gitignored-files-to-worktrees) не обрабатывается. Если вам нужно скопировать локальные файлы конфигурации, такие как `.env`, в новый worktree, сделайте это внутри вашего скрипта hook.2023Потому что hook заменяет поведение по умолчанию полностью, [`.worktreeinclude`](/ru/worktrees#copy-gitignored-files-into-worktrees) не обрабатывается. Если вам нужно скопировать локальные файлы конфигурации, такие как `.env`, в новый worktree, сделайте это внутри вашего скрипта hook.

2024 2024

2025Hook должен вернуть абсолютный путь к созданному каталогу worktree. Claude Code использует этот путь как рабочий каталог для изолированного сеанса. Command hooks выводят его на stdout; HTTP hooks возвращают его через `hookSpecificOutput.worktreePath`.2025Hook должен вернуть абсолютный путь к созданному каталогу worktree. Claude Code использует этот путь как рабочий каталог для изолированного сеанса. Command hooks выводят его на stdout; HTTP hooks возвращают его через `hookSpecificOutput.worktreePath`.

2026 2026

2407```2407```

2408 2408

2409| Поле | Описание |2409| Поле | Описание |

2410| :------- | :----------------------------------------------------------- |2410| :------- | :------------------------------------------------------------------------------------------- |

2411| `ok` | `true` разрешает действие, `false` предотвращает его |2411| `ok` | `true` разрешает действие, `false` предотвращает его. См. поведение для каждого события ниже |

2413 2413

2414Что происходит при `ok: false`, зависит от события:2414Что происходит при `ok: false`, зависит от события:

2415 2415

permissions.md +6 −6

Details

33Claude Code поддерживает несколько режимов разрешений, которые контролируют, как инструменты одобряются. См. [Permission modes](/ru/permission-modes) для определения того, когда использовать каждый из них. Установите `defaultMode` в ваших [файлах параметров](/ru/settings#settings-files):33Claude Code поддерживает несколько режимов разрешений, которые контролируют, как инструменты одобряются. См. [Permission modes](/ru/permission-modes) для определения того, когда использовать каждый из них. Установите `defaultMode` в ваших [файлах параметров](/ru/settings#settings-files):

34 34

35| Режим | Описание |35| Режим | Описание |

36| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |36| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

38| `acceptEdits` | Автоматически принимает редактирование файлов и общие команды файловой системы (`mkdir`, `touch`, `mv`, `cp` и т.д.) для путей в рабочем каталоге или `additionalDirectories` |38| `acceptEdits` | Автоматически принимает редактирование файлов и общие команды файловой системы (`mkdir`, `touch`, `mv`, `cp` и т.д.) для путей в рабочем каталоге или `additionalDirectories` |

40| `auto` | Автоматически одобряет вызовы инструментов с проверками безопасности в фоне, которые проверяют, соответствуют ли действия вашему запросу. В настоящее время исследовательский предпросмотр |40| `auto` | Автоматически одобряет вызовы инструментов с проверками безопасности в фоне, которые проверяют, соответствуют ли действия вашему запросу. В настоящее время исследовательский предпросмотр |

41| `dontAsk` | Автоматически отклоняет инструменты, если они не предварительно одобрены через `/permissions` или правила `permissions.allow` |41| `dontAsk` | Автоматически отклоняет инструменты, если они не предварительно одобрены через `/permissions` или правила `permissions.allow` |

42| `bypassPermissions` | Пропускает все запросы разрешений. Удаления, затрагивающие корневой каталог файловой системы или домашний каталог, такие как `rm -rf /` и `rm -rf ~`, по-прежнему запрашивают подтверждение в качестве защиты от ошибок модели |42| `bypassPermissions` | Пропускает все запросы разрешений. Удаления корневого каталога и домашнего каталога, такие как `rm -rf /`, по-прежнему запрашивают подтверждение в качестве защиты от ошибок модели |

43 43

44<Warning>44<Warning>

45 Режим `bypassPermissions` пропускает все запросы разрешений, включая записи в `.git`, `.claude`, `.vscode`, `.idea` и `.husky`. Удаления, затрагивающие корневой каталог файловой системы или домашний каталог, такие как `rm -rf /` и `rm -rf ~`, по-прежнему запрашивают подтверждение в качестве защиты от ошибок модели. Используйте этот режим только в изолированных средах, таких как контейнеры или виртуальные машины, где Claude Code не может причинить вред. Администраторы могут предотвратить этот режим, установив `permissions.disableBypassPermissionsMode` на `"disable"` в [управляемых параметрах](#managed-settings).45 Режим `bypassPermissions` пропускает все запросы разрешений, включая записи в `.git`, `.claude`, `.vscode`, `.idea` и `.husky`. Удаления, затрагивающие корневой каталог файловой системы или домашний каталог, такие как `rm -rf /` и `rm -rf ~`, по-прежнему запрашивают подтверждение в качестве защиты от ошибок модели. Используйте этот режим только в изолированных средах, таких как контейнеры или виртуальные машины, где Claude Code не может причинить вред. Администраторы могут предотвратить этот режим, установив `permissions.disableBypassPermissionsMode` на `"disable"` в [управляемых параметрах](#managed-settings).

296 296

297* Правила deny разрешений блокируют Claude от попытки доступа к ограниченным ресурсам297* Правила deny разрешений блокируют Claude от попытки доступа к ограниченным ресурсам

298* Ограничения sandbox предотвращают Bash команды от доступа к ресурсам вне определенных границ, даже если инъекция подсказки обходит принятие решений Claude298* Ограничения sandbox предотвращают Bash команды от доступа к ресурсам вне определенных границ, даже если инъекция подсказки обходит принятие решений Claude

299* Ограничения файловой системы в sandbox используют правила Read и Edit deny, а не отдельную конфигурацию sandbox299* Ограничения файловой системы в sandbox объединяют параметры [`sandbox.filesystem`](/ru/sandboxing) с правилами deny для Read и Edit; оба объединяются в финальную границу sandbox

300* Ограничения сети объединяют правила разрешений WebFetch со списками `allowedDomains` и `deniedDomains` sandbox300* Ограничения сети объединяют правила разрешений WebFetch со списками `allowedDomains` и `deniedDomains` sandbox

301 301

302Когда sandboxing включен с `autoAllowBashIfSandboxed: true`, что является значением по умолчанию, sandboxed Bash команды запускаются без запроса даже если ваши разрешения включают `ask: Bash(*)`. Граница sandbox заменяет запрос для каждой команды. Явные правила deny по-прежнему применяются, и команды `rm` или `rmdir`, которые нацелены на `/`, ваш домашний каталог или другие критические пути системы, по-прежнему вызывают запрос. См. [sandbox modes](/ru/sandboxing#sandbox-modes) для изменения этого поведения.302Когда sandboxing включен с `autoAllowBashIfSandboxed: true`, что является значением по умолчанию, sandboxed Bash команды запускаются без запроса даже если ваши разрешения включают `ask: Bash(*)`. Граница sandbox заменяет запрос для каждой команды. Явные правила deny по-прежнему применяются, и команды `rm` или `rmdir`, которые нацелены на `/`, ваш домашний каталог или другие критические пути системы, по-прежнему вызывают запрос. См. [sandbox modes](/ru/sandboxing#sandbox-modes) для изменения этого поведения.

316| `allowManagedMcpServersOnly` | Когда `true`, только `allowedMcpServers` из управляемых параметров учитываются. `deniedMcpServers` все еще объединяется из всех источников. См. [Управляемая конфигурация MCP](/ru/mcp#managed-mcp-configuration) |316| `allowManagedMcpServersOnly` | Когда `true`, только `allowedMcpServers` из управляемых параметров учитываются. `deniedMcpServers` все еще объединяется из всех источников. См. [Управляемая конфигурация MCP](/ru/mcp#managed-mcp-configuration) |

317| `allowManagedPermissionRulesOnly` | Когда `true`, предотвращает определение правил разрешений `allow`, `ask` или `deny` в параметрах пользователя и проекта. Применяются только правила в управляемых параметрах |317| `allowManagedPermissionRulesOnly` | Когда `true`, предотвращает определение правил разрешений `allow`, `ask` или `deny` в параметрах пользователя и проекта. Применяются только правила в управляемых параметрах |

318| `blockedMarketplaces` | Список блокировки источников marketplace. Заблокированные источники проверяются перед загрузкой, поэтому они никогда не касаются файловой системы. См. [управляемые ограничения marketplace](/ru/plugin-marketplaces#managed-marketplace-restrictions) |318| `blockedMarketplaces` | Список блокировки источников marketplace. Заблокированные источники проверяются перед загрузкой, поэтому они никогда не касаются файловой системы. См. [управляемые ограничения marketplace](/ru/plugin-marketplaces#managed-marketplace-restrictions) |

319| `channelsEnabled` | Разрешить [channels](/ru/channels) для пользователей Team и Enterprise. Если не установлено или `false`, блокирует доставку сообщений канала независимо от того, что пользователи передают в `--channels` |319| `channelsEnabled` | Разрешить [channels](/ru/channels) для организации. См. [элементы управления предприятием](/ru/channels#enterprise-controls) для значения по умолчанию на каждом плане |

320| `forceRemoteSettingsRefresh` | Когда `true`, блокирует запуск CLI до тех пор, пока удаленные управляемые параметры не будут свежо получены, и выходит, если получение не удается. См. [принудительное закрытие при запуске](/ru/server-managed-settings#enforce-fail-closed-startup) |320| `forceRemoteSettingsRefresh` | Когда `true`, блокирует запуск CLI до тех пор, пока удаленные управляемые параметры не будут свежо получены, и выходит, если получение не удается. См. [принудительное закрытие при запуске](/ru/server-managed-settings#enforce-fail-closed-startup) |

321| `pluginTrustMessage` | Пользовательское сообщение, добавленное к предупреждению о доверии плагина, показываемому перед установкой |321| `pluginTrustMessage` | Пользовательское сообщение, добавленное к предупреждению о доверии плагина, показываемому перед установкой |

322| `sandbox.filesystem.allowManagedReadPathsOnly` | Когда `true`, только пути `filesystem.allowRead` из управляемых параметров учитываются. `denyRead` все еще объединяется из всех источников |322| `sandbox.filesystem.allowManagedReadPathsOnly` | Когда `true`, только пути `filesystem.allowRead` из управляемых параметров учитываются. `denyRead` все еще объединяется из всех источников |

327`disableBypassPermissionsMode` обычно размещается в управляемых параметрах для обеспечения организационной политики, но работает из любой области. Пользователь может установить его в своих собственных параметрах, чтобы заблокировать себя из режима bypass.327`disableBypassPermissionsMode` обычно размещается в управляемых параметрах для обеспечения организационной политики, но работает из любой области. Пользователь может установить его в своих собственных параметрах, чтобы заблокировать себя из режима bypass.

328 328

329<Note>329<Note>

330 Доступ к [Remote Control](/ru/remote-control) и [веб-сеансам](/ru/claude-code-on-the-web) не контролируется ключом управляемых параметров. На планах Team и Enterprise администратор включает или отключает эти функции в [Claude Code admin settings](https://claude.ai/admin-settings/claude-code).330 На планах Team и Enterprise администратор включает или отключает [Remote Control](/ru/remote-control) и [веб-сеансы](/ru/claude-code-on-the-web) организации в целом в [Claude Code admin settings](https://claude.ai/admin-settings/claude-code). Remote Control может дополнительно быть отключен для каждого устройства с помощью управляемого параметра [`disableRemoteControl`](/ru/settings#available-settings). Веб-сеансы не имеют ключа управляемых параметров для каждого устройства.

331</Note>331</Note>

332 332

333## Приоритет параметров333## Приоритет параметров

platforms.md +7 −4

Details

4 4

5# Платформы и интеграции5# Платформы и интеграции

6 6

7> Выберите, где запустить Claude Code и что к нему подключить. Сравните CLI, Desktop, VS Code, JetBrains, веб и интеграции, такие как Chrome, Slack и CI/CD.7> Выберите, где запустить Claude Code и что к нему подключить. Сравните CLI, Desktop, VS Code, JetBrains, веб, мобильные приложения и интеграции, такие как Chrome, Slack и CI/CD.

8 8

9Claude Code запускает один и тот же базовый движок везде, но каждая поверхность оптимизирована для разного способа работы. Эта страница поможет вам выбрать правильную платформу для вашего рабочего процесса и подключить инструменты, которые вы уже используете.9Claude Code запускает один и тот же базовый движок везде, но каждая поверхность оптимизирована для разного способа работы. Эта страница поможет вам выбрать правильную платформу для вашего рабочего процесса и подключить инструменты, которые вы уже используете.

10 10

13Выберите платформу в зависимости от того, как вы предпочитаете работать и где находится ваш проект.13Выберите платформу в зависимости от того, как вы предпочитаете работать и где находится ваш проект.

14 14

16| :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |16| :-------------------------------- | :-------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

18| [Desktop](/ru/desktop) | Визуальный просмотр, параллельные сеансы, управляемая установка | Средство просмотра различий, предпросмотр приложения, [использование компьютера](/ru/desktop#let-claude-use-your-computer) и [Dispatch](/ru/desktop#sessions-from-dispatch) на Pro и Max |18| [Desktop](/ru/desktop) | Визуальный просмотр, параллельные сеансы, управляемая установка | Средство просмотра различий, предпросмотр приложения, [использование компьютера](/ru/desktop#let-claude-use-your-computer) и [Dispatch](/ru/desktop#sessions-from-dispatch) на Pro и Max |

21| [Web](/ru/claude-code-on-the-web) | Долгосрочные задачи, которые не требуют большого управления, или работа, которая должна продолжаться, когда вы в сети | Облако, управляемое Anthropic, продолжается после отключения |21| [Web](/ru/claude-code-on-the-web) | Долгосрочные задачи, которые не требуют большого управления, или работа, которая должна продолжаться, когда вы в сети | Облако, управляемое Anthropic, продолжается после отключения |

22| Mobile | Запуск и мониторинг задач вдали от вашего компьютера | Облачные сеансы из приложения Claude для iOS и Android, [Remote Control](/ru/remote-control) для локальных сеансов, [Dispatch](/ru/desktop#sessions-from-dispatch) на Desktop на Pro и Max |

22 23

23CLI — это наиболее полная поверхность для работы, ориентированной на терминал: скриптинг, сторонние поставщики и Agent SDK доступны только в CLI. Desktop и расширения IDE обменивают некоторые функции, доступные только в CLI, на визуальный просмотр и более тесную интеграцию с редактором. Веб работает в облаке Anthropic, поэтому задачи продолжают выполняться после отключения.24CLI — это наиболее полная поверхность для работы, ориентированной на терминал: скриптинг и Agent SDK доступны только в CLI. Сторонние поставщики также работают в [VS Code](/ru/vs-code#use-third-party-providers). Корпоративные развёртывания [Desktop](/ru/desktop) поддерживают Vertex AI и поставщиков шлюза; для Bedrock или Foundry используйте вместо Desktop CLI или VS Code. Desktop и расширения IDE обменивают некоторые функции, доступные только в CLI, на визуальный просмотр и более тесную интеграцию с редактором. Веб работает в облаке Anthropic, поэтому задачи продолжают выполняться после отключения. Mobile — это тонкий клиент для этих же облачных сеансов или для локального сеанса через Remote Control, и может отправлять задачи на Desktop с помощью Dispatch.

24 25

25Вы можете смешивать поверхности в одном проекте. Конфигурация, память проекта и MCP серверы совместно используются на локальных поверхностях.26Вы можете смешивать поверхности в одном проекте. Конфигурация, память проекта и MCP серверы совместно используются на локальных поверхностях.

26 27

61* [VS Code](/ru/vs-code): расширение Claude Code внутри вашего редактора62* [VS Code](/ru/vs-code): расширение Claude Code внутри вашего редактора

62* [JetBrains](/ru/jetbrains): расширение для IntelliJ, PyCharm и других IDE JetBrains63* [JetBrains](/ru/jetbrains): расширение для IntelliJ, PyCharm и других IDE JetBrains

63* [Claude Code в веб](/ru/claude-code-on-the-web): облачные сеансы, которые продолжают работать при отключении64* [Claude Code в веб](/ru/claude-code-on-the-web): облачные сеансы, которые продолжают работать при отключении

65* Mobile: приложение Claude для [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) и [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) для запуска и мониторинга задач вдали от вашего компьютера

64 66

65### Интеграции67### Интеграции

66 68

67* [Chrome](/ru/chrome): автоматизация задач браузера с вашими авторизованными сеансами69* [Chrome](/ru/chrome): автоматизация задач браузера с вашими авторизованными сеансами

70* [Использование компьютера](/ru/computer-use): позвольте Claude открывать приложения и управлять вашим экраном на macOS

68* [GitHub Actions](/ru/github-actions): запуск Claude в вашем конвейере CI71* [GitHub Actions](/ru/github-actions): запуск Claude в вашем конвейере CI

69* [GitLab CI/CD](/ru/gitlab-ci-cd): то же самое для GitLab72* [GitLab CI/CD](/ru/gitlab-ci-cd): то же самое для GitLab

70* [Code Review](/ru/code-review): автоматическая проверка при каждом pull request73* [Code Review](/ru/code-review): автоматическая проверка при каждом pull request

plugin-marketplaces.md +8 −6

Details

23 23

24## Пошаговое руководство: создание локального marketplace24## Пошаговое руководство: создание локального marketplace

25 25

26Этот пример создает marketplace с одним плагином: skill `/quality-review` для проверки кода. Вы создадите структуру каталогов, добавите skill, создадите манифест плагина и каталог marketplace, затем установите и протестируете его.26Этот пример создает marketplace с одним плагином: skill `quality-review` для проверки кода. Вы создадите структуру каталогов, добавите skill, создадите манифест плагина и каталог marketplace, затем установите и протестируете его.

27 27

28<Steps>28<Steps>

29 <Step title="Создание структуры каталогов">29 <Step title="Создание структуры каталогов">

35 </Step>35 </Step>

36 36

37 <Step title="Создание skill">37 <Step title="Создание skill">

~~38 Создайте файл `SKILL.md`, который определяет, что делает skill `/quality-review`.~~38 Создайте файл `SKILL.md`, который определяет, что делает skill `quality-review`.

39 39

40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

41 ---41 ---

59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

60 {60 {

61 "name": "quality-review-plugin",61 "name": "quality-review-plugin",

~~62 "description": "Добавляет skill /quality-review для быстрой проверки кода",~~62 "description": "Добавляет skill quality-review для быстрой проверки кода",

63 "version": "1.0.0"63 "version": "1.0.0"

64 }64 }

65 ```65 ```

82 {82 {

83 "name": "quality-review-plugin",83 "name": "quality-review-plugin",

84 "source": "./plugins/quality-review-plugin",84 "source": "./plugins/quality-review-plugin",

~~85 "description": "Добавляет skill /quality-review для быстрой проверки кода"~~85 "description": "Добавляет skill quality-review для быстрой проверки кода"

86 }86 }

87 ]87 ]

88 }88 }

99 </Step>99 </Step>

100 100

101 <Step title="Попробуйте">101 <Step title="Попробуйте">

102 Выберите некоторый код в вашем редакторе и запустите вашу новую skill.102 Выберите некоторый код в вашем редакторе и запустите вашу новую skill. Plugin skills имеют пространство имен с именем плагина.

103 103

104 ```shell theme={null}104 ```shell theme={null}

105 /quality-review105 /quality-review-plugin:quality-review

106 ```106 ```

107 </Step>107 </Step>

108</Steps>108</Steps>

693* Для источников `hostPattern`: хост marketplace сопоставляется с шаблоном регулярного выражения693* Для источников `hostPattern`: хост marketplace сопоставляется с шаблоном регулярного выражения

694* Для источников `pathPattern`: путь файловой системы marketplace сопоставляется с шаблоном регулярного выражения694* Для источников `pathPattern`: путь файловой системы marketplace сопоставляется с шаблоном регулярного выражения

695 695

696Точное сопоставление не нормализует URL: конечная косая черта, суффикс `.git` или форма `ssh://` в сравнении с `https://` рассматриваются как разные значения. Если marketplace вашей организации можно клонировать более чем одной формой URL, предпочтите запись `hostPattern` буквальному URL, чтобы все формы совпадали.

697

696Поскольку `strictKnownMarketplaces` установлен в [управляемых параметрах](/ru/settings#settings-files), отдельные пользователи и конфигурации проекта не могут переопределить эти ограничения.698Поскольку `strictKnownMarketplaces` установлен в [управляемых параметрах](/ru/settings#settings-files), отдельные пользователи и конфигурации проекта не могут переопределить эти ограничения.

697 699

698Для полных деталей конфигурации, включая все поддерживаемые типы источников и сравнение с `extraKnownMarketplaces`, см. [справку strictKnownMarketplaces](/ru/settings#strictknownmarketplaces).700Для полных деталей конфигурации, включая все поддерживаемые типы источников и сравнение с `extraKnownMarketplaces`, см. [справку strictKnownMarketplaces](/ru/settings#strictknownmarketplaces).

plugins-reference.md +7 −3

Details

262**Доступные плагины LSP:**262**Доступные плагины LSP:**

263 263

265| :--------------- | :------------------------- | :------------------------------------------------------------------------------------------- |265| :------------------ | :------------------------- | :------------------------------------------------------------------------------------------- |

269 269

270Сначала установите языковой сервер, затем установите плагин из маркетплейса.270Сначала установите языковой сервер, затем установите плагин из маркетплейса.

271 271

531 531

532Claude Code предоставляет две переменные для ссылки на пути плагина. Обе подставляются встроенно везде, где они появляются в содержимом skills, содержимом agents, командах hooks, командах monitors и конфигурациях серверов MCP или LSP. Обе также экспортируются как переменные окружения в процессы hooks и подпроцессы серверов MCP или LSP.532Claude Code предоставляет две переменные для ссылки на пути плагина. Обе подставляются встроенно везде, где они появляются в содержимом skills, содержимом agents, командах hooks, командах monitors и конфигурациях серверов MCP или LSP. Обе также экспортируются как переменные окружения в процессы hooks и подпроцессы серверов MCP или LSP.

533 533

534**`${CLAUDE_PLUGIN_ROOT}`**: абсолютный путь к каталогу установки вашего плагина. Используйте это для ссылки на скрипты, двоичные файлы и файлы конфигурации, поставляемые с плагином. Этот путь изменяется при обновлении плагина, поэтому файлы, которые вы пишете здесь, не сохраняются при обновлении.534**`${CLAUDE_PLUGIN_ROOT}`**: абсолютный путь к каталогу установки вашего плагина. Используйте это для ссылки на скрипты, двоичные файлы и файлы конфигурации, поставляемые с плагином. Этот путь изменяется при обновлении плагина. Каталог предыдущей версии остаётся на диске примерно семь дней после обновления перед очисткой, но рассматривайте его как временный и не записывайте состояние здесь.

535

536Когда плагин обновляется во время сеанса, команды hooks, monitors, серверы MCP и серверы LSP продолжают использовать путь предыдущей версии. Запустите `/reload-plugins` для переключения hooks, серверов MCP и серверов LSP на новый путь; monitors требуют перезагрузки сеанса.

535 537

536**`${CLAUDE_PLUGIN_DATA}`**: постоянный каталог для состояния плагина, который сохраняется при обновлениях. Используйте это для установленных зависимостей, таких как `node_modules` или виртуальные окружения Python, сгенерированный код, кэши и любые другие файлы, которые должны сохраняться между версиями плагина. Каталог создаётся автоматически при первом обращении к этой переменной.538**`${CLAUDE_PLUGIN_DATA}`**: постоянный каталог для состояния плагина, который сохраняется при обновлениях. Используйте это для установленных зависимостей, таких как `node_modules` или виртуальные окружения Python, сгенерированный код, кэши и любые другие файлы, которые должны сохраняться между версиями плагина. Каталог создаётся автоматически при первом обращении к этой переменной.

537 539

677 Каталог `.claude-plugin/` содержит файл `plugin.json`. Все остальные каталоги (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) должны быть в корне плагина, а не внутри `.claude-plugin/`.679 Каталог `.claude-plugin/` содержит файл `plugin.json`. Все остальные каталоги (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) должны быть в корне плагина, а не внутри `.claude-plugin/`.

678</Warning>680</Warning>

679 681

682Файл `CLAUDE.md` в корне плагина не загружается как контекст проекта. Плагины предоставляют контекст через skills, agents и hooks, а не через CLAUDE.md. Чтобы отправить инструкции, которые загружаются в контекст Claude, поместите их в [skill](#skills).

683

680### Справочник местоположений файлов684### Справочник местоположений файлов

681 685

security.md +1 −1

Details

27* **Изолированный bash инструмент**: [Sandbox](/ru/sandboxing) bash команды с изоляцией файловой системы и сети, снижая количество запросов разрешений при сохранении безопасности. Включите с помощью `/sandbox` для определения границ, в которых Claude Code может работать автономно27* **Изолированный bash инструмент**: [Sandbox](/ru/sandboxing) bash команды с изоляцией файловой системы и сети, снижая количество запросов разрешений при сохранении безопасности. Включите с помощью `/sandbox` для определения границ, в которых Claude Code может работать автономно

28* **Ограничение доступа на запись**: Claude Code может писать только в папку, в которой он был запущен, и её подпапки — он не может изменять файлы в родительских директориях без явного разрешения. Хотя Claude Code может читать файлы вне рабочей директории (полезно для доступа к системным библиотекам и зависимостям), операции записи строго ограничены областью проекта, создавая четкую границу безопасности28* **Ограничение доступа на запись**: Claude Code может писать только в папку, в которой он был запущен, и её подпапки — он не может изменять файлы в родительских директориях без явного разрешения. Хотя Claude Code может читать файлы вне рабочей директории (полезно для доступа к системным библиотекам и зависимостям), операции записи строго ограничены областью проекта, создавая четкую границу безопасности

29* **Смягчение усталости от запросов**: Поддержка списков разрешений часто используемых безопасных команд для каждого пользователя, кодовой базы или организации29* **Смягчение усталости от запросов**: Поддержка списков разрешений часто используемых безопасных команд для каждого пользователя, кодовой базы или организации

30* **Режим Accept Edits**: Пакетное принятие нескольких правок при сохранении запросов разрешений для команд с побочными эффектами30* **Режим Accept Edits**: Автоматически одобряет правки файлов и фиксированный набор команд Bash файловой системы, таких как `mkdir`, `touch`, `rm`, `mv`, `cp` и `sed` для путей в рабочей директории. Другие команды Bash и пути вне области действия по-прежнему запрашивают разрешение

31 31

32### Ответственность пользователя32### Ответственность пользователя

33 33

settings.md +26 −3

Details

73 73

74На Windows пути, отображаемые как `~/.claude`, разрешаются в `%USERPROFILE%\.claude`.

74***76***

75 77

76## Файлы параметров78## Файлы параметров

166| `apiKeyHelper` | Пользовательский скрипт, который будет выполнен в `/bin/sh`, для создания значения аутентификации. Это значение будет отправлено как заголовки `X-Api-Key` и `Authorization: Bearer` для запросов модели | `/bin/generate_temp_api_key.sh` |168| `apiKeyHelper` | Пользовательский скрипт, который будет выполнен в `/bin/sh`, для создания значения аутентификации. Это значение будет отправлено как заголовки `X-Api-Key` и `Authorization: Bearer` для запросов модели | `/bin/generate_temp_api_key.sh` |

167| `attribution` | Настройте атрибуцию для коммитов git и pull requests. См. [Параметры атрибуции](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |169| `attribution` | Настройте атрибуцию для коммитов git и pull requests. См. [Параметры атрибуции](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

168| `autoMemoryDirectory` | Пользовательский каталог для хранения [автоматической памяти](/ru/memory#storage-location). Принимает абсолютный путь или путь с префиксом `~/`. Принимается из политики и параметров пользователя, а также из флага `--settings`. Не принимается из параметров проекта или локальных параметров, так как клонированный репозиторий может предоставить любой файл для перенаправления записей памяти в чувствительные местоположения | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | Пользовательский каталог для хранения [автоматической памяти](/ru/memory#storage-location). Принимает абсолютный путь или путь с префиксом `~/`. Принимается из политики и параметров пользователя, а также из флага `--settings`. Не принимается из параметров проекта или локальных параметров, так как клонированный репозиторий может предоставить любой файл для перенаправления записей памяти в чувствительные местоположения | `"~/my-memory-dir"` |

171| `autoMemoryEnabled` | Включить [автоматическую память](/ru/memory#enable-or-disable-auto-memory). Когда `false`, Claude не читает и не записывает в каталог автоматической памяти. По умолчанию: `true`. Вы также можете переключить это с помощью `/memory` во время сеанса | `false` |

169| `autoMode` | Настройте, что классификатор [автоматического режима](/ru/permission-modes#eliminate-prompts-with-auto-mode) блокирует и разрешает. Содержит массивы `environment`, `allow` и `soft_deny` правил в виде текста. Включите буквальную строку `"$defaults"` в массив для наследования встроенных правил в этой позиции. См. [Настройте автоматический режим](/ru/auto-mode-config). Не читается из общих параметров проекта | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | Настройте, что классификатор [автоматического режима](/ru/permission-modes#eliminate-prompts-with-auto-mode) блокирует и разрешает. Содержит массивы `environment`, `allow` и `soft_deny` правил в виде текста. Включите буквальную строку `"$defaults"` в массив для наследования встроенных правил в этой позиции. См. [Настройте автоматический режим](/ru/auto-mode-config). Не читается из общих параметров проекта | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

170| `autoScrollEnabled` | В [fullscreen rendering](/ru/fullscreen), следить за новым выводом в конец разговора. По умолчанию: `true`. Появляется в `/config` как **Auto-scroll**. Запросы разрешений по-прежнему прокручиваются в поле зрения, когда это отключено | `false` |173| `autoScrollEnabled` | В [fullscreen rendering](/ru/fullscreen), следить за новым выводом в конец разговора. По умолчанию: `true`. Появляется в `/config` как **Auto-scroll**. Запросы разрешений по-прежнему прокручиваются в поле зрения, когда это отключено | `false` |

171| `autoUpdatesChannel` | Канал выпуска для отслеживания обновлений. Используйте `"stable"` для версии, которая обычно примерно на неделю старше и пропускает версии с серьезными регрессиями, или `"latest"` (по умолчанию) для самого последнего выпуска | `"stable"` |174| `autoUpdatesChannel` | Канал выпуска для отслеживания обновлений. Используйте `"stable"` для версии, которая обычно примерно на неделю старше и пропускает версии с серьезными регрессиями, или `"latest"` (по умолчанию) для самого последнего выпуска | `"stable"` |

174| `awsAuthRefresh` | Пользовательский скрипт, который изменяет каталог `.aws` (см. [расширенная конфигурация учетных данных](/ru/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |177| `awsAuthRefresh` | Пользовательский скрипт, который изменяет каталог `.aws` (см. [расширенная конфигурация учетных данных](/ru/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

175| `awsCredentialExport` | Пользовательский скрипт, который выводит JSON с учетными данными AWS (см. [расширенная конфигурация учетных данных](/ru/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |178| `awsCredentialExport` | Пользовательский скрипт, который выводит JSON с учетными данными AWS (см. [расширенная конфигурация учетных данных](/ru/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

176| `blockedMarketplaces` | (Только управляемые параметры) Список запретов источников marketplace. Применяется при добавлении marketplace и при установке, обновлении, обновлении и автоматическом обновлении plugin, поэтому marketplace, добавленный до установки политики, не может быть использован для получения plugins. Заблокированные источники проверяются перед загрузкой, поэтому они никогда не касаются файловой системы. См. [Управляемые ограничения marketplace](/ru/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | (Только управляемые параметры) Список запретов источников marketplace. Применяется при добавлении marketplace и при установке, обновлении, обновлении и автоматическом обновлении plugin, поэтому marketplace, добавленный до установки политики, не может быть использован для получения plugins. Заблокированные источники проверяются перед загрузкой, поэтому они никогда не касаются файловой системы. См. [Управляемые ограничения marketplace](/ru/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

177| `channelsEnabled` | (Только управляемые параметры) Разрешить [channels](/ru/channels) для пользователей Team и Enterprise. Не установлено или `false` блокирует доставку сообщений канала независимо от того, что пользователи передают в `--channels` | `true` |180| `channelsEnabled` | (Только управляемые параметры) Разрешить [channels](/ru/channels) для организации. На планах Claude.ai Team и Enterprise, channels блокируются, когда это не установлено или `false`. Для учетных записей [Anthropic Console](/ru/authentication#claude-console-authentication), использующих аутентификацию по ключу API, channels разрешены по умолчанию, если только ваша организация не развернула управляемые параметры, в этом случае этот ключ должен быть установлен на `true` | `true` |

178| `cleanupPeriodDays` | Сеансы, неактивные дольше этого периода, удаляются при запуске (по умолчанию: 30 дней, минимум 1). Установка на `0` отклоняется с ошибкой валидации. Также контролирует возрастной порог для автоматического удаления [orphaned subagent worktrees](/ru/worktrees#clean-up-worktrees) при запуске. Чтобы полностью отключить запись стенограмм, установите переменную окружения [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ru/env-vars), или в неинтерактивном режиме (`-p`) используйте флаг `--no-session-persistence` или опцию SDK `persistSession: false`. | `20` |181| `cleanupPeriodDays` | Сеансы, неактивные дольше этого периода, удаляются при запуске (по умолчанию: 30 дней, минимум 1). Установка на `0` отклоняется с ошибкой валидации. Также контролирует возрастной порог для автоматического удаления [orphaned subagent worktrees](/ru/worktrees#clean-up-worktrees) при запуске. Чтобы полностью отключить запись стенограмм, установите переменную окружения [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ru/env-vars), или в неинтерактивном режиме (`-p`) используйте флаг `--no-session-persistence` или опцию SDK `persistSession: false`. | `20` |

179| `companyAnnouncements` | Объявление для отображения пользователям при запуске. Если предоставлено несколько объявлений, они будут циклически отображаться случайным образом. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |182| `companyAnnouncements` | Объявление для отображения пользователям при запуске. Если предоставлено несколько объявлений, они будут циклически отображаться случайным образом. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

180| `defaultShell` | Оболочка по умолчанию для команд `!` в поле ввода. Принимает `"bash"` (по умолчанию) или `"powershell"`. Установка `"powershell"` направляет интерактивные команды `!` через PowerShell на Windows. Требует `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. См. [Инструмент PowerShell](/ru/tools-reference#powershell-tool) | `"powershell"` |183| `defaultShell` | Оболочка по умолчанию для команд `!` в поле ввода. Принимает `"bash"` (по умолчанию) или `"powershell"`. Установка `"powershell"` направляет интерактивные команды `!` через PowerShell на Windows. Требует `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. См. [Инструмент PowerShell](/ru/tools-reference#powershell-tool) | `"powershell"` |

183| `disableAutoMode` | Установите на `"disable"`, чтобы предотвратить активацию [автоматического режима](/ru/permission-modes#eliminate-prompts-with-auto-mode). Удаляет `auto` из цикла `Shift+Tab` и отклоняет `--permission-mode auto` при запуске. Наиболее полезно в [управляемых параметрах](/ru/permissions#managed-settings), где пользователи не могут его переопределить | `"disable"` |186| `disableAutoMode` | Установите на `"disable"`, чтобы предотвратить активацию [автоматического режима](/ru/permission-modes#eliminate-prompts-with-auto-mode). Удаляет `auto` из цикла `Shift+Tab` и отклоняет `--permission-mode auto` при запуске. Наиболее полезно в [управляемых параметрах](/ru/permissions#managed-settings), где пользователи не могут его переопределить | `"disable"` |

184| `disableDeepLinkRegistration` | Установите на `"disable"`, чтобы предотвратить регистрацию Claude Code обработчика протокола `claude-cli://` с операционной системой при запуске. Deep links позволяют внешним инструментам открыть сеанс Claude Code с предварительно заполненным запросом. Полезно в окружениях, где регистрация обработчика протокола ограничена или управляется отдельно | `"disable"` |187| `disableDeepLinkRegistration` | Установите на `"disable"`, чтобы предотвратить регистрацию Claude Code обработчика протокола `claude-cli://` с операционной системой при запуске. Deep links позволяют внешним инструментам открыть сеанс Claude Code с предварительно заполненным запросом. Полезно в окружениях, где регистрация обработчика протокола ограничена или управляется отдельно | `"disable"` |

189| `disableRemoteControl` | {/* min-version: 2.1.128 */}Отключить [Remote Control](/ru/remote-control): блокирует `claude remote-control`, флаг `--remote-control`, автозапуск и переключение в сеансе. Обычно размещается в [управляемых параметрах](/ru/permissions#managed-settings) для применения MDM на каждом устройстве, но работает из любой области. Требует Claude Code v2.1.128 или позже | `true` |

186| `disableSkillShellExecution` | Отключить встроенное выполнение shell для `` !`...` `` и ` ```! ` блоков в [skills](/ru/skills) и пользовательских команд из источников пользователя, проекта, plugin или дополнительного каталога. Команды заменяются на `[shell command execution disabled by policy]` вместо выполнения. Встроенные и управляемые skills не затронуты. Наиболее полезно в [управляемых параметрах](/ru/permissions#managed-settings), где пользователи не могут его переопределить | `true` |190| `disableSkillShellExecution` | Отключить встроенное выполнение shell для `` !`...` `` и ` ```! ` блоков в [skills](/ru/skills) и пользовательских команд из источников пользователя, проекта, plugin или дополнительного каталога. Команды заменяются на `[shell command execution disabled by policy]` вместо выполнения. Встроенные и управляемые skills не затронуты. Наиболее полезно в [управляемых параметрах](/ru/permissions#managed-settings), где пользователи не могут его переопределить | `true` |

187| `editorMode` | Режим сочетания клавиш для входного приглашения: `"normal"` или `"vim"`. По умолчанию: `"normal"`. Появляется в `/config` как **Editor mode** | `"vim"` |191| `editorMode` | Режим сочетания клавиш для входного приглашения: `"normal"` или `"vim"`. По умолчанию: `"normal"`. Появляется в `/config` как **Editor mode** | `"vim"` |

188| `effortLevel` | Сохранить [уровень усилий](/ru/model-config#adjust-effort-level) между сеансами. Принимает `"low"`, `"medium"`, `"high"` или `"xhigh"`. Записывается автоматически при запуске `/effort` с одним из этих значений. См. [Отрегулировать уровень усилий](/ru/model-config#adjust-effort-level) для поддерживаемых моделей | `"xhigh"` |192| `effortLevel` | Сохранить [уровень усилий](/ru/model-config#adjust-effort-level) между сеансами. Принимает `"low"`, `"medium"`, `"high"` или `"xhigh"`. Записывается автоматически при запуске `/effort` с одним из этих значений. См. [Отрегулировать уровень усилий](/ru/model-config#adjust-effort-level) для поддерживаемых моделей | `"xhigh"` |

550 },554 },

551 "extraKnownMarketplaces": {555 "extraKnownMarketplaces": {

552 "acme-tools": {556 "acme-tools": {

557 "source": {

553 "source": "github",558 "source": "github",

554 "repo": "acme-corp/claude-plugins"559 "repo": "acme-corp/claude-plugins"

555 }560 }

556 }561 }

562 }

557}563}

558```564```

559 565

568* **Локальные параметры** (`.claude/settings.local.json`): Переопределения для каждой машины (не зафиксированы)574* **Локальные параметры** (`.claude/settings.local.json`): Переопределения для каждой машины (не зафиксированы)

569* **Управляемые параметры** (`managed-settings.json`): Переопределения организационной политики, которые блокируют установку на всех уровнях и скрывают plugin из marketplace575* **Управляемые параметры** (`managed-settings.json`): Переопределения организационной политики, которые блокируют установку на всех уровнях и скрывают plugin из marketplace

570 576

577<Note>

578 Параметры проекта имеют приоритет над параметрами пользователя, поэтому установка plugin на `false` в `~/.claude/settings.json` не отключает plugin, который параметры проекта `.claude/settings.json` включают. Чтобы отказаться от plugin, включенного проектом, на вашей машине, установите его на `false` в `.claude/settings.local.json` вместо этого.

579

580 Plugins, принудительно включенные управляемыми параметрами, не могут быть отключены таким образом, так как управляемые параметры переопределяют локальные параметры.

581</Note>

582

571**Пример**:583**Пример**:

572 584

573```json theme={null}585```json theme={null}

659* Доступно только в управляемых параметрах (`managed-settings.json`)671* Доступно только в управляемых параметрах (`managed-settings.json`)

660* Не может быть переопределено параметрами пользователя или проекта (наивысший приоритет)672* Не может быть переопределено параметрами пользователя или проекта (наивысший приоритет)

661* Применяется ДО операций сети/файловой системы (заблокированные источники никогда не выполняются)673* Применяется ДО операций сети/файловой системы (заблокированные источники никогда не выполняются)

662* Использует точное сопоставление для спецификаций источников (включая `ref`, `path` для источников git), кроме `hostPattern`, который использует сопоставление regex674* Использует точное сопоставление для спецификаций источников (включая `ref`, `path` для источников git), кроме `hostPattern` и `pathPattern`, которые используют сопоставление regex

663 675

664**Поведение списка разрешений**:676**Поведение списка разрешений**:

665 677

669 681

670**Все поддерживаемые типы источников**:682**Все поддерживаемые типы источников**:

671 683

672Список разрешений поддерживает несколько типов источников marketplace. Большинство источников используют точное сопоставление, в то время как `hostPattern` использует сопоставление regex с хостом marketplace.684Список разрешений поддерживает несколько типов источников marketplace. Большинство источников используют точное сопоставление, в то время как `hostPattern` и `pathPattern` используют сопоставление regex с хостом marketplace и путем файловой системы соответственно.

673 685

6741. **Репозитории GitHub**:6861. **Репозитории GitHub**:

675 687

749* `url`: извлекает имя хоста из URL761* `url`: извлекает имя хоста из URL

750* `npm`, `file`, `directory`: не поддерживается для сопоставления шаблона хоста762* `npm`, `file`, `directory`: не поддерживается для сопоставления шаблона хоста

751 763

7648. **Сопоставление шаблона пути**:

765

766```json theme={null}

767{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }

768{ "source": "pathPattern", "pathPattern": ".*" }

769```

770

771Поля: `pathPattern` (обязательно: шаблон regex, сопоставляемый с полем `path` источников `file` и `directory`)

772

773Используйте сопоставление шаблона пути для разрешения marketplaces на основе файловой системы наряду с ограничениями `hostPattern` для сетевых источников. Установите `".*"` для разрешения всех локальных путей или более узкий шаблон для ограничения определенными каталогами.

774

752**Примеры конфигурации**:775**Примеры конфигурации**:

753 776

754Пример: разрешить только определенные marketplaces:777Пример: разрешить только определенные marketplaces:

sub-agents.md +35 −10

Details

51 </Tab>51 </Tab>

52 52

53 <Tab title="Plan">53 <Tab title="Plan">

54 Исследовательский агент, используемый во время [plan mode](/ru/common-workflows#use-plan-mode-for-safe-code-analysis) для сбора контекста перед представлением плана.54 Исследовательский агент, используемый во время [plan mode](/ru/permission-modes#analyze-before-you-edit-with-plan-mode) для сбора контекста перед представлением плана.

55 55

56 * **Model**: Наследуется из основного разговора56 * **Model**: Наследуется из основного разговора

57 * **Tools**: Инструменты только для чтения (запрещён доступ к инструментам Write и Edit)57 * **Tools**: Инструменты только для чтения (запрещён доступ к инструментам Write и Edit)

77 | :---------------- | :----- | :--------------------------------------------------------------- |77 | :---------------- | :----- | :--------------------------------------------------------------- |

80 </Tab>80 </Tab>

81</Tabs>81</Tabs>

82 82

180 180

181**CLI-определённые subagents** передаются как JSON при запуске Claude Code. Они существуют только для этой сессии и не сохраняются на диск, что делает их полезными для быстрого тестирования или скриптов автоматизации. Вы можете определить несколько subagents в одном вызове `--agents`:181**CLI-определённые subagents** передаются как JSON при запуске Claude Code. Они существуют только для этой сессии и не сохраняются на диск, что делает их полезными для быстрого тестирования или скриптов автоматизации. Вы можете определить несколько subagents в одном вызове `--agents`:

182 182

183```bash theme={null}183<Tabs>

184claude --agents '{184 <Tab title="macOS, Linux, WSL">

185 ```bash theme={null}

186 claude --agents '{

185 "code-reviewer": {187 "code-reviewer": {

186 "description": "Expert code reviewer. Use proactively after code changes.",188 "description": "Expert code reviewer. Use proactively after code changes.",

187 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",189 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

192 "description": "Debugging specialist for errors and test failures.",194 "description": "Debugging specialist for errors and test failures.",

193 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."195 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

194 }196 }

195}'197 }'

196```198 ```

199 </Tab>

200

201 <Tab title="Windows PowerShell">

202 ```powershell theme={null}

203 claude --agents @'

204 {

205 "code-reviewer": {

206 "description": "Expert code reviewer. Use proactively after code changes.",

207 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

208 "tools": ["Read", "Grep", "Glob", "Bash"],

209 "model": "sonnet"

210 },

211 "debugger": {

212 "description": "Debugging specialist for errors and test failures.",

213 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

214 }

215 }

216 '@

217 ```

218 </Tab>

219</Tabs>

197 220

198Флаг `--agents` принимает JSON с теми же полями [frontmatter](#supported-frontmatter-fields), что и файловые subagents: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation` и `color`. Используйте `prompt` для системного приглашения, эквивалентного телу markdown в файловых subagents.221Флаг `--agents` принимает JSON с теми же полями [frontmatter](#supported-frontmatter-fields), что и файловые subagents: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation` и `color`. Используйте `prompt` для системного приглашения, эквивалентного телу markdown в файловых subagents.

199 222

212Файлы subagent используют YAML frontmatter для конфигурации, за которым следует системное приглашение в Markdown:235Файлы subagent используют YAML frontmatter для конфигурации, за которым следует системное приглашение в Markdown:

213 236

214<Note>237<Note>

215 Subagents загружаются при запуске сессии. Если вы создаёте subagent путём ручного добавления файла, перезагрузите сессию или используйте `/agents` для немедленной загрузки.238 Subagents загружаются при запуске сессии. Если вы добавляете или редактируете файл subagent напрямую на диск, перезагрузите сессию для его загрузки. Subagents, созданные через интерфейс `/agents`, вступают в силу немедленно без перезагрузки.

216</Note>239</Note>

217 240

218```markdown theme={null}241```markdown theme={null}

250| `memory` | No | [Область постоянной памяти](#enable-persistent-memory): `user`, `project` или `local`. Включает кросс-сессионное обучение |273| `memory` | No | [Область постоянной памяти](#enable-persistent-memory): `user`, `project` или `local`. Включает кросс-сессионное обучение |

251| `background` | No | Установите на `true`, чтобы всегда запускать этот subagent как [фоновую задачу](#run-subagents-in-foreground-or-background). По умолчанию: `false` |274| `background` | No | Установите на `true`, чтобы всегда запускать этот subagent как [фоновую задачу](#run-subagents-in-foreground-or-background). По умолчанию: `false` |

252| `effort` | No | Уровень усилий, когда этот subagent активен. Переопределяет уровень усилий сессии. По умолчанию: наследуется из сессии. Параметры: `low`, `medium`, `high`, `xhigh`, `max`; доступные уровни зависят от модели |275| `effort` | No | Уровень усилий, когда этот subagent активен. Переопределяет уровень усилий сессии. По умолчанию: наследуется из сессии. Параметры: `low`, `medium`, `high`, `xhigh`, `max`; доступные уровни зависят от модели |

253| `isolation` | No | Установите на `worktree`, чтобы запустить subagent во временном [git worktree](/ru/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), дав ему изолированную копию репозитория. Worktree автоматически очищается, если subagent не вносит изменения |276| `isolation` | No | Установите на `worktree`, чтобы запустить subagent во временном [git worktree](/ru/worktrees), дав ему изолированную копию репозитория. Worktree автоматически очищается, если subagent не вносит изменения |

254| `color` | No | Цвет отображения для subagent в списке задач и транскрипте. Принимает `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink` или `cyan` |277| `color` | No | Цвет отображения для subagent в списке задач и транскрипте. Принимает `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink` или `cyan` |

255| `initialPrompt` | No | Автоматически отправляется как первый ход пользователя, когда этот агент работает как основной агент сессии (через `--agent` или параметр `agent`). [Commands](/ru/commands) и [skills](/ru/skills) обрабатываются. Добавляется в начало любого предоставленного пользователем приглашения |278| `initialPrompt` | No | Автоматически отправляется как первый ход пользователя, когда этот агент работает как основной агент сессии (через `--agent` или параметр `agent`). [Commands](/ru/commands) и [skills](/ru/skills) обрабатываются. Добавляется в начало любого предоставленного пользователем приглашения |

256 279

484exit 0507exit 0

485```508```

486 509

487См. [Hook input](/ru/hooks#pretooluse-input) для полной схемы входных данных и [exit codes](/ru/hooks#exit-code-output) для того, как коды выхода влияют на поведение.510См. [Hook input](/ru/hooks#pretooluse-input) для полной схемы входных данных и [exit codes](/ru/hooks#exit-code-output) для того, как коды выхода влияют на поведение. На Windows напишите скрипты hook в PowerShell и добавьте `shell: powershell` к записи hook, как показано в [запуске hooks в PowerShell](/ru/hooks#windows-powershell-tool).

488 511

489#### Отключите конкретные subagents512#### Отключите конкретные subagents

490 513

994exit 01017exit 0

995```1018```

996 1019

997Сделайте скрипт исполняемым:1020На macOS и Linux сделайте скрипт исполняемым:

998 1021

999```bash theme={null}1022```bash theme={null}

1000chmod +x ./scripts/validate-readonly-query.sh1023chmod +x ./scripts/validate-readonly-query.sh

1001```1024```

1002 1025

1026На Windows напишите скрипт валидации на PowerShell и добавьте `shell: powershell` к записи hook. См. [запуск hooks в PowerShell](/ru/hooks#windows-powershell-tool).

1027

1003Hook получает JSON через stdin с командой Bash в `tool_input.command`. Код выхода 2 блокирует операцию и передаёт сообщение об ошибке обратно Claude. См. [Hooks](/ru/hooks#exit-code-output) для деталей кодов выхода и [Hook input](/ru/hooks#pretooluse-input) для полной схемы входных данных.1028Hook получает JSON через stdin с командой Bash в `tool_input.command`. Код выхода 2 блокирует операцию и передаёт сообщение об ошибке обратно Claude. См. [Hooks](/ru/hooks#exit-code-output) для деталей кодов выхода и [Hook input](/ru/hooks#pretooluse-input) для полной схемы входных данных.

1004 1029

1005## Следующие шаги1030## Следующие шаги

vs-code.md +13 −3

Details

95* **Режимы разрешений**: нажмите на индикатор режима в нижней части поля ввода запроса, чтобы переключать режимы. В обычном режиме Claude запрашивает разрешение перед каждым действием. В Plan Mode Claude описывает, что он будет делать, и ждёт одобрения перед внесением изменений. VS Code автоматически открывает план как полный документ markdown, где вы можете добавлять встроенные комментарии, чтобы дать обратную связь перед началом работы Claude. В режиме автоматического принятия Claude вносит правки без запроса. Установите значение по умолчанию в параметрах VS Code в разделе `claudeCode.initialPermissionMode`.95* **Режимы разрешений**: нажмите на индикатор режима в нижней части поля ввода запроса, чтобы переключать режимы. В обычном режиме Claude запрашивает разрешение перед каждым действием. В Plan Mode Claude описывает, что он будет делать, и ждёт одобрения перед внесением изменений. VS Code автоматически открывает план как полный документ markdown, где вы можете добавлять встроенные комментарии, чтобы дать обратную связь перед началом работы Claude. В режиме автоматического принятия Claude вносит правки без запроса. Установите значение по умолчанию в параметрах VS Code в разделе `claudeCode.initialPermissionMode`.

96* **Меню команд**: нажмите `/` или введите `/`, чтобы открыть меню команд. Опции включают присоединение файлов, переключение моделей, переключение расширенного мышления, просмотр использования плана (`/usage`) и запуск сеанса [Remote Control](/ru/remote-control) (`/remote-control`). Раздел Customize предоставляет доступ к MCP servers, hooks, памяти, разрешениям и plugins. Элементы со значком терминала открываются во встроенном терминале.96* **Меню команд**: нажмите `/` или введите `/`, чтобы открыть меню команд. Опции включают присоединение файлов, переключение моделей, переключение расширенного мышления, просмотр использования плана (`/usage`) и запуск сеанса [Remote Control](/ru/remote-control) (`/remote-control`). Раздел Customize предоставляет доступ к MCP servers, hooks, памяти, разрешениям и plugins. Элементы со значком терминала открываются во встроенном терминале.

97* **Индикатор контекста**: поле ввода запроса показывает, сколько контекстного окна Claude вы используете. Claude автоматически выполняет компактизацию при необходимости, или вы можете выполнить `/compact` вручную.97* **Индикатор контекста**: поле ввода запроса показывает, сколько контекстного окна Claude вы используете. Claude автоматически выполняет компактизацию при необходимости, или вы можете выполнить `/compact` вручную.

98* **Расширенное мышление**: позволяет Claude потратить больше времени на рассуждение о сложных проблемах. Включите его через меню команд (`/`). Рассуждение Claude появляется в беседе как свёрнутые блоки: нажмите на блок, чтобы прочитать его, или нажмите `Ctrl+O`, чтобы развернуть или свернуть каждый блок мышления в сеансе. Подробности см. в разделе [Расширенное мышление](/ru/common-workflows#use-extended-thinking-thinking-mode).98* **Расширенное мышление**: позволяет Claude потратить больше времени на рассуждение о сложных проблемах. Включите его через меню команд (`/`). Рассуждение Claude появляется в беседе как свёрнутые блоки: нажмите на блок, чтобы прочитать его, или нажмите `Ctrl+O`, чтобы развернуть или свернуть каждый блок мышления в сеансе. Подробности см. в разделе [Расширенное мышление](/ru/model-config#extended-thinking).

99* **Многострочный ввод**: нажмите `Shift+Enter`, чтобы добавить новую строку без отправки. Это также работает в поле свободного текста "Other" диалогов вопросов.99* **Многострочный ввод**: нажмите `Shift+Enter`, чтобы добавить новую строку без отправки. Это также работает в поле свободного текста "Other" диалогов вопросов.

100 100

101### Ссылка на файлы и папки101### Ссылка на файлы и папки

115 115

116### Возобновление прошлых бесед116### Возобновление прошлых бесед

117 117

118Нажмите на кнопку **Session history** в верхней части панели Claude Code, чтобы получить доступ к истории вашей беседы. Вы можете искать по ключевому слову или просматривать по времени (Today, Yesterday, Last 7 days и т. д.). Нажмите на любую беседу, чтобы возобновить её с полной историей сообщений. Новые сеансы получают названия, созданные AI, на основе вашего первого сообщения. Наведите указатель на сеанс, чтобы открыть действия переименования и удаления: переименуйте, чтобы дать ему описательное название, или удалите, чтобы удалить его из списка. Дополнительную информацию о возобновлении сеансов см. в разделе [Распространённые рабочие процессы](/ru/common-workflows#resume-previous-conversations).118Нажмите на кнопку **Session history** в верхней части панели Claude Code, чтобы получить доступ к истории вашей беседы. Вы можете искать по ключевому слову или просматривать по времени (Today, Yesterday, Last 7 days и т. д.). Нажмите на любую беседу, чтобы возобновить её с полной историей сообщений. Новые сеансы получают названия, созданные AI, на основе вашего первого сообщения. Наведите указатель на сеанс, чтобы открыть действия переименования и удаления: переименуйте, чтобы дать ему описательное название, или удалите, чтобы удалить его из списка. Дополнительную информацию о возобновлении сеансов см. в разделе [Управление сеансами](/ru/sessions).

119 119

120### Возобновление удалённых сеансов из Claude.ai120### Возобновление удалённых сеансов из Claude.ai

121 121

399claude --worktree feature-auth399claude --worktree feature-auth

400```400```

401 401

402Каждый worktree сохраняет независимое состояние файлов при совместном использовании истории git. Это предотвращает помехи между экземплярами Claude при работе над различными задачами. Дополнительные подробности см. в разделе [Запуск параллельных сеансов Claude Code с помощью Git worktrees](/ru/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees).402Каждый worktree сохраняет независимое состояние файлов при совместном использовании истории git. Это предотвращает помехи между экземплярами Claude при работе над различными задачами. Дополнительные подробности см. в разделе [Запуск параллельных сеансов с Git worktrees](/ru/worktrees).

403 403

404## Использование поставщиков третьей стороны404## Использование поставщиков третьей стороны

405 405

476 476

477Альтернативно, нажмите "✱ Claude Code" в **Status Bar** (нижний правый угол). Это работает даже без открытого файла. Вы также можете использовать **Command Palette** (`Cmd+Shift+P` / `Ctrl+Shift+P`) и ввести "Claude Code".477Альтернативно, нажмите "✱ Claude Code" в **Status Bar** (нижний правый угол). Это работает даже без открытого файла. Вы также можете использовать **Command Palette** (`Cmd+Shift+P` / `Ctrl+Shift+P`) и ввести "Claude Code".

478 478

479### Cmd+Esc ничего не делает на macOS

480

481На macOS Tahoe и более поздних версиях системный ярлык Game Overlay по умолчанию привязан к `Cmd+Esc` и перехватывает нажатие клавиши перед тем, как оно достигнет VS Code. Чтобы освободить ярлык:

482

4831. Откройте System Settings

4842. Перейдите в Keyboard, затем Keyboard Shortcuts, затем Game Controllers

4853. Снимите флажок Game Overlay

486

487Альтернативно, переназначьте расширение на другую клавишу: откройте редактор [Keyboard Shortcuts](https://code.visualstudio.com/docs/configure/keybindings) в VS Code (`Cmd+K Cmd+S`), найдите `Claude Code: Focus input` и назначьте новое сочетание клавиш.

488

479### Claude Code никогда не отвечает489### Claude Code никогда не отвечает

480 490

481Если Claude Code не отвечает на ваши запросы:491Если Claude Code не отвечает на ваши запросы:

Documentation 2026-05-04 22:58 UTC to 2026-05-05 23:00 UTC