Feature Request: Native Project-as-Agent (Expert Sub-Agent) Support

Summary

Claude Code should natively support a Project-as-Agent (PAA) pattern — the ability to register standalone repos as callable "expert services" and invoke them by name from any session. Today this is achievable through prompt engineering in CLAUDE.md and the Task tool, but it's fragile, verbose, and hits friction with permissions, context routing, and discovery.

Problem

AI coding assistants are project-scoped. When you're working in Project A and need capabilities from Project B — a data warehouse client, a curated knowledge base, a metrics toolkit — your options are:

1. Switch sessions — Open Project B, do the work, copy results back. Loses context, breaks flow.
2. Duplicate everything — Copy Project B's libs, knowledge, and config into Project A. Doesn't scale, goes stale.
3. Prompt-engineer it — Write dispatch rules in CLAUDE.md, construct inline sub-agent prompts, manage permissions manually. Works but brittle — knowledge-first ordering isn't enforced, permissions block silently, output routing is convention-only.

None of these support clean parallel execution or keep the calling session's context window clean.

Why Not Just Skills?

Claude Code already has Skills (.claude/skills/) for reusable actions. They work well for self-contained tasks, but break down when the task requires an entire project's ecosystem.

| Dimension | Skills | Experts (proposed) |
|-----------|--------|-------------------|
| Scope | Single action (e.g., "load context", "run lint") | Entire project ecosystem (knowledge + tools + runtime + data access) |
| Knowledge | Embedded in the skill file or references a few files | Reads from a full knowledge base — dozens of files, structured by domain, maintained independently |
| Runtime | None — relies on whatever the session already has | Bootstraps its own (DB clients, browser automation, Python libs, credentials) |
| Execution | Inline, blocks the session | Background sub-agent, session stays free |
| Context | Runs in the session's context — everything leaks in | Isolated sub-agent — only final result returned, intermediate state discarded |
| Discovery | Must install/copy skills into each project, or use global skills | Register once globally, invoke from anywhere by name |
| Composability | One skill does one thing; chaining requires manual orchestration | One expert can run multi-step workflows internally (query DB → decode data → validate → produce report) |
| Maintenance | Skill authors must update every consumer when logic changes | Expert repo maintained in one place; consumers invoke it as-is |
| Shareability | Distribute skill files to each user/project | Clone the repo once, register it, done — git pull for updates |

When to use Skills: Simple, well-defined actions that don't need external tools or deep knowledge.

When to use Experts: The task requires specialized expertise backed by a maintained knowledge base, embedded runtimes, multi-step analysis, or live data access — and you don't want to pollute your current session with all of that.

