Implement initial agents permissions model

[KyleAMathews]

Summary

Implement the 0.1 agents permissions model agreed in the check-in: explicit per-entity grants, private-by-default Desktop sessions, workspace-level sharing, user-delegated spawned agents, and spawn-time grants. Do not rely on external permission webhooks for the first pass.

Specific answer from the discussion

The direction we converged on was:

1. Workspace is the coarse boundary for 0.1

   • If you are outside the workspace, you should not have access.
   • For now, we can tolerate workspace-level rather than per-service roles.
   • Longer-term per-service roles can be a follow-up.

2. Add explicit grants for sessions/entities

   • The missing primitive is an actual grants table/model plus APIs.
   • Permissions should not be just global rules or webhook callbacks.
   • Grants are attached to the specific agent/session/entity.

3. Desktop/Horton-created sessions are private by default

   • If I create a session on my desktop, only I have read/write access initially.
   • Other workspace members should not automatically see or write to it.

4. Sharing is done by writing explicit grants
   Initial grant targets/actions should cover:

   • grant read to a specific user
   • grant read/write to a specific user, e.g. pairing
   • grant read to everyone in the workspace
   • grant read/write to everyone in the workspace, e.g. bot-created shared sessions
   • optionally public/link read access if we decide to include that now

5. Bot/shared sessions can default to workspace grants

   • Sessions started from shared surfaces like Discord/PR-review agents can be created with workspace-wide read/write grants.

6. The spawn API should let the spawner specify initial grants

   • When spawning an agent/session, the caller should be able to provide the grants that should be attached to the spawned entity.
   • This is how shared/bot-created sessions can be created with workspace-wide access from the start.
   • The spawner must not be able to grant permissions they do not themselves have authority to grant.
   • If no grants are specified, use the safe default: creator/spawner read/write only.

7. Spawned agents act on behalf of the spawning user

   • If user Sam spawns an agent, that agent acts as/delegates from Sam.
   • It can use Sam’s permissions but cannot elevate beyond them.
   • Chained agent spawning should preserve this “on behalf of” behavior.
   • Permission narrowing/downgrading can be designed later.

8. Cloud should not expose service secrets to ordinary Desktop users

   • The immediate Cloud need is a restricted role/token path so Desktop users can connect/use the agents service without receiving broad admin/service-secret access.
   • This can be workspace-level for now.

9. Defer permission webhooks

   • Calling webhooks on every durable-stream read/long-poll is too expensive for the first pass.
   • Webhook auth should be a later phase, likely with TTL/caching.

Initial implementation scope

• Add a persistent grants model/table for agent/session/entity access.
• Add APIs to create/list/revoke grants.
• Extend the spawn API to accept initial grants for the spawned agent/session/entity.
• Validate spawn-time grants so the spawner cannot grant access beyond their authority.
• Apply default grants when sessions/entities are created:
  • Desktop/Horton local session: creator/spawner read/write only.
  • Shared/bot-created session: configurable workspace read/write grant, provided at spawn/create time.
• Update read/write permission checks to consult explicit grants.
• Implement user-delegated spawned-agent permission behavior.
• Add the minimal Cloud role/token behavior needed so normal Desktop users do not need service-secret access.

Out of scope for this issue

• Full per-service Cloud roles.
• End-to-end encryption / local-only readable streams.
• External authorization webhooks.
• Webhook TTL/caching implementation.
• Fine-grained permission narrowing for spawned agents.

Acceptance criteria

• A Desktop/Horton session created by a user is private by default.
• The creator/spawner has read/write access.
• Other workspace members cannot read/write the session unless granted.
• The creator can explicitly grant read or read/write access to another user.
• The creator can explicitly grant read or read/write access to the workspace.
• The spawn API accepts initial grants for the spawned entity/session.
• Spawn-time grants are validated against the spawner’s authority.
• Shared/bot-created sessions can be initialized with workspace-wide grants at spawn/create time.
• A user-spawned agent can access what the spawning user can access and cannot access what the user cannot access.
• Normal Desktop users can connect/use the cloud agents service without seeing or using the service secret.
• Tests cover private-by-default sessions, explicit user grants, workspace grants, denied access, spawn-time grants, invalid/escalating spawn-time grants, bot/shared defaults, and spawned-agent delegation.