--- id: "05-mcp-dependency-tools" title: "MCP dependency tools" status: done wave: 5 depends_on: ["01-core-dependency-relationship"] plan: "plan.md" spec: "../../specs/tasks/system-design/task-dependencies.md" --- # Task 05: MCP Dependency Tools ## Acceptance - `create_task_kandev` **declares** `blocked_by` (array of task IDs) and `start_when_unblocked` (boolean) in its `mcp.NewTool` schema in `internal/mcp/server/server.go`. Today the handler struct at `internal/mcp/handlers/handlers.go:576` reads `blocked_by` but the schema never declares it, so no agent can discover or reliably pass it. A pinning test asserts both parameters are present in the registered tool schema. - `blocked_by` non-empty plus `start_agent: true` (including the default) records a start-when-unblocked intent and launches nothing now. The create response reports `started: false` and `start_when_unblocked: true`. - `blocked_by` non-empty plus explicit `start_when_unblocked: false` creates the edges with no launch intent; completing the predecessor starts nothing. - `add_task_dependency_kandev` is registered: `{task_id?, depends_on_task_id}`, `task_id` defaults to the calling task, returns the resulting `depends_on` list. It rejects cycles with the cycle path, self-edges, and cross-workspace edges, using the single validator from Task 01. - `remove_task_dependency_kandev` is registered with the same shape. Removing an absent edge succeeds. Removing the last edge unblocks the task without launching it. - Both new tools are registered in the same modes as the other task-mutation tools, and neither widens the `ModeExternal` surface beyond what `create_task_kandev` already exposes there. - An agent cannot set `start_when_unblocked` on a task it did not create. - Tool descriptions state: a subtask means "part of" and a dependency means "not until"; decomposing a plan into ordered phases is N sibling tasks chained with `blocked_by` + `start_when_unblocked`, not N subtasks started at once; and a failed predecessor halts the chain and needs human action. - `list_related_tasks_kandev` populates `blockers` and `blocked_by` with `Features.Office` false (inherited from Task 01; asserted here at the MCP boundary). - Both tools authorize through the existing MCP scoping path — the owning task comes from the `AgentExecution`, never from an agent-supplied `task_id` used to reach another workspace's tasks. - The MCP tool list in the root `CLAUDE.md` / `AGENTS.md` "Kandev Task Creation" guidance is updated if the new tools change how an agent should decompose work. ## TDD sequence 1. Failing pinning test: the registered `create_task_kandev` schema declares `blocked_by` and `start_when_unblocked`. 2. Failing test: `blocked_by` + default `start_agent` creates the edge, starts no session, and returns `started: false`, `start_when_unblocked: true`. 3. Failing test: `blocked_by` + `start_when_unblocked: false` records no intent and completing the predecessor starts nothing. 4. Failing test: three chained `create_task_kandev` calls run in order — completing the first starts the second and not the third. 5. Failing tests for `add_task_dependency_kandev`: default `task_id`, returned `depends_on`, cycle rejection with path, self-edge, cross-workspace. 6. Failing tests for `remove_task_dependency_kandev`: removal, absent-edge success, last-edge removal unblocks without launching. 7. Failing test: an agent cannot set `start_when_unblocked` on a task it did not create. 8. Failing test: cross-workspace `task_id` on either tool is denied by the scoping path. 9. Failing test: with `Features.Office` false, `create_task_kandev` + `blocked_by` succeeds and `list_related_tasks_kandev` reports the edge. 10. Implement schema declarations, the two tools, the start-intent semantics, and the descriptions. ## Verification ```bash cd apps/backend go test -tags fts5 ./internal/mcp/... -run 'Test.*(Dependenc|BlockedBy|StartWhenUnblocked|ToolSchema)' -count=1 go test -tags fts5 ./internal/mcp/... -count=1 golangci-lint run ./... --new-from-rev=origin/main --timeout=5m ``` ## Files likely touched - `apps/backend/internal/mcp/server/server.go` - `apps/backend/internal/mcp/handlers/handlers.go` - `apps/backend/internal/mcp/server/handoff_handlers.go` - `apps/backend/internal/mcp/scope/` (if either tool needs a scope entry) - `CLAUDE.md` / `AGENTS.md` (task-decomposition guidance) - focused MCP handler and schema-pinning tests ## Dependencies Task 01 — needs the wired blocker repository, the single validator, and the `start_when_unblocked` create-request field. It does not need Tasks 02–04, so it may run alongside Task 06. ## Parallelism `sequential` ## Output contract Mark this task `in_progress` before the RED tests and `done` only after the listed commands pass. Record the two new tool names and their registered modes, the exact `blocked_by` + `start_agent` resolution rule as implemented, the schema-pinning test name, and test results in this file and `plan.md`.