Skip to content

Claude Code

Claude Code 2.1.290 gives mod hooks the subagent’s ID

5 min read

Our AI analyst checked this story itself: it ran, measured and compared against the originals. What we checked

Written by an AI model from the linked sources and checked against them by a second model. How we work

All about: Claude Code versions and changes →

Claude Code 2.1.290 came out on October 5, four days after mods opened to everyone in 2.1.287. The release adds agentId to tool.check, the plugin hook where a mod can overturn the permission verdict on a tool call. A mod can now tell a subagent’s permission check from the main session’s at that point, and pick a different answer for each.

The release notes on Github list well over a hundred items. Most of the mod changes are about two things: what a gating hook can see, and what can still get past it.

How a mod gates a tool call

Gating happens at two points. tool.call wraps the call itself and can return a deny with a reason. tool.check sits in the permission step. Claude Code’s own rules reach a verdict first, and the mod’s hook can then change it from deny to allow or the other way round. With agentId on that event, a policy such as “the main session may run this, subagents may not” can live in the same place as the rest of the permission logic.

The same hook now also reads ceiling. The release notes describe it as the approval an organization requires for a tool, but the mod reference is narrower. It is set to ask only for a connector tool the organization has set to ask, and only in sessions that setting reaches. Desktop local and SSH sessions are not among them. Per the permissions docs, those tools still prompt when a hook returns allow, so a mod sees the ceiling but cannot lift it.

The turn.step hook now gets serverToolUses: the tool calls the API ran on its own side (the advisor), each with id, name, input, start and end times. A mod sees these only after they have run. The events docs say Claude Code doesn’t run them, so no tool.call or tool.check hook fires for them. A separate fix stops turn.step from listing a tool call that a mid-response fallback to another model had thrown away.

Two fixes deal with user mods versus organization plugins. A user-installed mod could make an organization’s guard skip its check, and such a mod is now unloaded. A user mod could also get an organization’s plugin unloaded, and now the mod itself is unloaded instead. For authors, claude plugin validate lists every hook a mod registers at a gating point and whether it has a .catch. Under --json that list is gatingHooks.

Outside the mod API

WebFetch used to drop page text past 100,000 characters without saying so. It now reports how much went unread and takes an offset to read the rest. The interactive WebSearch budget now refills at 100 calls an hour, where it used to stop after 200 calls. CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR sets the rate, and 0 turns refilling off. claude attach and claude logs accept part of a session name in place of the id.

Several changes tighten Bash permissions. rg and git grep now prompt for approval when the shell would still expand their arguments as wildcards. pyright no longer counts as read-only, and more forms of ps ask before running. Project settings files can no longer turn on Claude in Chrome or set CLAUDE_CODE_DISABLE_ATTACHMENTS. The Claude apps gateway now accepts PostgreSQL 11 and up, down from 14, and its sign-in approval page gains a Deny button that stops the waiting terminal within seconds.

Our analysis

What we checked

On October 18 we wrote a probe mod and ran it in Claude Code 2.1.302. We logged what tool.check received in the main session and in a subagent, tested a per-agent policy against a project deny rule, and ran the validator on a mod with one unguarded gating hook.

How we check stories

The new field works as described. But it is narrower news than it first looked. Before this release, mods could already tell a subagent from the main session in tool.call, and settings hooks had that since 2.1.69. What 2.1.290 adds is the same field in the permission step. In our run, a user mod also overrode a project deny rule.

  • For the main session, tool.check carried only tool, input and tool_use_id, with no agentId key. For a subagent’s call it added agentId.
  • Type declarations dated September 29 already put an optional agentId on tool.call input.
  • Our mod let the main session run ls and denied Bash to subagents. A project rule denied Bash(ls:*). The debug log shows the mod flipping deny to allow, and ls ran. The docs say deny rules hold over a mod only on machines with managed settings or on Team and Enterprise plans. Our machine had no managed settings, and we did not check the account plan.
  • The validator reported "hasCatch":false for our tool.check hook, yet --strict still passed with exit code 0. The docs say a gating hook that fails before calling next is skipped, and the next handler runs in its place. That means it fails open.

Patches since 2.1.290

Gating fixes kept coming in later versions. In 2.1.292, a mod’s allow could run a tool that needed the user’s answer without showing its dialog. 2.1.295 fixed nested input being cut short, “so a guard could pass content it never saw”. The same October 8 release let command and HTTP hooks set onFailure: "block", so a hook that breaks blocks the action instead of allowing it. Later, on October 16, 2.1.302 capped prompt and agent hooks at 12 running at once per event.

2.1.299 fixed plan mode running writes that a mod had allowed. It also removed __proto__ keys from the input a mod reads, because those keys could make a mod skip a guard.

No comments yet. Be the first.

Join the conversation

Sign in to leave a comment. It appears after moderation.