Summary

This PR rebuilds POSIX command authorization on the Tree-sitter command model. The ad hoc shell splitter that previously decided allowlist matches and allow-always persistence is replaced by a candidate planner (planShellAuthorization) built on the Tree-sitter-backed explainShellCommand, so authorization, persistence, and shell rewriting all read one parsed view of the command instead of three approximations of it.

• replace the ad hoc POSIX authorization path with a Tree-sitter-backed command candidate planner; src/infra/exec-approvals-analysis.ts shrinks from ~1300 lines to a thin re-export shim, with parsing now owned by exec-authorization-plan.ts / exec-authorization-render.ts
• route shell/argv allowlist checks, allow-always persistence, and enforced-command rewriting through planned candidates, including static shell-wrapper payloads
• convert exec control-shell policy to a generic static command matcher over normalized argv/options/operands

Because the planner can now prove what a command does (or admit it cannot), approval trust gets safer as a consequence:

• reusable executable patterns persist only when plan coverage shows the command is fully represented; otherwise the approval stays one-shot
• optional unavailable approval decisions (unavailableDecisions) travel from the requesting host through the gateway protocol, and the gateway derives the rendered allowedDecisions snapshot so approval surfaces only offer decisions that can actually be honored

One parsed command model

flowchart LR
    CMD["raw shell command"] --> TS["explainShellCommand<br/>Tree-sitter parse"]
    TS --> PLAN["planShellAuthorization<br/>candidates + transports + trust modes"]
    PLAN --> AL["allowlist evaluation"]
    PLAN --> PERSIST["allow-always persistence<br/>coverage proof"]
    PLAN --> REW["enforced command rewrite"]
    OLD["old: ad hoc splitter<br/>re-derived per consumer"] -. replaced .-> PLAN

Before this PR, allowlist matching, persistence, and shell rewriting each re-derived command structure through the string splitter in exec-approvals-analysis.ts, and they could disagree. Now the plan is computed once and carried into every consumer; Windows keeps its dedicated analyzer (windows-shell-command.ts, moved out of the old monolith) because cmd/PowerShell parsing genuinely differs.

How an approval flows

sequenceDiagram
    participant H as Agent host (gateway/node exec)
    participant P as Authorization planner
    participant G as Gateway server
    participant U as Approval surfaces (UI, push, channels)

    H->>P: planShellAuthorization(command)
    P-->>H: candidates + trust modes + coverage
    H->>H: resolveAllowAlwaysPersistenceDecision
    H->>G: exec.approval.request (command, ask, unavailableDecisions)
    G->>G: derive allowedDecisions from ask policy<br/>minus unavailable optional decisions
    G->>U: snapshot with allowedDecisions
    U->>G: resolve(decision)
    G->>G: reject decision not in allowedDecisions
    G-->>H: decision
    H->>H: persistAllowAlwaysDecision (patterns / one-shot)

The requester is the only side that knows whether persistence is safe (it has the prepared argv, transport wrappers, platform, and coverage analysis), so it can mark optional approval decisions unavailable with the new unavailableDecisions request field. Today that list can only contain allow-always; allow-once and deny remain server-owned baseline decisions. The gateway normalizes the request, derives the allowedDecisions snapshot for renderers, and re-validates resolution server-side, so a client that ignores the narrowing still cannot push through a disallowed allow-always.

How allow-always persistence is decided

flowchart TD
    A["allow-always chosen"] --> B{"Plan has hard blockers?<br/>runtime payload, prompt-only, unplanned"}
    B -- yes --> OS["one-shot<br/>nothing persisted"]
    B -- no --> C{"Reusable pattern coverage<br/>complete for every candidate?"}
    C -- yes --> PAT["persist executable patterns"]
    C -- no --> OS
    PAT --> R["future runs auto-allowed via allowlist"]

On the gateway host, allowlisted commands whose execution plan cannot be safely rewritten (requiresAllowlistPlanApproval) are downgraded to one-shot approval. Pattern-based durable trust deliberately does not bypass that gate, because enforcement cannot pin the resolved executables for an unenforceable plan.

Decisions and rationale

• POSIX shell authorization now comes from one planned command model: planShellAuthorization() uses the Tree-sitter-backed explainShellCommand() path, and the plan is carried into allowlist evaluation, allow-always persistence, and shell rewrite. The old POSIX splitter/render fallback is no longer an alternate source of candidates.
• unavailableDecisions is additive protocol: optional field, enum-validated, and currently typed to the only optional exec approval decision (allow-always). Old or native clients that never send it keep the ask-derived behavior. The gateway still stores and publishes computed allowedDecisions for UI/rendering and resolve validation.
• Safe bins are treated as narrow, argument-profiled execution shortcuts, not blanket shell trust. Dynamic shells, command substitution, line continuations, path-scoped wrapper payloads, and pipe-to-shell cases remain approval-gated unless the whole relevant command graph is allowed.
• Static reads under .ssh / ~/.ssh through basic read commands are approval-required hard-coded control policy.
• Background & is preserved as shell topology; the planner models it as a background relationship instead of failing closed.
• deny still wins when deny-mode policy is active.

