docs: correct agent permission-model framing to match shipped D10

[os-zhuang]

Documentation accuracy pass after the ADR-0090 D10 agent work shipped this session (#2838 / #2843 / #2845). The agent docs still described the old model — "runs as you / consent scopes narrow which tool families" — which is now inaccurate.

What changed and why

An OAuth-connected MCP client is now an agent acting on behalf of the signing-in user, resolved to principalKind:'agent' + onBehalfOf. Every call is bounded by the intersection of a scope-derived ceiling and the user's own permissions/RLS — it can never exceed either. Consent scopes are a real data-layer ceiling, not just a tool-family filter (a data:read token can never write a record, even where the user could).

• packages/mcp/src/skill.ts (the SKILL.md served at GET /api/v1/mcp/skill — downloaded by every connecting agent): "every operation runs as you" → the intersection framing + the read-only-scope-can't-write caveat.
• content/docs/ai/agents.mdx (user-facing): same correction to the OAuth track.
• docs/design/permission-model.md — the "declared ≠ delivered" reconciliation:
  • the agent overlap rule is marked enforced (the evaluator intersects at every layer; the producer resolves the agent principal — feat(security): ADR-0090 D10 — agent/service intersection runtime #2838/feat(security): ADR-0090 D10 — activate agent principal (OAuth → scope ceiling) #2843/feat(security): ADR-0090 D10 — delegate action capabilities to MCP agents #2845);
  • the three agent guardrails are honestly marked: Ceiling (the runtime intersection caps it today; the dedicated bind-time lint is planned, Security: MCP action surface must gate on ai.exposed — action bodies run trusted (unbounded RLS/FLS), so invoke-time is the only agent boundary (#2849) #2849), human co-sign (planned), and double-signature audit (planned — the writer stamps only the delegating user; agent provenance is not yet captured).
• docs/adr/0090 — a status note that D10 evaluation semantics have landed.

Notes

Pure docs + the served SKILL.md string. The permission-model.md change is the honest counterpart to the D11 liveness discipline — it stops the design doc from over-claiming agent guardrails that are still on the roadmap while under-claiming the intersection that now ships.

@objectstack/mcp suite 66 green.

🤖 Generated with Claude Code

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jul 12, 2026 1:03pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/mcp.

9 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/ai/actions-as-tools.mdx(via @objectstack/mcp)
• content/docs/ai/agents.mdx(via @objectstack/mcp)
• content/docs/ai/index.mdx(via @objectstack/mcp)
• content/docs/ai/natural-language-queries.mdx(via @objectstack/mcp)
• content/docs/api/index.mdx(via @objectstack/mcp)
• content/docs/deployment/environment-variables.mdx(via @objectstack/mcp)
• content/docs/plugins/packages.mdx(via @objectstack/mcp)
• content/docs/protocol/knowledge.mdx(via @objectstack/mcp)
• content/docs/releases/implementation-status.mdx(via @objectstack/mcp)

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.