Several agents at once
A project record is shared state. Two agents on the same project should be able to work without quietly overwriting each other, and a human should always be able to see which one did what.
Everything is attributed
Every read and write is recorded against the token that made it, with a human-readable target like update.create · "Cutover rehearsal passed". One token per agent means you can tell them apart in the log and revoke one without disturbing the rest.
What a token can reach
| One project | Minted from a project's own Agents tab. Reaches that project and nothing else: it cannot read the workspace's other projects, and cannot create a new one to work around the limit. |
| Binds to its first project | What New project hands out. The project does not exist yet — the agent is about to create it — so instead of staying open, the token closes around whichever project it touches first and is a single-project token from then on. |
| Whole workspace | Minted from Agents & MCP. Reaches every project, including ones created later. Right for an agent that genuinely works across a portfolio; more than most agents need. |
Single-project tokens are what let a collaborator connect their own agent to a project inside someone else's workspace: their agent sees the project they were given, and the rest of the workspace stays private. project_list tells an agent exactly what its token reaches, which is the right first call when it does not know.
A workspace-wide token can be narrowed later without being replaced. On a project's Agents tab, Limit to this project confines it in place — the token string does not change, so nothing has to be reconnected. Each token also shows which projects it has actually been used on, which is usually enough to tell you what to narrow it to.
Stale writes are refused, not applied
Purpose, architecture, roadmap and theme are read-modify-write: an agent resumes, merges its change into what it read, and writes the whole section back. With two agents working, that silently loses whichever wrote first.
So those four calls accept ifRevision — the project.revision you saw when you resumed:
project_resume { project: "warehouse-migration" }
→ project.revision is 12
architecture_set {
project: "warehouse-migration",
conventions: [...],
ifRevision: 12
}If someone wrote in between, the call is refused rather than applied:
The project moved on while you were working: you resumed at revision 12, it is now 14. Call project_resume on "warehouse-migration" again, merge your change into what is there now, and retry.
Recover by resuming, merging into what is there now, and retrying. Omitting ifRevision keeps the single-agent case exactly as it was, so it costs nothing to pass when you are working alone.
Which writes need it
| Needs ifRevision | Does not |
|---|---|
purpose_set, architecture_set, roadmap_set, theme_set | update_create, feature_upsert, task_upsert, feedback_reply |
| They replace a whole section | They append, or address one keyed row |
Working alongside another agent
- Resume at the start of every session. Another agent may have changed the architecture or settled a decision since you last looked.
- Read the decisions before proposing something. If one covers the ground, follow it or argue with it explicitly — do not silently do the opposite.
- Trust recent verification. If
architecture.verifiedByshows another agent checked it recently, build on it rather than rewriting from scratch. - Reuse keys. Check
task_listbefore creating a task. Inventing a parallel key for work that already exists is the easiest way to make a mess someone has to tidy.
Undoing a bad write
Every write snapshots what the section held beforehand, so nothing an agent does is one-way. In the workspace, features, tasks, project details and purpose are all editable and deletable by hand — an agent getting something wrong is a correction, not an incident.