68 lines
4.3 KiB
Markdown
68 lines
4.3 KiB
Markdown
---
|
|
title: "Split direct and delegation authority for Pods"
|
|
state: "closed"
|
|
created_at: "2026-06-08T01:04:42Z"
|
|
updated_at: "2026-06-08T06:43:52Z"
|
|
queued_by: "workspace-panel"
|
|
queued_at: "2026-06-08T05:45:43Z"
|
|
---
|
|
|
|
## Background
|
|
|
|
Orchestrator currently needs enough authority to delegate write scope to Coder Pods, because `SpawnPod` requires child scope to be a subset of the parent Pod's effective write scope. After project profiles were adjusted to make non-coder roles read-only by default, `project:orchestrator` became read-only and could no longer spawn Coder Pods with write scope.
|
|
|
|
Observed active metadata for `yoi-orchestrator` showed only read scope:
|
|
|
|
```json
|
|
"scope": {
|
|
"allow": [
|
|
{ "permission": "read", "target": "/home/hare/Projects/yoi", "recursive": true }
|
|
]
|
|
}
|
|
```
|
|
|
|
The immediate workaround was to edit the Pod metadata under the user data `pods/` directory to grant the Orchestrator write authority. That is not a good long-term boundary.
|
|
|
|
The design issue is that Orchestrator may need *delegation authority* to give a child Coder a bounded write scope, while not necessarily needing broad direct write authority for its own tool calls. Today those two concepts are conflated in the same effective write scope.
|
|
|
|
## Goal
|
|
|
|
Separate a Pod's direct tool/write authority from its authority to delegate scoped write permissions to child Pods.
|
|
|
|
## Requirements
|
|
|
|
- Model direct filesystem/tool authority separately from delegation authority.
|
|
- Direct authority: what the Pod itself may do with tools such as Bash/Edit/Write/Ticket tools.
|
|
- Delegation authority: what scope the Pod may grant to child Pods through `SpawnPod`.
|
|
- Allow Orchestrator-like roles to delegate bounded child write scopes without necessarily granting themselves arbitrary direct workspace write tools.
|
|
- Preserve safety invariant that delegated child scope must be authorized by an explicit parent grant; do not allow arbitrary escalation.
|
|
- Ensure explicit denies still apply correctly to both direct and delegated permissions.
|
|
- Make the relationship between Profile scope, resolved Manifest scope, and delegation scope explicit and inspectable.
|
|
- Update `SpawnPod` preflight/policy to validate against delegation grants rather than only direct effective write scope if the split is implemented.
|
|
- Update profile authoring guidance so role profiles can express patterns such as:
|
|
- Companion: direct read, no write delegation.
|
|
- Intake/Reviewer: direct read, no write delegation by default.
|
|
- Orchestrator: limited direct writes for Ticket/project records if needed, plus delegation authority for child worktrees.
|
|
- Coder: direct write only within delegated worktree, no further delegation unless explicitly granted.
|
|
- Avoid requiring users to hand-edit `~/.yoi/pods/<name>/metadata.json` to repair Orchestrator delegation authority.
|
|
- Provide diagnostics when a Pod cannot spawn a child due to missing delegation authority, distinguishing it from missing direct write authority.
|
|
|
|
## Design questions
|
|
|
|
- Should delegation authority be represented as a separate `scope.delegate` / `scope.grant` section in Manifest/Profile resolution?
|
|
- Should delegation grants be path-scoped independently from direct grants?
|
|
- Should Ticket role launcher supply Orchestrator delegation grants based on workspace/worktree policy rather than broad workspace write?
|
|
- How should restored older Pod metadata without delegation grants behave?
|
|
- Should direct Ticket tool authority be separated from filesystem write authority in the same change, or remain a separate host-authority concern?
|
|
|
|
## Acceptance criteria
|
|
|
|
- Orchestrator can spawn a Coder with write scope to a child worktree without necessarily having broad direct write access to the whole workspace.
|
|
- A Pod without delegation authority cannot grant write scope even if it has read access.
|
|
- A Pod with direct write but no delegation grant cannot spawn write-capable children unless explicitly allowed.
|
|
- Diagnostics distinguish direct permission denial from delegation-authority denial.
|
|
- Profiles/manifests can express at least the Companion/Intake/Orchestrator/Coder/Reviewer patterns above.
|
|
- Tests cover delegation validation, deny handling, restoration/metadata behavior, and SpawnPod error messages.
|
|
- Relevant docs/profile examples are updated.
|
|
- Focused tests, `cargo fmt --check`, `git diff --check`, and `target/debug/yoi ticket doctor` pass.
|