claude-code - 💡(How to fix) Fix Agent tool `mode` parameter does not override sub-agent frontmatter `permissionMode` [1 participants]

Summary

The Agent tool's mode parameter (e.g. mode: "bypassPermissions") does not override a sub-agent's YAML frontmatter permissionMode. When the sub-agent has no permissionMode declared, behaviour falls back to default mode — and the spawn-time mode parameter is silently a no-op.

The docs read as if the Agent tool parameter wins per-spawn. Empirically, the frontmatter wins (or the absence of frontmatter wins).

Reproduction

Sub-agent definition with no permissionMode field:

---
name: architect
description: Technical architecture stewardship...
tools: Read, Write, Edit, Glob, Grep, Bash, Agent
model: sonnet
---

Parent spawns it via Agent tool:

Agent({
  subagent_type: "architect",
  isolation: "worktree",
  mode: "bypassPermissions",
  run_in_background: true,
  prompt: "Write two files and open a PR"
})

Expected: sub-agent has Write + Bash without per-call permission prompts. Actual: sub-agent returns a blocking report saying Write and Bash are denied. Read and Glob work fine, so the tools list is correctly applied — only the permission gating is wrong.

Re-spawning the same task with mode: "bypassPermissions" set explicitly produces the identical blocker. The agent's own report says: "the environment is not honouring [bypassPermissions] for either Bash or Write."

Workaround

Set permissionMode: bypassPermissions directly in the sub-agent's YAML frontmatter. After this, the agent runs Bash + Write freely. The Agent tool's mode parameter then becomes a redundant safety belt rather than the load-bearing setting.

Suggested fix (pick one)

1. Doc fix (low-risk) — make precedence explicit: "frontmatter permissionMode takes precedence over the Agent tool's mode parameter. To allow per-spawn override, set permissionMode in frontmatter to the most restrictive mode you'd ever want, then use the Agent tool's mode to widen it." (Or the inverse — whichever matches the actual behaviour.)
2. Behaviour fix — make the Agent tool's mode parameter actually override frontmatter for the spawn. Matches the natural reading of the existing docs.

Context

Hit this empirically while running a multi-agent planning session — three sub-agents (architect, business-analyst, service-experience-designer) all returned blockers when asked to write spec docs and open PRs. The parent session ended up doing all three sub-agents' git/write work directly because re-spawning didn't help. Investigation via /agents-style introspection of the claude-code docs identified the precedence gap.

This is the second mid-session paper-cut from agent configuration where docs and behaviour disagree (the prior was issue #55680 about /agents not rescanning the filesystem). Both are small individually but together they erode confidence that running parallel sub-agents will work as advertised.