Agent-scoped permissions so spawned agents don't need the workspace key

[khaliqgant]

Goal

Agents spawned by the relay broker should be able to do their job with their own agent token only. Today the broker also delegates the workspace key to every worker, in the worker environment and in each harness's MCP config, because a few endpoints the relay MCP tools call accept only the workspace key. The workspace key grants workspace-admin rights, so agents should not need it (least privilege).

Where agents need the workspace key today

relay MCP tool	Endpoint	Agent token accepted?
spawn	POST /v1/actions/spawn/invoke	Yes
list_agents	GET /v1/agents	No (allowAgent: false)
query_nodes	GET /v1/nodes	Workspace read: verify
add_agent / register_agent	POST /v1/agents	No, workspace key only
remove_agent	DELETE /v1/agents/:name	No, workspace key only
get_observer_url	POST /v1/observer-tokens	No, workspace key only

(create_workspace / set_workspace_key are human setup tools; spawned agents don't need them.)

Proposal

1. Agent-readable roster and nodes (engine): allow agent tokens on GET /v1/agents, GET /v1/agents/:name and GET /v1/nodes, read-only. Small and independent.
2. Ownership for team management (engine): record spawned_by at spawn. An agent may release or remove only agents it spawned, which covers the lead/worker pattern.
3. Keep workspace-key only: registering arbitrary identities, workspace deletion, webhooks, observer tokens, directory writes, node enrollment. MCP tools should say plainly that these need a workspace key rather than fail silently.
4. relay (follow-up): the MCP uses the agent token for everything, falling back while older engines exist. The broker then stops injecting the workspace key into worker env and harness MCP configs, gated on the engine version, only after 1–3 ship.

Open questions

• Do other MCP tools depend on the workspace key (e.g. channel creation)?
• How does packages/mcp authenticate?
• Does cloud orchestration rely on agents holding the workspace key?

Related

• fix(broker): scope credentials passed to spawned workers relay#1854 removes the broker's own credentials from workers. Workspace credentials are intentionally still delegated there; this issue is what removes that need.

🤖 Generated with Claude Code