zarvis: run read-only shell calls concurrently via explicit read_only flag (#331)

[edwin-zvs]

Closes #331 (execution-side enabler, option 2).

What

Adds a read_only: boolean argument to the shell tool. A non-interactive shell call flagged read_only: true is downgraded to Safe in effective_risk(), which is what lets the agent loop fan it out concurrently (join_all) instead of serializing it through the approval gate. So several read-only shell inspections issued in one turn now run in parallel — mirroring the dedicated read-only inspection tools (agentd_context, agentd_get_diff, …) that are already Safe.

Why option 2

Per the issue, this is the model-trusting approach: the harness honors the model's read_only declaration rather than parsing the command line (which command substitution / redirects / chaining can defeat). It's scoped conservatively:

• only the shell tool,
• only when the flag is literally true,
• never for interactive: true (a long-lived process is not a bounded read).

The read-only-only contract ("provably side-effect-free: no writes, redirects, $(...), or chaining into a mutator") lives in the tool's arg description and the system prompt.

Behavior change to note

A read-only shell call no longer prompts for approval — including in manual mode — exactly like other Safe read tools. This is intended (you don't want to approve every cat), but it does rely on the model labeling honestly. A mutating command the model mislabels would bypass the gate; that's the documented tradeoff of option 2. Option 1's command-line allowlist can be layered on later as defense-in-depth (the issue notes the options aren't mutually exclusive) — I left a Non-Goal in the spec for it.

Changes

• tools/shell.rs — read_only schema arg + description; updated tool description.
• tools/mod.rs — effective_risk() downgrade + shell_read_only_optin() helper; unit tests.
• agent.rs — system-prompt nudge to mark parallel reads read_only: true.
• specs/0017-read-only-shell-runs-concurrently.md — records the new approval-semantics decision (relates to 0015-approval-modes).

Tests

• effective_risk_downgrades_read_only_shell — classification: read_only:true → Safe; absent/false → Risky; interactive overrides; opt-in doesn't leak to other tools.
• read_only_shell_calls_are_safe_and_run_concurrently — duration test (two sleep 1 reads finish in ~1s, not ~2s).
• Full suite: 146 passed.

Where the code lives

Only touches crates/adapter-zarvis → relevant binary is agentd-adapter-zarvis. All workspace binaries built (debug) in the worktree; the rest are unchanged from main.

No recording — harness execution/approval logic with no user-visible TUI render to demo.

🤖 Generated with Claude Code