feat(fleet): adaptive anti-stall + wider read-only shell grammar (defaults, not per-user config)

[7jrxt42BxFZo4iAnN4CX]

Current Core scope (September 9): adaptive anti-stall and safe read-only shell grammar are admitted in C05/C06 of the Core plan. The earlier postrelease-only/no-broader-grammar restriction is superseded. Preserve one tool/permission authority, test actual stall/recovery behavior, and use model-led effort/resource decisions rather than a new keyword classifier. C20 separately decides the release cut.

---

Problem

Read-only fleet sub-agents (Scout/Reviewer/Planner) stall and burn tokens on today's defaults — no per-user [subagents] edit should be required to fix this.

Rôles recap: 8 roles (role.rs:64-98): Worker (full), Scout/Planner/Reviewer (read-only, role.rs:712-720 — spawn narrows them to a read-only shell), Builder (full), Verifier (dedicated Run surface), Consultant (shell-less even among read-only, role.rs:88, executor.rs:245), Custom (inherits parent). Agent surface maps through a separate alias layer (identity.rs:355-362: explore→scout, implement→builder, general→worker). Per-role deny lists exist (role.rs:14-320); inherit_disallowed_tools: false can never drop a posture denial (SUBAGENTS.md:100, pinned by fleet/exact.rs test) — read-only stays read-only through delegation.

Four root problems:

