Task Management System

Tasks are fully accessible to subagents via direct JSON manipulation, stored in a session-scoped filesystem with no API boundary or locking mechanism.

How It Works

The task management system persists tasks as JSON files at ~/.claude/tasks/{session-id}/{task-id}.json. Each task record contains an ID, subject, description, status (pending / in_progress / completed), and arrays for blocks and blockedBy dependencies. Subagents have full read-write access to the filesystem: they create tasks by writing JSON directly, update by modifying files, and delete by removing files. No API layer exists. The system supports arbitrary metadata fields for extension and stores tasks in a session namespace, isolating task lists across independent Claude Code sessions.

What the Test Found

Ten runtime tests verified the core CRUD operations, dependency tracking, and access model. Basic task creation, status transitions, and multiple blocker semantics all passed. The critical finding was total transparency: subagents can access and mutate tasks at will, with no permission checks or boundaries. However, the system revealed significant gaps. No referential integrity checking allows blockedBy to reference non-existent tasks or create circular dependencies (both tasks blocked forever). No locking mechanism means concurrent writes trigger last-write-wins data loss. No validation enforces schema, no timestamps track changes, and no cascade deletion cleans orphaned references when a blocking task is deleted.

Why It Matters

This design trades safety for simplicity and flexibility. Subagents can extend task records with custom metadata, implement their own dependency logic, and manage work queues without API overhead. The absence of an API boundary lets multiple agents coordinate directly over a shared persistent layer. For single-threaded orchestration or simple DAGs, the system works reliably.

Caveats

The system is unsuitable for multi-agent concurrent workflows or audit-critical pipelines. Operator code must detect cycles before creation, validate task references, serialize concurrent modifications (via ownership or locking), and clean up orphaned references manually. Storage lives at the filesystem layer with no built-in recovery, audit trail, or conflict resolution. Production use requires a wrapper layer for permissions, locking, and schema enforcement.