deny в параметрах разрешений.
Чтобы добавить пользовательские инструменты, подключите MCP server. Чтобы расширить Claude с помощью переиспользуемых рабочих процессов на основе подсказок, напишите skill, который работает через существующий инструмент Skill вместо добавления новой записи инструмента.
Столбец “Требуется разрешение” показывает, запрашивает ли инструмент разрешение в режиме разрешений по умолчанию для путей внутри рабочего каталога. Инструменты доступа к файлам, отмеченные “Нет”, включая Read, Grep и Glob, по-прежнему запрашивают разрешение для путей вне рабочего каталога и дополнительных каталогов. Bash отмечен как “Да”, но выполняет встроенный набор команд только для чтения без запроса разрешения.
Настройка инструментов с помощью правил разрешений и hooks
В большинстве случаев Claude решает, когда использовать эти инструменты, и вам не нужно называть их самостоятельно при взаимодействии с Claude. Вы ссылаетесь на названия инструментов напрямую при определении разрешений и другой конфигурации:- в
permissions.allowиpermissions.denyв параметрах и интерфейсе/permissions - в флагах CLI
--allowedToolsи--disallowedTools - в опциях
allowedToolsиdisallowedToolsAgent SDK - в frontmatter
toolsилиdisallowedToolssubagent - в frontmatter
allowed-toolsskill - в условии
ifhook
ToolName(specifier). Спецификатор зависит от инструмента, и несколько инструментов используют один формат:
Инструменты, не указанные здесь, такие как
ExitPlanMode или ShareOnboardingGuide, принимают только простое имя инструмента без спецификатора.
Правило разрешения Edit(...) также предоставляет доступ на чтение к тому же пути, поэтому вам не нужно соответствующее правило Read(...). Правило запрета Read(...) также блокирует инструмент Edit на том же пути, включая создание нового файла там, потому что редактирование требует чтения результата обратно. Проверка запрета Read при редактировании требует Claude Code v2.1.208 или более поздней версии.
Поля matcher Hook используют простые названия инструментов, а не формат с скобками. См. шаблоны сопоставления для правил сопоставления. Для названий полей, которые каждый инструмент передает в tool_input в hooks, см. справочник входных данных PreToolUse.
Поведение инструмента Agent
Инструмент Agent создает subagent в отдельном контекстном окне. Subagent самостоятельно выполняет свою задачу, а затем возвращает один текстовый результат в родительский разговор. Родитель не видит промежуточные вызовы инструментов или выходные данные subagent, только этот финальный результат. Чтобы ограничить количество ходов, которые выполняет subagent, установитеmaxTurns в определении subagent.
Тот же инструмент Agent также запускает forked subagents при включении режима fork. Fork наследует полный родительский разговор вместо начала с нуля, всегда работает в фоне и по-прежнему отображает подсказки разрешений в вашем терминале. Остальная часть этого раздела описывает именованные subagents.
Какие инструменты может использовать именованный subagent, зависит от полей tools и disallowedTools в определении subagent:
- Ни одно поле не установлено: subagent наследует каждый инструмент, доступный родителю.
- Только
tools: subagent получает только перечисленные инструменты. - Только
disallowedTools: subagent получает каждый инструмент родителя, кроме перечисленных. - Оба установлены:
disallowedToolsимеет приоритет. Инструмент, указанный в обоих, удаляется.
tools subagent разрешается в отсутствие инструментов вообще, например, потому что каждая запись содержит опечатку или называет инструмент, который недоступен для subagents, инструмент Agent возвращает ошибку, перечисляющую эти записи, вместо запуска subagent. До версии 2.1.208 subagent запускался без инструментов и мог вернуть пустой или запутанный результат.
Запуск subagent сам по себе не запрашивает разрешение. Claude Code проверяет вызовы инструментов subagent против ваших правил разрешений по мере его работы.
Начиная с версии 2.1.198, subagents работают в фоне по умолчанию; Claude запускает один на переднем плане, когда ему нужен результат перед продолжением.
- Foreground subagents показывают те же подсказки разрешений, которые вы видели бы в основном разговоре, в момент каждого вызова инструмента.
- Background subagents отображают подсказки разрешений в вашем основном сеансе начиная с версии 2.1.186. Подсказка указывает, какой subagent запрашивает разрешение, и нажатие Esc отклоняет этот вызов инструмента без остановки subagent. До версии 2.1.186 background subagents автоматически отклоняли любой вызов инструмента, который иначе запросил бы подсказку, и продолжали работу без этого инструмента.
tools, оставьте Bash вне списка или установите правила deny в ваших параметрах, как описано в Control subagent capabilities. Для получения дополнительной информации о выборе между foreground и background см. Run subagents in foreground or background.
Поведение инструмента Bash
Инструмент Bash запускает каждую команду в отдельном процессе со следующим поведением сохранения:- Когда Claude запускает
cdв основном сеансе, новый рабочий каталог переносится в более поздние команды Bash, пока он остается внутри каталога проекта или дополнительного рабочего каталога, который вы добавили с помощью--add-dir,/add-dirилиadditionalDirectoriesв параметрах. Сеансы subagent никогда не переносят изменения рабочего каталога.- Если
cdприводит вне этих каталогов, Claude Code сбрасывает в каталог проекта и добавляетShell cwd was reset to <dir>к результату инструмента. - Чтобы отключить этот перенос, чтобы каждая команда Bash начиналась в каталоге проекта, установите
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1.
- Если
- Переменные окружения не сохраняются.
exportв одной команде не будет доступен в следующей. - Псевдонимы и функции оболочки, определенные в файле запуска оболочки, доступны. При запуске сеанса Claude Code загружает
~/.zshrc,~/.bashrcили~/.profileв зависимости от вашей оболочки, захватывает полученные псевдонимы, функции и параметры оболочки и применяет их к каждой команде Bash.
CLAUDE_ENV_FILE на скрипт оболочки перед запуском Claude Code или используйте hook SessionStart для динамического заполнения.
Два ограничения ограничивают каждую команду:
- Timeout: два минуты по умолчанию. Claude может запросить до 10 минут на команду с параметром
timeout. Переопределите значение по умолчанию и потолок с помощьюBASH_DEFAULT_TIMEOUT_MSиBASH_MAX_TIMEOUT_MS. - Длина вывода: 30 000 символов по умолчанию. Когда команда производит больше, Claude Code сохраняет полный вывод в файл в каталоге сеанса и дает Claude путь к файлу плюс короткий предпросмотр с начала. Claude читает или ищет этот файл, когда ему нужен остаток. Увеличьте лимит с помощью
BASH_MAX_OUTPUT_LENGTH, до жесткого потолка в 150 000 символов.
run_in_background: true для запуска команды как фоновой задачи и продолжения работы во время ее выполнения. Выводите список и останавливайте фоновые задачи с помощью /tasks. В неинтерактивном режиме с флагом -p фоновые задачи завершаются вскоре после окончательного результата запуска.
Поведение инструмента Edit
Инструмент Edit выполняет точную замену строк. Он принимаетold_string и new_string и заменяет первый на второй. Он не использует regex или нечеткое сопоставление.
Три проверки должны пройти для применения редактирования. Перед любой из них путь, соответствующий правилу deny Read, отклоняется, включая создание нового файла там. Отклонение требует Claude Code v2.1.208 или позже.
- Read-before-edit: Claude читает файл в текущем разговоре перед редактированием, и файл, прочитанный с уведомлением
PARTIAL view, не считается. Claude Opus 4.6, Claude Haiku 4.5 и более старые модели всегда требуют чтение. Более новые модели могут редактировать непрочитанный файл при чтении, когда чтение не требует запроса разрешения и инструмент Read доступен. - Match:
old_stringдолжен появиться в файле точно так, как написано. Даже один символ пробела или различия в отступе достаточно, чтобы пропустить. - Uniqueness:
old_stringдолжен появиться ровно один раз. Когда он появляется более одного раза, Claude либо предоставляет более длинную строку с достаточным окружающим контекстом для определения одного вхождения, либо устанавливаетreplace_all: trueдля замены всех.
old_string точно и однозначно совпадает с текущим содержимым и Claude Code может прочитать файл без запроса. Сопоставление с текущим содержимым файла обеспечивает безопасность, и результат отмечает, что файл содержит другие изменения, поэтому Claude перечитывает его перед редактированиями, которые зависят от окружающего содержимого. В любом другом случае, например при устаревшем old_string или при совпадении более одного раза без replace_all, Claude читает файл снова перед редактированием. Расслабленная обработка непрочитанных и измененных файлов требует Claude Code v2.1.208 или позже; до этого Claude Code отклонял любое редактирование файла, который он не прочитал в разговоре или который изменился на диске после чтения.
Просмотр файла с помощью Bash также удовлетворяет требованию read-before-edit, когда команда — это cat, head, tail, sed -n 'X,Yp', grep, egrep или fgrep на одном файле без pipes или redirects. Piped вывод и другие команды Bash не считаются для проверки read-before-edit.
Это влияет только на приемлемость редактирования, а не на разрешения. Правила deny Read и Edit также применяются к командам файлов, которые Claude Code распознает в Bash, таким как cat, head, tail, sed и grep, но не к произвольным подпроцессам, которые косвенно читают или записывают файлы, такие как скрипт Python или Node, который открывает файлы сам. Набор команд, распознаваемых для правил deny, не совпадает со списком read-before-edit выше: например, egrep и fgrep считаются для read-before-edit, но не проверяются против правил deny Read. Для принудительного применения на уровне ОС, охватывающего каждый процесс, включите sandbox.
Поведение инструмента Glob
Инструмент Glob находит файлы по шаблону имени. Он поддерживает стандартный синтаксис glob, включая** для рекурсивного сопоставления каталогов:
**/*.jsсоответствует всем файлам.jsна любой глубинеsrc/**/*.tsсоответствует всем файлам.tsподsrc/*.{json,yaml}соответствует файлам.jsonи.yamlв текущем каталоге
.gitignore по умолчанию, поэтому он находит файлы, игнорируемые git, наряду с отслеживаемыми. Это отличается от Grep, который пропускает файлы, игнорируемые git. Чтобы заставить Glob соблюдать .gitignore, установите CLAUDE_CODE_GLOB_NO_IGNORE=false перед запуском Claude Code.
Значение pattern или path, содержащее нулевой байт, возвращает ошибку с просьбой к Claude удалить его.
Поведение инструмента Grep
Инструмент Grep ищет шаблоны в содержимом файлов. Где Glob находит файлы по имени, Grep находит строки внутри них. Grep построен на ripgrep и использует синтаксис regex ripgrep, а не POSIX grep. Шаблоны, которые включают метасимволы regex, нуждаются в экранировании. Например, поискinterface{} в коде Go требует шаблона interface\{\}.
Шаблон, glob или тип файла, который ripgrep отклоняет, возвращает ошибку, которая включает диагностику ripgrep, поэтому Claude может исправить входные данные и выполнить поиск снова. До версии 2.1.208 Claude Code сообщал об отклоненном входе как No files found вместо ошибки, даже когда искомый текст существовал в целевых файлах.
Три режима вывода контролируют, что возвращается:
files_with_matches: только пути к файлам, без содержимого строк. Это значение по умолчанию.content: соответствующие строки с номером файла и строки.count: количество совпадений на файл, за которым следует общее количество совпадений во всех соответствующих файлах. Общее количество охватывает каждое совпадение, даже когда параметрыhead_limitилиoffsetинструмента усекают перечисленные записи для каждого файла. До версии 2.1.208 общее количество суммировало только перечисленные записи.
glob, таким как **/*.tsx, или по языку с параметром type, таким как py или rust. По умолчанию шаблоны совпадают в одной строке. Claude может установить multiline: true для совпадения через границы строк.
Grep соблюдает .gitignore, поэтому файлы, игнорируемые git, пропускаются. Чтобы найти файл, игнорируемый git, Claude передает его путь напрямую.
Поведение инструмента LSP
Инструмент LSP предоставляет Claude интеллект кода от работающего языкового сервера. После каждого редактирования файла он автоматически сообщает об ошибках типов и предупреждениях, чтобы Claude мог исправить проблемы без отдельного этапа сборки. Claude также может вызвать его напрямую для навигации по коду:- Переход к определению символа
- Поиск всех ссылок на символ
- Получение информации о типе в позиции
- Список символов в файле
- Поиск символа по имени во всей рабочей области
- Поиск реализаций интерфейса
- Трассировка иерархий вызовов
Инструмент Monitor
Инструмент Monitor позволяет Claude наблюдать что-то в фоне и реагировать при изменении, без паузы разговора. Попросите Claude:- Отслеживать файл журнала и отмечать ошибки по мере их появления
- Опрашивать PR или задачу CI и сообщать при изменении статуса
- Наблюдать за каталогом на предмет изменений файлов
- Отслеживать вывод из любого долгоживущего скрипта, на который вы его указываете
- Подключиться к потоку WebSocket и сообщать каждое сообщение по мере его поступления
allow и deny, которые вы установили для Bash, применяются здесь также. Источник WebSocket имеет собственное приглашение на одобрение.
Инструмент недоступен на Amazon Bedrock, Google Cloud’s Agent Platform или Microsoft Foundry. Он также недоступен, когда установлены DISABLE_TELEMETRY или CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC.
Плагины могут объявлять мониторы, которые запускаются автоматически при активации плагина, вместо того чтобы просить Claude запустить их. См. мониторы плагинов.
Источник WebSocket
Источник WebSocket требует Claude Code версии 2.1.195 или более поздней.
- Текстовые сообщения: каждое становится одним событием, даже если сообщение охватывает несколько строк.
- Двоичные сообщения: не передаются. Claude получает строку-заполнитель, такую как
[binary frame, 512 bytes]. - Сообщения размером более 1 МиБ: наблюдение завершается, поэтому подпишитесь на отфильтрованный поток, если он существует.
- Закрытие сокета: наблюдение завершается и Claude получает код закрытия.
ws вместо command, и один вызов Monitor не может объединять оба. Входные данные ws имеют два поля:
Входные данные
timeout_ms и persistent ведут себя так же, как для команды: наблюдение завершается в крайний срок, если не установлен persistent, и TaskStop отменяет его раньше.
Открытие WebSocket запрашивает одобрение, и приглашение не предлагает возможность пропустить будущие приглашения для одного хоста.
Claude Code отклоняет URL-адреса, указывающие на приватный, link-local или адрес облачных метаданных, включая имена хостов, которые разрешаются в один. Он также отклоняет хосты в sandbox.network.deniedDomains, и когда allowManagedDomainsOnly установлен в управляемых параметрах, любой хост вне управляемого списка разрешений.
Поведение инструмента NotebookEdit
NotebookEdit изменяет Jupyter notebook по одной ячейке за раз, нацеливаясь на ячейки по ихcell_id. Он не выполняет замену строк по всему notebook так, как Edit делает на простых файлах.
Три режима редактирования контролируют, что происходит с целевой ячейкой:
replace: перезаписать источник ячейки. Это значение по умолчанию.insert: добавить новую ячейку после целевой. Безcell_idновая ячейка переходит в начало notebook. Требует установкиcell_typeнаcodeилиmarkdown.delete: удалить целевую ячейку.
Edit(...). Правило, такое как Edit(notebooks/**), охватывает вызовы NotebookEdit на файлы в этом каталоге.
Инструмент PowerShell
Инструмент PowerShell позволяет Claude запускать команды PowerShell изначально. На Windows это означает, что команды выполняются в PowerShell вместо маршрутизации через Git Bash. Доступность инструмента зависит от вашей платформы:- Windows без Git Bash: инструмент включается автоматически.
- Windows с установленным Git Bash: инструмент развертывается постепенно.
- Linux, macOS и WSL: инструмент является добровольным.
Включение инструмента PowerShell
УстановитеCLAUDE_CODE_USE_POWERSHELL_TOOL=1 в вашей среде или в settings.json:
0, чтобы отказаться от развертывания. На Linux, macOS и WSL инструмент требует PowerShell 7 или более поздней версии: установите pwsh и убедитесь, что он находится в вашем PATH.
На Windows Claude Code автоматически обнаруживает pwsh.exe для PowerShell 7+ с резервным вариантом powershell.exe для PowerShell 5.1. Когда инструмент включен, Claude рассматривает PowerShell как основную оболочку. Инструмент Bash остается доступным для POSIX-скриптов при установленном Git Bash.
Claude Code запускает PowerShell с -ExecutionPolicy Bypass только в области процесса, поэтому скрипты .ps1 и импорт модулей работают на стандартных установках Windows без изменения политики машины. Обход области процесса не переопределяет Group Policy MachinePolicy или UserPolicy, поэтому политики на уровне предприятия по-прежнему применяются. Чтобы соблюдать эффективную политику выполнения машины, установите CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1.
Выбор оболочки в параметрах, hooks и skills
Три дополнительных параметра контролируют, где используется PowerShell:"defaultShell": "powershell"вsettings.json: маршрутизирует интерактивные команды!через PowerShell. Требует включения инструмента PowerShell."shell": "powershell"на отдельных command hooks: запускает этот hook в PowerShell. Hooks запускают PowerShell напрямую, поэтому это работает независимо отCLAUDE_CODE_USE_POWERSHELL_TOOL.shell: powershellв frontmatter skill: запускает блоки!`command`в PowerShell. Требует включения инструмента PowerShell.
CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR.
Начиная с версии 2.1.196, инструмент PowerShell соответствует обработке инструментом Bash кодов выхода поиска и diff. Код выхода 1 из grep, egrep, fgrep и git grep означает отсутствие совпадений, а код выхода 1 из git diff означает наличие различий, поэтому эти результаты не сообщаются Claude как ошибки команд.
Ограничения предварительного просмотра
Инструмент PowerShell имеет следующие известные ограничения во время предварительного просмотра:- Профили PowerShell не загружаются
- На Windows sandboxing не поддерживается
Поведение инструмента Read
Инструмент Read принимает путь к файлу и возвращает содержимое с номерами строк. Claude инструктирован всегда передавать абсолютные пути. По умолчанию Read возвращает файл с начала. Когда чтение всего файла превышает лимит токенов, Read возвращает первую страницу с уведомлениемPARTIAL view, которое сообщает Claude, какую часть файла он получил, и как читать дальше с помощью offset и limit. Чтение, которое передает явный offset или limit и все еще превышает лимит токенов, возвращает ошибку.
Чтение с явным limit останавливается, как только выбранные строки превышают то, что лимит токенов когда-либо мог вместить, и возвращает ошибку без загрузки остальной части диапазона. Ошибка сообщает Claude использовать меньший limit, или искать конкретное содержимое с помощью Grep вместо этого, когда одна строка такая большая. До версии 2.1.208 Claude Code загружал весь диапазон в память перед его отклонением, поэтому файл с чрезвычайно длинной одной строкой мог исчерпать память.
Чтение пустого файла возвращает уведомление о том, что файл существует, но его содержимое пусто, и offset за последней строкой возвращает уведомление, дающее количество строк файла. До версии 2.1.208 чтение пустого файла возвращало уведомление о конце вместо этого.
Read обрабатывает несколько типов файлов помимо простого текста:
- Изображения: PNG, JPG и другие форматы изображений возвращаются как визуальное содержимое, которое Claude может видеть, а не как необработанные байты. Claude Code изменяет размер и переупаковывает большие изображения, чтобы они соответствовали ограничениям размера изображения модели перед отправкой, поэтому Claude может видеть уменьшенную версию большого снимка экрана. Начиная с версии 2.1.196, изображение, которое все еще больше 500KB после этого изменения размера, переупаковывается как JPEG с пониженным качеством с неизменными размерами пикселей. Если Claude пропустит детали на уровне пикселей в большом изображении, попросите его сначала обрезать интересующий регион, например с помощью ImageMagick через Bash.
- PDFs: Claude читает короткие файлы
.pdfцеликом. Для PDF-файлов длиннее 10 страниц он читает в диапазонах с параметромpages, таким как"1-5", до 20 страниц за раз. - Jupyter notebooks: файлы
.ipynbвозвращают все ячейки с их выходными данными, включая код, markdown и визуализации.
ls через инструмент Bash для вывода содержимого каталога.
Поведение инструмента WebFetch
WebFetch принимает URL и подсказку, описывающую, что извлечь. Он получает страницу, преобразует ответ в Markdown, когда сервер возвращает HTML, и запускает подсказку против содержимого, используя небольшую, быструю модель. Для большинства выборок Claude получает ответ этой модели, а не необработанную страницу. Этап преобразования не настраивается. Это делает WebFetch потерянным по дизайну. Подсказка извлечения определяет, что достигает Claude, поэтому результат, который говорит, что страница не упоминает что-то, может означать только, что подсказка не спросила об этом. Попросите Claude получить снова с более конкретной подсказкой или используйтеcurl через Bash для необработанной страницы.
Несколько поведений формируют ответ, который получает Claude:
- HTTP URLs автоматически обновляются до HTTPS.
- Большие страницы усекаются до фиксированного лимита символов перед обработкой.
- Ответы кэшируются на 15 минут, поэтому повторные выборки одного и того же URL возвращаются быстро.
- Когда URL перенаправляется на другой хост, WebFetch возвращает текстовый результат, который называет исходный URL и цель перенаправления вместо его следования. Claude затем получает новый URL со вторым вызовом WebFetch.
acceptEdits, WebFetch запрашивает в первый раз, когда он достигает нового домена, за исключением встроенного набора предварительно одобренных доменов документации, которые получают без подсказки. Чтобы разрешить домен заранее без подсказки, добавьте правило разрешения, такое как WebFetch(domain:example.com). Режимы разрешений auto и bypassPermissions permission modes полностью пропускают подсказку.
Явное правило WebFetch(domain:...) в deny, ask или allow имеет приоритет над предварительно одобренным набором, поэтому вы можете заблокировать предварительно одобренный домен или потребовать для него подсказку.
WebFetch устанавливает заголовок User-Agent, начинающийся с Claude-User, и заголовок Accept, который предпочитает Markdown перед HTML, чтобы серверы, поддерживающие согласование содержимого, могли возвращать Markdown напрямую.
Вы настраиваете sandbox правила сети отдельно, поэтому домен, который вы хотите, чтобы процесс в песочнице достиг, по-прежнему нуждается в явном правиле разрешения песочницы.
Поведение инструмента WebSearch
WebSearch запускает запрос против веб-поиска Anthropic и возвращает названия результатов и URLs. Он не получает страницы результатов. Чтобы прочитать страницу, которую Claude находит в результатах поиска, он следует с WebFetch. Инструмент может выполнить до восьми поисков на бэкенде на вызов, уточняя поиск внутри перед возвращением результатов. Claude может ограничить результаты с помощьюallowed_domains для включения только определенных хостов или blocked_domains для их исключения. Два списка не могут быть объединены в одном вызове.
Бэкенд поиска не настраивается. Чтобы выполнить поиск с другим поставщиком, добавьте MCP server, который предоставляет инструмент поиска.
Правила разрешений WebSearch не принимают спецификатор. Запись WebSearch в allow или deny — это единственная форма.
WebSearch доступен на Claude API, Claude Platform on AWS и Microsoft Foundry. На Google Cloud’s Agent Platform он работает с моделями Claude 4 и более поздними версиями, включая Opus, Sonnet и Haiku. Amazon Bedrock не предоставляет инструмент веб-поиска на стороне сервера.
Поведение инструмента Write
Инструмент Write создает новый файл или перезаписывает существующий с полным предоставленным содержимым. Он не добавляет и не объединяет. Если целевой путь уже существует, Claude должен был прочитать этот файл по крайней мере один раз в текущем разговоре перед перезаписью. Write на непрочитанный существующий файл не удается с ошибкой. Это ограничение не применяется к новым файлам. Просмотр файла с помощью Bash также удовлетворяет этому требованию в соответствии с теми же правилами, описанными в поведении инструмента Edit. Для частичных изменений существующего файла Claude использует Edit вместо Write.Проверка доступных инструментов
Ваш точный набор инструментов зависит от вашего поставщика, платформы и параметров. Чтобы проверить, что загружено в работающем сеансе, спросите Claude напрямую:/mcp.
Инструмент advisor — это серверный инструмент, который запускает API, а не инструмент, который реализует Claude Code. Он не имеет имени, на которое вы можете ссылаться в правилах разрешений или сопоставителях hooks.
См. также
- MCP servers: добавляйте пользовательские инструменты, подключая внешние серверы
- Разрешения: система разрешений, синтаксис правил и шаблоны для конкретных инструментов
- Subagents: настройка доступа к инструментам для subagents
- Hooks: запуск пользовательских команд до или после выполнения инструмента