claim_task
Assign yourself to available tasks for execution in Task Trellis. Use to pick up work items from the queue based on priority, scope, or specific task ID, enabling autonomous task execution workflows.
Instructions
Claims a task in the task trellis system
Use this tool to assign yourself to available tasks for execution. Essential for AI agents to pick up work items from the task queue and begin execution.
Claiming behavior:
Without 'taskId': Claims the next available task based on priority and readiness
With 'taskId': Claims a specific task by ID if available and ready
'scope': Limits claiming to tasks within a specific project or area
'force': Overrides normal claiming restrictions (use with caution)
Task readiness criteria:
Task status allows claiming (typically 'draft' or 'open' states)
All prerequisites are satisfied (prerequisite tasks completed)
Task is not already claimed by another agent
Task falls within specified scope if provided
Claiming workflow:
System evaluates available tasks against readiness criteria
Selects highest priority task that meets requirements
Updates task status to 'in-progress
Associates task with the claiming agent
Returns claimed task details for execution
Common patterns:
Claim any ready task: (no parameters)
Claim from project: scope='P-project-name'
Claim specific task: taskId='T-specific-task-id'
Force claim blocked task: taskId='T-task-id', force=true
Essential for autonomous task execution workflows where agents need to discover and claim work items dynamically.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | Scope to claim task from (optional) | |
| taskId | No | Specific task ID to claim (optional) | |
| force | No | Force claim flag (defaults to false) |
Implementation Reference
- src/tools/claimTaskTool.ts:56-72 (handler)The handleClaimTask function executes the core logic of the 'claim_task' tool by parsing arguments and delegating to TaskTrellisService.claimTask.export async function handleClaimTask( service: TaskTrellisService, repository: Repository, args: unknown, ) { const { scope, taskId, force = false, } = args as { scope?: string; taskId?: string; force?: boolean; }; return service.claimTask(repository, scope, taskId, force); }
- src/tools/claimTaskTool.ts:4-54 (schema)The claimTaskTool constant defines the tool's name 'claim_task', detailed description, and input schema for parameters scope, taskId, and force.export const claimTaskTool = { name: "claim_task", description: `Claims a task in the task trellis system Use this tool to assign yourself to available tasks for execution. Essential for AI agents to pick up work items from the task queue and begin execution. Claiming behavior: - Without 'taskId': Claims the next available task based on priority and readiness - With 'taskId': Claims a specific task by ID if available and ready - 'scope': Limits claiming to tasks within a specific project or area - 'force': Overrides normal claiming restrictions (use with caution) Task readiness criteria: - Task status allows claiming (typically 'draft' or 'open' states) - All prerequisites are satisfied (prerequisite tasks completed) - Task is not already claimed by another agent - Task falls within specified scope if provided Claiming workflow: 1. System evaluates available tasks against readiness criteria 2. Selects highest priority task that meets requirements 3. Updates task status to 'in-progress 4. Associates task with the claiming agent 5. Returns claimed task details for execution Common patterns: - Claim any ready task: (no parameters) - Claim from project: scope='P-project-name' - Claim specific task: taskId='T-specific-task-id' - Force claim blocked task: taskId='T-task-id', force=true Essential for autonomous task execution workflows where agents need to discover and claim work items dynamically.`, inputSchema: { type: "object", properties: { scope: { type: "string", description: "Scope to claim task from (optional)", }, taskId: { type: "string", description: "Specific task ID to claim (optional)", }, force: { type: "boolean", description: "Force claim flag (defaults to false)", default: false, }, }, }, } as const;
- src/server.ts:176-197 (registration)Registration of the claimTaskTool in the ListToolsRequestHandler, including it in the list of available tools.server.setRequestHandler(ListToolsRequestSchema, () => { const tools: unknown[] = [ createObjectTool, updateObjectTool, getObjectTool, deleteObjectTool, listObjectsTool, appendObjectLogTool, appendModifiedFilesTool, claimTaskTool, getNextAvailableIssueTool, completeTaskTool, ]; // Only include activate tool if server is not properly configured from command line // (i.e., local mode without projectRootFolder specified) if (serverConfig.mode === "local" && !serverConfig.planningRootFolder) { tools.push(activateTool); } return { tools }; });
- src/server.ts:270-271 (registration)Registration of the call handler for 'claim_task' tool in the CallToolRequestHandler switch statement.case "claim_task": return handleClaimTask(_getService(), repository, args);
- The core claimTask function implementing the business logic: task selection (specific or next available), validation, status update to IN_PROGRESS, and response formatting.export async function claimTask( repository: Repository, scope?: string, taskId?: string, force: boolean = false, ): Promise<{ content: Array<{ type: string; text: string }> }> { try { let claimedTask: TrellisObject; if (taskId) { claimedTask = await claimSpecificTask(taskId, force, repository); } else { claimedTask = await findNextAvailableTask(scope, repository); } const updatedTask = await updateTaskStatus(claimedTask, repository); return { content: [ { type: "text", text: `Successfully claimed task: ${JSON.stringify( { ...updatedTask, affectedFiles: Object.fromEntries(updatedTask.affectedFiles), }, null, 2, )}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error claiming task: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } }