{"record":{"id":"9737cc51ac26ae09","repo":"paperclipai/paperclip","slug":"approval-required","errorCode":"approval_required","errorMessage":"Tool action requires approval","messagePattern":"Tool action requires approval","errorType":"http","errorClass":"ToolGatewayHttpError","httpStatus":409,"severity":"error","filePath":"server/src/services/tool-gateway.ts","lineNumber":2145,"sourceCode":"  ): Promise<string> {\n    const [issue] = await db\n      .select({ identifier: issues.identifier })\n      .from(issues)\n      .where(eq(issues.id, issueId))\n      .limit(1);\n    const task = issue?.identifier ?? issueId;\n    return `A human approval card was posted on task ${task}. Do not retry this call now. Wrap up other work and end your run noting you are waiting on tool approval (status in_review). You will be woken when it is decided; if approved, the action runs automatically and your wake includes the result.`;\n  }\n\n  async function throwApprovalRequired(input: {\n    invocationId: string;\n    actionRequestId: string;\n    interactionId?: string | null;\n    issueId: string;\n    toolName: string;\n    argumentsHash: string;\n  }): Promise<never> {\n    throw new ToolGatewayHttpError(\n      409,\n      \"Tool action requires approval\",\n      \"approval_required\",\n      {\n        invocationId: input.invocationId,\n        actionRequestId: input.actionRequestId,\n        interactionId: input.interactionId ?? null,\n        issueId: input.issueId,\n        tool: input.toolName,\n        argumentsHash: input.argumentsHash,\n        instructions: await approvalRequiredInstructions(input.issueId),\n      },\n    );\n  }\n\n  async function requestApprovalForRecordedToolCall(input: {\n    invocation: typeof toolInvocations.$inferSelect;\n    actionRequest: typeof toolActionRequests.$inferSelect | null;","sourceCodeStart":2127,"sourceCodeEnd":2163,"githubUrl":"https://github.com/paperclipai/paperclip/blob/3f1d897a7c018d76563a21c6e39c3c9b03933622/server/src/services/tool-gateway.ts#L2127-L2163","documentation":"Approval-required flow: this helper builds the agent-facing instruction text returned with the 409/deferral when a governed tool call needs human approval. It resolves the issue identifier (falling back to the raw issueId) so the agent knows which task's approval card to wait on and to end its run in_review instead of retrying.","triggerScenarios":"Thrown at server/src/services/tool-gateway.ts:1483 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Request approval for the tool action (create an approval request) and wait for board approval before executing."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"3f1d897a7c018d76563a21c6e39c3c9b03933622","analyzedAt":"2026-09-18T08:03:59.046Z","contentChangedAt":"2026-09-18T08:03:59.046Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}