anthropics / anthropics/claude-code

Sub-agents receive the auto-memory index and skill listing, contrary to the docs — custom agent definitions included

Aperta
#92,750 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
area:agents bug has repro platform:macos
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

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.