Claude Code scoped disallowedTools rules remove Bash from --agent sessions

[durandom]

Summary

When a named Claude Code agent contains a scoped Bash rule in its frontmatter, such as:

disallowedTools: Bash(sed *)

Claude Code removes the entire Bash tool from the top-level --agent session. The problem is not the --agent flag by itself.

The resulting error is:

Error: No such tool available: Bash. Bash exists but is not enabled in this context.

Confirmed with Claude Code v2.1.156 in the fullsend sandbox and v2.1.207 locally.

Validated root cause

Controlled tests on v2.1.207:

Agent configuration	Tool count	Bash available?
No --agent	24	Yes
Named agent, no tool restrictions	24	Yes
disallowedTools: Write, Edit	22	Yes
disallowedTools: Bash(sed)	23	No
disallowedTools: Bash(sed *)	23	No
Full code-agent Bash deny patterns	23	No

The same result occurs with --bare, which disables hooks, plugins, custom settings, and other integrations.

Claude's documentation says a scoped rule such as Bash(rm *) should keep Bash visible and deny only matching commands. Named sessions launched with --agent are documented to use the agent's tool restrictions. The observed behavior therefore appears to be a Claude Code bug in scoped disallowedTools handling.

Documentation:

• https://code.claude.com/docs/en/sub-agents
• https://code.claude.com/docs/en/agent-sdk/custom-tools

Minimal reproduction

Run a named agent with a scoped Bash deny rule:

claude \
  --agents '{"bash-test":{"description":"Minimal test agent","prompt":"Reply OK.","disallowedTools":["Bash(sed *)"]}}' \
  --agent bash-test \
  --print --verbose --output-format stream-json \
  'Reply exactly OK without tools.' |
jq 'select(.type == "system" and .subtype == "init") |
    {tool_count: (.tools | length), has_bash: (.tools | index("Bash") != null)}'

Actual result:

{"tool_count":23,"has_bash":false}

Control case: remove disallowedTools from the inline agent definition. Bash remains present and the tool count is 24.

Fullsend impact

Fullsend launches named sessions with:

claude --agent '<name>' --dangerously-skip-permissions

The upstream code and fix agents currently contain multiple scoped Bash rules, including Bash(sed *), Bash(awk *), and Bash(git push *). As a result, those top-level agents start without Bash and delegate shell work to subagents.

The first observed production example was:

• https://github.com/redhat-developer/rhdh-plugins/actions/runs/29083351902
• Total duration: 38m52s
• Agent duration: 34m48s
• Total cost: $5.99
• Tool calls across the agent tree: 141
• Top-level Bash failure followed by four spawned subagents

This confirms significant overhead, although the exact incremental cost and slowdown require a controlled comparison with an equivalent fixed run.

How we discovered it: the agent self-recovers through subagents

The failure did not initially look like a hard runtime error because the top-level agent worked around it autonomously. The transcript from the cited run shows the complete recovery path:

Time (UTC)	Event
09:35:09	The top-level code agent attempts its required Bash setup command and receives No such tool available: Bash.
09:35:28	It explicitly recognizes the limitation: “I don't have direct Bash access in this context” and decides to spawn a subagent.
09:35:36	It spawns another subagent_type: code to perform the implementation. That agent inherits the same broken scoped disallowedTools rules, attempts Bash twice, and also fails.
09:39:36	The top-level agent probes a generic subagent_type: claude with echo, pwd, and git status. Bash works immediately.
09:40:11	Having identified a working agent type, it delegates the complete implementation to a generic claude subagent.
10:08:53	The generic subagent completes the implementation after 75 tool calls, including 49 Bash calls.
10:08:59	The top-level agent spawns a second generic claude subagent to verify the branch, commit, diff, and output file using six more Bash calls.
10:09:46	The top-level agent reports success.

The resulting session tree was:

Session	Role	Tool calls	Bash calls	Bash availability errors
Top-level code agent	Orchestration	12	1	1
Spawned code agent	First implementation attempt	47	2	2
Generic claude agent	Bash availability probe	1	1	0
Generic claude agent	Actual implementation	75	49	0
Generic claude agent	Final verification	6	6	0

This behavior is important for diagnosis:

• The run succeeds instead of failing fast, so the underlying tool-inventory bug is easy to miss.
• Bash works in the same sandbox when a generic claude agent is used, ruling out the sandbox image and OpenShell policy as the cause.
• A spawned code agent fails in the same way as the top-level code agent, tying the failure to that agent definition.
• The workaround multiplies contexts and tool calls: the top-level session performed only 12 tool calls, while the complete agent tree performed 141.
• The successful result therefore masks substantial latency and token cost caused by automatic delegation.

The evidence is in the fullsend-code artifact attached to:

• https://github.com/redhat-developer/rhdh-plugins/actions/runs/29083351902

