feat(agents): grants — the per-agent credential attach surface

[guyb1]

What

Aligns the CLI with the server's attach model: per-agent access is now written as grants — attach an app connection or secret to an agent, optionally naming per-tool --allow / --ask lists — replacing secret modes, assignment lists, and project-scope policy rules.

New surface

onecli agents grants list --id X
onecli agents grants attach-connection --id X --connection-id Y [--allow t1,t2] [--ask t3] [--json '{...}'] [--dry-run]
onecli agents grants detach-connection --id X --connection-id Y
onecli agents grants attach-secret --id X --secret-id Z
onecli agents grants detach-secret --id X --secret-id Z
onecli apps connections grants --id Y          # reverse view (intent)
onecli agents list --with-grants               # grants summary per agent

• Bare attach = full access; --allow/--ask derive a custom grant (--json takes the raw wire body, XOR with the flags).
• Custom grants always send both arrays on the wire (the server schema rejects null); the secret attach is a no-body PUT; detaches handle the bare 204.
• Grants are attach intent — agents credentials / apps connections agent-access stay the effective views with organization guardrails applied.

Retirement pass

Every retired family now says RETIRED in every help surface, each pointing at its replacement: the legacy rules / org rules families, org settings, agents secrets|set-secrets|set-secret-mode|granular-access|connections, and all project-scope policy writes (project rules are compiled from grants on updated servers). The commands keep calling — pre-cutover self-hosted servers still serve them — and the 410 action hint now splits project (grants) from org (org policy).

Tests

• internal/api/grants_test.go: table-driven httptest coverage — canonical paths, exact wire bodies (incl. the non-empty-array pin), the no-body PUT, 204 handling, X-Project-Id, 422 message passthrough.
• cmd/onecli/grants_test.go: the flag→body derivation matrix.
• cmd/onecli/help_test.go (first-ever coverage of help.go): a two-direction drift test pinning the hand-maintained onecli help list to the live Kong tree, plus RETIRED-marker parity between the two help surfaces. It caught real drift on its first run.

Server dependency

The grants API is live on OneCLI Cloud today (shipped via onecli/onecli-cloud#743 and the preceding attach-model PRs). OSS servers gain the surface with the next OSS sync — until then the new commands 404 against OSS builds, and the retired commands still work there.

Siblings: SDK onecli/node-sdk#56 · docs onecli/onecli-docs#11 (docs merges last).

Review

Full /review-change: hunk-by-hunk self-review, a 36-skill walk (10 applied: agent-first-cli, golang-patterns, golang-pro, typescript-pro, typescript-advanced-types, cloud-development, sync-app-docs, seo-audit, ai-artifact-review, find-skills), a field-by-field cross-repo contract check against the live routes, and an adversarial sweep. CLI-side fixes from review: two help pointers corrected (org policy default set --action).

Gates: go build · go test ./... · -race · golangci-lint (0 issues) · gofmt — all green.

Follow-ups (not this PR)

• Widen the remaining agent commands from do() to doProject (X-Project-Id for project keys everywhere).
• cmd/onecli/skill_gateway_fallback.md's 409 section lands in lockstep with the cloud-served /v1/skill/gateway copy.
• Eventual deletion of the retired families once pre-cutover servers age out.

🤖 Generated with Claude Code