Shell execution Phase 1: the run_command lane, and a never-list that parses with the standard library

[0x-copilot-dev]

Builds the vertical Phase 0 declared — a run_command tool the model can actually call — and then reduces the floor it landed with.

The lane

capabilities/shell/ holds the tool, the executor, the PEP, the never-list floor and the env allowlist; runtime_worker/shell_composition.py is the single wiring site; the desktop side projects a per-workspace shell bit with WorkspaceShellAccess as its settings surface.

Two properties are load-bearing and easy to dissolve in a later refactor, so they're named here:

• never_list.screen() runs PRE-PDP (policy_gate.py:285). A never-listed command is refused, not offered to a human. Being asked to approve sudo rm -rf / is a worse design than being refused.
• The executor uses exec, not shell=True. That's a security property, not a style choice: it's what keeps a smuggled ; from chaining inside one process.

Then: the floor parses with the standard library

~400 lines of hand-rolled CommandToken / CommandLexer / _read_single / ParsedCommandLine._split are gone, replaced by re.split on the chaining operators plus shlex per segment.

The old lexer's docstring gave three reasons shlex wouldn't do. Two dissolved:

• "shlex raises on an unbalanced quote" — catch it and refuse. Failing closed beats the total lexer running to end-of-string, and the corpus scores it as a strict improvement: cat 'unbalanced was allowed by the old floor and is refused now.
• "shlex discards operators" — true of the convenience wrapper only. Split on the operators first and the && vs | distinction survives.

The third — raw token spelling — is real and kept, because three call sites need it: always_grant_patterns must not offer a glob for a quoted head ("sudo" rm -rf /), and the two credential-path rules check both spellings.

_fork_bomb deliberately stays a raw-string check. :(){ :|:& };: tokenises to garbage under shlex, which doesn't model function definitions — a hazard that is a syntactic form rather than an executable name can't be asked of the tokens.

Coverage was measured, not assumed

81 commands through both the old floor and the new one:

	count
refused by both	41
refused by new only (improvement)	2
allowed by new, refused by old (regression)	0
allowed by both	38

And the product check that mattered: pytest -q, npm test, git status, make build, cargo test all still reach the ASK tier rather than being hard-refused. The vendored allow-list is 25 readers and contains none of those — making it the gate would have stopped the agent running your test suite, which is the whole point of the feature.

A built-and-never-called helper, now delivered

ShellCommandExecutor.timeout_note was written, unit-tested, and had no product caller. So a timed-out command reached the model with exit_code absent entirely (exclude_none drops the null) and no prose at all — the model could not distinguish a timeout from a refusal, nor learn that a larger timeout_s exists. _result now attaches it, and TestTimeoutIsExplained asserts it through the tool, so un-wiring it fails again instead of going quiet.

Dark-wiring rows

Three baselined with hand-written reasons. Two are scan blind spots and say so: RunCommandResult.exit_code originates as await process.wait() bound to a same-named local, so every hop the scanner can see looks like a copy of itself; reason is originated by ten product sites and projected through one reason=self.reason. The third, auto_approvable, is genuinely dark on purpose — it's the AUTO tier, and Phase 1's rule is that every command asks.

Known gaps, stated rather than buried

Found by the corpus run, pre-existing in both floors — not regressions from this change, and not fixed here:

• The NEVER tier protects only / and ~ as rm targets. rm -rf /usr, /etc, /var, /Users all pass to ASK.
• 15 clearly-not-ordinary commands reach ASK rather than NEVER, including cat ~/.config/gh/hosts.yml (a live OAuth token), cat /etc/shadow, chmod -R 777 /, and python -c 'import os;os.system("rm -rf /")'.

Also honest about the reduction itself: never_list.py's code shrank 646 → 529 lines (−117), but gained 245 lines of docstring, so the file is net +124. The prose wants trimming.

Tests

619 shell (+4), 10,782 ai-backend unit, 1,688 chat-surface, 802 desktop. check_dark_wiring.py and check_service_boundaries.py green.

Two ai-backend failures are local-only worktree venv skew (deepagents 0.7.1 installed vs 0.7.4 pinned, langgraph 1.2.9 vs 1.2.10) — they compare installed-to-pinned versions and pass in CI, which installs the pins.

🤖 Generated with Claude Code