[BUG] `memory:` field in subagent frontmatter not functional — reproduces on v2.1.137; tools allowlist appears to override auto-enable

[kirillgreen]

[BUG] memory: field in subagent frontmatter not functional — reproduces on v2.1.137; tools allowlist appears to override auto-enable

Re-reporting the bug from #31294 (closed-as-inactive 2026-04-11 by github-actions bot, not because it was fixed). Reporter (@Mationetap) explicitly rejected the bot's suggested duplicates as not relevant. @gvelesandro is collecting reports of the same pattern at https://www.agentsneedcontext.com/agent-failure-postmortem.

This issue adds a new finding from a 5-agent reproduction: the explicit tools: allowlist appears to take precedence over the documented "memory: auto-enables Read/Write/Edit" behavior, which may be one of the mechanisms behind the bug.

Environment

• Claude Code: v2.1.137 (current)
• macOS Darwin 25.4.0
• 5 user-defined subagents with memory: configured (mix of user and project scopes)

Reproduction

5 subagents in ~/.claude/agents/, all with memory: field:

Agent	model	memory:	Has Write/Edit in tools:	MEMORY.md created?
tdd-test-writer	sonnet	user	✅ explicit	✅ yes (multiple files, recent activity)
docs-updater	sonnet	user	✅ explicit	✅ yes (multiple files)
dev-lead	opus	user	✅ explicit	❌ empty after 5+ invocations in 3 days
design-lead	opus	user	❌ NOT in explicit tools:	❌ empty
code-reviewer	opus	project	❌ NOT in explicit tools:	❌ empty (no project dirs created across 5 projects)

Telemetry shows 50+ invocations across these agents in the last 3 days with status:completed and no errors.

Two distinct subpatterns visible

Subpattern A — explicit tools: allowlist excludes Write/Edit (code-reviewer, design-lead)

Per the Anthropic subagent docs: "Read, Write, and Edit tools are automatically enabled so the subagent can manage its memory files."

This phrasing implies the auto-enable is additive. But agents whose explicit tools: allowlist excludes Write, Edit show no memory file creation. Suggests the allowlist takes precedence over the auto-enable, contradicting the documented behavior.

Test: I just added Write, Edit to the tools: field of code-reviewer and design-lead. Will report back whether memory accumulates after the next invocation.

Subpattern B — has Write/Edit but still doesn't write (dev-lead)

dev-lead has Read, Edit, Write, Glob, Grep, Bash, Agent in tools: and memory: user configured. Despite multiple invocations in the last 3 days (architecture reviews, multi-transport refactor, iOS popup), the directory ~/.claude/agent-memory/dev-lead/ remains empty. No MEMORY.md was ever created.

This matches the bug as @Mationetap originally reported it: the memory infrastructure simply doesn't activate for Task()-spawned subagents.

A plausible prompt-engineering contributor to this subpattern: dev-lead's memory section has elaborate Curate criteria ("Append only when X, Y, Z fires") that, combined with Opus 4.7's more-literal interpretation, may cause the agent to self-censor every potential write. Working agents (tdd-test-writer, docs-updater) have brief 2-line permissive memory sections. Need to test by simplifying the broken agents' memory sections — but this is a workaround, not a fix.

Why this matters

The persistent-memory feature shipped in v2.1.33 (Feb 2026) and is positioned as a primary value-add for subagent system design. Multiple users (including those producing 50+ daily invocations against memory-configured agents) cannot use it. Auto-closing as inactive doesn't reflect actual usage state — it reflects that frustrated users moved on to workarounds (external KB, manual file management).

Asks

1. Re-open [BUG] Subagents with memory field never create or update MEMORY.md — memory system not functional for Task() subagents #31294 or treat this as a fresh report
2. Confirm whether explicit tools: allowlist is intended to override memory: auto-enable (doc clarification needed regardless)
3. Investigate why Task()-spawned Opus subagents with proper tool access don't create MEMORY.md
4. Provide an officially-supported workaround until the root cause is fixed

Workaround currently being tested

Adding Write, Edit to all explicit tools: lists for memory-enabled subagents. Will edit this issue with results in 3-5 days of usage.

---

Filed by a Claude Code power user with 8 subagents + 59 skills + 6 active projects. Full background research and observability data in: 2026-04-17 claude-code-subagent-design-refresh.md, 2026-05-06 agent-prompt-engineering-techniques.md (private knowledge base, willing to share excerpts on request).

[yurukusa]

Independent reproduction here, with a slightly different angle. I built a SessionStart hook (subagent-inheritance-tester) specifically to detect this misconfiguration before a session runs. It scans ~/.claude/agents/ and any project-level .claude/agents/ for frontmatter that uses memory:. When found, it warns that the field is silently ignored at runtime and recommends moving scope/context into the prompt body.

The hook was born from this exact issue and #57068 (parent Deny rules not propagating to subagents that lack an explicit tools: list). Both share the same structural cause: subagent frontmatter contains keys the runtime does not honor, and there is no operator-visible signal that the silently-ignored field is silently-ignored.

On Subpattern A. Your observation that explicit tools: takes precedence over the documented auto-enable matches what I see in my own agent docs. The runtime appears to treat the tools: allowlist as authoritative; the documented auto-enable for Read/Write/Edit happens only when tools: is absent or does not list any of them. This is the opposite of additive. It is a precedence rule that the documentation does not reflect.

On Subpattern B. dev-lead having Write in tools: but still not writing is harder to reproduce. One pattern I have seen: subagent prompts that have memory: user configured but no explicit instruction in the prompt body to write to memory. The auto-enable enables the tool, it does not bind the agent to actually use it. If dev-lead's system prompt focuses on architecture review without a "log decisions to memory" line, the agent may have access but never invoke Write. Worth checking the prompt body for an explicit memory-writing instruction in addition to the frontmatter memory: field.

Both subpatterns point at the same operational gap. The user can configure memory: correctly and still get silent no-op behavior, with no warning surfaced. The detection hook lives in cc-safe-setup (MIT, free), and I am happy to share the commit hash once the PR lands.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.