Skip to content

fix: enforce CLAUDE_ALLOWED_TOOLS with a PreToolUse hook (#221) - #245

Open
FrundlesTian wants to merge 1 commit into
overwirehq:mainfrom
FrundlesTian:fix/221-enforce-allowed-tools
Open

FrundlesTian wants to merge 1 commit into
overwirehq:mainfrom
FrundlesTian:fix/221-enforce-allowed-tools

Conversation

@FrundlesTian

Copy link
Copy Markdown
Collaborator

Description

CLAUDE_ALLOWED_TOOLS is 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:

#221 acceptance item Status
A tool absent from CLAUDE_ALLOWED_TOOLS is denied, with a clear reason surfaced to the user ✅ Denied by a PreToolUse hook. The CLI reports the denial in permission_denials, so the reply ends with "🚫 1 tool call was blocked: CronList" (#236), and Claude gets a reason telling it not to retry.
MCP tools still work with ENABLE_MCP=true ✅ Every tool of a server in MCP_CONFIG_PATH is allowed (option 2 from the issue: resolved from the configured servers, not a blanket mcp__*). mcp__<server> / mcp__<server>__* entries are also honoured.
Task / sub-agent tool calls still work ✅ Sub-agent calls are checked against the same list. Task and Agent (the CLI's newer name) are aliases.
settings.py, .env.example and docs/tools.md agree on the default list and its count ✅ 20 tools, and docs/configuration.md matches too.
DISABLE_TOOL_VALIDATION=true continues to bypass the check ✅ No hook is installed.
Verified against a live session, not only unit tests ✅ See Testing below. The live run is also what changed the design.

Type of Change

  • New feature
  • Bug fix
  • Breaking change
  • Documentation update

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 consults can_use_tool for calls that need no permission: CronList, Agent and a Read inside 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 PreToolUse hook, 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, never allow, so can_use_tool and the APPROVED_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

  • Failure mode for unknown/new CLI tools (item 4): fail closed. The issue leaned towards fail-open-and-log, but acceptance item 1 requires that unlisted tools be denied, and the live session made the stakes concrete. The bundled CLI (2.1.277) exposes 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.
  • CLI-internal tools (item 3): TaskStop, BashOutput and KillShell were added to the default list. AskUserQuestion, EnterPlanMode and ExitPlanMode were 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.
  • Scoped rules such as Bash(git:*) allow their base tool in the hook. The hook runs before the CLI's allow rules and cannot evaluate the scope, so denying Bash would block the very calls the rule pre-approves.
  • An empty CLAUDE_ALLOWED_TOOLS means no allowlist, matching the CLI, which receives no allow rules in that case.

⚠️ Behaviour change for operators

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_TOOLS to opt in. Removing a tool from the list, a filesystem tool included, now disables it.

Testing

  • Tests added/updated (allowlist matcher, hook decisions, execute_command wiring incl. MCP config, disable flag, empty list, removed guarded tool)
  • All tests pass (706 passed); black/isort/flake8 clean; no new mypy errors
  • Live session, bundled CLI 2.1.277, real ClaudeSDKManager + SecurityValidator, ENABLE_MCP=true with a local stdio MCP server:
    • CronList called in the main thread → denied, reported in permission_denials
    • CronList called inside a general-purpose sub-agent → denied (hook saw agent_type=general-purpose), reported
    • Agent sub-agent, Read inside the sub-agent, mcp__probe__magic_number → all ran
    • can_use_tool was still consulted (for the MCP tool) with the hook installed, so the hook's empty result does not short-circuit the callback
    • Not verified live: an out-of-boundary Write being denied, because the model declined to attempt it twice. The callback path is unchanged and covered by the existing tests.

Checklist

  • make format has been run
  • Code follows project style guidelines
  • Self-review completed
  • Documentation updated (SECURITY.md, docs/tools.md, docs/configuration.md, .env.example, CLAUDE.md)

🤖 Generated with Claude Code

)

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>
@github-actions

Copy link
Copy Markdown
  • CHANGELOG.md (no entry in the diff): this changes default behaviour. A tool left off CLAUDE_ALLOWED_TOOLS used to be allowed. It is now denied, and that includes tools a newer CLI introduces. It also adds TaskStop, BashOutput and KillShell to the default list. Add an Unreleased entry that says so, so operators with a custom list or a newer CLI know to extend it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

CLAUDE_ALLOWED_TOOLS does not restrict anything while can_use_tool is wired — unlisted tools fall through to an unconditional allow

1 participant