@elu-labs/elu 0.0.0-stage → 0.1.1

package/docs/peer-network.md

@@ -0,0 +1,257 @@
+# Peer network
+
+How two ELU Code installs find each other, what they send, and how a team keeps its list of
+members. This page is also the A2A custom binding document (A2A v1.0.1 §12 requires one for a
+custom binding). The commands a person types are in the [README](../README.md#teammates).
+
+## What it does
+
+1. Your agents talk to your teammates' agents, machine to machine, with no company server.
+   - **ask:** a question, answered by a read-only run in a project they shared.
+   - **ask a bot:** a question to one teammate can name a bot they share. That bot answers it in place of their model.
+   - **review:** a diff sent for a read-only review.
+   - **pictures:** a message you type to a teammate or a channel takes along the pictures it names. See [Pictures](#pictures).
+   - **handoff:** a goal for their machine. Any message can be answered (read-only) or worked on in a mode the owner picks; work never starts on its own.
+   - **status and overlap:** teammates see each other's live agents and get a warning when two agents edit the same file.
+   - Agents can draft asks themselves. A draft is sent only when you approve it, or automatically to teammates you set to auto.
+2. A2A v1.0 data model end to end. A local A2A JSON-RPC endpoint on 127.0.0.1, off by default, lets other A2A tools reach your agent and, through it, your teammates.
+3. Sessions shows peer items that need you. **Chats** shows channels, teammates, their agents and threads.
+
+Not supported:
+
+- One device per person; no multi-device.
+- Offline catch-up only through the sender's outbox, with no always-on mirror.
+- Handoffs are text goals, not patches.
+- Only pictures travel with a message (PNG, JPEG, GIF, WebP). No other file does.
+- No Windows support.
+- A share grants the whole repository (tracked files minus sensitive ones), not per-path globs.
+
+## Layers
+
+```
+identity    ed25519 key per install (Node crypto), shown as hex + 8-char fingerprint
+roster      per team: signed append-only log of create/admit/remove/role/relays/leave/channel ops
+discovery   each daemon announces its own key on HyperDHT; teammates are dialled by key
+transport   Hyperswarm (Noise IK, UDP holepunch) -> blind relay you run -> outbox retry
+binding     newline-delimited JSON-RPC 2.0 over the Noise stream (this document)
+messages    A2A v1.0 Message/Task/Artifact + extension urn:elu-code:a2a-ext:peer:v1
+channels    team: pairwise A2A tasks + status notifications
+conductor   peer daemon <-> conductor through files only (requests, outbox, commands)
+```
+
+There is no ELU server anywhere. Defaults that touch third parties:
+
+- the HyperDHT bootstrap nodes. HyperDHT's own public nodes are used unless `bootstrap` in `peer/settings.json` names others; the routing table is cached after the first join.
+- other HyperDHT nodes. Announcing the key and dialling a teammate send requests to DHT nodes that anyone may run, and they see this machine's IP address and port.
+  - The daemon's own DHT node is ephemeral: it is never added to other nodes' routing tables, so strangers' lookups, announcements and connections are not routed through it, however long it runs.
+  - A relay you run keeps HyperDHT's default instead: on a reachable server it can join other nodes' routing tables after about 20 minutes and route lookups for anyone.
+
+## Binding: `urn:elu-code:a2a-binding:hyperswarm-ndjson:v1`
+
+- **Transport.** A Hyperswarm connection. Noise IK authenticates both device keys. Each side `listen()`s on its own key pair, and a teammate is dialled with `swarm.joinPeer(key)`.
+- **Framing.** One UTF-8 JSON object per line; a frame may be at most 1 MiB. A larger frame closes the connection.
+- **JSON-RPC 2.0, both directions.** Either side may send requests; responses are matched by `id`. Notifications have no `id`. Requests time out after 30 s.
+- **First frame.** Each side's first frame must be `elu.hello` with params `{binding, a2aVersion: "1.0", name, teams: [{id, seq, head, ops}], handles, plans}`. `plans: true` says this build reads [Tasks](#tasks); a build that does not know a field ignores it. With no valid hello within 5 s, the connection closes.
+  - The hello is written for the receiver's key, which Noise has proved before the first frame. `teams` lists only the sender's teams that this key is an active member of in the sender's log. `name` is the sender's display name when `teams` lists one, and empty otherwise.
+  - `ops` (at most 8 per team) are the roster ops that admit the sender, so a teammate admitted elsewhere can prove it. They are merged only for a key the receiver has never seen in that team.
+  - `handles` (at most 20) are the sender's share handles that the receiver may ask about: the projects shared with a team both machines are on. A teammate admitted by this same exchange gets them on the next connect.
+  - **Service parameters.** A2A-Version travels as `a2aVersion`; any `1.x` is accepted, and another major version closes the connection with a logged reason. The only extension, `urn:elu-code:a2a-ext:peer:v1`, is listed in each `Message.extensions` (A2A-Extensions has no other carrier here).
+- **Admission.** The Hyperswarm firewall admits every key. The application layer then accepts a connection only if:
+  - the remote key is an active member of a team we share; or
+  - its hello carries roster ops that validly extend our log and make it a member; or
+  - it opens with `elu.join` carrying a pending invite.
+
+  Anything else is closed. The decision is logged.
+
+  Before admission, a key on none of this machine's teams (a stranger, someone removed from them, a joiner) is sent only the hello `{binding, a2aVersion, name: "", teams: [], handles: [], plans: true}`: no team, no member and no name. A joiner gets the roster in the reply to `elu.join`. On a direct connection the handshake also shows the other side this machine's IP address and port.
+- **Methods.**
+  - **A2A core:** `SendMessage`, `GetTask`, `CancelTask`. The push-config methods return PushNotificationNotSupported; any other core method returns UnsupportedOperation.
+  - `SendMessage` never blocks: it returns the Task (SUBMITTED, or REJECTED with a reason) at once, whatever `returnImmediately` says. Later states arrive as `elu.taskUpdate` or through `GetTask`.
+  - Unknown fields in A2A objects and params are ignored (A2A §5.7); size limits still apply.
+  - **Extensions:** `elu.hello`, `elu.join` `{teamId, secret, name}`, `elu.roster.get` `{teamId, after}`, `elu.roster.push` `{teamId, ops}`, `elu.picture.put` `{id, seq, last, size, sha256, data}` (see [Pictures](#pictures)).
+  - **Notifications:** `elu.status` `{rows, box, bots: [{name, about}]}`, `elu.plans` `{tasks}` and `elu.taskUpdate` `{task}`. `box` and `bots` are described under [Status](#status), `elu.plans` under [Tasks](#tasks).
+- **Errors.** JSON-RPC error objects; `data` is a list of `google.rpc.ErrorInfo` with `reason` set to the code's name. Messages carry no local paths, unless the caller is a peer I trust (`trusted` in `peers.json`), who gets them as written.
+
+  | code | meaning | the asker |
+  |---|---|---|
+  | -32000 | too many requests (more than 20 in 10 s; more than 40 closes the connection) | retries with backoff |
+  | -32001 | TaskNotFound | marks the ask failed |
+  | -32002 | TaskNotCancelable | stops cancelling |
+  | -32003 | PushNotificationNotSupported | |
+  | -32004 | UnsupportedOperation | marks the ask failed |
+  | -32009 | VersionNotSupported | |
+  | -32602 | invalid params, including every refusal | marks the ask failed |
+  | -32603 | internal error | retries with backoff |
+
+- **Idempotency.** `SendMessage` is idempotent on (sender key, `messageId`). A repeat returns the original Task. The sender stores the server's `taskId` in `asks/` and polls `GetTask` when it reconnects.
+- **Exact names.** JSON field names, enum strings and method names must match A2A v1.0.1 (`specification/a2a.proto` and `docs/specification.md` at tag v1.0.1). `lib/peer/a2a.mjs` cites the section each one comes from.
+
+Extension `urn:elu-code:a2a-ext:peer:v1`:
+
+- It is listed in `Message.extensions`.
+- Its data lives in `metadata["urn:elu-code:a2a-ext:peer:v1"]` = `{kind, project, hop, from: {key, name}, team?, room?, bot?}`. `team: true` marks a team ask; older peers drop it and show a plain ask.
+- `kind` is one of `ask`, `review`, `handoff`, `answer`.
+- `project` is a share handle or repository id, or null for the team's project.
+  - The receiver takes it only for a project it shared with a team both machines are on. A project shared with another team is refused in the same words as one that is not shared.
+  - A share saved by a build from before shares kept their teams is open to every team of the receiver's until it is shared again.
+- `room: {team, channel}` says where a team ask was sent. `team` is the team id. `channel` is the channel id, or null for `#general`.
+  - The receiver keeps the room only when both machines are on that team and, for a channel, both are in it. Otherwise it drops the room and shows a team ask with no channel.
+  - A room whose ids are malformed is refused as invalid params.
+  - Older peers drop the field.
+- `bot` names one of the receiver's shared bots, the one the question is for.
+  - It is a bot name: 1 to 30 lowercase letters, digits or `-`, starting with a letter. Anything else is refused as invalid params.
+  - Only an `ask` to one teammate may carry it. With another kind, or with `team: true`, the message is refused as invalid params.
+  - Older peers drop the field. There the question reaches the person as a plain ask.
+
+Task state mapping:
+
+| ELU Code | A2A |
+|---|---|
+| waiting for the owner to accept | SUBMITTED |
+| run in progress | WORKING |
+| reply held for the owner's approval | WORKING, with ext metadata `{substate: "awaiting-owner"}` |
+| reply sent | COMPLETED, with the reply as one Artifact (text part) |
+| owner declined, or blocked by policy or caps | REJECTED, with a reason message |
+| run failed | FAILED |
+| asker cancelled | CANCELED |
+
+## Pictures
+
+A message you type to a teammate or a channel takes along the pictures it names.
+
+**What is sent**
+
+- Write or drag a picture's path into the message box. A path with its spaces escaped (as a terminal writes a dropped file), a quoted path and a `~/` path all work.
+- The path in the text becomes the picture's file name. The teammate never sees your folders.
+- A file counts as a picture when its first bytes say PNG, JPEG, GIF or WebP. Its ending does not matter. Any other path stays the text it was. Nothing else in the file is checked, and it is sent unchanged: what a photo records about the place, the device and the time goes with it.
+- Only a message you typed carries pictures. A model's draft (sent by hand or by itself), a review, the command line and the local A2A endpoint never attach a file, so a model cannot send a file out by naming its path.
+- A path in text you pasted into the message box is a path you typed. The line that says how many pictures went (`with 2 pictures`) is shown after the message is sent.
+- A picture in a folder that holds secrets (`~/.ssh`, `~/.aws`, `~/.config` and the rest of that list, and ELU Code's own state folder) is refused. `~/Library` is the one folder of the list that stays open, because screenshot tools save there. A hard link in another folder to a file in such a folder is not recognized, and is attached.
+
+**Limits**
+
+| | limit |
+|---|---|
+| one picture | 8 MB |
+| pictures in one message | 4 |
+| all pictures in one message | 16 MB |
+
+Over a limit, the message is not sent, it stays in the message box, and one line says why, for example `shot.png is 14 MB; a picture can be up to 8 MB.`
+
+**On the wire**
+
+1. The app you typed in copies each picture to `pictures/out/<set>/<n>` in the state folder. The daemon sends only from there, never from a path in a command.
+2. Before the message, the daemon sends each picture in pieces of 700 KiB with `elu.picture.put` `{id, seq, last, size, sha256, data}`. `data` is base64, so a piece stays under the 1 MiB frame. Pieces count toward the same request rate as everything else, and one message with pictures goes to a teammate at a time.
+3. The message then names each picture as an A2A file part by reference: `{url: "urn:elu-code:picture:<id>", filename, mediaType, metadata: {"urn:elu-code:a2a-ext:peer:v1": {size, sha256}}}`. A file part does not count toward the text limit.
+4. The Task that `SendMessage` returns says how many pictures were kept, in its extension metadata as `pictures`.
+
+**On the receiving side**
+
+- Pieces are taken only from a teammate who is not muted. Each picture is checked again: its first bytes, its size and its SHA-256.
+- A finished picture waits in `pictures/in/<sender key>/` for the message that names it. One that waits longer than 10 minutes is removed.
+- When the message is accepted, its pictures move to `pictures/kept/<sender key>/<task id>/1.png` and so on: a folder only you can read, names made here, never the sender's path. The sender's file name is kept as cleaned text. A kept file is known as a picture by its first bytes only; it is readable by you alone (0600) and ELU Code never runs it.
+- In Chats, the row says how many pictures came and how large (`@kim asks you with 2 pictures (1.5 MB)`), and the opened message lists each name and size. The sender's row says `with 2 pictures`.
+- A refused message keeps no pictures. Kept pictures are removed with the message's record.
+- Caps, so a teammate cannot fill the disk: 32 MB or 16 pictures on their way from one teammate, 64 MB kept from one teammate, 256 MB kept in all. Over the first, the sender tries again later. Over the others, the text arrives without the pictures and the sender's row says so.
+
+**When the question runs**
+
+- The pictures are copied to a folder of their own under `elu-code-pictures` in the temporary directory. The folder is yours alone (0700) and holds only that question's pictures.
+- A question run reads the shared project and, when the message came with pictures, that one folder. Nothing else changes about what a teammate's question can read.
+- The pictures are named inside the teammate's data block, so the model treats them as the teammate's material and never as instructions.
+- The copies are removed when the run ends. While it runs, another session of yours that can read the temporary directory could read them.
+- If the copies cannot be made, the model is told the pictures' names and that it could not see them.
+- A message you take on as your own session, in a mode you pick, gets the same copies as paths in the teammate's data, like a picture you name in your own session. Those copies stay in the temporary directory, as the copy of your own picture does.
+- With another model than Claude, a teammate's message can only be taken on as your own session, so that is the one way its pictures reach that model.
+
+**Older builds**
+
+- A teammate on a build from before pictures answers `elu.picture.put` with "Method not found". The sender then sends the text alone, with the pictures' names in it, and the row says `@kim's ELU Code can't take pictures yet. The text went without them.`
+- A message from such a build has no file part and is taken as before.
+
+## Roster
+
+- **Ops.** `{teamId, id: sha256(canonical body), type, by: hexKey, at, body, sig}`. `sig` is ed25519 over the canonical JSON of everything except `sig`; canonical means sorted keys and no whitespace.
+- **Types.**
+  - `create`: by the founder; body `{name}`. The teamId is the id of this op.
+  - `admit`: body `{key, name, role: "member"|"admin", invite: sha256(secret)}`.
+  - `remove`: body `{key}`.
+  - `role`: body `{key, role}`.
+  - `relays`: body `{keys}`.
+  - `leave`: by the member leaving.
+  - `channel`: by a member, with body `{id, name, members}`.
+    - `id` is 16 hex characters.
+    - `name` is 1 to 30 lowercase letters, digits, `-` or `_`. It starts with a letter or digit, and `general` is taken.
+    - `members` is a list of up to 20 distinct keys.
+- **Merge.** A pushed op is stored only if the fold applies it. Ops over 10 minutes in the future, and every op from a key the receiver's log already shows removed or departed (whatever its `at`), are dropped. Two logs can then differ by refused ops; sync keeps offering them and the receiver keeps refusing.
+- **Fold.**
+  - The log is a grow-only set. State is computed by sorting ops by `(at, id)` and applying them in that order.
+  - An op is applied only if, at that point in the fold, its signer holds the needed role: the founder for create; an admin for admit, remove, role and relays; anyone for their own leave; a member for a channel op, under the channel rules below.
+  - Removal wins: a removed key's later ops are ignored, and a removed key is never re-admitted with the same key. The founder cannot be removed.
+  - The fold returns `channels: [{id, name, members, createdBy, createdAt}]`, oldest first.
+- **Channels.** A channel is a named group inside a team. `#general` is everyone on the team and needs no op.
+  - One `channel` op sets the whole channel: its name and its members. An op with no members deletes the channel.
+  - Any active member may create a channel that lists them.
+  - A channel's members and the team's admins may change it.
+  - Every key listed must be an active member of the team.
+  - No two channels share a name.
+  - A member who is removed from the team, or leaves it, drops out of its channels. A channel with nobody left is gone, and its name is free again.
+  - Limits: 50 channels per team, and 200 channel ops per signer. An op past a limit is not applied.
+  - A channel op syncs like every other op, so the people added get the channel from any teammate.
+  - A teammate on an older build refuses the op and sees no channels.
+- **Sync.**
+  - On every connection, each side compares `{seq, head}`, where head is the sha256 of the sorted op ids.
+  - The side with ops the other lacks pushes them with `elu.roster.push`. The receiver validates every op and drops invalid ones.
+  - A team both are on that the other side's hello left out (it did not know this machine was on it yet) is synced too.
+  - New ops are also pushed to every connected teammate, including ops another process (the CLI) wrote to the log.
+- **Invites.**
+  - The code is `elu-team:v1:` + base32 of `{teamId, inviter key, secret(32), expiresAt}`. It is single use and expires after 24 h by default.
+  - Only `sha256(secret)` is stored, in the inviter's `invites.json`.
+  - The joiner dials the inviter and calls `elu.join {teamId, secret, name}`. The inviter checks the hash, the expiry and that it is unused, appends `admit`, and returns the full log. Until then neither hello names the team, since the joiner is not on it.
+  - The inviter must be online for the join.
+
+## Status
+
+- Status is on by default when a project is shared; `elu share --no-status` turns it off. While it is on, `elu.status` carries one row for each live task that edits the project (preparing, running, ready or waiting for input), at most 50 rows in all: `{repoId, handle, taskId, label, now, files}`. A session that only answers has no row.
+  - `label` is the first line of the task's request, up to 80 characters.
+  - `now` is what the task is doing: its state and who is at work (a role such as `lead`, a shared bot's `@name`, or `bot` for a bot that is not shared), up to 80 characters.
+  - `files` is up to 200 paths, relative to the project, of the files the task changed from the commit it started from, and of the new files Git does not ignore.
+- The rows go only to connected teammates on a team the project is shared with, as its name does. A project with no `origin` remote has no `repoId` and sends no rows.
+- Every 10 s the daemon builds the rows again and sends them when they changed.
+- `repoId` is the sha256 of the normalised `origin` remote URL, so the same repository matches across machines.
+- Overlap is computed locally: my live tasks' changed files against teammates' rows with the same repoId. No query is sent for it.
+- Status is also sent on every connection, even with no rows, and a teammate's saved rows are shown only while they are connected.
+- `elu.status` also carries `box`, the name of the machine, and `bots`, the bots its owner shares: `[{name, about}]`, at most 20. These two go to every connected teammate, also when no project is shared or status is off.
+  - The box name is the peer setting `box`. With none set it is the first label of the host name, without any character a box name cannot have and cut to 32 characters, or `box` when nothing is left.
+  - The daemon reads the box name and the bots file again on every tick. When either changes, every connected teammate gets a new `elu.status` on that tick.
+  - The receiver checks each field on its own. A box name that is not valid reads as none. A bot with a bad name, or an `about` that is not text, is dropped. An `about` is cut to one line of 120 characters.
+  - The daemon keeps what each teammate last said in `state.json`, so it is still known after a restart while they are offline.
+  - A machine on an older build reads only `rows` and sends neither field. It shows with no box name and no bots.
+
+## Tasks
+
+A Task is a session's approved plan: what the owner agreed the model should do. For a project shared with a team, each machine tells the teammates on that team which Tasks its sessions are working on.
+
+- **What is told.** For each session of the project, the Task whose work is going on (its newest approved one), and any Task finished within the last 24 hours. Each is `{repoId, handle, id, revision, title, description, goal, objectives, priority, severity, state (approved or done), startedBy (owner, schedule or handoff), who, subtasks: [{text, state}], met, approvedAt, doneAt, updatedAt}`. `who` is the model's name, a shared bot's `@name`, or `bot` for a bot that is not shared.
+- **What is never told.** A Task that is only proposed or was rejected, the request and repository that approval starts, the chat, file contents, and any path of the machine. While status is on, a [status row](#status) does carry the first line of that request and the changed paths inside the project.
+- **To whom.** Only a teammate on a team the project is shared with, as for its name and status rows. A project that is not shared tells nothing. A share with `status: false` tells nothing, and neither does a project with no `origin` remote, since it has no `repoId`.
+- **When.** `elu.plans` carries the whole present list for that teammate. It is sent on connect, and within 5 s of a change (so at most one every 5 s to each teammate, well inside the 20 requests in 10 s a connection allows): an approval, a subtask's state, a finished Task, a new revision. A Task that ended, or whose share ended, is absent from the next list, and the receiver replaces what it had.
+- **Size.** At most 30 Tasks and 512 KiB in one message; the oldest are left out first.
+- **Receiving.** Every field is checked against the same lists and limits, control characters and terminal escapes are removed, unknown fields are dropped, and a Task that fails a check is dropped. The list is kept whole in `peer/plans/<key>.json` (mode 0600), at most 30 Tasks per teammate across all projects. At most 20 of one teammate's Tasks are shown in one project.
+- **Where it counts.** A teammate's Tasks are used only in a project this machine also shares with a team that teammate is on. Tasks named for any other project are kept and never shown or used.
+- **On the board.** In that project the Kanban tab shows a section under its four columns, `Teammates' Tasks N · read-only`: a row with each teammate's name and whether they are online, then one row for each of their Tasks with its title, priority · severity, state, subtasks done, who works on it, and how long ago it changed. Enter opens the whole Task to read. No key changes a teammate's Task or makes a card of it. A shared project with no `origin` remote shows one line there instead: its Tasks are not shown to teammates.
+- **For the models.** Each turn of the owner's own lead, and of a bot, in that project is given a block headed "What teammates are working on in this project". One line of ours says it is information to avoid doing the same work twice, never a request. Each teammate's Tasks follow inside a peer-data block, the kind used for any teammate's text: title, state, subtasks done, priority, severity, who works on it, and the goal cut to 300 characters. No description. At most 8 teammates, 6 Tasks each and 6000 characters in all. A teammate's question running on this machine is given none of it, and neither is a reviewer. With peer mode off nobody is.
+- **Ageing.** A teammate who is offline keeps their Tasks, marked as last heard, for 48 hours after they were last connected. They are deleted at once when that person is no longer on a team with this machine. A finished Task leaves 24 hours after it was done.
+- **Older builds.** A machine says `plans: true` in its `elu.hello` when it reads Tasks. One that does not say so is sent no `elu.plans`, and sends none.
+
+## Local A2A endpoint
+
+- Off by default. It listens on 127.0.0.1 on a random port; port and token are in `local-a2a.json` (0600).
+- Every request needs `Authorization: Bearer <token>`. The Host must be `127.0.0.1:<port>` or `localhost:<port>`, and requests carrying an `Origin` header are refused.
+- **Agent Card.** Served at `/.well-known/agent-card.json` with a JSONRPC interface. One skill per share, plus one skill per teammate.
+- **Routing.**
+  - `SendMessage` at `/a2a` goes to my own agent: an owner-authorised request in the named project (`metadata.project`), queued, not read-only.
+  - `SendMessage` at `/a2a/peer/<name>` becomes an ask from me to that teammate.
+  - `GetTask` works for both, also after the conductor drops the request row (`local-tasks/`).
+  - A client `contextId` is kept (it becomes the ask's thread). A message with `taskId` gets UnsupportedOperation. `SendMessage` returns at once; poll `GetTask`.
+- **Conformance.** Tested with the official `@a2a-js/sdk` 1.3.0 client (a dev dependency).

package/docs/permissions.md

@@ -0,0 +1,285 @@
+# Permissions
+
+A turn runs in one of four profiles. You choose one of three modes when you start a
+session; a turn that is not your own session's runs read only.
+
+## Modes
+
+| | Read only | Ask for approval | Approve for me | Full access |
+| --- | --- | --- | --- | --- |
+| Who gets it | bots that review or answer, teammate questions, tasks saved without a mode | your session | your session | your session |
+| Reads | the workspace; answer turns may read your home | without asking: the workspace, folders and, for answer turns, your home (below) | same | anything |
+| Edits in the workspace | edit turns only | yes | yes | yes |
+| Edits outside it | no | asks | a reviewer model decides; on Antigravity refused, and on Claude Code an answer turn's edit asks | yes |
+| Shell inside the vendor sandbox | no | yes; Antigravity runs no sandbox, so every command asks | yes | yes, no sandbox |
+| Shell outside it, network, web tools | no | asks | a reviewer model decides | yes |
+| Secrets and ELU Code state | no | no | no | file tools denied; a shell can read |
+| Never list (push, tag, merge, deploy, publish) | blocked | blocked; every escape asks | stand-in commands and, except on Codex, deny rules; a command that gets past them gets through if the reviewer allows it | stand-in commands, prompt text and, except on Codex, deny rules; no sandbox behind them |
+| Runs in | worktree | worktree or a named branch | same | also here |
+| Checks | sandboxed, no network, structural limits | same | no network; dependency files may change | network on; only secret paths and deleted tests block |
+
+"Asks" is a live approval in your terminal where the vendor has a relay: Claude
+Code, and Antigravity and Grok Build once the `relay` step of their one-time check
+has passed on this machine. Elsewhere the action is denied and reported, and the
+model returns `needs_input` naming what it needs. "A reviewer model decides" is the
+vendor's own reviewer, such as Claude Code's auto mode.
+
+A reply ELU Code cannot read is asked for once more. Claude Code is asked in the
+same session, which has done the work already, and the chat says it was asked for
+its reply again. Another vendor, or a Claude Code session that cannot be picked
+up, starts once more for the same message. The chat then says it was started
+twice, because anything the first one ran the second may have run again. A
+`needs_input` reply that names what it needs in its summary and asks no question
+is read as it is.
+
+Read only has no shell unless the project's settings file names command prefixes
+for the model (`roles.lead.commands` in `.elu-code/config.yaml`, for example
+`npm test`). ELU Code never adds one by itself. The test and build scripts it
+finds in a project run as checks after an edit, inside the check sandbox. A
+settings file counts only after you have approved it on this machine: ELU Code
+shows it and asks when it is new or changed. Until you approve a change, the
+settings you approved last stay in use.
+
+The workspace is the place you picked: a worktree on a new task branch, a
+worktree with a named branch checked out, or, in Full access, the checkout
+itself with its current branch and a dirty tree allowed. Folders are extra
+directories in your home that the model may read this session, added with
+`/permissions folders add <path>`; they are never a secret folder or ELU Code's
+state. A folder that holds one of those is refused too, and a link counts as
+where it leads: with `~/.config` linked to `~/dotfiles/config`, `~/dotfiles` is
+refused. In Ask for approval and Approve for me a folder is read and never written:
+Claude Code denies writes there to its file tools and to sandboxed commands, Codex gives
+the folder read access only, and Antigravity denies writes there to its file tool. On
+Claude Code and Antigravity a folder that holds the workspace or lies inside it, such as
+the folder of all your projects (a worktree sits beside its project), gets no such deny,
+because a deny there would refuse every edit in the workspace. Full access adds no rule
+for folders. Answer turns have no workspace: they run in the project
+folder, and in Ask and Auto a write there asks like any outside write.
+
+In Ask for approval and Approve for me, answer turns read your whole home folder
+without asking on Claude Code, Codex and Grok Build: your session's own, and a working
+bot's when you write to it. Claude Code is given the home folder with `--add-dir` for
+those turns; Codex reads anywhere in every turn; Grok Build allows `Read` and `Grep`
+with no path. On Claude Code a command that stays in the sandbox also reads outside the
+workspace without asking. Antigravity keeps its file tool to the workspace and folders.
+The secret folders (`~/.ssh`, `~/.aws`, `~/.config`, `~/Library` and the rest) and ELU
+Code's state stay closed, as the table says. Your session's answer turns, and a working
+bot's until the session's work is published, also get a list of up to 60 Git
+repositories found in your home, so the model can find the code you mean.
+
+## Which profile a turn runs with
+
+In order: a bot that reviews or answers runs read only; a teammate's question or
+review, or a read-only turn, runs read only; otherwise the session's mode. A task
+saved without a mode runs read only.
+
+A bot that works (one with a schedule, and `@lead`, `@qa` and each bot you make) runs in
+the session's mode when you write to it, and so do the helpers it hands work to. On Claude
+Code a working bot can start helpers when its instructions ask for them. They run on the
+bot's own model unless the bot was saved with another for them, as `@lead` was, with the
+tools and the denied commands of the bot's turn, and they start no helpers of their own.
+A bot that is allowed to merge pull requests starts helpers only when it was saved with a
+model for them. A turn its schedule started runs with Approve for me at most, because
+nobody may be watching.
+
+One entry of the never list can open: a bot that is allowed to merge pull requests
+(`@elu` comes allowed; a bot you make is not) may run `gh pr merge` in its own working
+turn on `claude`. Ask for approval still asks you before each merge. Push, tag,
+`git merge`, deploy and publish stay blocked for that bot and for everyone else.
+
+A longer command line that holds a never-list command is refused whole. The chat
+then names the part, as in `Blocked: git tag is never allowed, in any mode`, and
+does not point at `/permissions`. Each turn's instructions name the commands once
+and say how to list tags without `git tag`: `git for-each-ref
+--sort=-creatordate refs/tags` or `git describe --tags`.
+
+A rule on the command's text does not see what a script runs, and Codex has no
+deny rules. So every session with permissions also gets stand-in commands, on
+every vendor; on Codex they alone hold the never list. A
+private folder goes first on the session's PATH with one small script per command
+word (`git`, `gh`, `npm` and the rest). Each refuses the never-list call by name,
+in the same words, whatever runs it: the model, a script, `sh -c`, `npm test`.
+The command is read as the tool reads it, so `git -C dir push` is refused and
+`git merge-base` or `git stash push` is not. Every other call goes to the real
+command with its arguments untouched; `git tag` alone and `git tag -l` only list
+tags and pass. The chat shows the refusal as a Blocked line even when the turn
+went on to answer.
+
+Pushing to a folder on this machine and working in a scratch repository under the
+temporary directory are not publishing, and a project's own tests do both, so the
+stand-in for `git` lets them through:
+
+- `git push` passes when every place it would push to is a path or a `file://` URL
+  on this machine. git itself is asked, so the remote's `pushurl`, every
+  `url.<base>.insteadOf` and `pushInsteadOf` rule and the remote of a push that
+  names none are read as git reads them. A destination on another machine, one git
+  cannot place, or an option the stand-in does not know (`--receive-pack`,
+  `--repo`, submodules pushed on demand) is refused before anything is sent.
+- `git merge` and a `git tag` that makes or deletes a tag pass when the repository
+  they act on lies inside the system temporary directory: its top level and the
+  folder that holds its history, links resolved. Everywhere else they are refused.
+  A worktree under the temporary directory of a repository kept elsewhere is that
+  repository, and is refused.
+
+The temporary directory is the one ELU Code itself was started with, and `/tmp`;
+a session cannot name another by changing `TMPDIR`.
+
+Stand-in commands are not a sandbox. A full path to the real command
+(`/usr/bin/git push`), a changed PATH, a Git alias or another program that does the
+same work gets past them, and a session in Full access can rewrite the folder; it
+is written again when the next session starts. In Ask for approval and Approve for
+me the vendor's sandbox, where it runs one, still stands behind them; Antigravity in
+Ask for approval runs none, so every command asks and one you approve runs outside
+any sandbox. In Full access nothing does.
+
+## Git in the sandbox
+
+In Read only, Ask for approval and Approve for me a command in the sandbox reads the
+repository's Git folder and writes nothing there. `git status`, `git diff`, `git log`
+and `git show` work without asking. `git add`, `git commit`, `git stash` and the like
+are refused in the sandbox.
+
+What a sandboxed command can read that way:
+
+- The repository's history through git: every committed version of every file. That
+  includes a file committed once and later removed, and committed files the sandbox
+  hides by name in the worktree (`.env*`, `*.pem`, `.npmrc`): `git show HEAD:.env`
+  prints one.
+- The Git settings file: remote URLs, and a token if one is written into a URL.
+- The stash and the reflog.
+
+The sandbox has no network, so a sandboxed command cannot send any of it anywhere.
+What it prints goes to the model, as all output does, and into the session's record.
+ELU Code's own records in the folder (`.git/elu-code`) stay closed to commands and
+to the file tools. A teammate's question reads none of the Git folder.
+
+## Approvals
+
+Claude Code is started with ELU Code's approval relay as its permission prompt
+tool: a small MCP server over stdio, started from the same private config file
+as your own servers, with one tool. When Claude would prompt, the call becomes a
+request under ELU Code's personal directory and the terminal shows it under
+Needs you. Allow lets the action run; deny tells the model not to retry it
+another way; no answer within 20 minutes counts as a denial. The role's time
+limit waits while a request is open, and the conductor does not treat the wait
+as a stall. Every decision is kept with the task, and blocked actions are kept
+on the run.
+
+The keys are `y` allow and `n` deny. Where the session can be given Full access
+there is a third, `f`: it asks what `/permissions full` asks, then allows the
+action and switches the session to Full access, so that session stops asking.
+It is not offered for a bot's scheduled turn or a turn that runs read only.
+
+## Plan first
+
+A message that asks for a change to code or files, or for work that needs planning, comes
+back as a Task before anything is edited: a title, a description, the goal, the objectives
+that say when it is done, a priority and a severity. You approve it with `y`, reject it
+with `n`, or change it with a message. This holds in every mode, Full access included, for
+the session's model and for a bot that works, such as `@lead`.
+
+ELU Code enforces this much, on every vendor:
+
+- The editing turn starts only for a Task you approved. That is the turn that runs in the
+  session's workspace and is followed by the checks and the review. A reply that asks for
+  an edit with no Task is asked for its Task once more. If none comes, the reply is kept
+  as a plain answer with a line that says no Task was read, and nothing starts.
+- Only you approve, in your own session: with the key, or by typing `yes`. A teammate's
+  message, a schedule and a bot's own turn cannot approve a Task.
+- A Task is read as untrusted text. The title is one line of up to 80 characters; the
+  description up to 2000; the goal up to 500; one to eight objectives of up to 300 each;
+  the priority is urgent, high, medium or low; the severity is critical, high, medium or
+  low. Control characters are refused, and markup is shown as typed.
+- After approval the model reports its subtasks and the objectives it says are met. A
+  report cannot change the goal or an objective: those change only through a revised Task
+  that you approve again. Done on the card is the model's report. The checks and the
+  review are what verify the edit.
+
+The rest is an instruction to the model, not a boundary. The model decides whether a
+message needs a Task and whether a follow-up is inside a Task you already approved, and
+it is told to change nothing in the turn that proposes one. That
+first turn runs with the session's mode, in the project folder, so what stops an edit
+there is the mode:
+
+| First turn | Claude Code | Codex | Grok Build | Antigravity |
+| --- | --- | --- | --- | --- |
+| Read only | no edit tools | read-only sandbox | edits denied | edits denied |
+| Ask for approval | an edit in the project folder asks you | read-only sandbox | an edit asks you, or is denied and reported | not fenced: it can edit in the project folder |
+| Approve for me | an edit in the project folder asks you | read-only sandbox; Codex's reviewer model decides a request to leave it | Grok's reviewer model decides | not fenced |
+| Full access | not fenced | not fenced | not fenced | not fenced |
+
+Some turns wait for nobody:
+
+- A session a schedule starts, and a bot's own scheduled turn, have nobody to approve.
+  The Task is recorded as started by schedule and the work goes on.
+- A teammate's handoff you chose to work on with `w` records its Task as started by a
+  handoff and goes on.
+- A teammate's question and any read-only turn change nothing and make no Task.
+- `elu run "<goal>"` on the command line makes no Task.
+
+## Lifecycle
+
+- New sessions start with your personal default, `ask` until you change it
+  with `/permissions default <mode>`; the place is a worktree.
+- A follow-up inherits the session's mode, place and folders. Switching the
+  mode applies from the next turn and is recorded on the session; the pinned
+  policy does not change.
+- A switch made while a turn runs is saved at once, and so are the spending
+  limit, the folders and the bots. The turn in progress keeps the mode it
+  started with, with one exception: after a switch to Full access, ELU Code
+  allows that turn's approvals for you, the one that waits and the ones it asks
+  next. Three kinds stay yours to answer: a removal with `rm` or `rmdir`, an
+  MCP tool, and a command too long to show whole. The never list is not asked,
+  so it stays refused. A bot's scheduled turn is not answered this way: it runs
+  with Approve for me at most.
+- A turn that starts in Full access is never answered for you. What it still
+  asks, its vendor asks in every mode (Claude Code asks before `rm` or `rmdir`
+  on your home, the working folder or a top-level folder), and you answer it.
+- The automatic edit task of a conversation inherits the conversation's choices.
+- A schedule stores `ask` or `auto`; it never runs with Full access. An
+  unanswered approval times out and the task asks you.
+- A request sent to the local A2A endpoint, which is off by default, runs your
+  personal default, capped at `auto`.
+- A teammate's message you answer runs read only and never gets a mode. One you
+  choose to work on runs with the mode you pick then.
+- `elu run` runs read only unless you pass `--permissions auto|full`,
+  with `--place here|branch:<name>` and `--folder <path>` (repeatable). `ask`
+  needs the terminal app.
+- Publishing pushes the session's branch. A `here` session on a default branch
+  cannot publish. The publish preview says when the model ran with Full access.
+
+## Linux
+
+Claude Code's shell sandbox on Linux is bubblewrap. It needs `bwrap` and `socat`
+on PATH, and `bwrap` must be allowed to make user namespaces. Where the sandbox
+does not start, the system fences nothing, so Ask for approval asks you for every
+command and Approve for me sends every command to the reviewer.
+
+The Permissions picker says which case this machine is: "No OS sandbox here" when
+a tool is not installed, "The OS sandbox cannot start here" when both are installed
+and `bwrap` cannot start. ELU Code finds out by starting `bwrap` once, around a
+command that does nothing, when the picker first opens; start ELU Code again after
+a fix.
+
+Ubuntu 24.04 stops a program from making user namespaces unless an AppArmor
+profile lets it, and has no profile for `bwrap`. This one does, saved as
+`/etc/apparmor.d/bwrap`:
+
+    abi <abi/4.0>,
+    include <tunables/global>
+
+    profile bwrap /usr/bin/bwrap flags=(unconfined) {
+      userns,
+      include if exists <local/bwrap>
+    }
+
+and loaded once with `sudo apparmor_parser -r /etc/apparmor.d/bwrap`. Nothing is
+installed or changed for you.
+
+The check sandbox (`codex sandbox`), which runs every project's checks whatever the
+vendor, is bubblewrap on Linux too. The Linux tests run with `bubblewrap` installed
+and an AppArmor profile like this one loaded.
+
+## Claude Code
+
+See [vendors/claude.md](vendors/claude.md) for the exact launch per profile.