Skip to content

Subagent Invariants

Contracts governing subagent prompt generation, ownership identification, explicit force authorization, orphan pruning, and multi-subagent shared-file aggregation.

Core Rules

INV-SUB-01: Header Marker as Subagent Ownership Evidence Scoped to Target Node [current]

Aikito establishes ownership of subagent target definitions solely through an exact Aikito header marker (generated by aikito from subagents/<name>.md - edits will be overwritten). In dedicated files (e.g. ~/.claude/agents/<name>.md), the marker establishes ownership of the entire file. In shared configuration files (e.g. .dsh/cordis.patch.yml), ownership evidence is strictly scoped to the specific logical subagent block; the presence of an Aikito marker in one block does not confer ownership over the remainder of the shared configuration file. Files lacking the marker evaluate to CONFLICT and are never overwritten without explicit authorization.

Targeted tests: tests/test_subagent_plan.py, tests/test_config_characterization.py, tests/test_subagent.py

INV-SUB-02: Explicit Target Authorization for Overwrite via Force [current]

The --force <agent>/<subagent> option provides granular, target-specific authorization to overwrite a conflicting subagent target. Authorizing agentA/subagentX does not authorize any other target, and global wildcards are forbidden. Operations requiring force remain blocked (is_authorized=False) unless explicitly authorized in the plan.

Targeted tests: tests/test_subagent_plan.py, tests/test_config_characterization.py, tests/test_subagent.py

INV-SUB-03: Prune Authorization Strictly Bound to Managed Orphans [current]

Passing --prune authorizes the removal of orphaned subagent configurations if and only if they possess valid Aikito ownership markers and no longer exist in canonical workspace definitions (subagents/). Unmanaged configuration files and unrecognized entries are strictly preserved and never pruned.

Targeted tests: tests/test_subagent_plan.py, tests/test_config_characterization.py, tests/test_subagent.py

INV-SUB-04: DSH Shared Configuration Multi-Subagent Write-Once Aggregation [current]

When managing subagents in DeepSeek Harness (cordis.patch.yml), all pending subagent mutations (creations, updates, and prune removals) targeting that file must be aggregated in memory and executed in a single atomic file write. Unmanaged blocks, settings, and other configuration sections within cordis.patch.yml must remain intact.

Targeted tests: tests/test_subagent_plan.py, tests/test_config_characterization.py, tests/test_subagent.py

INV-SUB-05: Unified Agent Availability Resolution via AgentRegistry [current]

Subagent target resolution resolves agent installation and availability exclusively through agents.py::AgentRegistry and AgentAvailability. Subagent planning must not import or depend on cross-resource availability helpers owned by other resource subsystems such as MCP.

Targeted tests: tests/test_subagent_plan.py, tests/test_subagent.py

INV-SUB-06: Subagent Execution Result Segmentation and Exact File Commit Alignment [current]

Subagent sync execution returns a structured SubagentExecutionResult reflecting the exact operations applied, skipped, conflicted, or failed per physical file. If a file mutation fails, the result explicitly reports the failed file and partial completion state without masking errors as generic booleans.

Targeted tests: tests/test_subagent_plan.py, tests/test_subagent.py

Subagent State Table

Target State Marker Present In Canonical? Force / Prune Authorized Planned Action
Missing N/A Yes N/A CREATE
Present Yes (content identical) Yes N/A NOOP
Present Yes (content changed) Yes N/A UPDATE
Present No (unmanaged) Yes No CONFLICT (preserve)
Present No (unmanaged) Yes Yes (--force <agent>/<name>) UPDATE (authorized)
Present Yes (managed) No No ORPHAN (notify only)
Present Yes (managed) No Yes (--prune) REMOVE (authorized)
Present No (unmanaged) No Any IGNORE (preserve)