The v3 server exposes 13 MCP tools organized around a single WorkItem graph model. Every entity — whether a project, feature, or task — is a WorkItem with a role (queue, work, review, blocked, terminal), optional parentId, a type field that selects a work-item schema (lifecycle mode + required notes), optional tags for categorization, and optional traits that compose additional note requirements. Notes are first-class keyed documents attached to items. Dependencies link items with typed blocking or relational edges.

Purpose. Write operations for WorkItems: batch-create, partial-update, or batch-delete. Depth is computed automatically from the parent; the maximum nesting depth is 3.

Operations. create, update, delete

Item object fields (create):

Item object fields (update): Same fields as create plus required id (UUID), including type, properties, and traits. Only provided fields are changed; omitted fields retain existing values. Setting parentId to JSON null moves the item to root.

Note: The role field is not accepted in update operations. Use advance_item with an appropriate trigger instead.

Response (update).

{
 "items": [
 { "id": "uuid", "modifiedAt": "2025年01月01日T00:00:00Z", "requiresVerification": false }
 ],
 "updated": 1,
 "failed": 0
}

Examples.

// Create two child items under a shared parent
{
 "operation": "create",
 "parentId": "550e8400-e29b-41d4-a716-446655440000",
 "items": [
 { "title": "Design API schema", "priority": "high", "tags": "task-implementation" },
 { "title": "Write unit tests", "priority": "medium" }
 ]
}
// Partial update
{
 "operation": "update",
 "items": [
 { "id": "550e8400-e29b-41d4-a716-446655440001", "priority": "high", "complexity": 3 }
 ]
}
// Recursive delete
{
 "operation": "delete",
 "ids": ["550e8400-e29b-41d4-a716-446655440000"],
 "recursive": true
}

Response (delete).

{
 "ids": ["550e8400-e29b-41d4-a716-446655440000"],
 "deleted": 5,
 "failed": 0,
 "descendantsDeleted": 4
}

descendantsDeleted is only present when recursive: true and descendants were actually deleted; it counts the number of descendant items removed (not including the root items listed in ids). The deleted count includes both the root items and their descendants. Without recursive: true, deleting an item with children fails proactively (via a child-count check, not a DB constraint) with an error message listing the child count.

Response (create).

{
 "items": [
 {
 "id": "uuid",
 "title": "Design API schema",
 "depth": 1,
 "role": "queue",
 "priority": "high",
 "requiresVerification": false,
 "tags": "task-implementation",
 "type": null,
 "expectedNotes": [
 { "key": "requirements", "role": "queue", "required": true, "description": "...", "exists": false }
 ]
 }
 ],
 "created": 1,
 "failed": 0
}

expectedNotes is included only when a note schema is resolved for the item (via type, tag match, or default fallback). Check it immediately after creation to know which notes to fill before calling advance_item(trigger="start"). Both full item responses (from get) and minimal responses (from search and overview) include type when it is non-null.

Purpose. Read-only queries for WorkItems: full fetch by ID, filtered search with pagination, or hierarchical overview.

Operations. get, search, overview

Examples.

// Fetch single item with ancestor breadcrumbs
{ "operation": "get", "id": "550e8400-e29b-41d4-a716-446655440001", "includeAncestors": true }
// Search with pagination
{ "operation": "search", "role": "work", "priority": "high", "limit": 20, "offset": 0 }
// Scoped overview of a feature's children
{ "operation": "overview", "itemId": "550e8400-e29b-41d4-a716-446655440000" }

Response (search).

{
 "items": [
 { "id": "uuid", "parentId": "uuid", "title": "...", "role": "work", "priority": "high", "depth": 1, "tags": null, "type": null }
 ],
 "total": 42,
 "returned": 20,
 "limit": 20,
 "offset": 0
}

Search returns minimal fields (id, parentId, title, role, statusLabel, priority, depth, tags, type). Nullable fields (parentId, statusLabel, tags, type) are omitted when null — they do not appear as JSON null. Use get for full item JSON including description, summary, timestamps, and roleChangedAt.

Response (overview — scoped mode, with itemId).

