feat: add tasks tool with dependencies and cross-session persistence

[silvin-lubecki]

Summary

Add a tasks tool with dependency management and automatic persistence, inspired by Claude Code's task system. The existing todo tool remains unchanged for simple cases.

Features

Task Management with Dependencies

• Struct Task: ID, Description, Status, BlockedBy, Blocks, Owner
• Tools: create_task, create_tasks, update_tasks, list_tasks, add_task_dependency, remove_task_dependency, get_blocked_tasks
• Enforcement: Cannot start a blocked task (status in-progress)
• Cycle Detection: Prevents circular dependencies (direct and transitive)
• Notifications: Informs when tasks become unblocked
• Display: ✓ done, ■ in-progress, □ pending, ⚠ blocked + stats header

Always Shared, Always Persisted

• All agents automatically share the same task list (singleton)
• Tasks automatically persist to ~/.cagent/tasks/<id>.json
• Git-aware: Task list ID auto-detected from git repo (shared across worktrees!)
• Multiple worktrees of the same repo share the same task list for coordination
• --task-list <id> flag or CAGENT_TASK_LIST_ID env var to override

TUI Support

• Tasks panel in sidebar
• Component: pkg/tui/components/tool/taskstool/
• Shows blocker descriptions (not just IDs)

Tests

• 35+ unit tests (pkg/tools/builtin/tasks_test.go)
• 15+ persistence tests (pkg/tools/builtin/tasks_store_test.go)
  • Worktree sharing tests
  • Cross-repo isolation tests
  • Load error handling tests
• Flag tests (cmd/root/flags_test.go)
• Concurrency tests with -race flag
• E2E configs: e2e/testdata/tasks_dependencies.yaml, e2e/testdata/shared_tasks.yaml

Usage

# Tasks auto-persist based on git repo (default)
cagent run agent.yaml

# Override with custom task list ID
cagent run agent.yaml --task-list my-project

# Or via env var
export CAGENT_TASK_LIST_ID="my-project"
cagent run agent.yaml

Example Config

# Single agent with tasks
version: "2"
agents:
  root:
    model: openai/gpt-4o
    toolsets:
      - type: tasks

# Multi-agent - tasks automatically shared
version: "2"
agents:
  coordinator:
    toolsets:
      - type: tasks
      - type: transfer_task
    sub_agents: [backend, frontend]
  backend:
    toolsets:
      - type: tasks
  frontend:
    toolsets:
      - type: tasks

Storage Format

~/.cagent/tasks/
├── cagent-a1b2c3d4.json      # Auto-detected from git repo
├── my-project.json           # Custom --task-list ID
└── other-repo-e5f6g7h8.json  # Another repo

{
  "version": 1,
  "tasks": [
    {
      "id": "task_1",
      "description": "Setup database",
      "status": "completed",
      "blocked_by": [],
      "blocks": ["task_2"],
      "owner": "backend-dev"
    }
  ]
}

[silvin-lubecki]

/review

[github-actions]

Review Summary

Found 4 high-severity concurrency bugs in shared tasks mode that could lead to data corruption:

1. Race in ensureLoaded() - Multiple agents can load duplicate tasks from disk
2. Race in task ID generation - Concurrent creates can generate duplicate task IDs
3. Race in Clear operation - Newly created tasks can be incorrectly deleted

Also found several medium/low severity issues with TOCTOU patterns and eventual consistency concerns.

Root cause: The tasksHandler struct lacks synchronization at the handler level. While concurrent.Slice provides thread-safe operations, compound operations (check-then-act, read-compute-write) are not atomic.

Recommendation: Add a handler-level mutex (sync.RWMutex) to protect compound operations in shared mode, or document that shared mode is not thread-safe.

[silvin-lubecki]

/review

[github-actions]

Review Summary

Found 4 confirmed issues in the changed code:

• 2 HIGH severity bugs requiring fixes
• 1 MEDIUM severity issue worth addressing
• 1 LOW severity issue to consider

The major concerns are:

1. Missing circular dependency validation in batch task creation
2. Shared store singleton pattern that could cause confusion
3. Silent persistence failures
4. Task ID reuse after clearing completed tasks

Please review the inline comments for details.

[silvin-lubecki]

/review

[github-actions]

Code Review Summary

Found 1 high-severity bug in the task persistence layer that could lead to data loss.

Critical Issue

• Data Loss Risk: Silent load failures can permanently overwrite existing task data

Analysis Details

Reviewed the new tasks tool implementation focusing on:

• ✅ Concurrent access patterns (mutexes correctly used)
• ✅ Circular dependency detection (comprehensive)
• ✅ File I/O atomicity (temp file + rename pattern)
• ❌ Error handling in lazy loading (found critical bug)
• ✅ Shared instance management (working as designed)
• ✅ Batch task validation (ordering constraints prevent cycles)

The identified bug occurs when task loading fails but operations continue with empty state, potentially overwriting existing data.

[silvin-lubecki]

/review

[github-actions]

Code Review Summary

Found 3 issues in the new tasks tool implementation that should be addressed:

Issues Found

1. MEDIUM: Race condition in file writes due to non-unique temp filename
2. MEDIUM: Empty/dot listID causes unintended file sharing
3. LOW: Git symlink resolution order may break worktree ID consistency

The core functionality looks solid with good test coverage. The issues are edge cases that could cause data corruption in multi-process scenarios or with unusual configurations.

[krissetto]

btw i love seeing you try out the review bot <3