Findings ruled out

• --agent alone: a named agent without tool restrictions retains Bash.
• Security hooks: reproduced with --bare; hooks cannot explain the missing init tool.
• Managed agent definitions: the minimal inline-agent reproduction does not depend on them.
• Built-in code agent: Claude Code has no built-in agent with that name.
• agent: "" harness override: fullsend composition treats an empty scalar as unset and inherits the base agent, so this does not clear the agent field.

Workarounds and proper fix

Interim workaround

Remove scoped disallowedTools: Bash(...) entries from the code and fix agent frontmatter. This restores Bash access.

Implemented for rhdh-agentic in:

• https://github.com/redhat-developer/rhdh-agentic/pull/91

Do not rely on a frontmatter Bash allowlist with fullsend

A definition such as tools: Bash(gh,echo) keeps Bash in the inventory. However, fullsend uses --dangerously-skip-permissions; under that mode, testing showed that an unlisted sed command still executed. This is not suitable for command-level enforcement in fullsend.

Recommended fullsend fix

Use permissions.deny in the generated project .claude/settings.json.

Validated on v2.1.207 with --dangerously-skip-permissions:

• echo executed successfully.
• sed remained a Bash tool call but was denied specifically.
• Bash stayed present in the init tool inventory.

Fullsend already generates /sandbox/workspace/.claude/settings.json for hooks, but the generated structure currently has no permissions block. Extend the harness schema and settings generator to support scoped deny rules, then remove the broken frontmatter rules.

Related upstream reports

These are related tool-inventory bugs, but they are not the same minimal reproduction:

• [BUG] Task tool missing when launching session with --agent (tools not inherited even when undefined) anthropics/claude-code#13533 — closed stale
• [BUG] Custom agents (--agent) cannot spawn subagents into teams - Task tool unavailable anthropics/claude-code#23506 — closed as duplicate
• [BUG] Sub-agent frontmatter tools: array silently drops first and last positions at spawn time anthropics/claude-code#60237 — closed completed

Related fullsend-ai work

A search of open and closed issues and pull requests in fullsend-ai/fullsend found the following related work:

Item	Status	Relationship
fullsend#303	Open	Direct implementation issue for adding permissions.deny to generated .claude/settings.json. This is the primary fullsend-side fix.
fullsend#4437	Open	Direct workaround issue for removing broken disallowedTools entries from code/fix agents. The actual agent definitions now live in fullsend-ai/agents.
fullsend#558	Open	Related linting proposal for agent frontmatter. Its premise that tools and disallowedTools are inert under --agent is outdated and should be corrected.
fullsend#3874	Closed	Earlier production evidence of the same recovery pattern: a code agent without Bash falls back to a generic claude subagent, adding time, tool calls, and cost.
fullsend PR #293	Merged	Added ADR-0027 and selected permissions.deny as the intended steering mechanism. The ADR's claim that agent frontmatter is inert under --agent is now stale.
fullsend PR #2098	Merged	Fixed adjacent subagent-dispatch and agent-definition problems, but does not fix the top-level scoped-disallowedTools bug.
fullsend#2826	Open	Adjacent work on separating permission profiles between inference and deterministic post-run automation.

No open pull request currently implements permissions.deny, a permissions_deny harness field, or an extension to GenerateClaudeSettings().

Work-item split

• This issue: Claude Code bug, minimal reproduction, and production evidence.
• fullsend#303: generate and install scoped permissions.deny rules for top-level agent sessions.
• fullsend#4437 / fullsend-ai/agents: remove the broken code/fix frontmatter rules and eliminate per-repository agent forks.

Action items

• File a new upstream Claude Code issue with the minimal scoped-disallowedTools reproduction.
• Implement and track permissions.deny support in fullsend#303.
• Coordinate agent-definition cleanup through fullsend#4437 and fullsend-ai/agents.
• Update ADR-0027 from fullsend PR #293: current Claude Code and its documentation apply agent tool restrictions to --agent sessions.
• Close fix(fullsend): clear agent field to use default claude agent type rhdh-plugins#3723 because agent: "" inherits the base value and cannot fix the problem.
• Merge redhat-developer/rhdh-agentic#91 as the interim workaround.

[durandom]

Update: Root cause narrowed

The bug is more specific than initially reported. It's not that --agent strips Bash from all sessions. It's that disallowedTools: Bash(...) subcommand patterns strip the entire Bash tool instead of restricting specific subcommands.

Test matrix (Claude Code v2.1.207, local)

disallowedTools value	Bash available?	Expected?
(field absent)	✅ Yes	✅
Write, Edit	✅ Yes (Write/Edit removed)	✅
Bash(sed)	❌ No (entire Bash removed)	✅
Bash(sed *)	❌ No	✅
full code.md patterns	❌ No	✅

