file-backed-state-module

Persist agent state by externalizing all transferable information into durable, path-addressable files like TASK.md and RESPONSE.md before any child stage reads them. This ensures context compression and delegated stages resume reliably without losing or misordering state.

Manage child agent handoffs by establishing a stable STATE_ROOT directory and persisting each child's outputs into children/<id>/RESPONSE.md only after required durable files are complete. This transfer discipline guarantees role instructions and reusable replies are safely addressed by file path.

Track agent run status and maintain audit logs by writing completion status to STATE_ROOT/RESPONSE.md and appending every state transition to an append-only state/task_history.jsonl log. This provides authoritative run tracking and enables recovery via relaunch or retry when durable outputs are corrupted or missing.

Index final deliverables and promote artifacts by maintaining an artifacts/manifest.json file that catalogs produced deliverables and key supporting files. This artifact promotion discipline ensures all outputs are addressable by file path for later evaluation across long horizon agent runs.

Avoid file-based state persistence if your agent runs are short-lived, single-stage, or do not require context compression and child handoffs. This approach requires a stable STATE_ROOT layout and adds transfer discipline overhead, making it unnecessary for simple, stateless agent tasks.