{
 "item": { "id": "uuid", "title": "Auth Feature", "role": "work", "priority": "high", "depth": 1, ... },
 "childCounts": { "queue": 2, "work": 1, "review": 0, "blocked": 0, "terminal": 1 },
 "children": [
 { "id": "uuid", "parentId": "uuid", "title": "Design login flow", "role": "terminal", "priority": "high", "depth": 2 }
 ]
}

Scoped overview returns the full item JSON in item, a count per role in childCounts, and a minimal JSON list of direct children in children (using toMinimalJson fields). Note: scoped overview children do not include childCounts or traits.

Response (overview — global mode, no itemId).

Global overview returns root items with the same minimal fields as search, plus childCounts and optional traits. When includeChildren is true, each root includes a children array where each child has the minimal fields plus its own childCounts and optional traits.

{
 "items": [
 {
 "id": "uuid", "title": "Auth Feature", "role": "work", "priority": "high", "depth": 0,
 "tags": "backend", "type": "feature-implementation",
 "traits": ["needs-migration-review"],
 "childCounts": { "queue": 2, "work": 1, "review": 0, "blocked": 0, "terminal": 1 },
 "children": [
 {
 "id": "uuid", "parentId": "uuid", "title": "Design login flow", "role": "work",
 "priority": "high", "depth": 1, "tags": "backend", "type": "feature-task",
 "childCounts": { "queue": 0, "work": 0, "review": 0, "blocked": 0, "terminal": 0 }
 }
 ]
 }
 ],
 "total": 5
}

Nullable fields (parentId, statusLabel, tags, type) are omitted when null. traits is omitted when the item has no traits (never an empty array). children is only present when includeChildren is true. total reflects the count of root items returned (not a total-in-DB count).

Purpose. Atomically create a root WorkItem, optional child items, optional dependency edges between them, and optional blank notes — all in a single call. Eliminates the round-trips required when calling manage_items, manage_dependencies, and manage_notes separately.

Operations. Single operation (no operation parameter).

Depth cap: root must be at depth < 3 (i.e., root can be at depth 0, 1, or 2). Children are always root.depth + 1, so children can reach depth 3 (when root is at depth 2).

Example.

{
 "root": { "title": "Authentication Feature", "priority": "high", "tags": "feature" },
 "children": [
 { "ref": "t1", "title": "Design login flow", "priority": "high" },
 { "ref": "t2", "title": "Implement JWT handler", "priority": "high" },
 { "ref": "t3", "title": "Write integration tests", "priority": "medium" }
 ],
 "deps": [
 { "from": "t1", "to": "t2", "type": "BLOCKS" },
 { "from": "t2", "to": "t3", "type": "BLOCKS" }
 ],
 "createNotes": false
}

Response.

{
 "root": { "id": "uuid", "title": "Authentication Feature", "role": "queue", "depth": 0, "tags": "feature" },
 "children": [
 { "ref": "t1", "id": "uuid", "title": "Design login flow", "role": "queue", "depth": 1, "tags": null },
 { "ref": "t2", "id": "uuid", "title": "Implement JWT handler", "role": "queue", "depth": 1, "tags": null }
 ],
 "dependencies": [
 { "id": "uuid", "fromRef": "t1", "toRef": "t2", "type": "BLOCKS" }
 ],
 "notes": []
}

tags is included on both root and each child when it was set; when not set, the field is omitted (not null). When createNotes=true and items have tags matching a schema, the notes array is populated with created note entries:

"notes": [
 { "itemRef": "t1", "key": "acceptance-criteria", "role": "queue", "id": "uuid" },
 { "itemRef": "t1", "key": "done-criteria", "role": "work", "id": "uuid" }
]

When createNotes=false (default) or no items match a schema, notes is [].

Purpose. Batch-complete (or cancel) all descendants of a root item, or an explicit list of items, in topological dependency order. Gate enforcement applies per item: if required notes are missing, that item fails and its downstream dependents within the set are skipped.

Operations. Single operation (no operation parameter).

Exactly one of rootId or itemIds must be provided.

Gate enforcement and trigger: When trigger="complete", gate enforcement applies — items whose schema resolves (via type, tag match, or default fallback) must have all required notes filled before completing; items that fail gating are recorded as gateErrors and their dependents within the set are skipped. When trigger="cancel", gate enforcement is bypassed — all items in the set are cancelled regardless of note state.

Example.

