{"record":{"id":"1a2debcf2de9ee10","repo":"paperclipai/paperclip","slug":"pass-acknowledge-retention-to-enable-the-statefu","errorCode":null,"errorMessage":"Pass --acknowledge-retention to enable the stateful beta Managed Agents service","messagePattern":"Pass --acknowledge-retention to enable the stateful beta Managed Agents service","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/src/commands/managed-agent.ts","lineNumber":73,"sourceCode":"    : {};\n}\n\nfunction required(value: string | undefined, label: string): string {\n  const normalized = value?.trim() ?? \"\";\n  if (!normalized) throw new Error(`${label} is required`);\n  return normalized;\n}\n\nexport function validateManagedAgentSetup(\n  options: ManagedAgentSetupOptions,\n  env: NodeJS.ProcessEnv = process.env,\n): ValidatedSetup {\n  const anthropicApiKey = env.ANTHROPIC_API_KEY?.trim();\n  if (!anthropicApiKey) {\n    throw new Error(\"ANTHROPIC_API_KEY is required in the CLI process environment\");\n  }\n  if (!options.acknowledgeRetention) {\n    throw new Error(\n      \"Pass --acknowledge-retention to enable the stateful beta Managed Agents service\",\n    );\n  }\n\n  const profileKey = required(options.profileKey, \"--profile-key\");\n  const displayName = required(options.displayName, \"--display-name\");\n  const apiKeySecretId = required(options.apiKeySecretId, \"--api-key-secret-id\");\n  const model = required(options.model, \"--model\");\n  if (model !== CLAUDE_MANAGED_QUALIFIED_MODEL) {\n    throw new Error(\n      `--model must be the qualified Managed Agents model ${CLAUDE_MANAGED_QUALIFIED_MODEL}`,\n    );\n  }\n  if (!UUID_RE.test(apiKeySecretId)) {\n    throw new Error(\"--api-key-secret-id must be a UUID\");\n  }\n\n  const defaultMaxListCostUsd = Number(options.maxSessionListCostUsd);","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/paperclipai/paperclip/blob/5716fe907e596ce73501408fc6efdb19fb61edf2/cli/src/commands/managed-agent.ts#L55-L91","documentation":"The Managed Agents service is a stateful beta that retains Anthropic-side resources (environments, agents), so the CLI requires an explicit opt-in acknowledgement flag. `validateManagedAgentSetup` throws this when `options.acknowledgeRetention` is falsy. It is a deliberate friction gate, not a malfunction.","triggerScenarios":"Running the managed-agent setup command without `--acknowledge-retention`; passing the flag with no value in a way that resolves to false; calling `validateManagedAgentSetup` programmatically with `acknowledgeRetention` omitted from the options object.","commonSituations":"Copy-pasting an older command example from before the flag existed; wrapping the CLI in a script that builds args dynamically and drops the flag; assuming a `--yes`/`-y` style flag covers it.","solutions":["Add `--acknowledge-retention` to the command line","When invoking validateManagedAgentSetup in code, set acknowledgeRetention: true in the options object","Update wrapper scripts/templates that construct the argument list","Review the retention implications first — the flag exists because Anthropic retains beta resources"],"exampleFix":"// before\npaperclip managed-agent setup --profile-key acme --display-name \"Acme\" --api-key-secret-id <uuid> --model claude-sonnet-5\n// after\npaperclip managed-agent setup --profile-key acme --display-name \"Acme\" --api-key-secret-id <uuid> --model claude-sonnet-5 --acknowledge-retention","handlingStrategy":"validation","validationCode":"const args = [\"managed-agent\", \"setup\", ...];\nif (!opts.acknowledgeRetention) args.push(\"--acknowledge-retention\");\n// or in code:\nif (!options.acknowledgeRetention) throw new Error(\"Refusing to run: retention not acknowledged\");","typeGuard":"function acknowledgesRetention(o: { acknowledgeRetention?: boolean }): o is typeof o & { acknowledgeRetention: true } {\n  return o.acknowledgeRetention === true;\n}","tryCatchPattern":"try {\n  await setupManagedAgent(opts);\n} catch (err) {\n  if (err instanceof Error && err.message.includes(\"--acknowledge-retention\")) {\n    console.error(\"Add --acknowledge-retention after reviewing retention implications\"); process.exitCode = 2;\n  } else throw err;\n}","preventionTips":["Always include --acknowledge-retention in managed-agent command templates","Read the retention implications once and record the decision in team docs","Don't alias the CLI with a wrapper that strips unknown flags","Set the flag explicitly in scripted/CI invocations rather than relying on defaults"],"tags":["cli","input-validation","beta-flag","opt-in"],"backgroundTag":"missing-required-cli-flag","analyzedSha":"5716fe907e596ce73501408fc6efdb19fb61edf2","analyzedAt":"2026-09-02T18:44:00.616Z","contentChangedAt":"2026-09-02T18:44:00.616Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}