agshell 0.5.1

A supervised execution shell for coding agents: per-command and per-stage exit status instead of one exit code per command string.
Documentation
# agshell

**Your agent's shell says `exit 0`. Often, something in the command failed.**

agshell is a drop-in supervised shell for coding agents. It runs the same bash your agent already writes, but reports what *actually happened*: the status of every command in a chain, every stage of a pipeline, and every `$( )`, as typed JSON instead of one exit code.

```console
$ bash -c 'false | head -1'; echo "exit=$?"
exit=0                                   # the agent concludes: success

$ agshell -c 'false | head -1' --human
  #0  false      status=1   pipe1.0
  #1  head -1    status=0   pipe1.1

class=stage_failed exit=0                # the agent learns: stage 0 failed
```

> Proof of concept, MIT, one Rust binary, tested on Linux and Windows. Built on [brush](https://brush.sh), a real bash-compatible shell embedded as a library. No new syntax to teach your agent.

## The problem nobody sees

Agents don't run single commands. We measured **37,700 real agent shell calls**:

| What the command looked like | Share |
|---|---|
| a single simple command (the only case one exit code can describe) | **21%** |
| contains a pipeline (`a \| b`) | **62%** |
| a `;` chain (`a; b; c`) | **51%** |
| an `&&` chain | **28%** |

So for about four commands in five, the status the agent reads is structurally unable to describe what happened. `a; b; c` returns `c`'s status. `false | head -1` returns `head`'s. Without `pipefail`, **64% of "successful" calls in the corpus were vouched for only by the last stage of a pipeline**, usually `head`, `grep` or `awk`. And **about 10% of exit-0 calls had printed an error line**. The agent noticed 9 times in 31,000 calls.

The result is not noise. It is wrong conclusions, stated confidently: "tests pass", "file written", "no matches", from a command that failed three stages ago.

## What it does instead

```console
$ bash -c 'false; echo hi; true'; echo "exit=$?"
hi
exit=0                                   # the failure is gone

$ agshell -c 'false; echo hi; true' --human
  #0  false      status=1
  #1  echo hi    status=0
  #2  true       status=0

class=chain_partial exit=0 hidden_failures=[0]
```

Every run returns an envelope your harness can branch on:

```json
{
  "class": "stage_failed",
  "exit": 0,
  "duration_ms": 2,
  "commands": [
    {"i": 0, "text": "false",   "bin": "false", "status": 1, "ms": 0, "pipeline": 1, "stage": 0},
    {"i": 1, "text": "head -1", "bin": "head",  "status": 0, "ms": 2, "pipeline": 1, "stage": 1}
  ],
  "hidden_failures": [0],
  "stdout": "", "stdout_bytes": 0
}
```

`exit` stays bash-compatible, so agshell can slide under an existing harness without breaking anything. Then you opt in to the truth:

| `class` | what the agent is told |
|---|---|
| `ok` | everything exited 0 and the output looks clean |
| `ok_noisy` | exited 0, **but printed something that reads like an error** |
| `chain_partial` | exited 0, **an earlier command in the chain failed** |
| `stage_failed` | exited 0, **a pipeline stage failed** |
| `substitution_failed` | exited 0, **a `$( )` failed** |
| `failed` | the final status was non-zero |
| `timeout` | killed at `--timeout`, **whole process tree**, no orphans |
| `parse_error` | bash itself would not have parsed it |

## What makes it different

**It reports truth without changing behaviour.** `set -e` and `pipefail` change what a script *does*. agshell changes only what the agent is *told*. Same commands, same side effects, honest status.

**It sees inside `if`, loops, functions, subshells and `eval`.** Other tools stop at the statement boundary: a `for` loop is one opaque unit with one exit code. agshell watches the shell's own `DEBUG` and `ERR` traps while the statement runs, so a failure three iterations deep is reported, and a failure bash already handled (an `if` condition, a `||`, a `!`) is not.

```console
$ ls
a.txt                                    # b.txt does not exist
$ agshell -c 'for f in a b; do cat $f.txt; echo "checked $f"; done' --human
  #0  cat a.txt          status=0   in #4
  #1  echo checked a     status=0   in #4
  #2  cat b.txt          status=1   in #4
  #3  echo checked b     status=0   in #4 inferred
  #4  for f in a b; ...  status=0   delegated
       stderr: cat: b.txt: No such file or directory

class=chain_partial exit=0 hidden_failures=[2]
```

bash says `exit 0` and prints "checked b" anyway. agshell says which `cat` failed. No control flow is re-implemented: brush still decides what runs, and agshell reads what it announces. Reported commands carry their *expanded* words (`echo item 7`, not `echo item $i`). The same mechanism sees into `$( )` and backticks wherever they sit, with no flag: `echo $(git rev-parse HEAD) done` exits 0 in bash even when git fails, and comes back as `class=substitution_failed` here, with the git command and its status in `commands`.

**`--strict`: the `set -e` that actually works.** `set -e` does not fire on `a | b`, on earlier commands in a `;` chain, or inside `$( )`. `--strict` stops at the first failed statement, masked pipeline stage, failed substitution, or unhandled failure inside a loop body or function. `false || true` is left alone, because `||` handled it.

```console
$ agshell -c 'echo ok; false; echo never' --strict --human
class=failed exit=1 aborted_at=1         # "never" never ran
```

**`--check`: lint before you spend the tool call.** It parses without executing and tells the agent what its own script is about to hide: `dropped_status`, `masked_stage`, `negated_status`, `wont_persist` (a `cd` inside a pipeline subshell), `unquoted_substitution`, `opaque_substitution`.

**`serve`: one live shell, with undo.** A JSON-lines protocol over stdin/stdout. State (`cd`, `export`, functions, arrays) persists across calls, because it is one shell and not one process per command.

```console
$ agshell serve
{"id":1,"op":"run","script":"cd /tmp; x=41"}
{"id":2,"op":"snapshot","key":"before-build"}
{"id":3,"op":"run","script":"x=99; cd /"}
{"id":4,"op":"restore","snapshot":"before-build"}     # cwd and variables rewind
{"id":5,"op":"branch","scripts":["npm test","pnpm test"]}   # two isolated forks, concurrently
```

- **Checkpoints** are cheap clones of persistent data structures. `restore` rewinds shell state (cwd, vars, functions, options). It does not un-write files.
- **Branches** run each script on an isolated fork. A branch's `cd` or `export` cannot leak into the session or another branch.
- **20 runs in 8 ms**, against about 3.9 ms of startup each if you spawn a shell per call. Builtins cost ~0.1 ms.

**Timeouts that actually kill things.** A timeout takes down the entire process tree (subshells, nested `bash -c`, loops, pipelines), verified with zero leftovers. Linux uses subreaper plus a `/proc` walk; Windows uses a Toolhelp32 snapshot plus `TerminateProcess`.

**It's a library too.**

```rust
let mut session = agshell::Session::new(Options::default()).await?;
let report = session.run("false | head -1").await;
assert_eq!(report.class, "stage_failed");
assert_eq!(report.commands[0].status, 1);     // typed, not text-parsed
```

## Try it

```console
$ cargo install agshell                       # Rust 1.88+, Linux and Windows
$ agshell -c 'go test ./... 2>&1 | tail -5'    # JSON envelope
$ agshell -c 'make' --human --timeout 5m       # readable report
$ agshell --check -c 'cd /tmp; false | head -1; echo done'
```

Build from source if you want the Windows `.cmd` fix (see the limits below):

```console
$ cargo install --git https://github.com/adhikasp/agshell
$ git clone https://github.com/adhikasp/agshell && cd agshell && cargo build --release
```

### Wire it into your agent

1. **Replace the shell tool's backend.** Run `agshell -c "$SCRIPT"` and return the JSON. Keep your existing interface; use `exit` as before.
2. **Surface the class.** Prepend one line to the tool result when `class` is not `ok`, for example `chain_partial: command #0 (false) failed`. That single line is the whole intervention.
3. **Or keep a session.** Spawn `agshell serve` once and speak JSON lines for the whole conversation: persistent `cd`, checkpoints before risky steps, branches to try two approaches.

## Why not just…

| | | |
|---|---|---|
| `set -o pipefail` | fixes pipelines only, changes script behaviour, silent on chains and `$( )` | agshell reports all of them without altering execution |
| `set -e` | misses pipelines, chains, substitutions; famously inconsistent | `--strict` covers all three |
| a hook or regex on output | text matching on exit-0 output is how errors slip by | structural: reads the parse tree and real statuses |
| a sandbox (`srt`, `nono`, Landlock) | enforces *what may run* | complementary: agshell reports *what did run*. Use both |
| output compressors (RTK) | save tokens | complementary: they shrink the output, agshell makes it truthful |

## Deliberate non-goals

- **No new syntax.** Not one operator. bash fluency is what makes your agent useful; agshell refuses to spend it.
- **No shell of its own.** Parsing and evaluation are `brush`. agshell decides what runs next and records the result.
- **No policy engine.** Sandboxing has good answers already. See the table above.

## Honest limits (PoC)

- Compound statements are run by the shell and observed through its traps, so the numbers are as good as what the shell announces. The last command of a context, when nothing failed, has its status *assumed* (`inferred: true`). A standalone `[[ ]]` or `(( ))` is not announced by the shell, so its failure is reported as `(failure at or after: ...)` instead of being pinned on a neighbour. A statement keeps at most 200 ordinary inner commands (`inner_omitted` says how many were dropped); unhandled failures are never dropped. Your own `DEBUG`/`ERR` traps are suspended while such a statement runs.
- Background jobs (`cmd &`) and pipelines with a compound stage (`{ ...; } | cat`) are still handed over whole and marked `delegated: true`. Coarse, but correct, and a wrong status is worse than a coarse one.
- Stderr and timing are reported per pipeline, not per stage, because the shell owns the pipe graph.
- A `$( )` in a pipeline stage (`echo $(cmd) | grep x`) or a background job is not observed and is flagged `opaque_substitution`. Everywhere else, in a lone command, a heredoc, a loop body or a function, it is.
- `brush`'s Windows support is a preview; timeouts and scripts work, POSIX signals and process groups do not exist there.
- **Windows installs from crates.io** resolve `.cmd`/`.bat` programs (`npm`, `npx`, `opencode`, ...) with the unpatched `brush-core` resolver, so they fail with `os error 193`. The fix is a pinned `brush` fork, and cargo does not publish `[patch]` sections; use `cargo install --git https://github.com/adhikasp/agshell` until it lands upstream.
- Next up: an exec observer in `brush-core` for real `argv`, per-stage pids and a policy seam. That is an upstream change.

## Under the hood

Parse with `brush-parser`, evaluate with embedded `brush-core`, walk the statement list yourself. For statements the shell runs whole, install a `DEBUG`/`ERR` trap that calls a builtin of ours, and read the log back. One shell instance per script (or session), pipelines run by the shell with real streaming and `SIGPIPE`, per-stage statuses read back from `PIPESTATUS`. Statement text is sliced from your original source, so what the report quotes is what you wrote.

## License

MIT. Issues and "my agent hit this" reports welcome, especially real transcripts where the exit code lied.