{ "rootId": "550e8400-e29b-41d4-a716-446655440000", "trigger": "complete" }

Response.

{
 "results": [
 { "itemId": "uuid", "title": "Design login flow", "applied": true, "trigger": "complete" },
 { "itemId": "uuid", "title": "Implement handler", "applied": false, "gateErrors": ["missing: done-criteria"] },
 { "itemId": "uuid", "title": "Write tests", "applied": false, "skipped": true, "skippedReason": "dependency gate failed" }
 ],
 "summary": { "total": 3, "completed": 1, "skipped": 1, "gateFailures": 1 }
}

skippedReason values: Items can be skipped for two reasons:

• "dependency gate failed" — a blocker item in the same target set failed its gate check or failed to apply, and this item is a downstream dependent.
• "Cannot transition" (or a specific error message) — the item itself could not be resolved for transition (e.g., it is already terminal or the role is incompatible with the trigger).

summary fields: total = completed + skipped + gateFailures. completed = items successfully transitioned. skipped = items skipped due to upstream gate/apply failures or items already terminal. gateFailures = items that failed gate checks (missing required notes); their downstream dependents are counted in skipped.

Purpose. Write operations for Notes: batch-upsert (create-or-update by (itemId, key)) or delete by IDs, by item, or by item and key.

Operations. upsert, delete

When both ids and itemId are provided, the delete is additive: notes matched by ids are deleted first, then notes matched by itemId (optionally scoped by key) are deleted. Both deletions contribute to the final deleted count. Deleting a non-existent note by (itemId, key) is a silent no-op (returns success with that note not counted in deleted).

Note object fields (upsert):

Each upsert note element may include an optional actor object:

• id (required string): Identifier for the actor writing this note
• kind (required string): One of orchestrator, subagent, user, external
• parent (optional string): ID of the dispatching agent (forms delegation chain)
• proof (optional string): Opaque credential blob (persisted, unused by Stage 1)

When provided, the upsert response includes actor and verification objects on each successfully upserted note, and the note is persisted with actor claim data that appears in subsequent query_notes responses.

The (itemId, key) pair is unique — upserting with an existing pair updates the note in place (preserving its UUID).

Examples.

// Fill required notes before starting an item
{
 "operation": "upsert",
 "notes": [
 {
 "itemId": "550e8400-e29b-41d4-a716-446655440001",
 "key": "requirements",
 "role": "queue",
 "body": "The handler must validate JWT signatures and return 401 on failure."
 }
 ]
}
// Delete all notes for an item
{ "operation": "delete", "itemId": "550e8400-e29b-41d4-a716-446655440001" }

Response (upsert).

{
 "notes": [
 { "id": "uuid", "itemId": "uuid", "key": "requirements", "role": "queue" }
 ],
 "upserted": 1,
 "failed": 0,
 "itemContext": {
 "<itemId>": {
 "guidancePointer": "Guidance text for the next unfilled required note, or null",
 "noteProgress": { "filled": 1, "remaining": 0, "total": 1 }
 }
 }
}

The itemContext map is keyed by each itemId that had at least one successful upsert. For each item:

• guidancePointer — the guidance text from the first unfilled required note in the item's current phase, or null if all required notes are filled (or no schema matches).
• noteProgress — { filled, remaining, total } counts of required notes for the current phase, or null if the item has no matching schema or is in terminal state.

This eliminates the need to call get_context after each manage_notes upsert to check remaining work.

Purpose. Read-only queries for Notes: fetch a single note by UUID, or list all notes for a WorkItem with optional role filtering.

Operations. get, list

Examples.

// List queue-phase notes for an item, bodies omitted
{ "operation": "list", "itemId": "550e8400-e29b-41d4-a716-446655440001", "role": "queue", "includeBody": false }

Response (list).

{
 "notes": [
 {
 "id": "uuid",
 "itemId": "uuid",
 "key": "requirements",
 "role": "queue",
 "body": "The handler must...",
 "createdAt": "2025年01月01日T00:00:00Z",
 "modifiedAt": "2025年01月01日T00:00:00Z"
 }
 ],
 "total": 1
}

Purpose. Create or delete dependency edges between WorkItems. Create supports an explicit dependencies array (atomic batch) or topology pattern shortcuts (linear, fan-out, fan-in).

Operations. create, delete

