anthropics / anthropics/claude-code
Sub-agents receive the auto-memory index and skill listing, contrary to the docs — custom agent definitions included
- Lingua principale
- Python
- Stelle
- 145k
- Fork
- 23.1k
- Metriche di merge delle PR
- Metriche PR in attesa
Descrizione
**Environment:** Claude Code 2.1.263, macOS 15 (Darwin 25.5), Claude Max, model `claude-fable-5-1` for the probe (also seen on 2.1.261 and 2.1.258 with `claude-opus-5`).
## Expected
The sub-agents docs ("What loads at startup") and the memory docs say:
> The main conversation's auto memory isn't loaded into subagents; the exception is a fork.
> Subagents don't receive a pre-populated listing [of skills and MCP tools]. They can discover and invoke unlisted project, user, and plugin skills through the Skill tool during execution.
## Actual
A do-nothing sub-agent's first request carries both, as attachments recorded in the transcript:
- an `instructions` attachment containing the project's `MEMORY.md` in full (19,850 chars here), alongside the CLAUDE.md files (which *are* documented as loading);
- a `skill_listing` attachment with one description line per skill (24–26k chars, ~49 skills here).
This is the case for the built-in `general-purpose` agent **and for custom agent definitions** (`.claude/agents/*.md`). A custom definition does replace the Claude Code system prompt as documented, and a `tools:` allowlist does trim the schemas — but memory index, skill listing and CLAUDE.md files arrive unchanged in all three cases:
| Sub-agent | First-request tokens (cold cache) |
|---|---|
| built-in `general-purpose` | 45,907 |
| custom definition, no `tools:` | 33,244 |
| custom definition, 8-tool allowlist | 27,832 |
The ~24k that remains in the last row is memory index + skill listing + CLAUDE.md files (+ ~3k of tool names/session context).
## Steps to reproduce
1. In a project with a populated `~/.claude/projects//memory/MEMORY.md` and a dozen or more skills installed, create `.claude/agents/probe.md`:
```
---
name: probe
description: measurement probe
---
You are a measurement probe. Do exactly what the prompt says and nothing else.
```
2. Start a new session (agent definitions load at session start) and dispatch:
`Agent(subagent_type="probe", prompt="Reply with exactly the single word DONE. Do not call any tool.")`
3. Open the sub-agent transcript under `~/.claude/projects///subagents/agent-*.jsonl`. The `attachment` records before the first assistant turn include `instructions` (with the MEMORY.md path and content) and `skill_listing`; the first assistant `usage.cache_creation_input_tokens` is the figure above.
## Why it matters
In sub-agent-heavy workflows this block is re-read on every call. In ours (batch runs of ~70-call sub-agents, ~250k mean context) the memory index and skill listing together are ~17k tokens, about 7% of all cache-read tokens per run — and unlike the system prompt, there is no per-agent way to leave them out: the `memory` frontmatter field adds a *separate* memory directory rather than suppressing the main index, and `skills:` preloads skill bodies rather than shrinking the listing. `claudeMdExcludes` and `CLAUDE_CODE_DISABLE_AUTO_MEMORY` are session-wide, so they also strip the parent conversation.
## Ask
Either of:
- make the behaviour match the docs (or add a per-agent switch — e.g. a frontmatter field to opt a custom agent out of the memory index and skill listing); or
- correct the docs to describe what sub-agents actually receive, so people sizing sub-agent context can plan on it.
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Direzione di ricerca
Reproduce with the provided .claude/agents/probe.md, Agent(subagent_type="probe", ...) call, and the subagent transcript under ~/.claude/projects///subagents/agent-*.jsonl. Inspect where sub-agent startup attachments are assembled and compare them with the sub-agent and memory docs. Done means the behavior matches the documented memory/skill-loading rules, a per-agent opt-out exists, or the docs are corrected.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- macos, python
- Ambito
- ai-infra-agents, cli, documentation
- Tipo di issue
- Bug
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Attiva
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 35/100