Get startedCLIAPIMCPWebDesktopAgentsSupportBillingChangelog
Agents · Concepts

Signed-agent inheritance

Every Agent has a required ownerUserId. That link is the accountability substrate: any workspace the owner has membership on, the signed agent inherits at the owner's role. Cross-org included.

Why

Without inheritance, every agent would need its own explicit WorkspaceMember row on every workspace it touches. For an agent serving its owner across 50 workspaces, that's 50 admin operations. Inheritance means: trust the owner, the agent's access follows.

Inversely, when the owner loses access (removed from workspace, removed from org), every agent owned by that user loses access at the same instant — atomic cascade.

Discovery

At LIST time, the agent sees every workspace its owner has access to. No auto-enrollment yet — the agent hasn't written. You can call GET /api/workspaces as the agent and see the full union.

Auto-enrollment on first write

On the agent's FIRST write to a workspace it doesn't already have a membership on:

  1. The system checks: does the agent's owner have access here?
  2. If yes: a WorkspaceMember row is created for the agent with the same role as the owner's effective role (inherited from owner's WorkspaceMember row OR org membership).
  3. The write proceeds.
  4. From that point, attribution points at the AGENT, not the owner. The agent is now a real member.

Cross-org IS the design

If Govind invites Mike (a member of OrgB) to a workspace in Govind's org, Mike's agents in OrgB inherit access to that workspace at Mike's role. The trust substrate is the OWNER, not the agent'sorgId.

Govind extended trust to Mike. Trusting Mike means trusting Mike's tools — which Mike, not Govind, manages. Govind manages Mike: remove Mike, the agents follow.

What inheritance does NOT span

Inheritance covers explicit WorkspaceMember rows held by the owner. It does NOT extend org-visibility (the "virtual editor" access on visibility: org workspaces) cross-org.

An agent in OrgA doesn't get virtual editor on OrgB workspaces just because its owner happens to be in both. Cross-org access only flows through explicit WorkspaceMember rows.

Cascade contract

When a user is removed from a workspace OR has their role changed, the cascade in PATCH/DELETE /api/workspaces/[slug]/members/[memberId] updates every agent owned by that user on the same workspace. Atomic in a transaction so the manager UI never sees a window where the user's access has been revoked but the agents linger.

Same for org-level removal: every agent owned by the removed user loses access to every workspace in the org where they were enrolled via inheritance.

How to audit

  • GET /api/workspaces/:slug/members shows every member, including auto-enrolled agents, with the owner attribution visible.
  • The events log shows member.auto_enrolled when an agent gets implicitly added.
  • Every write attributes to the agent's id, with the owner's id available in the event payload for downstream analysis.