The dependencies array create is atomic: all succeed or all fail (cycle and duplicate detection spans the entire batch).

Examples.

// Explicit batch with unblockAt
{
 "operation": "create",
 "dependencies": [
 { "fromItemId": "uuid-a", "toItemId": "uuid-b", "type": "BLOCKS", "unblockAt": "terminal" }
 ]
}
// Linear chain shortcut
{
 "operation": "create",
 "pattern": "linear",
 "itemIds": ["uuid-a", "uuid-b", "uuid-c"]
}
// Delete by relationship
{
 "operation": "delete",
 "fromItemId": "uuid-a",
 "toItemId": "uuid-b"
}

Response (create).

{
 "dependencies": [
 { "id": "uuid", "fromItemId": "uuid-a", "toItemId": "uuid-b", "type": "BLOCKS", "unblockAt": "terminal" }
 ],
 "created": 1
}

unblockAt is only included in the response when it was explicitly set. When unblockAt is null (the default), it is omitted from each dependency object in the response. All pattern shortcuts (linear, fan-out, fan-in) return the same dependencies array response shape as the explicit array create.

Validation Failure Response (any validation error: self-dependency, cycle, RELATES_TO+unblockAt, invalid threshold, etc.):

{
 "dependencies": [],
 "created": 0,
 "failed": 1,
 "failures": [{ "index": 0, "error": "A dependency cannot reference the same item on both sides" }]
}

Note: atomicity is preserved — either all dependencies are created or none. On any validation failure, created is always 0 and failures contains a single entry describing the rejection reason. The failures[].index field is 0-based (the first item is index 0).

Constraint: RELATES_TO and unblockAt. Specifying unblockAt on a RELATES_TO dependency is a validation error. RELATES_TO dependencies have no blocking semantics and do not support an unblock threshold; providing one will return a validation failure response.

Response (delete by relationship).

{
 "fromItemId": "uuid-a",
 "toItemId": "uuid-b",
 "deleted": 1
}

Response (delete all by item).

{
 "itemId": "uuid-a",
 "deleted": 3
}

When deleteAll=true, provide either fromItemId or toItemId (not both required). All dependencies attached to that item (in either direction) are deleted, and the response contains the itemId and deleted count.

Purpose. Read-only dependency queries with direction and type filtering, optional WorkItem detail enrichment, and optional BFS graph traversal.

Examples.

// Incoming blocking dependencies
{ "itemId": "550e8400-e29b-41d4-a716-446655440001", "direction": "incoming", "includeItemInfo": true }
// Full dependency graph traversal
{ "itemId": "550e8400-e29b-41d4-a716-446655440001", "neighborsOnly": false }

Response.

{
 "dependencies": [
 {
 "id": "uuid",
 "fromItemId": "uuid-a",
 "toItemId": "uuid-b",
 "type": "BLOCKS",
 "unblockAt": "terminal",
 "effectiveUnblockRole": "terminal",
 "fromItem": { "title": "Design API", "role": "terminal", "priority": "high" }
 }
 ],
 "counts": { "incoming": 1, "outgoing": 0, "relatesTo": 0 },
 "graph": { "chain": ["uuid-a", "uuid-b"], "depth": 1 }
}

graph is only included when neighborsOnly=false.

Purpose. Trigger-based role transitions for WorkItems with dependency validation, note-schema gate enforcement, cascade detection, and unblock reporting. Supports batch transitions.

Transition object fields:

Each transition element may include an optional actor object:

• id (required string): Identifier for the actor making this transition
• kind (required string): One of orchestrator, subagent, user, external
• parent (optional string): ID of the dispatching agent (forms delegation chain)
• proof (optional string): Opaque credential blob (persisted, unused by Stage 1)

When provided, the response includes actor and verification objects on each successful transition.

Trigger effects:

Gate enforcement. The schema used for gate checks is resolved in this order:

1. type field → direct lookup in work_item_schemas (highest priority)
2. Tag fallback → first tag in the item's tags that matches a schema key
3. default schema fallback (if configured)

When a schema is resolved:

• start: required notes for the current phase must exist and be filled.
• complete: all required notes across all phases must be filled.

Trait notes are merged into the resolved schema: default_traits from config apply globally, and per-item traits (stored in properties JSON) add their note requirements on top.