Behavior changes

• Static POSIX shell wrappers like sh -c 'git status' can now be authorized by the inner git candidate when the payload is static and safely parsed.
• Dynamic wrappers like sh -c '$CMD', command substitution, line continuations, and path-scoped wrapper payloads stay approval-gated instead of becoming reusable inner approvals.
• Commands that cannot be safely persisted no longer offer Always Allow anywhere (Control UI, native push, channel approvals); they offer Allow Once / Deny.
• curl URL | sh behavior is preserved: both sides must be allowed for auto-run; allow-always persists curl only; persisted curl alone does not authorize the shell side on rerun.
• Gateway commands whose allowlist plan cannot be safely rewritten no longer offer Always Allow; they stay Allow Once / Deny.
• ask=always approval requests no longer offer an unusable Always Allow action.
• Exec control-shell policy denies OpenClaw channel login commands and requires approval for security audit suppression mutation through the same normalized command matcher.

Protocol and storage

• unavailableDecisions is an optional gateway protocol request field; no version bump required. Computed allowedDecisions remains in stored/request snapshots for approval renderers.
• Persisted approvals files are read unchanged.
• No config surface added.

Known follow-up

Node system.run keeps the shipped behavior of auto-running allowlist-satisfied POSIX shell payloads even when the authorization plan cannot rebuild an enforced command (src/node-host/invoke-system-run-allowlist.ts, resolveSystemRunExecArgv). The gateway host is now stricter for the same case (requiresAllowlistPlanApproval). Extending the plan-unavailable approval gate to the node daemon is deliberate follow-up work, not part of this PR, to keep the diff bounded; node behavior is unchanged from shipped releases.

Verification

Behavior addressed: plan-based command authorization with provable allow-always persistence and decision narrowing across all approval surfaces.

Real environment tested: local macOS focused suites on current head (824c85b), including the final unavailableDecisions protocol change.

Exact steps or command run after this patch:

PATH=/Users/jmerhi/.nvm/versions/node/v24.12.0/bin:$PATH node scripts/run-vitest.mjs packages/gateway-protocol/src/exec-approvals-validators.test.ts src/infra/exec-approvals-policy.test.ts src/gateway/server-methods/server-methods.test.ts src/agents/bash-tools.exec-host-node.test.ts src/agents/bash-tools.exec-host-gateway.test.ts --reporter=verbose
PATH=/Users/jmerhi/.nvm/versions/node/v24.12.0/bin:$PATH corepack pnpm tsgo:prod
PATH=/Users/jmerhi/.nvm/versions/node/v24.12.0/bin:$PATH corepack pnpm exec oxfmt --check packages/gateway-protocol/src/exec-approvals-validators.test.ts packages/gateway-protocol/src/schema/exec-approvals.ts src/agents/bash-tools.exec-approval-request.ts src/agents/bash-tools.exec-host-gateway.test.ts src/agents/bash-tools.exec-host-gateway.ts src/agents/bash-tools.exec-host-node.test.ts src/agents/bash-tools.exec-host-node.ts src/gateway/server-methods/exec-approval.ts src/gateway/server-methods/server-methods.test.ts src/infra/exec-approvals-policy.test.ts src/infra/exec-approvals.ts
git diff --check
.agents/skills/autoreview/scripts/autoreview --mode local --prompt 'Context for compatibility review: the removed exec.approval.request allowedDecisions input was introduced only on this unmerged PR branch. origin/main packages/gateway-protocol/src/schema/exec-approvals.ts has neither allowedDecisions nor unavailableDecisions on ExecApprovalRequestParamsSchema, and origin/main src/agents/bash-tools.exec-approval-request.ts sends neither field. OpenClaw policy does not preserve branch-local/unshipped protocol fields. Do not flag backward compatibility for rejecting the PR-local allowedDecisions input.'

Evidence after fix: targeted Vitest passed 4 shards covering protocol validation, approval policy helpers, gateway approval handlers, and node/gateway host approval behavior; pnpm tsgo:prod exited 0; oxfmt --check exited 0 on the touched TypeScript files; git diff --check exited 0; autoreview reported no accepted/actionable findings after verifying allowedDecisions was PR-local and unshipped.

Observed result after fix: unpersistable commands offer Allow Once / Deny only; allow-always on a coverage-complete command persists executable patterns; unenforceable allowlisted commands stay one-shot; requesters disable only optional exec decisions through unavailableDecisions, while gateway snapshots still expose computed allowedDecisions.

What was not tested: Windows-native end-to-end exec; full GitHub CI for current head.