{"record":{"id":"89778d4e7ef7742e","repo":"paperclipai/paperclip","slug":"agent-key-belongs-to-agent-name-agent-id","errorCode":null,"errorMessage":"Agent key belongs to ${agent.name} (${agent.id}), not '${reference}'. Use the matching agent or a board prompt.","messagePattern":"Agent key belongs to (.+?) \\((.+?)\\), not '(.+?)'\\. Use the matching agent or a board prompt\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"cli/src/commands/client/prompt.ts","lineNumber":257,"sourceCode":"  if (!normalized) throw new Error(\"Prompt text is required\");\n  return normalized;\n}\n\nfunction defaultPromptTitle(prompt: string): string {\n  const firstLine = prompt.split(/\\r?\\n/).map((line) => line.trim()).find(Boolean) ?? \"Prompt handoff\";\n  return firstLine.length > 100 ? `${firstLine.slice(0, 97)}...` : firstLine;\n}\n\nfunction assertAgentMatchesReference(agent: Agent, reference: string): void {\n  const normalized = reference.trim().toLowerCase();\n  if (!normalized) throw new Error(\"Agent reference is required\");\n  const matches = [\n    agent.id,\n    agent.name,\n    typeof agent.urlKey === \"string\" ? agent.urlKey : null,\n  ].some((value) => value?.toLowerCase() === normalized);\n  if (!matches) {\n    throw new Error(\n      `Agent key belongs to ${agent.name} (${agent.id}), not '${reference}'. Use the matching agent or a board prompt.`,\n    );\n  }\n}\n\nfunction agentSummary(agent: Agent): PromptResult[\"agent\"] {\n  return {\n    id: agent.id,\n    name: agent.name,\n    urlKey: typeof agent.urlKey === \"string\" ? agent.urlKey : null,\n  };\n}\n\nfunction readApiKeyEnvOption(opts: PromptOptions): string | undefined {\n  if (!opts.apiKeyEnv?.trim()) return undefined;\n  const value = process.env[opts.apiKeyEnv.trim()]?.trim();\n  if (!value) throw new Error(`Environment variable ${opts.apiKeyEnv.trim()} is not set`);\n  return value;","sourceCodeStart":239,"sourceCodeEnd":275,"githubUrl":"https://github.com/paperclipai/paperclip/blob/67001ec6eb96ae601aa27bc91d9b2415d665334a/cli/src/commands/client/prompt.ts#L239-L275","documentation":"`assertAgentMatchesReference` compares the authenticated agent (`me` from `/api/agents/me`) against the requested reference by matching `me.id`, `me.name`, or `me.urlKey` (case-insensitive). If none match, it throws, naming the key's true owner. This prevents using one agent's API key to impersonate or target a different agent in an agent-prompt (which must be self-directed).","triggerScenarios":"Authenticating as agent A (via `--api-key` or profile env) but passing `--agent agentB` (or a profile.agentId pointing at agentB) to `agent-prompt`/`agent prompt`. The key owner and the requested target disagree.","commonSituations":"Reusing a shared CI key across multiple agents but forgetting to update the `--agent` ref; profile.agentId stale after the agent identity changed; copy-pasting an agent ref from one context into a command run with another agent's key.","solutions":["Use an agent prompt without `--agent` so it targets the authenticated agent (`me.id`)","Provide the `--agent` ref that matches the API key's owner (id/shortname/url-key of the same agent)","If you need to target a different agent, use `board prompt --agent <ref>` with board credentials instead"],"exampleFix":"# before: key belongs to agent A, targeting agent B\npaperclipai agent prompt --agent agent-b \"do work\"\n# after\npaperclipai agent prompt \"do work\"   # targets the authenticated agent\n# or, to target a different agent:\npaperclipai board prompt --agent agent-b \"do work\"","handlingStrategy":"validation","validationCode":"function agentMatchesRef(agent: { id: string; name: string; urlKey?: string | null }, ref: string): boolean {\n  const n = ref.trim().toLowerCase();\n  if (!n) return false;\n  return [agent.id, agent.name, agent.urlKey].some((v) => typeof v === \"string\" && v.toLowerCase() === n);\n}\nif (!agentMatchesRef(me, expectedRef)) {\n  throw new Error(`Key owner ${me.name} (${me.id}) does not match ref '${expectedRef}'`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["For agent prompts, omit --agent so it self-targets the authenticated agent","Keep one API key per agent and pair it with the matching profile.agentId","Use board prompt (board credentials) to target a different agent"],"tags":["cli","agent","auth","mismatch","validation"],"backgroundTag":null,"analyzedSha":"67001ec6eb96ae601aa27bc91d9b2415d665334a","analyzedAt":"2026-08-12T12:05:45.408Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}