@elu-labs/elu 0.0.0-stage → 0.1.1

package/docs/vendors/antigravity.md

@@ -0,0 +1,131 @@
+# Antigravity CLI
+
+`agy` is Google's terminal coding agent for Google One AI Pro and Ultra subscribers (Plus
+and Free with a quota). In ELU Code it can run sessions and reviews, in every permission mode. `agy`
+runs only after it passes the one-time check below on this machine.
+
+## Install
+
+Use the vendor's installer from [antigravity.google/docs](https://antigravity.google/docs).
+It puts `agy` in your user bin folder (`~/.local/bin`); nothing needs sudo. ELU Code never
+installs it and never updates it: its own runs set `AGY_CLI_DISABLE_AUTO_UPDATE=true`, your
+own runs keep the vendor's default.
+
+## Sign in
+
+Run `agy` once and sign in with your Google account. The token lives in the OS keychain
+(on Linux, the keyring reached over `DBUS_SESSION_BUS_ADDRESS`, which ELU Code passes
+through). ELU Code checks sign-in with `agy -p /usage --output-format json`: exit code only,
+no model turn, no quota spent. Signed out, ELU Code says: `Antigravity: not signed in. Run: agy`.
+
+Google's FAQ at [antigravity.google/docs/faq](https://antigravity.google/docs/faq) says,
+verbatim: "Using third-party software, tools, or services to access Antigravity is a
+violation of our Terms of Service and severely degrades the experience for legitimate
+product users. Such actions can result in suspension or termination of your account…" and,
+on headless use: "Antigravity CLI headless mode (`agy -p`) is intended for direct scripting
+and CI workflows. Wrapping `agy` inside third-party coding agents or applications, or
+automating account rotation, is not supported under consumer plans." ELU Code wraps `agy`.
+Enabling it is your decision; the risk is your account, and ELU Code cannot reduce it.
+
+## The one-time check
+
+The check proves, on this machine and for the exact binary and release found, that the
+enforcement designed from Google's documentation holds. ELU Code starts it by itself
+before your first message to Antigravity goes out, whether you wrote to a session on it or
+to a bot on it. The session says so first, then shows each step as it ends, and then your
+message goes on. The check takes about seven short turns on Antigravity and a few minutes.
+Only a message you just sent starts it: a scheduled turn, a shadow turn or a review never
+does. It runs in a throwaway repository with a planted file outside it, a local web
+listener and a marker command:
+
+| Step | Proves |
+| --- | --- |
+| `signin` | the sign-in probe passes under ELU Code's private HOME |
+| `locked-no-write` | a read-only run told to create files creates nothing, inside or outside |
+| `locked-no-shell` | told to run the marker command, the marker never runs |
+| `locked-no-network` | told to fetch the local URL, the listener sees nothing |
+| `json` | headless output parses and the result matches the schema |
+| `resume` | a second run with the conversation id continues the first |
+| `relay` (optional) | over `agy acp`, a write outside the workspace arrives as a permission request, and a denial writes nothing |
+
+The result is saved under your ELU Code state. A different binary path or release has to
+pass again, on your next message to it; until it does, no run starts, and a turn you did
+not send yourself says
+`Antigravity CLI has not been checked on this machine yet. Your first message to it runs the check.`
+If a required step fails, Antigravity stays off here, the session says which step was not
+proven, and your next message to it runs the check again. When `relay` fails,
+Ask and Auto still run: blocked actions are denied and reported instead of asked live, and
+the permissions picker says so.
+
+## The private HOME
+
+`agy` reads `~/.gemini` for settings, hooks, MCP servers, plugins, skills and context files,
+and has no flag to turn that off. So ELU Code runs it with `HOME` set to a folder under its
+own state (`agy-home/`, mode 0700), one per workspace, holding only:
+
+- `.gemini/antigravity-cli/settings.json`: the mode's permission rules, written before each run;
+- `.gemini/config/hooks.json`: one PreToolUse hook, `lib/agy-hook.mjs`, run with the mode's name;
+- the conversations `agy` keeps there, so a session resumes with `--conversation`, also
+  after `/permissions` changed its mode: the rules are rewritten for every run.
+
+A mode switch applies from the next turn: the same conversation continues under the
+workspace HOME, whose settings and hook are rewritten for the new mode before the run.
+
+Nothing in your real `~/.gemini` reaches a run: not your settings, hooks, MCP servers,
+plugins, skills, `GEMINI.md` or `AGENTS.md`. Context files inside the workspace
+(`AGENTS.md`, `GEMINI.md`, `.agents/rules/*.md`) do reach the prompt; `agy` has no flag to
+skip them, so a repository can steer the model. `.agents` is a protected path, so the model
+cannot add such files itself.
+
+The prompt goes on standard input, never on the command line, so other users on the
+machine cannot read it with `ps`.
+
+## What each mode enforces
+
+| | Read only | Ask for approval | Approve for me | Full access |
+| --- | --- | --- | --- | --- |
+| How it runs | `agy -p --sandbox` | `agy acp` after `relay` passed, else `-p` | `agy acp` after `relay` passed, else `-p --mode=accept-edits --sandbox` | `-p --dangerously-skip-permissions` |
+| Settings | `request-review`; `command`, `write_file`, `read_url`, `execute_url`, `mcp` denied; workspace only | `request-review`; `command`, `read_url`, `execute_url`, `mcp` ask; workspace only; protected files and secret folders denied to the file tool | `proceed-in-sandbox`; `sudo` and `.git` denied; workspace only; protected files and secret folders denied | outside access allowed; `read_url`, `execute_url`, `mcp` allowed; secret folders denied to the file tool |
+| Hook | denies web search, commands, edits, image generation, scheduling and subagents | asks for web search; denies push, tag, merge, deploy and publish by command text | denies web search and the never list; sends the rest to the reviewer | denies the never list by command text |
+| Named folders | none | `--add-dir` each; `write_file` denied in each | same | `--add-dir` each |
+| Web | denied | asks, or reported | reviewed, or reported | allowed |
+
+A named folder is read and never written in Ask for approval and Approve for me: its
+`write_file` deny is the one a protected file gets. A folder that holds the workspace or
+lies inside it gets no deny, because a deny wins over the workspace's edits: for example
+the folder of all your projects, where a worktree sits beside its repository.
+
+In headless mode a blocked action is a soft deny: the run goes on, exits 0, and prints a
+notice on stderr naming the tool. ELU Code records each notice as a denial on the run and
+the model is told to return `needs_input` naming what it needs. Over ACP, a permission
+request reaches you under Needs you; no answer within 20 minutes counts as a denial.
+
+## What is not enforced, or not verified
+
+Everything above comes from Google's documentation and the Antigravity changelog; the
+one-time check is the proof, per machine. In particular, until a check says otherwise:
+
+- the never list is matched on command text by the hook, a tripwire that an obfuscated
+  command gets past; in Full access it is prompt text and that hook only;
+- stand-in commands first on the session's PATH also refuse the never list by name for
+  what a script runs. That was seen only in tests against a stand-in `agy`, not with the
+  real one;
+- whether `read_url` denies cover web search (hence the hook), whether the hook loads from
+  the private HOME, and the exact shape of the headless notice and of the ACP permission
+  request;
+- whether `-p` in a folder it does not trust refuses instead of denying softly, and whether
+  the keychain sign-in is visible under the private HOME;
+- that `-p` reads the task from standard input, that `--print-timeout` takes seconds
+  (`900s`), and that the output names the conversation id (the `json` and `resume` steps);
+- secret reads: `agy` has no read deny, so a read of a secret folder is stopped only by
+  workspace-only access (Read only, Ask, Approve for me); Full access can read anything;
+- whether a command can write in a folder given with `--add-dir`: the `write_file` deny
+  covers the file tool;
+- on Linux, `--sandbox` needs unprivileged user namespaces; without them Read only and
+  Approve for me report instead of sandboxing.
+
+## Telemetry
+
+Antigravity's "Interactions data" (prompts and responses used to improve the product) is an
+account setting, not a file or an environment variable. ELU Code cannot turn it off; opt out
+in your Antigravity account settings.

