[Feature Request] Subagents should inherit project rules and support cross-agent contract enforcement

Summary

When dispatching parallel subagents via the Task/Agent tool, project-level rules (CLAUDE.md, forbidden-patterns, etc.) are not injected into subagent context. Combined with no mechanism for shared contracts between agents working on adjacent boundaries, this produces massive debt accumulation that only surfaces at final review time.

I just hit this in a real project: 8 parallel waves of agent work, followed by a single pr-zero review (a local skill that reviews PRs until zero issues remain), surfaced ~100 findings. Every single cluster traces back to one of the structural gaps below.

Problem Clusters

1. Parallel agents have no shared contract mechanism

When two agents work on adjacent boundaries (frontend ↔ backend, test ↔ impl, schema ↔ router), there is no way to give them a shared contract file. My frontend agent invented mock_n/answers; the backend agent invented mock_number/responses. Every submit would 422 on extra="forbid".

The orchestrator has to manually write and maintain contract files and inject them into each agent prompt. This is fragile and easy to forget.

Ask: Support a contract or shared_context parameter on Agent/Task dispatch that gets automatically injected into every agent working on the same plan/wave.

2. Subagents don't inherit project rules

CLAUDE.md has a forbidden-patterns.md that bans bare except Exception: pass, silent failures, and untracked deferrals. These rules are in the orchestrator's context but never reach subagent prompts. Every Sonnet/Haiku subagent starts fresh and defaults to defensive try/except/pass because that's the training-data median.

Result: 10+ findings of silent failures and bare excepts across the codebase, all from agents that "didn't know the rules."

Ask: Automatically inject relevant CLAUDE.md rules (especially forbidden-patterns, rules/ files) into subagent prompts. At minimum, add a flag like inherit_rules: true on Agent dispatch.

3. No per-wave/per-agent review cadence

Running pr-zero (a local review-until-clean skill) once against 14 commits of parallel-agent churn produces 100 stacked findings. The standard practice would be to run review after each wave — catching 3-8 findings per wave, immediately fixable. But there's no built-in mechanism to trigger review between agent dispatches.

Ask: Support a post_agent_hook or on_agent_complete callback that can trigger review/lint/test between waves. This would make incremental quality gates automatic rather than requiring manual orchestration.

4. Tests mirror the code, not the user

1079 unit tests passed green. Not a single one caught that the frontend sends different field names than the backend expects. The test suite built Pydantic models in Python and hit TestClient — it never saw the actual UI payloads.

Ask: When agents write both tests and implementation, the test agent should receive a prompt that says "test the boundary, not just the unit." A project-level rule like tests_must_cross_boundaries: true could enforce this.

5. Agents default to hiding failures

Prompts said "handle the fallback" and "don't crash" — agents interpreted this as "silently swallow errors and continue." The result was except Exception: pass and catch(_) { questions = [] } throughout.

Ask: The default agent behavior should be "surface failures loudly." Project rules like "never silently catch" should propagate automatically.

Environment

• Claude Code CLI, model Opus 4.7
• Dispatching 3-4 parallel Sonnet/Haiku agents per wave
• Project has CLAUDE.md with forbidden-patterns section, not inherited by subagents

Proposed Solution (minimal viable)

1. Rule inheritance: When spawning an agent via the Agent tool, automatically include the project's CLAUDE.md rules section in the subagent prompt. Add a inherit_rules: true (default) flag.

1. Shared context / contracts: Add a shared_context parameter to Agent dispatch — a string or file path that gets injected verbatim into every agent in the same plan. This replaces the manual "write a contracts file and remember to mention it in every prompt" dance.

1. Inter-wave hooks: Allow registering a command (e.g., bun run typecheck && bun test) that runs automatically between agent completions in a multi-agent workflow. This catches drift before it compounds.

These three changes would have prevented ~80 of the 100 findings in my case. The remaining 20 (weak Pydantic invariants, determinism claims without replay tests) are project-specific and solvable with better prompt templates.