Lifecycle modes (set on the schema via work_item_schemas):

• AUTO (default) — terminal cascade fires automatically when all children reach terminal
• MANUAL — suppresses terminal cascade; parent must be advanced explicitly
• PERMANENT — item never auto-terminates; intended for persistent containers
• AUTO_REOPEN — cascade fires as in AUTO, and parent is also reopened when a new child is added

Start cascade. When a child item transitions to WORK, the parent is automatically advanced from QUEUE to WORK if it is still in QUEUE (same cascade logic applies up the ancestor chain). This appears in cascadeEvents in the response with trigger="cascade".

Terminal cascade. When a child item reaches TERMINAL, the parent may also automatically advance if all its children are terminal.

Reopen cascade. When a child item is reopened (TERMINAL → QUEUE) and its parent is TERMINAL, the parent is automatically reopened to WORK. This ensures the parent reflects that it has active children again.

All cascade types are recorded in cascadeEvents.

Examples.

// Single transition
{ "transitions": [{ "itemId": "550e8400-e29b-41d4-a716-446655440001", "trigger": "start" }] }
// Batch
{
 "transitions": [
 { "itemId": "uuid-1", "trigger": "complete" },
 { "itemId": "uuid-2", "trigger": "complete" }
 ]
}

Response (success).

{
 "results": [
 {
 "itemId": "uuid",
 "previousRole": "queue",
 "newRole": "work",
 "trigger": "start",
 "applied": true,
 "cascadeEvents": [
 { "itemId": "uuid-parent", "title": "Auth Feature", "previousRole": "queue", "targetRole": "work", "applied": true }
 ],
 "unblockedItems": [{ "itemId": "uuid-next", "title": "Next task" }],
 "expectedNotes": [
 { "key": "done-criteria", "role": "work", "required": true, "description": "...", "exists": false }
 ],
 "guidancePointer": "Fill the done-criteria note with...",
 "noteProgress": { "filled": 0, "remaining": 1, "total": 1 }
 }
 ],
 "summary": { "total": 1, "succeeded": 1, "failed": 0 },
 "allUnblockedItems": [{ "itemId": "uuid-next", "title": "Next task" }]
}

