Feature request: Extend agent definitions with auto-loaded context files and persistent memory namespace

Problem

The Task tool creates subagents with no persistent identity across invocations. Every call starts with a blank context. A specialist that has handled 50 tasks starts from zero on task 51.

We run a multi-agent team (orchestrator + 6 specialists) inside Claude Code. To compensate for stateless subagents, we have built:

• ~15 per-agent skill files manually loaded via prompt instructions
• A custom memory CLI (12 commands, frontmatter schema, search) backed by a git repository
• Routing policies encoding which agent handles what
• A "Standard Reminders Block" in every delegation prompt — a checklist of context the orchestrator must manually include each call

This works but has three failure modes:

1. Prompt fragility — Knowledge transfer depends entirely on prompt quality. If the orchestrator forgets to include a skill reference, the specialist does not know it exists. We have lost specialist knowledge across sessions because the orchestrator forgot to mention a skill file.

2. Duplicate work — Every invocation re-reads files, re-discovers state. Wasted tokens and latency on every call, at the cost of both performance and context budget.

3. Skill staleness — Even when the prompt correctly references a skill file, the content may be outdated from earlier-session changes made by the specialist. Skills do not hot-reload because the orchestrator caches the reference at session start, not at invocation time.

Proposed Solution

Extend the existing .claude/agents/ definition format with two primitives:

context_files — A list of file paths auto-loaded into the subagent's context at invocation time (read from disk at call time, not session start). These are the agent's persistent knowledge base. The key detail: reading at invocation time, not at session start, means the content is always current.

memory_namespace — A persistent scratchpad scoped to this agent that survives across invocations. The agent can read and write to it without external CLI tools or orchestrator mediation.

These are minimal extensions to what .claude/agents/ already supports (name, role, tools). Full agent profiles could be sugar on top of these primitives later.

Example:

# .claude/agents/research.md (extended)
---
context_files:
  - .claude/skills/research_knowledge/SKILL.md
  - .claude/skills/research_lessons/SKILL.md
memory_namespace: research
---
You are a research specialist...

What This Enables

• Orchestrator prompt complexity drops significantly — the agent name and task description become the delegation, not 200 words of context setup
• Specialist knowledge becomes reliable — the harness loads it, not the prompt, so no skill is ever silently missing
• Hot-reload: context_files read at invocation time means a specialist always gets the current version of its own skill files
• Migration path is clean — existing skill files become context_files entries, no rewrite required

Trade-offs We Want to Acknowledge

We are not filing this as a pure request. We see genuine risks:

Orchestrator judgment loss — Automatic context loading removes the orchestrator's selective judgment about what context to include per-task. Some of our most effective delegation decisions came from selectively including OR excluding context based on task specifics. Auto-loading makes this impossible.

Auditability — If memory_namespace enables agent-to-agent delegation without orchestrator mediation, the principal loses visibility into coordination chains. We think this is a real governance risk, not a theoretical one.

Specialization friction is healthy — If creating capable agents becomes trivially easy (define context_files, done), teams may over-fragment into 50 micro-agents instead of 10 well-scoped ones. Some friction in agent creation prevents poorly-scoped proliferation. We are not sure this concern outweighs the benefits, but it should be in the design conversation.

Evidence

We have operated this multi-agent team for 3+ weeks inside Claude Code, building workarounds for each gap. The workaround surface area is the evidence:

• Agent Swarm Protocol (~10K lines) — pub/sub messaging between agents across separate Claude Code sessions and VMs (referenced in #24798)
• agent-memory CLI — 12-command persistent memory system with frontmatter schema, BM25 search, git-backed storage, and lifecycle hooks (PreCompact, SessionStart, SubagentStart, SubagentStop)
• 15+ skill files — manually maintained per-agent knowledge bases, manually referenced in every delegation prompt
• Routing subagent — dedicated agent for matching tasks to specialists, because the orchestrator cannot reliably make this decision without specialist knowledge of which specialist handles what
• Cron + swarm wake — event-driven agent lifecycle management built because the Task tool provides no native mechanism for agents to receive events between invocations

The primitives we propose (context_files, memory_namespace) would eliminate the need for most of this infrastructure. The fact that we built all of it suggests the gap is real.

Related Issues

• #24798 (inter-session communication)
• #25999 (persistent state across compaction)
• #25134 (agent context in hook events)
• #28221 (PostTask hook)