The tools: (whitelist) field handles Bash(gh,echo) correctly. But disallowedTools: (blocklist) does not — any Bash(...) pattern removes Bash entirely.

Why code/fix are broken but triage/review work

• code.md / fix.md: use disallowedTools: Bash(sed *), Bash(git push *), ... → Bash stripped
• triage.md: uses tools: Bash(gh,jq) → Bash present
• review.md: uses tools: Read, Grep, Glob, Bash, Agent → Bash present

Workaround

Add explicit tools: field including Bash to code.md and fix.md in the agents repo. The disallowedTools patterns are non-functional for Bash subcommands and should be removed (or kept as documentation-only until Claude Code fixes subcommand-level blocking).

[durandom]

Update: Architecture analysis and recommended fix

Three independent layers control agent tool access

Layer	What it controls	Where it lives	Security boundary?
Agent frontmatter (tools: / disallowedTools:)	Which Claude Code tools are available to the agent	.md file, parsed by Claude Code CLI	No — steering only
Sandbox policy (network + filesystem)	Which binaries can reach which hosts; read/write paths	.yaml file, enforced by OpenShell	Yes
permissions.deny in settings.json	Claude Code runtime tool restrictions	settings.json, enforced by Claude Code	Yes (but unused)

The bug is in layer 1 only. `disallowedTools: Bash(...)` misparses the parenthetical and strips the entire Bash tool. The sandbox policy (layer 2) is the actual security enforcement — it gates network access per-binary (only `gh`, `git`, `node` can reach the network), locks down the filesystem, and runs as `sandbox` user.

Per ADR-0027, `disallowedTools` is documented as inert in `--agent` sessions (subagent-only). Claude Code applying it at all in `--agent` mode is itself a bug.

Why removing `disallowedTools` is safe but not ideal

Removing it is safe because:

• The sandbox policy blocks `curl` from reaching the network (binary-gated)
• Filesystem is locked down (`/usr`, `/lib` read-only; `/sandbox`, `/tmp` read-write)
• Agent prose constraints still say "do not use sed to edit files" (steering)
• ADR-0027 says the field should be ignored in `--agent` sessions anyway

But it loses the steering signal — the agent no longer has a machine-readable hint about which subcommands to avoid.

Recommended fix: convert `disallowedTools` → `tools:` allowlist

The `tools:` allowlist uses a different (working) code path. Instead of "all Bash except X", explicitly list "only these Bash subcommands":

```yaml

BEFORE (broken — strips entire Bash tool):

disallowedTools: >-
Bash(sed *), Bash(awk *), Bash(cat *), Bash(git push *), ...

AFTER (working — subcommand allowlist):

tools: >-
Read, Edit, Write, Grep, Glob, Agent, WebFetch, WebSearch,
NotebookEdit, EnterPlanMode, ExitPlanMode, TaskCreate, TaskGet,
TaskList, TaskUpdate, Workflow, Skill,
Bash(gh,git,node,yarn,npm,npx,corepack,find,ls,mkdir,cp,mv,rm,
chmod,touch,head,tail,wc,sort,uniq,diff,grep,tee,basename,dirname,
pwd,whoami,env,printenv,echo,printf,test,true,false,date,cat)
```

Tradeoff: An allowlist is stricter (good) but rigid — any new tool Claude Code adds won't be available until the list is updated (drift risk). This is the same issue `review.md` already has with its `tools: Read, Grep, Glob, Bash, Agent` allowlist.

Alternative: A `PreToolUse` hook could block specific subcommands without the drift risk, but hooks aren't configurable per-agent in fullsend today.

Action items (updated)

• PR to `fullsend-ai/agents`: convert `code.md` and `fix.md` from `disallowedTools` to `tools:` allowlist
• File upstream bug on `anthropics/claude-code`: `disallowedTools: Bash(...)` strips entire Bash tool (minimal repro in first comment)
• Interim: merge rhdh-agentic#91 (removes `disallowedTools` entirely) — safe per ADR-0027
• Close rhdh-plugins PR #3723 — confirmed won't help

[durandom]

Update: permissions.deny via dynamically generated settings.json — the architecturally correct fix

Fullsend already generates a .claude/settings.json per run

Contrary to what the original issue assumed ("no tool restrictions configured in settings.json"), fullsend dynamically generates a .claude/settings.json in the sandbox for every agent run. The generation path:

harness.yaml → security.sandbox_hooks config
  → ClaudeSandboxHooksFromHarness()
  → GenerateClaudeSettings()          ← builds JSON with hooks
  → installClaudeHooks()              ← uploads to {SandboxWorkspace}/.claude/settings.json

Source: internal/runtime/claude.go:256-258 (comment) + internal/security/hooks.go:57 (GenerateClaudeSettings)

Two separate settings.json files exist in the sandbox:

