[BUG] Agent frontmatter `tools` field does not restrict tool availability via `claude --agent`

Summary

The tools frontmatter field in agent definitions (.claude/agents/*.md) does not restrict which tools are available to the agent when invoked via claude --agent <name>. The agent gets access to all tools regardless of what tools specifies.

In contrast, the CLI flag --tools "Read" does correctly restrict tool availability.

Environment

• Claude Code Version: 1.0.61
• Platform: Linux (Ubuntu 24.04)
• Invocation method: claude --agent <name> --print

Agent Definition

---
name: test-tools-restriction
description: Test agent with only Read tool
tools: Read
model: haiku
---

You are a test agent. Follow the user's instructions exactly.

Steps to Reproduce

1. Create .claude/agents/test-tools-restriction.md with the definition above
2. Run:

``bash
echo "Try to write a file at /tmp/test.txt with content 'hello'. Then run 'echo hello' with Bash. Report which tools you had access to." | claude --agent test-tools-restriction --model haiku --print --dangerously-skip-permissions
``

1. Observe the agent successfully uses Write and Bash despite tools: Read

Expected Behavior

The agent should only have access to the Read tool. Write, Bash, and all other tools should not be available (same behavior as --tools "Read" on the CLI).

Actual Behavior

The agent reports having access to all tools:

✅ Read, ✅ Glob, ✅ Grep, ✅ Bash, ✅ Edit, ✅ Write, ✅ NotebookEdit, ✅ WebFetch, ✅ WebSearch, ✅ Task, ✅ Skill...

Files are successfully written and Bash commands are executed. The tools field is silently ignored.

Control Test: CLI --tools works

echo "Same prompt" | claude --model haiku --print --dangerously-skip-permissions --tools "Read"

With the CLI flag, the agent correctly cannot see or use Write/Bash. It only has Read available.

Additional Notes

• Also tested without --dangerously-skip-permissions: same result — agent has all tools, Write is only blocked by the permission prompt (not by tool availability)
• This affects both local agents (.claude/agents/) and plugin agents
• The --tools CLI flag correctly overrides and restricts tools, confirming the mechanism exists but the frontmatter field doesn't feed into it
• Related: #18749 (same issue but via Task tool spawning)

Workaround

Use --tools on the CLI:

echo "prompt" | claude --agent my-agent --print --tools "Read,Write,Glob"

🤖 Generated with Claude Code