get-approval-status
Check the approval status of a request by polling with the approval ID. Designed for tracking changes in approval workflows within structured spec-driven development environments.
Instructions
Check the status of an approval request. Use this to poll for approval status changes.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| approvalId | Yes | The ID of the approval request to check |
Input Schema (JSON Schema)
{
"properties": {
"approvalId": {
"description": "The ID of the approval request to check",
"type": "string"
}
},
"required": [
"approvalId"
],
"type": "object"
}
Implementation Reference
- src/tools/approvals.ts:279-398 (handler)The main handler function that retrieves and returns the status of a specific approval request using ApprovalStorage. Handles pending, approved, rejected, and needs-revision states, providing nextSteps and blocking logic.async function handleGetApprovalStatus( args: StatusApprovalArgs, context: ToolContext ): Promise<ToolResponse> { // approvalId is guaranteed by type try { // Use provided projectPath or fall back to context const projectPath = args.projectPath || context.projectPath; if (!projectPath) { return { success: false, message: 'Project path is required. Please provide projectPath parameter.' }; } // Validate and resolve project path const validatedProjectPath = await validateProjectPath(projectPath); const approvalStorage = new ApprovalStorage(validatedProjectPath); await approvalStorage.start(); const approval = await approvalStorage.getApproval(args.approvalId); if (!approval) { await approvalStorage.stop(); return { success: false, message: `Approval request not found: ${args.approvalId}` }; } await approvalStorage.stop(); const isCompleted = approval.status === 'approved' || approval.status === 'rejected'; const canProceed = approval.status === 'approved'; const mustWait = approval.status !== 'approved'; const nextSteps: string[] = []; if (approval.status === 'pending') { nextSteps.push('BLOCKED - Do not proceed'); nextSteps.push('VERBAL APPROVAL NOT ACCEPTED - Use dashboard or VS Code extension only'); nextSteps.push('Approval must be done via dashboard or VS Code extension'); nextSteps.push('Continue polling with approvals action:"status"'); } else if (approval.status === 'approved') { nextSteps.push('APPROVED - Can proceed'); nextSteps.push('Run approvals action:"delete" before continuing'); if (approval.response) { nextSteps.push(`Response: ${approval.response}`); } } else if (approval.status === 'rejected') { nextSteps.push('BLOCKED - REJECTED'); nextSteps.push('Do not proceed'); nextSteps.push('Review feedback and revise'); if (approval.response) { nextSteps.push(`Reason: ${approval.response}`); } if (approval.annotations) { nextSteps.push(`Notes: ${approval.annotations}`); } } else if (approval.status === 'needs-revision') { nextSteps.push('BLOCKED - Do not proceed'); nextSteps.push('Update document with feedback'); nextSteps.push('Create NEW approval request'); if (approval.response) { nextSteps.push(`Feedback: ${approval.response}`); } if (approval.annotations) { nextSteps.push(`Notes: ${approval.annotations}`); } if (approval.comments && approval.comments.length > 0) { nextSteps.push(`${approval.comments.length} comments for targeted fixes:`); // Add each comment to nextSteps for visibility approval.comments.forEach((comment, index) => { if (comment.type === 'selection' && comment.selectedText) { nextSteps.push(` Comment ${index + 1} on "${comment.selectedText.substring(0, 50)}...": ${comment.comment}`); } else { nextSteps.push(` Comment ${index + 1} (general): ${comment.comment}`); } }); } } return { success: true, message: approval.status === 'pending' ? `BLOCKED: Status is ${approval.status}. Verbal approval is NOT accepted. Use dashboard or VS Code extension only.` : `Approval status: ${approval.status}`, data: { approvalId: args.approvalId, title: approval.title, type: approval.type, status: approval.status, createdAt: approval.createdAt, respondedAt: approval.respondedAt, response: approval.response, annotations: approval.annotations, comments: approval.comments, isCompleted, canProceed, mustWait, blockNext: !canProceed, dashboardUrl: context.dashboardUrl }, nextSteps, projectContext: { projectPath: validatedProjectPath, workflowRoot: join(validatedProjectPath, '.spec-workflow'), dashboardUrl: context.dashboardUrl } }; } catch (error) { const errorMessage = error instanceof Error ? error.message : String(error); return { success: false, message: `Failed to check approval status: ${errorMessage}` }; } }
- src/tools/approvals.ts:9-61 (schema)Tool definition and input schema for the 'approvals' tool. The 'status' action with 'approvalId' implements get-approval-status functionality.export const approvalsTool: Tool = { name: 'approvals', description: `Manage approval requests through the dashboard interface. # Instructions Use this tool to request, check status, or delete approval requests. The action parameter determines the operation: - 'request': Create a new approval request after creating each document - 'status': Check the current status of an approval request - 'delete': Clean up completed, rejected, or needs-revision approval requests (cannot delete pending requests) CRITICAL: Only provide filePath parameter for requests - the dashboard reads files directly. Never include document content. Wait for user to review and approve before continuing.`, inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['request', 'status', 'delete'], description: 'The action to perform: request, status, or delete' }, projectPath: { type: 'string', description: 'Absolute path to the project root (optional - uses server context path if not provided)' }, approvalId: { type: 'string', description: 'The ID of the approval request (required for status and delete actions)' }, title: { type: 'string', description: 'Brief title describing what needs approval (required for request action)' }, filePath: { type: 'string', description: 'Path to the file that needs approval, relative to project root (required for request action)' }, type: { type: 'string', enum: ['document', 'action'], description: 'Type of approval request - "document" for content approval, "action" for action approval (required for request)' }, category: { type: 'string', enum: ['spec', 'steering'], description: 'Category of the approval request - "spec" for specifications, "steering" for steering documents (required for request)' }, categoryName: { type: 'string', description: 'Name of the spec or "steering" for steering documents (required for request)' } }, required: ['action'] } };
- src/tools/index.ts:9-17 (registration)Registration of the approvals tool in the central tools registry.export function registerTools(): Tool[] { return [ specWorkflowGuideTool, steeringGuideTool, specStatusTool, approvalsTool, logImplementationTool ]; }
- src/tools/approvals.ts:131-140 (handler)Dispatch within the main approvalsHandler to the specific get approval status handler.if (isStatusApproval(typedArgs)) { // Validate required fields for status if (!args.approvalId) { return { success: false, message: 'Missing required field for status action. Required: approvalId' }; } return handleGetApprovalStatus(typedArgs, context); }
- src/tools/approvals.ts:74-78 (schema)Type definition for arguments specific to the status action (get-approval-status).type StatusApprovalArgs = { action: 'status'; projectPath?: string; approvalId: string; };