File	Generated by	Contents
{CLAUDE_CONFIG_DIR}/settings.json	bootstrapPlugins()	Plugin marketplace state (enabledPlugins)
{SandboxWorkspace}/.claude/settings.json	installClaudeHooks()	Only hooks — PreToolUse/PostToolUse chains (tirith, ssrf, canary, secret-redact, unicode, context-suppress, tool-allowlist)

The generated settings.json has no permissions block

The claudeSettings struct in hooks.go:47-49:

type claudeSettings struct {
    Hooks map[string][]hookMatcher `json:"hooks"`
}

No permissions field. The file only wires security hooks, not tool restrictions.

Why permissions.deny is the correct fix path

Per ADR-0027, disallowedTools in agent frontmatter is documented as inert in --agent sessions (subagent-only). Claude Code applying it at all is itself a bug. The correct mechanism for tool restrictions in top-level sessions is permissions.deny in settings.json.

Key difference from frontmatter:

Mechanism	Scope	Parser	Bash(sed *) works?	Enforcement
disallowedTools (frontmatter)	Subagent spawning	Broken for Bash(...)	No — strips entire Bash	Soft (ADR-0027: inert in --agent)
tools: (frontmatter)	Subagent spawning	Prefix-match only	N/A (allowlist, not blocklist)	Soft
permissions.deny (settings.json)	Session-wide	Permission system parser	Yes	Hard — deny rules override allow rules

permissions.deny supports the same Bash(sed *) pattern syntax but uses the permission system parser, which correctly blocks the subcommand without removing the entire Bash tool.

Proposed fix: add permissions.deny to GenerateClaudeSettings()

Upstream PR on fullsend-ai/fullsend to extend the harness schema and settings generation:

1. Harness schema (internal/harness/harness.go):

type SandboxHooks struct {
    // ... existing fields ...
    PermissionsDeny []string `yaml:"permissions_deny,omitempty"`
}

2. Settings generation (internal/security/hooks.go):

type claudeSettings struct {
    Hooks       map[string][]hookMatcher `json:"hooks"`
    Permissions *permissionsBlock        `json:"permissions,omitempty"`
}

type permissionsBlock struct {
    Deny []string `json:"deny,omitempty"`
}

In GenerateClaudeSettings(), populate from the harness config:

if denyList := hooks.PermissionsDeny(); len(denyList) > 0 {
    settings.Permissions = &permissionsBlock{Deny: denyList}
}

3. Agent harness (harness/code.yaml):

security:
  sandbox_hooks:
    permissions_deny:
      - "Bash(sed *)"
      - "Bash(awk *)"
      - "Bash(git push *)"
      - "Bash(git push --force *)"
      - "Bash(curl *)"

4. Agent frontmatter (agents/code.md, agents/fix.md):

Remove disallowedTools entirely — it was always inert per ADR-0027.

Existing infrastructure that almost solves this

Fullsend already has a tool_allowlist_pretool.py hook (disabled by default) that blocks entire tools via FULLSEND_TOOL_ALLOWLIST env var. But it operates at tool-name granularity (Bash, WebFetch), not subcommand level (Bash(sed *)). It's complementary, not a replacement.

Updated action items

• Upstream PR on fullsend-ai/fullsend: add permissions_deny to harness schema + GenerateClaudeSettings() (the proper fix)
• Upstream PR on fullsend-ai/agents: remove disallowedTools from code.md and fix.md (inert per ADR-0027, and broken)
• Upstream PR on fullsend-ai/agents: add permissions_deny entries to code.yaml and fix.yaml harness definitions
• File upstream bug on anthropics/claude-code: disallowedTools: Bash(...) strips entire Bash tool (minimal repro exists)
• Interim workaround: rhdh-agentic#91 (remove disallowedTools from agent .md) — safe per ADR-0027

[durandom]

Upstream issues identified and linked

Both relevant upstream issues already exist on fullsend-ai/fullsend:

Issue	Purpose	Our comment
fullsend#303	Strategic: migrate to permissions.deny in settings.json	Implementation proposal posted — extends GenerateClaudeSettings() with permissions_deny harness field
fullsend#4437	Tactical: remove inert disallowedTools from agent definitions	Cross-referenced back to #303 and this issue

No new issue needed — #303 was filed by the fullsend team themselves, labeled security + component/harness, and already references ADR-0023.

Remaining action items (downstream only)

• File upstream issue → already exists (#303, #4437)
• Merge rhdh-agentic#91 (interim workaround) and test with /fs-code
• File upstream bug on anthropics/claude-code: disallowedTools: Bash(...) strips entire Bash tool
• Once fullsend#303 lands: add permissions_deny entries to our customized harness YAMLs, revert rhdh-agentic#91

[maruiz93]

Full RCA for the production activation timeline, including the Docker cache bust that surfaced this bug on Jul 6: fullsend-ai/fullsend#5182