package/docs/vendors/claude.md

@@ -0,0 +1,124 @@
+# Claude Code
+
+Sessions and reviews. Sign-in is `claude`'s own; ELU Code never reads your sign-in
+token. The Usage tab names the account from `~/.claude.json` (email, organization,
+plan and rate limit tier) and shows only the five-hour and weekly usage windows that
+Claude Code prints during sessions. Tested releases:
+2.1.319 and 2.1.322. The modes are described in
+[../permissions.md](../permissions.md); this page is how `claude` is launched
+for each.
+
+## Read only
+
+The launch: `--restricted --permission-mode dontAsk --permission-prompts none`,
+`--safe-mode` unless your own MCP servers are on (it would drop them), an explicit
+`--tools` list with no shell unless the role declares command prefixes, strict MCP
+configuration (none for a review, a read-only turn or a teammate's question; for a task
+saved without a mode, your own Claude Code servers, all of them unless `/mcp off NAME`
+turned one off for the project), no setting sources,
+disabled hooks, the OS sandbox with network off, and
+`blockReadsOutsideWorkingDirectories`. An answer turn in a session saved without a
+mode also gets `--add-dir` for your home folder and for a private copy of your Claude
+Code memory, when there is one.
+
+## Ask for approval, Approve for me, Full access
+
+| | Ask | Auto | Full |
+| --- | --- | --- | --- |
+| `--permission-mode` | `default` | `auto` | `bypassPermissions` |
+| `--permission-prompts` / `--permission-prompt-tool` | `host` / `mcp__elu-code-approval__approve` | same | same |
+| `--restricted` / `--safe-mode` | no | no | no |
+| `--tools` | `Read,Grep,Glob,Edit,Write,Bash,WebFetch,WebSearch` | same | same |
+| `--allowedTools` | your MCP servers, `Read`, `Grep`, `Glob`, `Edit` and `Write` on the workspace | same | none |
+| `--disallowedTools` | `Agent,Task,NotebookEdit,PowerShell,Monitor`; a turn with helpers, below | same | same |
+| `--add-dir` | each folder of the session; an answer turn (yours, or a working bot's) also gets your home folder and a private copy of your Claude Code memory when there is one | same | same |
+| Sandbox | on where it starts, never required, no network; unsandboxed commands ask you | on where it starts, never required, no network; unsandboxed commands go to the reviewer | off |
+| Asks | web tools; answer turns also edits in the project folder | answer-turn edits only | none |
+| Denies | protected paths, writes in the folders of the session, secret reads, ELU Code state, the never list | same, without dependency files | secret reads, ELU Code state, the never list |
+
+Every profile keeps `--setting-sources ''`, `--strict-mcp-config` with a private
+config file and disabled hooks. `--max-budget-usd` is passed only when the session
+has a spending limit (`/budget`) or the run is a teammate's question. The approval relay is the
+one server ELU Code adds to that file; it is never in the allow list.
+
+A folder you name with `/permissions folders add` is read and never written in Ask and
+Auto: `Edit` and `Write` deny rules cover it and the sandbox's `denyWrite` lists it, the
+way protected paths are kept. Claude Code lets a deny win over an allow, so a folder that
+holds the workspace or lies inside it gets neither: for example the folder of all your
+projects, where a worktree sits beside its repository. Nor does a folder that holds the
+cache folder where the run keeps its temporary files (below). Not seen with the real
+service yet.
+
+The never list as deny rules: `git push`, `git tag`, `git merge`, `gh pr merge`,
+`gh release`, `npm publish`, `pnpm publish`, `yarn publish`, `cargo publish`,
+`firebase deploy`, `vercel deploy`, `gcloud run deploy`, `gcloud app deploy`,
+`fly deploy`, `kubectl apply`, `terraform apply`. They match command text, so
+`git -C . push` or a shell wrapper gets past them; in Ask the sandbox has no
+network and the common directory is read-only, which is what holds. A bot that is
+allowed to merge pull requests (`@elu` comes allowed; a bot you make is not) runs its
+own working turn without the `gh pr merge` rule; in Ask that command asks you instead.
+
+A working bot's turn that may start helpers (see [../permissions.md](../permissions.md))
+is launched with these changes: `--tools` adds `Agent`; `--allowedTools` adds
+`Agent(executor)`, except in Full; `--disallowedTools` is
+`NotebookEdit,PowerShell,Monitor`; `--agents` defines the one helper, `executor`, with
+the turn's own tools and the helpers' model; the deny rules add each built-in agent type
+and an `Agent` call that names a model or an isolation; and the settings and the
+environment turn off built-in agents, forked agents, helpers of helpers and background
+tasks, and force the helpers' model when the bot names one.
+
+Stand-in commands (`lib/never-shims.mjs`) cover what those rules cannot read: a
+script, `sh -c`, `npm test`. Claude Code starts each command from a snapshot of
+your shell setup, which builds PATH again, so a folder put first on the PATH it was
+started with ends up behind the system's. ELU Code sets `CLAUDE_ENV_FILE` to a
+one-line file that puts the folder first again; Claude Code runs that file ahead of
+each command. Seen on 2.1.322 in Ask for approval and in Approve for me: `npm test`
+whose script ran `git push` to an origin on another machine printed `git push is
+never allowed, in any mode.` and the push exited 126, and the run kept the refusal
+for the chat; the same turn without the file reached `/usr/bin/git`. Not seen with
+the real service: Full access.
+
+Claude Code keeps files of its own while it runs. After every command it writes a
+note of its working folder, and its sandboxed commands are given the same folder as
+`TMPDIR`. Its own place for them is `/tmp/claude-<uid>`, and the sandbox ELU Code
+sets for Read only, Ask for approval and Approve for me denies writes under `/tmp`,
+so every sandboxed command ended `Exit code 1` whatever it did. In those modes ELU
+Code names a private folder of the run in `CLAUDE_CODE_TMPDIR`:
+`<cache folder>/elu/<two letters>`, yours alone to read, made for the run and
+removed when it ends. The cache folder is `XDG_CACHE_HOME`, or `~/.cache`. Claude
+Code uses a named folder for sandboxed commands only while `<folder>/claude-<uid>`
+is at most 44 bytes. Where the cache folder is too long for that (a home folder of
+more than nineteen bytes, with a three-digit user number) your own runtime folder
+is tried, `XDG_RUNTIME_DIR` (`/run/user/<uid>` on Linux): the run's folder there is
+`<runtime folder>/elu<two letters>`, which fits a ten-digit user number. Where
+neither fits none is named, and commands there still end 1. Seen on 2.1.322 in Ask
+for approval: `npm test` ended 0 with `TMPDIR` in the cache folder's place, and the
+folder was gone after the run. Not seen with the real service: Approve for me, Read
+only, Linux, the runtime folder.
+
+A sandboxed command reads the repository's Git folder. The sandbox's `denyRead`
+holds only ELU Code's records in it (`<Git folder>/elu-code`) and `denyWrite` holds
+the whole folder; a teammate's question keeps the whole folder in `denyRead`. Seen
+on 2.1.322 in Ask for approval, in an answer turn: `git status`, `git diff` and
+`git log` ran in the sandbox with no approval asked; `git commit` ended 128 on
+`index.lock: Operation not permitted`; `ls .git/elu-code` was refused. A text
+filter named in the Git settings ran inside the sandbox when `git diff` used it:
+it could write nothing, and its call to the network was refused. Not seen with the
+real service: Approve for me, Read only, an edit turn in a worktree, Linux.
+
+`parse` reads the profile Claude ran with from its init line. A run asked for
+Auto that reports `default` is shown as Ask. Denied tool calls come back on the
+result as `permission_denials` and are kept on the run.
+
+On Linux, Claude Code's shell sandbox needs `bwrap` and `socat` on PATH, and `bwrap`
+must be able to start (Ubuntu 24.04 needs an AppArmor profile for it; see Linux in
+[permissions.md](../permissions.md)). Where the sandbox does not start, Claude Code
+runs commands without one: Ask for approval asks you for each, and Approve for me
+sends each to the reviewer. The Permissions picker says "No OS sandbox here" when a
+tool is missing. Where both are installed and `bwrap` cannot start, Claude Code says
+its sandbox is disabled; seen on 2.1.322, `npm test` then came to the owner as an
+approval. Nothing is installed for you.
+
+Not enforced or not verified on these releases: Bash rules match text only;
+WebFetch runs outside the sandbox; a `bypassPermissions` run does not check
+protected paths; whether Claude's auto reviewer counts toward the dollar budget.

package/docs/vendors/codex.md

@@ -0,0 +1,64 @@
+# Codex
+
+Sessions and reviews. Tested release: 0.166.0-alpha.5.1. Subscription: ChatGPT.
+
+Labels: **[run]** checked by running the tested release of `codex` against a local mock model server (the real backend was never called); **[docs]** from OpenAI's documentation or `codex exec --help`; **[unverified]** neither.
+
+## Install and sign in
+
+- `npm i -g @openai/codex` (a user prefix, no sudo).
+- `codex login` and choose ChatGPT. ELU Code reads `codex login status` and accepts only `Logged in using ChatGPT` [run]. An API key sign-in exits 0 too, so it is reported as signed out and the status line says `Codex: sign in with ChatGPT. Run: codex login`. No key variable is read or passed.
+- If another `codex` shim comes first on your PATH (the cmux shim does on some machines), put the real binary first. ELU Code launches with `features.hooks=false`; whether that neutralizes a shim's hooks is [unverified].
+
+## What each mode launches
+
+Every mode keeps the same isolation: `--ignore-user-config --ignore-rules --json`, `-c mcp_servers={}`, hooks, apps, plugins, browser, multi-agent, image and skill features off, user input and plan tools off, and a refusal to launch when a project or managed `config.toml` could add MCP servers. The output schema goes through `--output-schema`; the prompt arrives on stdin. A session's model also gets `--skip-git-repo-check`: a project folder need not be a Git repository, and without the flag Codex refuses to start there [run].
+
+| | Read only (reviewer) | Ask for approval | Approve for me | Full access |
+|---|---|---|---|---|
+| Sandbox | `--sandbox read-only` | profile `elu_ask` (below) [run] | the same profile [run] | `-c sandbox_mode="danger-full-access"` [run] |
+| Approvals | `never` | `never`; a blocked action produces no stream item [run] | `on-request` with `approvals_reviewer="auto_review"` [run] | `never` |
+| Shell | none | `exec_command` inside the sandbox [run] | same; an escalation goes to the reviewer model [run] | any command, no sandbox [run] |
+| Network | blocked | blocked, loopback included [run] | blocked unless the reviewer allows an escalation | open [run] |
+| Web search | off | off | off | `web_search="live"` [run: the tool is offered; a real search is unverified] |
+| Named folders | n/a | read-only | read-only | n/a |
+| Where | task worktree | worktree or branch | worktree or branch | also your checkout |
+
+The `elu_ask` profile is one `-c permissions.elu_ask=…` value with `default_permissions="elu_ask"` [run]:
+
+- `extends=":workspace"` for edit turns: the workspace is writable, everything else readable [run]. Answer turns use `extends=":read-only"` [run].
+- `":slash_tmp"="read"` and `":tmpdir"="read"`: the shared temp folders the workspace sandbox adds are read-only again [run]. The `sandbox_workspace_write.exclude_*` keys do nothing under a profile [run], so they are not passed.
+- Each named folder `"<dir>"="read"`: readable, not writable, the same entry a protected file gets below.
+- Each protected file `"<path>"="read"`: readable, not writable [run]. The structural checks still run afterwards.
+- Home secrets, ELU Code's state folder and the repository's `.git/elu-code` as `"<path>"="deny"`: a shell `cat` or `ls` there never starts and no item is reported [run]. The reviewer model in Approve for me sees the same deny list in its context [run].
+
+A profile value containing `*`, `?`, `[`, `]`, `{` or `}` is refused before launch: Codex reads those as patterns.
+
+Resume: `codex exec resume <thread_id> -` with the same `-c` set. `exec resume` has no `--sandbox` or `--cd`, so the sandbox and profile come from `-c` keys and the process runs in the workspace [run: the profile, Approve for me and Full access all applied on a resumed thread].
+
+## What the owner sees
+
+- Approve for me: an action the reviewer declines comes back as `status: "declined"` and is listed on the run as a denial (`Run: <command>` or `Edit: <paths>`) [run]. The model is told not to retry it and to return `needs_input`.
+- Ask for approval: Codex has no live approval relay. A sandbox block produces no stream item and no denial record [run]; the model reports what it could not do.
+- No dollar figure: Codex reports no cost in its stream. `maxCostUsd` must be `null`; the time limit bounds the run.
+
+## Code mode, seen with the real service
+
+These lines come from real turns on 0.166.0-alpha.5.1 with a ChatGPT sign-in, not from the mock model server.
+
+- Every model in the release's catalog but one takes its tools only through the code-mode host (`"tool_mode": "code_mode_only"` in `codex debug models --bundled`). The mock server knows no such model, so the [run] checks above never met it.
+- With `features.code_mode_host=false` a turn opens with `Code Mode is unavailable because code-mode host is disabled. Code mode will fail closed`. No command and no file read starts; the model can only ask you to enable shell execution. A session therefore leaves `code_mode_host` at the release's default. A reviewer has no tools and keeps it off.
+- With the host on, in Ask for approval and in Approve for me: a command runs as `/bin/zsh -lc '…'` and arrives as a `command_execution` item, a patch as a `file_change` item, and the adapter reads the stream. No other kind of item appeared.
+- The sandbox still refused: a write beside the workspace (`Operation not permitted`), a patch to a protected file (rejected, no item, no denial record) and a host lookup by `curl`.
+- The never list: with `allow_login_shell=false` a command runs as `/bin/zsh -c '…'`, and `command -v git` inside the sandbox names the stand-in. In Ask for approval, `npm test` whose script ran `git push` to an origin on another machine (an `ssh://` URL to a name that does not resolve) printed `git push is never allowed, in any mode.`, the push exited 126, ssh was never started, and the run kept the refusal for the chat. The same script's push to a bare repository inside the project went to the real git, and the sandbox of the mode refused its write (`remote unpack failed`). Approve for me was seen with the same refusal before local pushes were let through. With a login shell (`-lc`) the stand-in folder lands behind `/usr/bin` on macOS and would refuse nothing. Asked to run `git push` itself, the model declined, citing its instructions.
+- After a refused step the model answers `needs_input`, names what it needs in the summary and leaves `question` empty (three turns of three). ELU Code reads that reply as it is. Refusing it started a second session that ran the turn's commands again.
+- Not seen: Full access with the real service, a declined escalation in Approve for me, and what a code-mode cell can do without calling a tool.
+
+## Not enforced or not verified
+
+- No per-command allow or deny rules (`--ignore-rules`). In every mode but Read only the never list is held by stand-in commands first on the session's PATH (`lib/never-shims.mjs`), and `-c allow_login_shell=false` keeps a login shell from rebuilding PATH with the system folders ahead of them. They refuse by name and are not a sandbox: a full path to the real command, a changed PATH, a Git alias or another program that does the same work gets past them. A `git push` to a folder on this machine and a `git merge` or `git tag` in a scratch repository under the temporary directory pass, since a project's own tests do both. Behind them, in Ask the sandbox has no network and the Git common directory is read-only; in Approve for me an escape depends on the reviewer model; in Full access there is nothing.
+- Reads are open everywhere except the profile's deny entries. Glob deny entries such as `**/.env*` are [unverified].
+- Approve for me: an allowed escalation ran a write outside the sandbox [run]; an allowed escalated `curl` to a loopback address still could not connect [run, cause unknown]. An allowed escalation to an external host reached it in an earlier run.
+- Full access web search: the `web_search` tool is offered with `web_search="live"` [run]; no search was performed against the real service.
+- Whether `features.hooks=false` stops a PATH shim's hooks [unverified].
+- Linux: the tested release runs its sandbox on bubblewrap, with its own copy of `bwrap` (Landlock is its older option). The profile semantics above were checked on macOS only; the Linux tests run with `bubblewrap` installed and an AppArmor profile loaded ([../permissions.md](../permissions.md#linux)).

package/docs/vendors/grok.md

@@ -0,0 +1,151 @@
+# Grok Build
+
+Grok Build (`grok`) is xAI's coding CLI for SuperGrok and X Premium+ subscribers. ELU Code
+runs sessions on it. Its enforcement follows the vendor's documentation; a one-time check on
+your machine proves it before the first run.
+
+## Install and sign in
+
+```
+npm i -g @xai-official/grok
+grok login
+```
+
+Install into a user-writable npm prefix; nothing here needs sudo. `grok login` opens the
+browser (`grok login --device-auth` on a remote machine) and keeps the token in
+`~/.grok/auth.json`. ELU Code never reads that file, never copies it, and reads no API key
+variable: if `grok` is signed out, the session says `Grok Build: not signed in. Run: grok login`.
+
+## The one-time check
+
+ELU Code starts the check by itself before your first message to Grok goes out, whether
+you wrote to a session on it or to a bot on it. The session says so first, then shows each
+step as it ends, and then your message goes on. The check takes about seven short turns on
+Grok and a few minutes. Only a message you just sent starts it: a scheduled turn, a shadow
+turn or a review never does.
+
+The check runs eight steps against the installed binary in a throwaway repository, with a
+planted file outside it, a local web listener and a marker command:
+
+| Step | What it proves |
+|---|---|
+| `signin` | the token works from ELU Code's private Grok home |
+| `locked-no-write` | a read-only run told to create files creates none, inside or outside |
+| `locked-no-shell` | told to run the marker command, it never runs |
+| `locked-no-network` | told to fetch the local URL, the listener sees nothing |
+| `json` | the headless result parses and follows ELU Code's schema |
+| `resume` | a second run with the session id continues the first |
+| `relay` | over ACP, a write outside the workspace asks first; denied, nothing is written |
+| `isolation` | `grok inspect --json` shows no Claude or Cursor instructions, hooks or servers |
+
+Every step but `relay` must pass. The result is stored per binary and version; a new
+release proves itself again, on your next message to it. Until the check passes, no Grok
+run starts, and a turn you did not send yourself says
+`Grok Build has not been checked on this machine yet. Your first message to it runs the check.`
+If a required step fails, Grok stays off here, the session says which step was not proven,
+and your next message to it runs the check again. If `relay` fails, Ask and
+Auto still work, but a blocked action is reported instead of asked:
+`Grok can't ask live here. Blocked actions are reported.`
+
+## How each mode runs
+
+| Mode | Transport | Permissions |
+|---|---|---|
+| Read only | headless (`--prompt-file`) | `--permission-mode dontAsk`, `--sandbox read-only`, tools `read_file,grep,list_dir`, every write, shell, web and MCP tool denied |
+| Ask | ACP (`grok agent stdio`) when `relay` passed, else headless `dontAsk` | `Read` and `Grep` with no path, workspace edits and reads of each named folder allowed by rule; outside edits, named folders included, shell and web ask you (ACP) or are denied and reported (headless); `--sandbox workspace` in headless mode |
+| Auto | ACP with `autoMode`, else headless `--permission-mode auto` | Grok's own reviewer model decides routine actions; what it refuses asks you over ACP |
+| Full | headless `--permission-mode bypassPermissions`, `--sandbox off` | anything; the never list stays as deny rules |
+
+Every profile denies reads of secret folders (`~/.ssh`, `~/.aws`, `~/.claude`, `~/.codex`,
+`.env*`, `auth.json`, key files, ELU Code's own state) by rule, and denies the never list on
+command text (`git push`, `git tag`, `git merge`, `gh pr merge`, `gh release`, package
+publishes, deploys, `kubectl apply`, `terraform apply`). Those rules match text: `sh -c`
+and aliases get past them, so in Auto and Full they are a tripwire, not a boundary.
+Stand-in commands first on the session's PATH also refuse the list by name for what a
+script or `sh -c` runs; that was seen only in tests against a stand-in `grok`, not with the
+real one, and whether Grok's sandbox lets a command read that folder is not proven. The
+Read only profile has no shell, so there the never list holds. Grok's sandbox blocks a
+child process's network on Linux only; on macOS the read-only profile holds because it has
+no shell and no web tools, not because the sandbox blocks the network.
+
+Headless runs have no schema flag, so ELU Code puts the output schema in the prompt and
+validates the answer. Sessions resume with `-r`; a mode switch that changes the sandbox
+profile cannot resume (Grok keeps a session's sandbox), so that turn's retry starts a fresh
+session without the earlier context. The time limit is the role's; `--max-turns` (40 for
+read-only turns, 120 for edit turns) bounds the model rounds. Cost is not reported under a
+subscription; the role's `maxCostUsd` must be `null`.
+
+## The private home
+
+By default Grok reads your `~/.grok` tree (config, rules, hooks, skills, agents,
+`AGENTS.md`), `/etc/grok`, the workspace's `.grok`, every `AGENTS.md` and `CLAUDE.md` up
+the tree, `.envrc`, and your Claude Code configuration: `~/.claude/settings.json` and
+`settings.local.json` (hooks and permission rules), `~/.claude/CLAUDE.md`,
+`~/.claude/rules/*.md`, `~/.claude/agents/*.md`, `~/.claude/skills/`, `~/.claude.json`
+(MCP servers), plus the same Cursor files. The switches
+`GROK_CLAUDE_{SKILLS,RULES,AGENTS,MCPS,HOOKS}_ENABLED=0` and `GROK_CURSOR_*_ENABLED=0`
+exist, and ELU Code sets all ten, but
+[xai-org/grok-build-plugin-cc#34](https://github.com/xai-org/grok-build-plugin-cc/issues/34)
+(open, filed against CLI 1.0.5) reports `~/.claude/CLAUDE.md`, `rules` and `agents` still
+loading with every switch off, and the `~/.claude` scan is anchored on `HOME`, which
+`GROK_HOME` does not move.
+
+So every run gets a private `HOME` under ELU Code's state (`grok-home` in your personal
+directory) and a `GROK_HOME` inside it holding only what ELU Code wrote:
+
+- `config.toml`: Claude and Cursor compatibility off, telemetry, trace upload, Mixpanel,
+  feedback, managed config, campaigns, remote fetch and server-side search off, workspace
+  snapshots and codebase uploads off, auto-update off, session relay off, `.envrc` off,
+  subagents off, and the never list as deny rules. It is rewritten before every run.
+- `trusted_folders.toml`: empty. A workspace is never trusted, so its `.grok/config.toml`,
+  hooks, MCP servers and skills never load. Its `AGENTS.md` and `CLAUDE.md` still reach the
+  prompt; they are repository content, treated as untrusted.
+- `sessions/`: Grok's session store, so `-r` works.
+- `auth.json`: a symbolic link to your real `~/.grok/auth.json`. `grok login`, `grok logout`
+  and token refreshes write through it; ELU Code holds no copy. If Grok ever replaces the
+  link with a file, the newer token wins at the next run.
+
+There is no `~/.claude` under that home, so the `isolation` step shows what actually
+reaches a run on your machine. If it fails, Grok stays off here and the session says why.
+
+## Telemetry and uploads
+
+On consumer plans Grok's product analytics, session trace upload (which includes file
+contents) and per-turn workspace snapshots are on by default. ELU Code turns off every
+documented switch, in the environment and in `config.toml`: `GROK_TELEMETRY_ENABLED=0`,
+`GROK_TELEMETRY_TRACE_UPLOAD=0`, `GROK_TELEMETRY_MIXPANEL_ENABLED=0`,
+`GROK_FEEDBACK_ENABLED=0`, `GROK_MEMORY=0`, `GROK_SUBAGENTS=0`, `GROK_CAMPAIGNS=0`,
+`GROK_DISABLE_AUTOUPDATER=1`, `[telemetry] trace_upload=false`,
+`[harness] disable_workspace_teleport=true` and the older `disable_codebase_upload=true`
+(the key that stopped per-turn repository uploads on earlier releases), `[relay]
+enabled=false`. With trace upload on, a headless run can spend up to 150 seconds draining
+uploads at exit; off, it ends when the turn ends. Grok's server-side web search
+(`[features] backend_tools`, `GROK_BACKEND_SEARCH`) runs inside the model call, where no
+permission rule applies, so it is off in every mode; the model's own web tools follow the
+mode. Account-level settings for coding data, retention and training live in Grok's own
+`/privacy` screen; ELU Code cannot change them.
+
+## What is enforced and what is not
+
+Enforced by the vendor and proven by the one-time check on your machine: no writes, no shell and
+no network in Read only; the schema result; resume; where `relay` passed, a live question
+before an outside write in Ask.
+
+Not enforced, or not proven:
+
+- Deny rules match command text. Obfuscated commands reach Auto's reviewer model and run
+  unprompted in Full.
+- `--permission-mode` values other than `bypassPermissions` in headless mode are
+  documented for the enterprise build; the check's locked steps prove `dontAsk` here, and
+  Ask falls back to it only when `relay` failed.
+- Whether the server-side search switch and the older codebase-upload key are honoured on
+  this release, and whether `auto` mode is available on your plan without
+  `[auto_mode] enabled`, is not settled by the docs.
+- The exact ACP permission request shape and `session/load` come from the ACP standard and
+  Grok's docs; the `relay` step is the only proof.
+- Whether Grok refreshes the token through the symbolic link or replaces it is not settled;
+  the rule above keeps the newer token either way.
+- Workspace `AGENTS.md` and `CLAUDE.md` reach the prompt in every mode. A repository can
+  steer the model's instructions, not its permissions.
+- A full shell in Full access can push, tag, merge, deploy and publish. ELU Code keeps the
+  prompt line, the deny rules and its own publish gate, and claims no more.

package/lib/acp-client.mjs

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import { spawn } from 'node:child_process';
+import { EluCodeError, atomic, noSymlinks, refuse } from './util.mjs';
+import { killGroup, processIdentity } from './process.mjs';
+
+// Newline-delimited JSON-RPC 2.0 over a child's stdio, as the ACP vendors speak it. No
+// dependencies. The child's lines are appended to logFile, so a run's log reads like a
+// vendor's stream; stderr goes to <logFile>.stderr. The same logFile, processFile, signal
+// and hold plumbing as runProcess, and `exit` resolves to the shape runProcess returns.
+const OUTPUT_LIMIT = 16 * 1024 * 1024, LINE_LIMIT = 4 * 1024 * 1024, REQUEST_TIMEOUT_MS = 60000;
+const rpcError = (message, code) => Object.assign(new EluCodeError(message, { code }), { code });
+
+export async function startAcp({ bin, args = [], cwd, env, logFile, processFile, signal, hold = null, timeoutSeconds = null }) {
+  signal?.throwIfAborted();
+  if (typeof bin !== 'string' || !bin) refuse('An ACP client needs a program to start.');
+  noSymlinks(logFile);
+  const fd = fs.openSync(logFile, 'wx', 0o600), stderrFile = `${logFile}.stderr`;
+  noSymlinks(stderrFile);
+  const stderrFd = fs.openSync(stderrFile, 'wx', 0o600);
+  let child;
+  try { child = spawn(bin, args, { cwd, env, detached: true, stdio: ['pipe', 'pipe', stderrFd] }); }
+  finally { fs.closeSync(stderrFd); }
+  const pending = new Map(), handlers = new Map();
+  let next = 0, written = 0, timedOut = false, outputLimit = false, closed = false, elapsed = 0;
+  const stop = () => killGroup(child.pid, 'SIGKILL');
+  const send = value => { if (child.stdin.destroyed || closed) return false; child.stdin.write(`${JSON.stringify(value)}\n`); return true; };
+  const log = line => { written += line.length + 1; if (written > OUTPUT_LIMIT) { outputLimit = true; stop(); return; } fs.writeSync(fd, `${line}\n`); };
+  const failAll = reason => { for (const [id, entry] of pending) { pending.delete(id); clearTimeout(entry.timer); entry.reject(rpcError(reason, -32001)); } };
+  if (child.pid) {
+    const record = { pid: child.pid, identity: processIdentity(child.pid), bin: path.basename(bin) };
+    if (processFile) atomic(processFile, record);
+  }
+  // A held run (an approval waiting for the owner) does not spend its time limit.
+  const timer = timeoutSeconds ? setInterval(() => { if (hold?.()) return; elapsed += 1; if (elapsed >= timeoutSeconds) { timedOut = true; stop(); } }, 1000) : null;
+  signal?.addEventListener('abort', stop, { once: true });
+  if (signal?.aborted) stop();
+  for (const name of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(name, stop);
+  child.stdin.on('error', () => {});
+  const exit = new Promise(resolve => {
+    child.once('error', error => resolve({ code: null, error: error.message }));
+    child.once('close', (code, signalName) => resolve({ code, signal: signalName }));
+  }).then(result => {
+    closed = true; if (timer) clearInterval(timer); stop();
+    signal?.removeEventListener('abort', stop);
+    for (const name of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.off(name, stop);
+    if (processFile) atomic(processFile, { pid: null, identity: null });
+    fs.closeSync(fd);
+    failAll(`${path.basename(bin)} exited.`);
+    return { ...result, timedOut, outputLimit, stderrFile, log: logFile };
+  });
+  // Each server line: a reply to one of our requests, a request we must answer, or a notification.
+  async function receive(row) {
+    if (row.id !== undefined && row.method === undefined) {
+      const entry = pending.get(row.id); if (!entry) return;
+      pending.delete(row.id); clearTimeout(entry.timer);
+      if (row.error) entry.reject(rpcError(String(row.error.message ?? 'The vendor returned an error.').slice(0, 1000), Number.isInteger(row.error.code) ? row.error.code : -32000));
+      else entry.resolve(row.result);
+      return;
+    }
+    if (typeof row.method !== 'string') return;
+    const handler = handlers.get(row.method);
+    if (row.id === undefined) { if (handler) { try { await handler(row.params); } catch { /* A notification handler's failure is the handler's own. */ } } return; }
+    if (!handler) { send({ jsonrpc: '2.0', id: row.id, error: { code: -32601, message: 'Method not found' } }); return; }
+    try { send({ jsonrpc: '2.0', id: row.id, result: await handler(row.params) ?? null }); }
+    catch (error) { send({ jsonrpc: '2.0', id: row.id, error: { code: Number.isInteger(error.code) ? error.code : -32000, message: String(error.message ?? 'The handler failed.').slice(0, 1000) } }); }
+  }
+  const lines = readline.createInterface({ input: child.stdout, crlfDelay: Infinity });
+  let chain = Promise.resolve();
+  lines.on('line', line => {
+    if (line.length > LINE_LIMIT) { outputLimit = true; stop(); return; }
+    log(line);
+    let row; try { row = JSON.parse(line); } catch { return; }
+    if (!row || typeof row !== 'object') return;
+    chain = chain.then(() => receive(row));
+  });
+  return {
+    pid: child.pid, exit,
+    request(method, params = {}, { timeoutMs = REQUEST_TIMEOUT_MS } = {}) {
+      if (typeof method !== 'string' || !method) refuse('A request names its method.');
+      if (closed) return Promise.reject(rpcError(`${path.basename(bin)} exited.`, -32001));
+      const id = ++next;
+      return new Promise((resolve, reject) => {
+        const entry = { resolve, reject, timer: setTimeout(() => { if (pending.delete(id)) reject(rpcError(`No answer to ${method} within ${Math.round(timeoutMs / 1000)} seconds.`, -32002)); }, timeoutMs) };
+        pending.set(id, entry);
+        if (!send({ jsonrpc: '2.0', id, method, params })) { pending.delete(id); clearTimeout(entry.timer); reject(rpcError(`${path.basename(bin)} exited.`, -32001)); }
+      });
+    },
+    notify(method, params = {}) { if (typeof method !== 'string' || !method) refuse('A notification names its method.'); return send({ jsonrpc: '2.0', method, params }); },
+    on(method, handler) { if (typeof method !== 'string' || typeof handler !== 'function') refuse('on(method, handler) needs a method name and a function.'); handlers.set(method, handler); },
+    close() {
+      if (closed) return exit;
+      try { child.stdin.end(); } catch { /* Already closed. */ }
+      killGroup(child.pid, 'SIGTERM');
+      const force = setTimeout(stop, 250);
+      return exit.then(result => { clearTimeout(force); return result; });
+    },
+  };
+}