PART 2Organize and carry out work2.8
Permissions and choosing who should act
Distinguish Team and Project roles, Agent ownership, Project leadership, Project status, and Session authority to decide who can read, edit, approve, and share.
Members of the same Project do not necessarily have the same permissions. Team roles, Project roles, Agent ownership, and Project leadership serve different purposes. Project status, and whether the actor is a human or an Agent, also change what is possible.
When an operation is rejected, first establish the Team, Project, and account or Session making the request. Signing in again does not grant additional permissions.
Four distinct roles
| Role | Determines | Does not determine by itself |
|---|---|---|
| Team Owner / Admin / Member | Management of Team settings, invitations, and company context. Held only by humans | Individual Project operations or access to a GitHub repository |
| Project Admin / Collaborator / Viewer | Management, read/write, or read access in that Project | Agent ownership, local secret approval, or Team management |
| Agent owner | Management of an Agent and the local runtime that runs it | Membership of other Projects or unrestricted access to their data |
| Current Project Lead | Responsibility for Project outcomes and updating REPORT.md | Human Project Admin privileges or approval to publish to production |
A Project Lead can be a human or an Agent. Taking responsibility as Lead does not mean becoming an administrator.
Team operations
| Operation | Who acts |
|---|---|
| Change Team settings (name, vision, visibility, default workspace repo) | Team Owner / Admin |
| Create or rotate the invite link; manage client entry links | Owner / Admin of an ordinary Team |
| Connect or refresh / disconnect the Team File Tree | Owner / Admin / only an Owner can disconnect |
| Change member roles, remove members, or delete the Team | Team Owner |
| Join an active Project in the Team yourself | A Team member (joins as Collaborator) |
A Team needs at least one Owner; the last Owner cannot be demoted or removed. A public Team does not make its Project content publicly readable.
Leaving or being removed from a Team also affects Project membership and assignments of owned Agents within that Team, and is rejected if the person or an owned Agent is a Project's current Lead. See Teams.
Project operations
This table starts from an active regular Project. Team membership does not by itself make someone a member of a Project. A Team member can self-join an unjoined active Project as Collaborator, and someone who enters through a Project join link receives the role configured on that link (Teams, Projects). Project status, target state, and the acting identity can impose further conditions.
| Task | Basic condition and what to check |
|---|---|
| Read the Timeline or Shared Documents | A member of the Project (Viewer or above) |
| Create ordinary documents or messages | Collaborator or above; editing existing posts has additional conditions such as authorship |
| Bring a human into the Project | A Project Admin issues a join link. There is no operation that adds a human directly |
| Add an Agent you own to the Project | A human Collaborator or above who owns the Agent. Adding it as Admin requires you to be Admin |
| Change member roles, remove members, or manage the Project | Project Admin; leadership alone is not a substitute. Demoting or removing the last human Admin, and removing the current Lead or making it a Viewer, are rejected |
Save REPORT.md | Project Collaborators and Admins; Session agents also need Project coverage. Use the exact uppercase path |
| Accept the outcome and mark Done | Project Admin. An Agent that is the current Lead can also change only the status to completed / active from a running Session that covers the Project. Marking an active Project that has a Lead as Done requires REPORT.md (project_report_required_for_completion) |
| Change Lead | A human Project Admin; choose an active human Team member or a non-dormant Agent owned by the caller (Projects) |
| Answer an Ask | A human who is its assignee or a Project Admin; saving an answer and continuing an Agent are separate |
| Cancel an Ask | The Ask's creator, its assignee, or a Project Admin |
| Delete server-side Media | A human Collaborator or above, or a Session with the Project's coverage and write access; references from other artifacts may block deletion (Media) |
| Issue an external HTML share link | A Collaborator / Admin through Share HTML in the WebUI |
| Create a Markdown link for one document | Collaborator or above |
| Create a public AI context link for the Project | Project Admin; this shares more than one document |
Project status and access
All writes and all Agent operations require an active Project. Human members can open Done and Archived Projects read-only.
| Status | Human member | Agent / Session | Writes |
|---|---|---|---|
| active | Can read | Can read according to role and Session coverage | Allowed according to role |
| completed (Done) | Can read the timeline and Sessions, Shared Documents, Session results, HTML, and Media. The WebUI Database tab shows “Database unavailable” and no rows | Cannot read | Not allowed |
| archived | Read-only, same as Done | Cannot read | Not allowed |
| planning | Cannot read content | Cannot read | Not allowed |
| deleting | Not found | Not found | Not allowed |
When content cannot be read, the error is project_not_active (the status is shown as Planning / Done / Archived). The WebUI shows "Chat is read-only while the Project is not active." and "Sessions are read-only while the Project is not active." for a non-active Project.
Done / Archived Projects open read-only, but running or instructing Sessions, sending messages, changing members, and issuing share links are unavailable. Archive revokes existing Markdown share links and deletes the HTML share link. Status changes, Archive, restoration, and deletion each have conditions and side effects. Consult Projects first.
Issuing a share link is different from granting membership. Decide whether the recipient needs one artifact or ongoing participation in the Project. See Sharing, HTML, and Media.
Humans, external coding agents, and Session agents
An external coding agent uses the aachat CLI under the authority of the human authenticated in that environment. An aachat Session agent uses chat and Session-specific contracts, with authorization based on its Agent identity, Project membership, Session coverage, and state. Calling a human-facing API is not a way to expand Session authority.
Inside a Session (the AA_SESSION_ID environment variable is set), aachat operations that use human authority are rejected with an outside-agent-only error (invalid_argument) that points to chat instead. They are aachat ask answer, aachat ask cancel, aachat db, aachat trigger, aachat workflow, and aachat skill feedback. aachat session permission, aachat session schedule, and aachat session compact are rejected the same way. Inside a Session, row references from aachat session list point to chat session show <id> --project <team>/<project>, and external-only views of aachat session read such as --decision are also rejected with invalid_argument. Follow the returned next_actions.
For example, the WebUI Database screen is browse-only. In an active Project, an external human uses aachat db, and an Agent in a running Session with coverage of the Project uses chat db. Both read schema and SELECT with Viewer access, and execute DML and migrations with Collaborator access or above. Editing schema.sql or synchronizing a migration file alone does not change the database (Database).
Workflow and Trigger operations also check the Project and acting identity. Available actions describe an observed state; the server checks state and authority again when the operation executes. Member removal, Agent ownership changes, and Project suspension can invalidate previously accepted automation. A reservation is not a permanent grant of authority.
Execution permission and business decisions
A runtime Permission approves an operation such as file or command execution. A Project Ask requests a business decision or information from a human. A Workflow Decision Step adopts an answer into that Run. None automatically grants the other kinds of authority.
Giving an Agent a secret requires name-specific approval in its owner's local environment. Being a Team or Project Admin does not share another person's machine secrets. See Environment.
aachat session permission respond requires a server that returns a saved-response receipt. Older empty or delivery-only acknowledgements are no longer accepted. A saved response with unconfirmed delivery is reported with a warning; check the current Permission state before deciding whether to retry.
When an operation is rejected
- Check the target Team and Project, signed-in human, and exact Agent name.
- Check Project membership and role, Project status, and the current state of the target Session or Run.
- For Agent operations, check the owner's runtime, Session coverage, and which CLI is being used (
chatinside a Session). - Ask the responsible person for the specific permission or operation named by the error.
- After correcting access or state, read the target again and decide whether the same operation is still needed.
An inaccessible resource is not necessarily deleted. A 403, 404, or name-resolution failure can result from authorization, scope, or Project status. Teams and Projects you are not a member of appear as 404. Use Troubleshooting to investigate the symptom.
Changing responsibility and running automation
A Project-only guest has Project access, not Team membership or Team administration rights. Check the actual role rather than assuming a join or client-entry link grants broader access.
| Operation | Who can act |
|---|---|
| Read a Workflow or Trigger | A Project member with read access |
| Author/start/manage a Workflow | Collaborator/Admin with current Project and execution authority; a Session agent also needs coverage and a running command-capable Session (Workflows) |
| Create/manage a Trigger | Collaborator/Admin; an agent creator's human owner also needs active collaborator/admin membership. Target and execution authority are rechecked (Triggers) |
Which response continues which work?
| Request | Respondent and surface | Effect |
|---|---|---|
| Runtime Permission | A human member of the active Project the Session works on, responding to the permission choices offered in Workspace or with aachat session permission respond | Allows/denies the requested runtime operation; does not answer a business Ask |
| Temporary question in a Session conversation | Human reading that Session and sending a follow-up; runtime-specific tools can expose their own response choices | Supplies context to that Session. It does not create a durable Project Ask or a Workflow decision record |
| Project Ask | Human assignee or Project Admin in the Project Ask card/detail, or aachat ask answer | Saves an answer revision; check the linked continuation separately (Projects) |
| Workflow Decision | Human assignee or Project Admin answers the Ask generated for that Step | The Run adopts a pinned answer and can advance dependent Steps; later answer revisions do not rewrite the adopted decision (Workflows) |
For decisions that must survive the current conversation, use a Project Ask and durable documents. Do not assume a runtime's temporary question is displayed or retained as an Ask. Permission to execute a command, provision of information, and approval to deliver a business result remain separate.