unblockedItems and allUnblockedItems are always present (as [] when empty). cascadeEvents is always present (as [] when no cascades occurred). expectedNotes is always present (as [] when no schema matches the item's tags). Each entry in expectedNotes includes: key, role, required, description, exists, and optionally skill (present only when a skill is configured for that note).

guidancePointer (string or null) is the guidance text for the first unfilled required note in the new role. It is null when no schema matches, no required notes exist for the new role, or all required notes are already filled. Omitted from the response when null.

skillPointer (string, optional): Skill name to invoke for the first unfilled required note. Omitted when no skill is configured or all required notes are filled.

noteProgress provides counts of required notes for the new role: filled (notes that exist with non-blank body), remaining (missing or blank), and total (filled + remaining). Omitted from the response when no schema matches the item's tags.

Response (failed transition). When applied: false, the result shape differs from the success shape:

{
 "results": [
 {
 "itemId": "uuid",
 "trigger": "start",
 "applied": false,
 "error": "Gate check failed: required notes not filled for queue phase: requirements",
 "blockers": [
 { "fromItemId": "uuid-blocker", "currentRole": "queue", "requiredRole": "terminal" }
 ]
 }
 ],
 "summary": { "total": 1, "succeeded": 0, "failed": 1 },
 "allUnblockedItems": []
}

blockers is only present when the transition failed due to dependency constraints. error contains a human-readable description of why the transition was rejected. Note that previousRole, newRole, and expectedNotes are absent from failed results.

Purpose. Read-only status progression recommendation for a single WorkItem. Returns whether the item is Ready to advance, Blocked, or Terminal, without making any changes.

Example.

{ "itemId": "550e8400-e29b-41d4-a716-446655440001" }

recommendation values: "Ready", "Blocked", or "Terminal".

Response.

// Ready — item can advance
{
 "recommendation": "Ready",
 "currentRole": "queue",
 "nextRole": "work",
 "trigger": "start",
 "progressionPosition": "1/3"
}
// Blocked by dependency
{
 "recommendation": "Blocked",
 "currentRole": "queue",
 "blockers": [
 { "fromItemId": "uuid-blocker", "currentRole": "queue", "requiredRole": "terminal" }
 ]
}
// Blocked — item is explicitly in BLOCKED role (set via block/hold trigger)
{
 "recommendation": "Blocked",
 "currentRole": "blocked",
 "suggestion": "Use 'resume' trigger to return to previous role"
}
// Terminal
{ "recommendation": "Terminal", "currentRole": "terminal", "reason": "Item is terminal. Use 'reopen' trigger to move back to queue, or 'cancel' if already cancelled." }

When the item is in BLOCKED role, the response includes a suggestion field instead of blockers. When the item is blocked by unsatisfied dependencies, the response includes blockers but no suggestion.

Purpose. Read-only context snapshot in one of three modes determined by which parameters are supplied. Use for session startup, work-summary dashboards, and pre-advance gate checks.

Modes:

• Item mode — itemId provided: note schema, existing notes with fill status, and gate status for a specific item.
• Session resume — since provided: active items, recent role transitions since the timestamp, and stalled items.
• Health check — no parameters: all active items (work/review), blocked items, and stalled items.

Examples.

// Health check (no params)
{}
// Session resume
{ "since": "2025年01月01日T09:00:00Z", "includeAncestors": true }
// Item gate check
{ "itemId": "550e8400-e29b-41d4-a716-446655440001" }

Response (item mode).

{
 "mode": "item",
 "item": { "id": "uuid", "title": "JWT Handler", "role": "queue", "tags": "task-implementation", "depth": 1 },
 "schema": [
 { "key": "requirements", "role": "queue", "required": true, "description": "...", "exists": true, "filled": true },
 { "key": "done-criteria", "role": "work", "required": true, "description": "...", "exists": false, "filled": false }
 ],
 "gateStatus": { "canAdvance": true, "phase": "queue", "missing": [] },
 "guidancePointer": null,
 "noteProgress": { "filled": 1, "remaining": 1, "total": 2 }
}

guidancePointer (string or null) is the guidance text for the first unfilled required note in the current role. Null when no schema matches, no required notes exist, or all are filled.

skillPointer (string, optional): Skill name to invoke for the first unfilled required note. Omitted when no skill is configured or all required notes are filled. Derived from the skill field on the first unfilled required note in the schema.

noteProgress provides counts of required notes for the current role: filled (notes that exist with non-blank body), remaining (missing or blank), and total (filled + remaining). Null when no schema matches the item's tags or the item is in terminal role (distinguishes "no schema" from "empty schema").

Each entry in the schema array includes: key, role, required, description, exists, filled, and optionally skill (present only when a skill is configured for that note entry).

Response (health-check mode).

{
 "mode": "health-check",
 "activeItems": [{ "id": "uuid", "title": "...", "role": "work", "tags": null }],
 "blockedItems": [{ "id": "uuid", "title": "...", "role": "blocked" }],
 "stalledItems": [{ "id": "uuid", "title": "...", "role": "work", "missingNotes": ["done-criteria"] }]
}

Purpose. Priority-ranked recommendation of the next WorkItem(s) to work on. Finds QUEUE items, filters out those with unsatisfied blocking dependencies, and ranks by priority descending then complexity ascending (quick wins first).

Example.

{ "parentId": "550e8400-e29b-41d4-a716-446655440000", "limit": 3, "includeDetails": true }

Response.

{
 "recommendations": [
 {
 "itemId": "uuid",
 "title": "Design login flow",
 "role": "queue",
 "priority": "high",
 "complexity": 2,
 "summary": "Create wireframes and API contract",
 "tags": "task-implementation",
 "parentId": "uuid-parent"
 }
 ],
 "total": 1
}

Purpose. Identifies all WorkItems that are blocked, either explicitly (role=blocked via a block/hold trigger) or implicitly (items in queue/work/review with unsatisfied blocking dependency edges). Terminal items are never included.

Example.

{ "includeItemDetails": true, "includeAncestors": true }

Response.

{
 "blockedItems": [
 {
 "itemId": "uuid",
 "title": "Implement JWT handler",
 "role": "queue",
 "priority": "high",
 "complexity": 5,
 "blockType": "dependency",
 "blockedBy": [
 {
 "itemId": "uuid-blocker",
 "title": "Design login flow",
 "role": "queue",
 "unblockAt": "terminal",
 "effectiveUnblockRole": "terminal",
 "satisfied": false
 }
 ],
 "blockerCount": 1,
 "summary": "Handle JWT validation",
 "tags": "task-implementation"
 }
 ],
 "total": 1
}

blockType values:

• "explicit" — item is in the BLOCKED role (set via a block or hold trigger). blockedBy lists any associated dependency blockers but the item is included regardless.
• "dependency" — item is in QUEUE, WORK, or REVIEW with one or more unsatisfied blocking dependency edges.

satisfied is true when the blocker has reached its effectiveUnblockRole.

blockerCount reflects only the number of unsatisfied blockers (not total blockers). For "explicit" items with no dependency blockers, blockerCount is 0.

Actor attribution tracks who made changes to work items. Every advance_item transition and manage_notes upsert can include an optional actor claim. Stage 1 ships with a no-op verifier — all claims are persisted as unverified.

Every persisted actor claim includes a verification record:

Delegation chains are built by convention:

1. The orchestrator includes actor: { id: "orch-1", kind: "orchestrator" } on its calls
2. When dispatching a subagent, it passes its own id as context
3. The subagent includes actor: { id: "sub-1", kind: "subagent", parent: "orch-1" } on its MCP calls
4. Query responses preserve the chain for post-mortem analysis

This is a documentation convention, not enforced by the server. Stage 1 trusts self-reported claims.

Actor claims are optional by default — users who don't need auditing pay no extra token cost. To require actor claims on all write operations, enable auditing in .taskorchestrator/config.yaml:

auditing:
 enabled: true

When enabled, the plugin's PreToolUse hook blocks any advance_item or manage_notes(upsert) call where one or more elements are missing an actor object. The call never reaches the server — the agent must retry with actor claims included.

When enabled is false or the auditing section is absent, calls pass through with no enforcement. Actor claims can still be provided voluntarily.

Note: Config changes require an MCP reconnect (/mcp) or session restart to take effect.

Actor claims are self-reported by convention — the server does not inject them automatically. This means:

• Uninstructed subagents make calls with no actor data, producing anonymous transitions and notes
• Instructed subagents include actor claims only when the delegation prompt tells them to
• The enforcement hook applies to all callers in the session, including subagents, providing a safety net regardless of prompt quality

For reliable attribution, combine auditing enforcement with explicit delegation instructions:

Include an "actor" object on every advance_item and manage_notes call:
{ "id": "your-agent-name", "kind": "subagent", "parent": "orchestrator-id" }

The auditing section in .taskorchestrator/config.yaml controls actor attribution enforcement and verification. The enabled flag and the verifier block are independent — enforcement checks actor presence, while the verifier checks proof validity.

auditing:
 enabled: true # Enforce actor claims on write operations
 verifier:
 type: jwks # "noop" (default) | "jwks"
 oidc_discovery: "https://provider.example/.well-known/openid-configuration"
 jwks_uri: "https://provider.example/.well-known/jwks.json"
 jwks_path: ".agentlair/jwks.json"
 issuer: "https://provider.example"
 audience: "task-orchestrator"
 algorithms: ["EdDSA", "RS256"]
 cache_ttl_seconds: 300
 require_sub_match: true

oidc_discovery, jwks_uri, and jwks_path can be used alone or combined. URI-sourced keys and file-sourced keys are merged into a single key set. When both oidc_discovery and explicit jwks_uri/issuer are set, the explicit values override the OIDC-discovered values.

When using jwks_path, the .agentlair/ directory must be mounted into the container alongside .taskorchestrator/:

docker run --rm -i \
 -v mcp-task-data:/app/data \
 -v "$(pwd)"/.taskorchestrator:/project/.taskorchestrator:ro \
 -v "$(pwd)"/.agentlair:/project/.agentlair:ro \
 -e AGENT_CONFIG_DIR=/project \
 task-orchestrator:dev

The .agentlair/ mount is only needed when using jwks_path. When using jwks_uri or oidc_discovery, the container must be able to reach the endpoint over the network.

Network access from Docker containers:

jwks_path (local file) avoids all networking concerns — recommended for local dev and air-gapped environments.