{"record":{"id":"8001f7d2bfb9256c","repo":"paperclipai/paperclip","slug":"agent-context-required","errorCode":"agent_context_required","errorMessage":"Paperclip self tools require an agent-scoped gateway session","messagePattern":"Paperclip self tools require an agent-scoped gateway session","errorType":"http","errorClass":"ToolGatewayHttpError","httpStatus":403,"severity":"error","filePath":"server/src/services/tool-gateway.ts","lineNumber":2118,"sourceCode":"              allowStandingDelegation: false, excludeGrantId: original.id,\n            });\n            const accountId = original.providerTenant?.github?.userId;\n            if (!accountId || !alternate.grant\n              || alternate.grant.providerTenant?.github?.userId !== accountId\n              || alternate.grant.subjectUserId !== original.subjectUserId\n              || alternate.grant.subjectAgentId !== original.subjectAgentId) throw error;\n            selected = alternate;\n          }\n        }\n        throw new ToolGatewayHttpError(409, \"GitHub credentials are unavailable\", \"github_identity_unavailable\");\n      }\n    }\n    return tool;\n  }\n\n  function virtualRunToolInput(parameters: unknown): { targetToolName: string; targetParameters: unknown } {\n    const params = asRecord(parameters) ?? {};\n    const targetToolName = typeof params.tool === \"string\" ? params.tool.trim() : \"\";\n    if (!targetToolName) {\n      throw new ToolGatewayHttpError(400, \"run_tool requires a target tool name\", \"invalid_parameters\");\n    }\n    return {\n      targetToolName,\n      targetParameters: params.arguments ?? {},\n    };\n  }\n\n  async function searchableOnDemandTools(session: ToolGatewaySession): Promise<ToolGatewayDescriptor[]> {\n    const tools = (await connectedMcpToolsForCompany(session.companyId)).filter(isOnDemandRemoteTool);\n    const decisions = await Promise.all(tools.map(async (tool) => ({\n      tool,\n      decision: await policyService.decide(policyInputForTool({ session, tool })),\n    })));\n    return decisions\n      .filter(({ decision }) => decision.allowed || decision.decision === \"require_approval\")\n      .map(({ tool }) => tool);","sourceCodeStart":2100,"sourceCodeEnd":2136,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/server/src/services/tool-gateway.ts#L2100-L2136","documentation":"paperclip-self tools (like list_my_issues / get_issue_context) are restricted to agent-identified sessions, but the current gateway session has no agentId (e.g. a user/board-issued token). The 403 agent_context_required fires before any self-tool logic runs because there is no 'self' to scope the query to.","triggerScenarios":"Thrown at server/src/services/tool-gateway.ts:2022 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Use an agent-scoped gateway session (agent API key + run context) to call Paperclip self tools."],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-08-18T22:49:45.177Z","contentChangedAt":"2026-08-18T22:49:45.177Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}