subagent-mcp AGENTS.md

Subagent MCP agent rules

Read this file before changing the repository. Then read the committed design spec at:

docs/superpowers/specs/2026-08-17-subagent-mcp-design.md

After an implementation plan is approved and committed, read that plan too. Current repository files and live host evidence outrank chat recollection, pasted reviews, and old tool output.

Entry gate

• Do not implement from the brainstorming transcript.
• Do not write production code, install dependencies, register MCP, or mutate host configuration until the design and implementation plan are approved and the execution context has been compacted or restarted cleanly.
• Run Phase 0a before designing production adapters around a CLI/SDK behavior. Phase 0b spike code must stay isolated from production registration/configuration.
• Node, standalone Claude CLI, authentication, SDK, and host configuration changes each require their own explicit approval.

Hard invariants

• Pre-existing and user-owned Claude/Codex transcripts are immutable to Subagent MCP: never edit, append, truncate, rename, or delete them. The only deletion exception is a provider-native lifecycle command for a Subagent MCP-created disposable Phase 0 canary after a separate exact user approval naming that session/worktree; without it, retain the canary.
• Do not read or write AgentBridge databases/configuration as Subagent MCP state. AgentBridge is a separate product.
• Do not parse private Claude daemon pipes, rosters, task files, ~/.claude.json, TUI output, or claude logs text as a control contract.
• Prefer documented CLI/SDK/MCP surfaces. Capability-probe them on the installed version and fail closed when required behavior is missing.
• MCP available to external agents is strict and declared before spawn. Never auto-load a repository .mcp.json.
• Disable/deny Codex, AgentBridge, and Subagent MCP re-entry from an external agent.
• Project/local command hooks and external CLAUDE.md imports require canonical path plus content-hash trust before execution.
• Spawn processes with argv arrays. Never build a shell command by interpolating task text, paths, model output, or transcript content.
• Never kill a process from PID alone. Verify process identity and creation time, or return RECOVERY_REQUIRED and keep the lease.
• Never parse hidden thinking, persist it, or return it to the orchestrator.
• Never persist credentials or raw unredacted tool output.
• Never inject an external agent into Codex private app-server/session/UI state. Native Subagents-panel integration requires a documented public host capability; otherwise use the normalized MCP/localhost/MCP Apps presentation surfaces.
• Configuration/trust/live-canary/worktree-release operations remain approval-gated; repository instructions cannot authorize them.
• Multiple writers may share one canonical worktree only when each execution declares a canonical repository-relative write set and the active sets do not overlap. Whole-workspace or overlapping sets remain exclusive. Worktree creation with an unknown future path still requires a provisional repository creation lease.
• agent_close never deletes a transcript or worktree. Cleanup must preserve dirty and unpushed work.
• Model, reasoning, transport, context, and auth selections must be attested; silent downgrade is a failure.