1. Read-only shell grammar too narrow. command_safety.rs:361 allowlists 21 prefixes + gh … view/list; charset gate (:465+) rejects any command containing ; & | > < $ * ? [ ] { }or newline.sed, awk, find, pipes, cd &&impossible.sed -n '300,400p' f` → rejection → retries → stalls.
2. Rejection isn't treated as no-progress. The agent retries bash variants; stall not detected.
3. Model-step defaults unbounded. [subagents] default_max_steps = 0 = unbounded (SUBAGENTS.md:423-433; FLEET.md:502-503 "must not synthesize"); DEFAULT_MAX_MODEL_STEPS=200 exists only for the exec path (turn_budget.rs:40), fleet workers get None (executor.rs:202). Wall-clock does have a 1800s default — model steps do not.
4. Allow-vs-reject contradiction. Read-only role surface permits exec_shell (executor.rs:325 allow/deny lists empty by default), the grammar then rejects it → model confused, keeps trying.

Real case (2026-09-08, bug-hunt):

• "errors" lens, ~18 files → 85 model steps, ~6M provider input-tokens, repeated context compaction, no report (kept retrying grammar-rejected bash; steps 80-84 alternated read_file/bash/bash/bash).
• "bugs" lens, same task → 30 steps, ~1.4M, via read_file, clean report.
• Why 6M: quadratic growth — each step resends the full growing transcript (169 msgs), compactions re-enter as fresh context; provider input_tokens sums all resends. Real generation was ~35k tokens — the cost is stall + resend, not "the model thought a lot".

Proposed solutions (options for maintainers)

• A. Adaptive anti-stall detector (core). Same action / same rejection N× consecutively (same command shape or error signature) → stalled → force strategy-switch, or stop-with-partial-report / ask operator. No fixed budget → doesn't chop agents making real progress. Needs precise "same action" definition; false positives route to strategy-switch, not kill.
• B. Widen read-only grammar. Add sed -n (never -i), awk (no write), find, sort, uniq, diff; relax | only for allowlisted read-only pipelines; keep banning ; && $() > < and globs. Every addition must be proven mutation-proof.
• C. Rejection-aware role prompt. Read-only roles: "grammar rejection = hard no → use read_file/grep_files/fd". Cheapest; behavior-only.
• D. Truth the surface. Deny exec_shell for these roles (a posture denial — cannot be dropped by inheritance) → removes contradiction #4.
• E. Fallback budgets — NOTE: conflicts with a stated invariant. FLEET.md:502-503 ("must not synthesize a default step budget"). Alert+checkpoint defaults would change that invariant deliberately; flag for explicit decision. Only if A is rejected.
• F. Combination. A+B strongest (mechanism + tooling); C+D cheap first wave; E only if A rejected (and the invariant consciously changed).
• G. Text-review path. Text review (issues, docs, design proposals) is a different job from code review; the fleet reviewer role is code-oriented and read-only-shell-constrained. Route document/issue reviews to a general/custom sub-agent with explicit bounds ("no bash, no code verification", step/output limits, strict output template), or add a dedicated text-review role. Removes the same stall causes from document work.

Use case

Bug-hunt reviewers, same task: 85 steps / 6M / no report (retrying rejected bash) vs 30 steps / 1.4M via read_file. Defaults should catch the first case for everyone — without per-user config, and without chopping agents that are doing real work.

Alternatives considered

• Per-user [subagents] limits: local patch; asks everyone to fix defaults; hard budgets chop working agents.
• Grammar-only (B): removes tool stalls, not "re-reading same files" stalls.
• Prompt-only (C): not a mechanism.
• Do nothing: ~6M tokens per stall, no report.

Impact

Anyone running read-only fleet review/exploration (bug-hunt, security-review, research). Today: unbounded cost per stall (observed 6M tokens, no report). Compatibility: explicit positive budgets must keep winning; the stall detector stops on no-progress, not on budget — preserving "omitted = unbounded".

Open questions

1. A: define "same action" — command-shape hash? tool-call + first-arg prefix? rejection signature? (avoid false positives on legit repeated calls).
2. A: stall action default — force strategy-switch vs partial-report vs ask operator?
3. B: allow | only when both sides are allowlisted read-only? $(...) in read-only context (e.g. cat $(git ls-files))?
4. D: deny exec_shell entirely vs keep the classifier-bounded shell (executor.rs:245 design)?
5. E: since it conflicts with FLEET.md:502 ("must not synthesize"), is changing that invariant acceptable — and what are the alert/kill semantics?
6. Should the anti-stall detector also cover non-read-only roles (Worker/Builder) for "same error retry" loops?
7. Text review: dedicated text-review role vs documented recommendation to use general/custom with explicit "no bash/no code" bounds — which default?

References (verified in fork, upstream/main)

• crates/tui/src/command_safety.rs:361 (allowlist), :465+ (charset gate)
• crates/tui/src/fleet/role.rs:64-98 (roles), :88 (Consultant shell-less), :712-720 (read-only), :14-320 (deny lists)
• crates/tui/src/fleet/identity.rs:355-362 (surface aliases)
• crates/tui/src/fleet/executor.rs:202 (max_turns None), :245 (classifier-bounded shell; consultants shell-less), :325 (allow/deny)
• crates/tui/src/core/engine/turn_budget.rs:40 (DEFAULT_MAX_MODEL_STEPS=200, exec only)
• docs/SUBAGENTS.md:100 (posture denial not droppable), :423-433 (zero = unbounded; 1800s wall)
• docs/FLEET.md:502-503 ("must not synthesize a default step budget")
• Real case: 85 steps / ~6M / no report vs 30 steps / ~1.4M (2026-09-08)

[github-actions]

Thanks @7jrxt42BxFZo4iAnN4CX for the report.

This issue is staying open for maintainer triage. CodeWhale gets better because people bring us real edge cases from real machines, providers, regions, and workflows.

If you can add a reproduction, logs, version output, screenshots, or the provider/model involved, that makes it much easier for us to verify and harvest the fix. Maintainers may comment /lgtmi to mark recurring issue reporters as approved so this intake note is skipped next time.

[7jrxt42BxFZo4iAnN4CX]

Second datapoint — a reviewer child on a small PR review (2026-09-12)

Adding an independent observation to problems 1, 2 and 4 above, in a different shape from the 2026-09-08 bug-hunt case: reviewing a 98-line diff in a foreign repository before opening a PR, rather than a code-wide hunt.

• Role and surface: agent_type=reviewer, runtime_permissions = { write: false, shell: "read_only", network: true }.
• Outcome: 39 steps, provider-reported usage 1,271,849 tokens (1,256,143 input / 15,706 output), no verdict. I interrupted it and did the review myself.
• Rejection text, verbatim: [shell.readonly.command] Tool bash input did not match the bounded read-only shell grammar for Fleet role 'reviewer'. Use read-only inspection commands, or an 'implement'/'general' role for mutation or arbitrary execution.

Rejected, in the child's first two tool batches:

cd /home/f2/Documents/gitHub-forks/Codewhale && git status --short
cd /home/f2/Documents/gitHub-forks/Codewhale && git diff upstream/main...HEAD --stat

Accepted afterwards:

git -C /home/f2/Documents/gitHub-forks/Codewhale status --short

Rejected even though the shape is identical to the accepted one:

git -C /home/f2/Documents/gitHub-forks/Codewhale branch -a --list
git -C /home/f2/Documents/gitHub-forks/Codewhale rev-parse upstream/main

Two details that may be useful for the work:

1. The accepted boundary is not predictable from outside the grammar. The same git -C <path> form is accepted for one subcommand and rejected for another, so the model has to probe to find it — and each probe costs a step plus a full re-send of the growing transcript. Same quadratic shape as the 2026-09-08 case, one order of magnitude smaller.
2. The rejection message routes the model somewhere it cannot go. It suggests using an implement/general role, but a child spawned as reviewer cannot re-spawn itself under a different role, so the advertised escape is not actionable inside the run. The model keeps searching for a command that will be accepted — the allow-versus-reject contradiction in problem 4, now with a concrete instance.

Net effect: the role whose purpose is reviewing a diff could not complete a review of a 98-line diff, and the parent session paid ~1.27M input tokens for that outcome. The child transcript and step log are retained if they would help.

[7jrxt42BxFZo4iAnN4CX]

Refinement after reading the grammar

Following up on the datapoint above with the mechanism, because it changes what I would ask for.

Both rejections I reported are explained by crates/execpolicy/src/command_safety.rs, and neither is an inconsistency:

• The charset gate rejects any command containing ; & > < $ ? [ ] { } ( )or a newline, socd && git …` cannot pass by construction.
• git -C <dir> is admitted explicitly (is_agent_readonly_git): the --no-pager and -C <dir> preambles are stripped and the remainder re-enters the per-subcommand table, which admits exactly status, log, diff, show, ls-files, blame, grep.

