docs: document x/ namespace and x/elevate in scripts/README.md

Add x/ to the namespace list and add an x/elevate section describing
its role as the elevation plugin for execute_code elevated steps, the
calling convention, the default superpowerd implementation, and how to
replace or disable it.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Levi Neely 2026-04-25 11:22:29 +02:00
parent d42778c61a
commit df651908c4
1 changed files with 21 additions and 0 deletions

View File

@ -20,6 +20,7 @@ Scripts are organized by the filesystem namespace they are hosted under:
- `s/` — session management and one-shot query scripts
- `u/` — utility scripts; compositions of other ollie primitives
- `x/` — elevation plugins; called by `execute_code` for privileged steps
---
@ -202,3 +203,23 @@ u/optimize "generate a hello world program. use c++." >[2]/dev/null | s/bfg
```
Outputs to stdout, making it composable with other pipeline stages.
---
## x/elevate
Elevation plugin invoked by `execute_code` when a step is marked `elevated: true`.
Runs the command outside the sandbox and returns its output.
`execute_code` looks for `x/elevate` in the plugins path and calls it as:
```sh
x/elevate -- <cmd>
```
The default implementation delegates to `superpowerd` via a Unix socket. Replace the
script to use a different elevation mechanism — the interface is just stdin/stdout with
a shell exit code.
To disable elevation entirely, remove or replace `x/elevate` with a script that exits
non-zero. Steps with `elevated: true` will then fail rather than run unsandboxed.