[AGE-4067] docs(agents): Plan custom secret setup and delivery

[mmabrouk]

Context

Users can save custom secrets and select them for HTTP MCP authentication, but cannot attach an arbitrary saved token to an agent's shell or skills. A setup card also needs to carry the user all the way from creating a secret to continuing the same conversation with the saved binding applied.

Changes

This design splits #5703 / AGE-4067 into two milestones. The first delivers explicitly readable text credentials for internal use, with saved environment bindings, backend resolution, runner injection, and one shared select/create/attach flow for settings and an agent request card. Its implementation includes secret-handling guidance in the shared platform module introduced by #6365. The second adds vault-owned host restrictions and hidden Daytona delivery.

After setup, the card reports a saved binding and revision, never a value. The next run resolves that revision and applies its credentials before the harness continues. The plan covers partial saves, revision conflicts, reloads, cancellation, runtime failure, replacement, and removal.

The simplification pass removes a separate apply endpoint, readiness polling, session-only attachment storage, distributed rollback, and a new runtime lifecycle system. It reuses agent revisions, the vault form, client-tool settlement, and supported reopen/rebuild behavior. The tradeoffs are persistent agent-variant bindings, readable process credentials, and possible process restarts between turns.

This is a design-only child of #6365, based directly on its remote head ecb28ea14b. No runtime code or prompt text changes in this PR. References #5703; does not close it.

How to review

1. Read context.md for the milestone boundary, then plan.md for the card-to-resume sequence and interrupted setup.
2. Check contracts.md for ownership, permission checks, proposed shapes, and the required shared guidance.
3. Read simplification.md for the removed machinery and tradeoffs, then qa.md for the implementation acceptance checks. research.md records current code entry points.

Tests

• Checked relative documentation links, whitespace, and absence of em dashes.
• Prettier formatting checked on all eight planning files.
• The published child diff is restricted to docs/design/agent-custom-secrets/ and scanned with gitleaks.
• Runtime tests and live QA have not run; their required coverage is documented for implementation.

The shared GitButler workspace could not preview updating its stale local parent because of a base-merge conflict. Publication uses the documented temporary-index fallback against #6365's remote head. It does not rewrite the parent PR or apply a new local lane.

[linear-code]

AGE-4067

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
agenta-documentation	Ready	Preview	Sep 5, 2026 7:20am UTC

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

🤖 The AI agent says:

The design is ready for review. The two-milestone split and dependency on #6365 follow the agreed scope. Milestone one's implementation includes the shared credential-handling guidance; this draft PR contains the plan only.

Please review plan.md's Complete the request card and resume sequence first. The card settles only after the binding is saved and the host has selected that revision. The next run resolves and applies it before model execution. Partial saves, reloads, cancellation, revision conflicts, and failed resume each have an explicit recovery path.

🔸 Decision needed: the plan recommends these narrower implementation choices:

• Persist bindings on the agent variant, so later runs reuse them. The alternative is session-only attachments, which requires a second configuration lifetime and is deferred.
• Require existing secret-edit and agent-edit permissions when attaching a readable secret. The alternative is a new secret-use permission, which adds RBAC scope to this internal version.
• Allow a supported reopen/rebuild between turns when environment values cannot update live. Preserve the conversation and durable files, but accept loss of transient process state. Live environment patching remains a later optimization.

simplification.md explains why the plan uses existing vault forms, agent revisions, client-tool settlement, and runtime reconciliation without a new apply endpoint, readiness poll, or attachment store.

The exact eight-file child diff passes formatting, link/whitespace checks, and gitleaks. Runtime validation is specified in qa.md and has not run for this design-only PR.