So git -C … status --short passes while git -C … branch -a --list and git -C … rev-parse … do not — because those subcommands sit outside the table, not because the -C form is treated inconsistently.

For the sed half of problem 1: 36b5b5d85 ("admit bounded sed inspection through worker authority") is already in main, so that gap is closed — my run happened with it present, and the rejections were the git/&& boundary above.

What I would ask for, then, is discoverability rather than more width. The admitted set is fixed and reasonable, but a reviewer/scout child has no way to see it: the rejection text names the role and points at a role the child cannot switch to, and I could not find the admitted command set in the child's visible surface (shell tool description or role prose). The model is left to probe, and every probe costs a step plus a full re-send of the growing transcript — the amplification problem 2 describes.

Either of these removes the probing:

• name the admitted set, or the rule that rejects, in the rejection text itself or in the shell tool's description when the policy is read-only; or
• treat a repeated grammar rejection as the no-progress signal from option A, so the child switches strategy or stops with a partial report instead of iterating.

One detail that may be relevant to problem 4: Scout/Reviewer resolve with ShellPolicy::Full in worker_profile.rs and are then narrowed by the registry's read-only classifier — which is why the refusal names the role. That indirection is likely part of why the boundary is hard to reason about from the model side.

[Hmbown]

A bounded anti-stall aid landed in 7a1d1ca: read-only workers now receive command guidance both when discovering the shell tool and when a command is denied. The examples are derived from the existing accepted grammar, explain using the working-directory argument instead of compound shell expressions, and tell the worker to return an essential blocked probe to its parent. A child cannot promote its own permissions.

Discovery/denial regression coverage passed in the complete local suite (15,416 Rust tests, zero failures). This change does not widen the grammar or add an adaptive stall/retry controller; those larger parts remain open.

[Hmbown]

Status (v0.9.14 run): not reached in this slice; remains open (fleet anti-stall + shell grammar).

[Hmbown]

Landed on v0914-chunk2 in f088466d3 (pushed; on PR #6175).

What changed: child sub-agent workers now run the same FleetDenialGuard as the parent turn — no second policy loop.

• Every admission refusal in SubAgentToolRegistry::execute_full (posture, catalog scope, network, claim, coordination, held-call) is now a typed ToolError::PermissionDenied instead of an opaque anyhow, so the guard can name it. This is what makes the [shell.readonly.command] grammar rejections guard-visible.
• The worker loop feeds each tool outcome into a per-response FleetDenialBatch → finish_batch: 3 no-progress denied rounds inject the strategy-switch notice as append-only history; 3 more held rounds flip to a report-only response (tool_choice: "none" + admission holds any emitted calls); the report response then terminates the worker as Failed with "Fleet worker stopped after repeated permission denials without new evidence." — never BudgetExhausted.
• User steering or a child completion resets the guard (changed direction); cancellation and genuine budget exhaustion keep their existing provenance.
• Engine notice/stop strings are now shared constants so parent and child agree verbatim.

Evidence: cargo check -p codewhale-tui --all-targets --locked clean; cargo fmt --all -- --check clean; new regression repeated_typed_denials_stop_worker_as_failed_not_budget drives a Scout through 6 denied/held rounds + the report response → asserts Failed at exactly 7 model calls, and was verified failing (Completed) with the impl reverted. The 8 existing fleet_denial_* guard tests still pass. Also repaired three pre-existing branch-red surface fixtures in 7f99fa895 (session recall tools drifted INSPECTION/COUNSEL/VERIFICATION/DOER and the parent byte ceiling).

Scope note: catalog-miss calls ("not in this child's catalog"/"not active") still return generic errors — a hallucinated-tool stall is a different class from permission denial and stays out of the guard, matching the engine.