fix(fleet): read-only agents run read-only commands; refusals are actionable (#6015)

[Hmbown]

Closes #6015

What was wrong

Read-only children were refused commands that really are read-only. The reported trigger was cd X && git diff. Four defects caused this:

1. Grammar. The agent read-only classifier refused any ;, &, > or $ anywhere in the string. It also split pipes with a quote-unaware split('|'). So cd sub && git diff, cat a && echo --- && cat b, rg x 2>/dev/null and git log -3; git status were all refused, even though every program in them is an admitted read.
2. Two authorities. Durable Fleet workers were judged by the parent's parallel grammar plus a special case for bounded sed. In-process children were judged by the agent grammar. So rg x | head, find . -name '*.rs' and git -C . log ran in one path and were refused in the other.
3. Refusals. The refusal text did not say which rule failed. It said "avoid pipes", and it pointed children at Git and Run tools they do not have. The executor returned Ok(error), so the no-progress guard never counted the refusal. Child tool results were sent with is_error: None.
4. A separate route to 0 steps. The launch-permit wait shared the child's work deadline. A child that never got a launch slot was reported as child_wall_time_exhausted with 0 steps.

What changed

• One classifier, the same on every host (command_safety.rs). A new lexer tracks quotes and splits only on unquoted |, &&, || and ;. It admits exactly three redirects: 2>/dev/null, >/dev/null and 2>&1. It refuses every other unquoted metacharacter it does not recognise, so anything unknown fails closed.
  • Each segment must pass the existing per-segment grammar, which is unchanged. The only new segment form is echo/printf with literal text.
  • No new programs are admitted: python, awk, jq and cargo are still refused.
  • agent_readonly_verdict returns the rule that refused the command, so the reason comes from the same code that made the decision.
  • readonly_command_help() now describes the real grammar.
• A leading cd <dir> && is moved into the cwd field (normalize_readonly_cd) before any gate judges the call. The existing working-directory workspace check then decides whether that directory is allowed.
• One authority. The registry's durable-worker check now admits exactly agent_readonly_bash_verdict(). This is the same predicate and normalization used by the posture gate and by BashTool::execute. The bounded_sed special case is deleted.
• gh and npm view reads need the network grant wherever they appear in a command. is_github_readonly_command is deleted. A full-shell parent is unchanged.
• Workspace operand checks run per segment.
• Execution rebuilds pipelines and chains from argv that the classifier approved, using only the admitted operators and redirect words.
• One refusal builder (readonly_refusal) is shared by the posture gate, the durable authority and the executor. The rule text is identical across them, and the next steps name only tools a read-only agent has. The executor now returns a typed PermissionDenied. Child tool results carry is_error: Some(true) when they fail.
• A queued agent that never starts now fails with "never started: no sub-agent launch slot opened within Ns, so no work ran", with 0 steps. A child that gets a slot after waiting gets its full wall time from launch. Any parent, saved-run or source deadline still caps it.
  • This reverses the v0.9.14: a worker's reserved report turn is spent by its own descendants — budget death returns nothing at all #6277 rule that queue time counts against the run, so it is a separate commit (4510178) and can be dropped on its own.
  • The restarted deadline is saved to the worker record at launch, so continuing a child that launched late is bounded by the deadline it actually worked to.
  • The cost of keeping it: a parent can wait up to about twice wall_time_secs for a queued child.
• Docs. docs/SUBAGENTS.md gains a "Read-only shell commands" section and an updated launch-clock paragraph. docs/FLEET.md notes that durable workers use the same grammar. CHANGELOG.md [Unreleased] has a new entry.

Deviations from the approved design

• End-to-end test commands. The e2e test uses git grep -n needle instead of rg, because rg is not guaranteed on CI runners.
• Durable codewhale exec test. I did not add a new end-to-end test for a durable run where every call is refused. The existing pieces already pin that path: no-progress returns TurnOutcomeStatus::Failed, which exits 1 in exec_agent.rs, and classify_worker_exit(Some(1)) gives Failed, which is already tested in fleet/executor.rs.
• Where refusal reasons come from. Refusals from the lexer (operator, quote) are produced by the code that decides. For segment-level refusals (program, subcommand, option), the existing boolean grammar decides and a diagnoser names the rule. The diagnoser runs only after a refusal, so it can never widen what is admitted.

Related

#6298 argues for moving away from grammar-defined read-only, towards one grant model and a sandbox. This PR stays inside the current grammar. It fixes what gets refused and how refusals read now; it does not start that rework.

Verification (local)

• cargo test -p codewhale-execpolicy --lib command_safety: 79 passed, 0 failed.

• cargo test -p codewhale-tui --lib -- tools::shell tools::registry tools::subagent tools::execution_envelope core::engine::tool_catalog core::engine::dispatch: 1001 passed, 0 failed, 1 ignored.

• After the launch-clock commit, cargo test -p codewhale-tui --lib -- tools::subagent: 751 passed, 0 failed.

  • late_launch_permit_still_gets_the_full_work_budget fails (BudgetExhausted) with the clock restart disabled, and passes with it.

• New tests:

  • A Scout runs cd sub && ls, git grep, then git log, and completes.
  • touch evil.txt returns an error result that names program: touch and does not mention Git, Run or /mode. The worker takes another step and completes.
  • When every shell call is refused, the transcript shows (error).
  • For 20 commands, the posture gate, predicate, durable authority and executor give the same answer and byte-identical rule text.
  • gh and npm view reads need the network grant wherever they appear in a command.
  • A late-launched child's saved deadline starts from launch, not spawn.
  • Lexer unit tests cover quoted operators, $ inside double quotes, backslash escapes and redirect edge cases.

• cargo clippy -p codewhale-execpolicy -p codewhale-tui --all-targets --all-features --locked with CI flags: clean.

• cargo fmt --all -- --check: clean.

• check-blocking-calls-budget.py, check-dead-code-budget.py, check-command-crate-boundaries.py and split/module_graph.py --check: pass.

• Changelog sync, web derive, check-versions.sh --range-audit-advisory, check-contributor-credit.py v0.10.0 and vitest lib/public-copy.test.ts (6 passed): pass.

• After the review fixes (62739c9): cargo test -p codewhale-execpolicy --lib command_safety 79 passed, 0 failed; cargo test -p codewhale-tui --lib -- tools::shell tools::registry tools::subagent 972 passed, 0 failed, 1 ignored; clippy with CI flags, cargo fmt --check and the lint gates: clean.

Not run here: the full workspace test suite (CI covers it) and a live Fleet run against a real provider. The 0-step report from 9cdfa92 was not reproduced on current main. The evidence for the fix is the scripted-provider end-to-end tests above.

Suggested squash message

fix(fleet): read-only agents run read-only commands; refusals are actionable (#6015) with a body that describes behaviour only: read-only chains and pipelines of admitted reads run; one read-only shell authority for in-session and durable agents; refusals name the rule and are counted; gh and npm view reads need the network grant wherever they appear in a command; a queued agent that never starts says so, and its work clock starts at launch.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.