Repository navigation
fix: enforce CLAUDE_ALLOWED_TOOLS with a PreToolUse hook (#221) - #245
Open
FrundlesTian wants to merge 1 commit into
Open
FrundlesTian wants to merge 1 commit into
FrundlesTian wants to merge 1 commit into
Conversation
) A tool left off CLAUDE_ALLOWED_TOOLS was not blocked: it fell through to the can_use_tool callback, which allowed it. Moving the check into that callback is not enough either -- a live session shows the CLI never consults it for calls that need no permission (read-only tools such as CronList, Task/Agent, reads inside the working directory). Enforce the list with a PreToolUse hook instead, which the CLI runs for every call, sub-agents' included. The hook denies unlisted tools and returns no decision for listed ones, so can_use_tool and its boundary checks still run. Tools of MCP servers in MCP_CONFIG_PATH are allowed when ENABLE_MCP=true, Task/Agent are aliases, scoped rules allow their base tool, and DISABLE_TOOL_VALIDATION=true turns the hook off. The CLI reports hook denials in permission_denials, so they reach the user. The default list gains TaskStop, BashOutput and KillShell, and settings.py, .env.example, docs/configuration.md and docs/tools.md now agree on it (20 tools). Verified against a live session (bundled CLI 2.1.277, ENABLE_MCP=true): CronList denied in the main thread and inside a sub-agent and reported in permission_denials; Agent, Read inside the sub-agent and an MCP tool still ran; can_use_tool still consulted with the hook in place. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
CLAUDE_ALLOWED_TOOLSis now enforced: a tool that is not on the list is denied, the user is told which call was blocked, and every other check still runs.Related Issue
Closes #221
How each acceptance item in #221 is covered:
CLAUDE_ALLOWED_TOOLSis denied, with a clear reason surfaced to the userPreToolUsehook. The CLI reports the denial inpermission_denials, so the reply ends with "🚫 1 tool call was blocked: CronList" (#236), and Claude gets a reason telling it not to retry.ENABLE_MCP=trueMCP_CONFIG_PATHis allowed (option 2 from the issue: resolved from the configured servers, not a blanketmcp__*).mcp__<server>/mcp__<server>__*entries are also honoured.Task/ sub-agent tool calls still workTaskandAgent(the CLI's newer name) are aliases.settings.py,.env.exampleanddocs/tools.mdagree on the default list and its countdocs/configuration.mdmatches too.DISABLE_TOOL_VALIDATION=truecontinues to bypass the checkType of Change
Why a hook and not the callback
The issue suggests denying unlisted tools in
can_use_tool. I built that first and the unit tests passed. A live session then showed that the CLI never consultscan_use_toolfor calls that need no permission:CronList,Agentand aReadinside a sub-agent all ran without reaching the callback. A callback-only allowlist would have been inert for exactly those tools. This is the #219 failure again, from the other side.The SDK's own guidance (see the 0.2 comment on #221) is a
PreToolUsehook, which runs for every call, sub-agents' calls included. The trap noted in that comment is handled: for a listed tool the hook returns no decision, neverallow, socan_use_tooland theAPPROVED_DIRECTORY/ Bash boundary checks still run. The boundary checks stay in the callback and the allowlist moves to the hook. The two are not layered on the same decision.Decisions on the issue's open questions
CronCreate,Workflow,SendMessage,PushNotification,Monitor(which runs shell commands outside the Bash boundary check) and more, and none of them are listed. Failing open would have let all of them run. Each denial is logged and shown to the user, so an operator can see what to add.TaskStop,BashOutputandKillShellwere added to the default list.AskUserQuestion,EnterPlanModeandExitPlanModewere deliberately left out (and removed from.env.example) because they need an interactive Claude Code UI the bot does not have. The default keeps older-CLI names (Glob,Grep,LS, ...) so it works across versions.Bash(git:*)allow their base tool in the hook. The hook runs before the CLI's allow rules and cannot evaluate the scope, so denyingBashwould block the very calls the rule pre-approves.CLAUDE_ALLOWED_TOOLSmeans no allowlist, matching the CLI, which receives no allow rules in that case.Tools that are not on the list used to run and are now denied. With the default list, that covers the newer CLI tools above. Add a tool to
CLAUDE_ALLOWED_TOOLSto opt in. Removing a tool from the list, a filesystem tool included, now disables it.Testing
execute_commandwiring incl. MCP config, disable flag, empty list, removed guarded tool)ClaudeSDKManager+SecurityValidator,ENABLE_MCP=truewith a local stdio MCP server:CronListcalled in the main thread → denied, reported inpermission_denialsCronListcalled inside ageneral-purposesub-agent → denied (hook sawagent_type=general-purpose), reportedAgentsub-agent,Readinside the sub-agent,mcp__probe__magic_number→ all rancan_use_toolwas still consulted (for the MCP tool) with the hook installed, so the hook's empty result does not short-circuit the callbackWritebeing denied, because the model declined to attempt it twice. The callback path is unchanged and covered by the existing tests.Checklist
make formathas been runSECURITY.md,docs/tools.md,docs/configuration.md,.env.example,CLAUDE.md)🤖 Generated with Claude Code