They compose well. A skill can invoke an expert (e.g., a load-context skill triggers an expert's bootstrap). An expert can use its own internal skills during execution.

Proposed Solution

A first-class experts configuration and invocation mechanism:

1. Expert Registry (new config)

# ~/.claude/experts.yaml (or per-project .claude/experts.yaml)
experts:
  data-brain:
    path: /path/to/data-analysis-toolkit
    description: "Data warehouse queries, domain knowledge, embedded Presto client"
    bootstrap:
      python_path: ["."]
      env_file: ".env"
      modules:
        query_client: "lib.query_client.QueryClient"
    knowledge:
      quick: ["knowledge/core/quick-reference.md"]
      general: ["knowledge/core/domain-knowledge.md"]
      domains_dir: "knowledge/domains"
    short_names: ["data-brain", "DataBrain"]

  infra-kb:
    path: /path/to/infra-knowledge-base
    description: "Grafana metrics, Loki logs, incident analysis, service lookups"
    knowledge:
      index: "domain/QUICK_REFERENCE.md"
      datasources: "domain/DATASOURCES.md"
    short_names: ["infra-kb", "InfraKB"]

2. Invocation (new behavior)

When a user says @data-brain check the latest order metrics by region, Claude Code would:

1. Look up data-brain in the expert registry
2. Spawn a background sub-agent with:

• Working directory set to the expert's path
• Expert's .env loaded
• python_path configured
• Knowledge files read first (enforced by runtime, not by prompt)

1. Execute the task
2. Route output to the calling project's directory
3. Return a summary to the parent session
4. Discard the sub-agent's context (no pollution of parent)

3. Key Capabilities Needed

| Capability | Current Workaround | Native Support Needed |
|---|---|---|
| Expert registry | Prose tables in CLAUDE.md | Structured config (experts.yaml) with validation |
| Name-based invocation | Prompt rules ("when user says X, do Y") | First-class @expert-name syntax or explicit trigger |
| Knowledge-first enforcement | Prompt instruction (easily ignored) | Runtime guarantee: knowledge files loaded before any tool calls |
| Permission bypass for sub-agents | Named agents with permissionMode: bypassPermissions or manual allowlists | Inherited or scoped permissions per expert (e.g., expert declares what tools it needs) |
| Output routing | Convention ("write to caller's dir") in prompt | Explicit OUTPUT_DIR injected by runtime, enforced |
| Background execution | Task with run_in_background: true | Dedicated expert invocation (better progress tracking, completion notification) |
| Context isolation | Sub-agent naturally isolated, but no formal guarantee | Guaranteed: parent only receives final output, never intermediate state |
| Bootstrap / runtime setup | Inline Python in prompt (sys.path.insert, os.chdir) | Declarative config (env file, python paths, modules) handled by runtime |

Example Workflow

# User is building an e-commerce feature in their main project

User: @data-brain what's the current fulfillment rate by warehouse for the ELECTRONICS category?

Claude Code:
  → Looks up "data-brain" in experts.yaml
  → Spawns background agent with data-analysis-toolkit context
  → Agent reads knowledge/domains/fulfillment/*.md (enforced)
  → Agent finds exact table names, partition keys, formulas from knowledge
  → Agent queries data warehouse using embedded client
  → Agent writes report to ./local/reports/fulfillment-rate.md
  → Parent session shows: "Report ready at local/reports/fulfillment-rate.md"
  → User continues coding without context switch

User: @infra-kb check if the order-service had any latency spikes in the past 6 hours

Claude Code:
  → Spawns second background agent with infra-knowledge-base context
  → Agent reads DATASOURCES.md, finds exact Grafana datasource + service name
  → Agent queries Grafana metrics API
  → Returns summary inline to parent session

Why Native?

The prompt-engineering approach works but has real failure modes:

• Knowledge-first is advisory, not enforced. LLMs skip knowledge reading under complex prompts and guess parameters instead — leading to wrong queries with wildcard regex instead of exact values.
• Permissions are fragile. Background sub-agents silently fail when a tool isn't pre-approved. Users must manually maintain allowlists across projects.
• No structured discovery. Users can't run claude experts list to see what's available. The registry is buried in markdown prose.
• Bootstrap is hacky. Injecting sys.path.insert(0, ...) and os.chdir(...) via prompt text is unreliable.
• Output routing is convention-only. Nothing prevents a sub-agent from writing to the expert's directory or returning excessive intermediate context.
• No progress visibility. Background Task agents can't be checked mid-execution.

Native support would make these guarantees structural, not behavioral.

Scope

This is not asking for a full plugin/extension system. It's a focused addition:

1. A config file format for declaring expert repos
2. A runtime mechanism to spawn scoped sub-agents from that config
3. Enforcement of knowledge-first loading, output routing, and context isolation
4. A way for users to discover and manage registered experts

Prior Art

• MCP servers solve a related problem (external tool access) but at the tool level, not the project level. An expert is a bundle of tools + knowledge + runtime + domain expertise.
• Named agents (~/.claude/agents/) are close but lack structured config, knowledge-first enforcement, and output routing.
• Skills solve reusable single actions but not cross-project, multi-step expert workflows with their own runtimes and knowledge bases (see comparison above).