coding-cli-management

# Coding CLI Management This skill enables the delegating agent (Manager, team Leader, or an authorized Worker) to execute AI coding CLI tools (claude/gemini/qodercli/qwen/opencode) on behalf of Workers. Workers generate precise prompts; the delegating agent runs the CLI in the Worker's workspace and returns the result. Operational guidance distilled from field operation, in two parts, both detailed in [`references/delegation-guidance.md`](references/delegation-guidance.md) — Part A (first increment, currently supported): task-spec discipline, auth and execution boundary, preflight checks (including runner placement), and a pitfalls list; Part B (later capabilities, not yet implemented, evaluated separately): supervision and steering (including the delivery and wake contract), approval expectations, and a pitfalls list. ## Config File Path: `~/coding-cli-config.json` — this is the **delegating agent's own** config file (the agent running this skill), not a shared one. ```json { "enabled": true, "cli": "claude", "confirmed_at": "2026-02-23T10:00:00Z" } ``` | `enabled` | `cli` | Meaning | |-----------|-------|---------| | `false` | any | Admin declined; use normal task flow | | `true` | `"claude"` / `"gemini"` / `"qodercli"` / `"qwen"` / `"opencode"` | Active — use this CLI | Optional budget / execution-boundary fields (consumed by `run-coding-cli.sh` for `qwen` only — the other runners have no equivalent and ignore them): | Field | Type / default | Meaning | |-------|----------------|---------| | `max_session_turns` | integer, default absent / `0` (flag not passed) | Caps the qwen run at N model turns (`--max-session-turns <N>`); a run that reaches the cap terminates at the budget | | `sandbox` | boolean, default `false` | Adds `--sandbox` (Docker-backed) to the qwen run. Requires docker at the execution site — leave off where docker is unavailable (as in many agent containers) | | `approval_mode` | string, default `yolo` | Approval tier for the qwen run: `yolo` → `--yolo` (the default, byte-identical to the pre-boundary wrapper); `plan` / `default` / `auto-edit` / `auto` → `--approval-mode <tier>`. In a non-interactive one-shot run only `yolo` and `plan` actually work — the ask tiers stall (see Execution boundary below). An invalid value fails the run with the valid values listed; there is no silent fallback | | `max_wall_time` | string, default absent (flag not passed) | Native qwen wall budget → `--max-wall-time <val>` (qwen value formats: `90` / `30s` / `5m` / `1h` / `1.5h`); qwen aborts an over-budget run with exit code 55. The wrapper's `--timeout` remains the hard backstop for all runners | Config example (tight one-shot boundary — read-only plan + 30-minute native wall budget): ```json { "enabled": true, "cli": "qwen", "approval_mode": "plan", "max_wall_time": "30m" } ``` The config path can be overridden with the `CODING_CLI_CONFIG` environment variable (the verify script uses this for its turn-budget case). **Per-run governance flags (qwen).** `run-coding-cli.sh` accepts optional per-run control flags for the qwen runner (other runners warn and ignore them — they have no equivalent surface): | Flag | Maps to | Effect | |---|---|---| | `--model <name>` | `-m` | per-run model override — the task-level tier of two-tier model control (platform default from the runner's settings, per-task switch here) | | `--allowed-tools <csv>` | `--allowed-tools` | tool allowlist — a **code-level** permission boundary, independent of prompt discipline | | `--allowed-mcp <csv>` | `--allowed-mcp-server-names` | MCP server allowlist — scenario isolation (e.g. only this task's toolchain MCP) | | `--safe-mode` | `--safe-mode` | disable all customizations (hooks, extensions, skills, MCP, QWEN.md) — clean-environment runs | | `--bare` | `--bare` | minimal mode | | `--approval-mode <tier>` | `--yolo` / `--approval-mode <tier>` | execution-boundary tier for the qwen run (`plan` / `default` / `auto-edit` / `auto` / `yolo`). Precedence: per-run flag > config `approval_mode` > `yolo` default. An invalid tier fails the run with the valid values listed (no fallback) | | `--max-wall-time <val>` | `--max-wall-time <val>` | native qwen wall budget (value formats `90` / `30s` / `5m` / `1h` / `1.5h`); an over-budget run aborts with exit code 55. Precedence: per-run flag > config `max_wall_time` > unset (flag not passed) | Use the runner's own init frame (`-o json` prints a `tools` array and `permission_mode`) to size an allowlist from the actual capability list rather than from memory. The five governance flags were field-verified on qwen 0.25.0 (safe-mode banner, emptied MCP list, per-run model override observed in one run). `--approval-mode` / `--max-wall-time` were field-verified on qwen 0.25.1 (one-shot plan-tier read boundary, and the native exit-55 wall-budget path observed end to end through this wrapper), and the wrapper's arg assembly for all seven is covered by `manager/tests/test-run-coding-cli-exec-boundary.sh`. **Updates.** Re-run the npm install command to upgrade in place, or use the runner's built-in `qwen update` self-update command (see `qwen update --help` for its channel behavior). Either way, re-run `verify-coding-cli.sh` afterwards (upgrade discipline above). **Runner notes (Qwen Code / OpenCode).** Headless invocations used by `run-coding-cli.sh`: `qwen --yolo "<prompt>"` and `opencode run --auto --dir <workspace> "<prompt>"`. Config surfaces: `~/.qwen` (`settings.json` `security.auth`, or provider env) and `~/.config/opencode` plus `~/.local/share/opencode/auth.json` (credentials stored by `opencode auth login`) or provider env. Both runners were verified with a headless round trip before inclusion. Qwen Code has **no fixed pin**: deployments choose their own npm channel tag (Section below, stable by default); `0.25.1` is the most recent field-verified reference (2026-10-11, Pi arm64/node 24 LTS end-to-end), `0.25.0` the previous one. Re-run `verify-coding-cli.sh` whenever the version actually used changes. **Version behavior note (0.25.1, field-verified by request capture):** the built-in default model changed to `qwen3.7-max`; a settings file carrying only `security.auth` (plus even an explicit `model.name`) still produced requests for `qwen3.7-max`. On a custom OpenAI-compatible gateway that does not serve that model this surfaces as `API Error: 403 (no body)`. Managed deployments: pass `-m <model>` per run (or the `--model` flag of `run-coding-cli.sh`) rather than relying on a settings-level default. **Platform note (16K-page arm64, e.g. Raspberry Pi 5, kernel `PAGESIZE=16384`):** the vendored ripgrep arm64 binary crashes on startup (`jemalloc: Unsupported system page size`, core dump); `qwen` logs it and falls back to the built-in grep, so runs complete — expect the stderr noise and core files, and do not treat them as run failures. Upstream issue pending. - --json-file <path> — optional structured output: the final result JSON is written to <path> for machine audit; default off, raw stream still tees to the run log (the audit source of truth when the flag is absent). **Version channels and upgrades (Qwen Code).** qwen-code iterates fast (several hundred npm versions published) and ships three channels as dist-tags: `latest` (stable), `nightly` (dated + commit, published daily), and `preview`. Install or upgrade with npm (Node.js **24 LTS** — floor 22.20+ / 24.5+, OpenSSL 3.5 generation; see the Node-generation note in the install matrix), choosing the channel per the user's preference — stable by default, nightly only when the user explicitly wants newer behavior: ```bash npm install -g @qwen-code/qwen-code@latest # stable npm install -g @qwen-code/qwen-code@nightly # nightly ``` Re-running the same command upgrades in place; `qwen --version` confirms the result. **Upgrade discipline: after any version change — including a channel switch — re-run `scripts/verify-coding-cli.sh`; a channel switch is a pin promotion and needs the same verification.** The official standalone installer and Homebrew are fine for interactive use; the verify discipline above is defined for the npm channel. **Install matrix and network environment.** Three official installers; pick by what the execution site has (a Node.js generation requirement applies to the npm channel, below): | Installer | Requires | Version selection | |---|---|---| | npm: `npm install -g @qwen-code/qwen-code@<tag>` | Node.js **24 LTS** (floor 22.20+ / 24.5+, OpenSSL 3.5 generation — see note) | channel tag (`latest` / `nightly` / `preview`) — the route this skill's verify discipline is defined for | | official standalone script: `curl -fsSL https://qwen-code-assets.oss-cn-hangzhou.aliyuncs.com/installation/install-qwen-standalone.sh \| bash` (Windows: `irm …install-qwen-standalone.ps1 \| iex`) | bash, no Node | the build the script ships; re-run to refresh | | Homebrew: `brew install qwen-code` | brew | brew's current release | npm and the release assets cover Linux x64/arm64, macOS x64/arm64, and Windows. Restart the terminal after a standalone install so the PATH entry takes effect. **Node generation matters on restrictive links.** The npm package runs on Node.js; early Node 22.x (22.0–22.19) bundles OpenSSL 3.0, whose TLS client fingerprint is reset by some middle boxes, while Node 22.20+, 24.5+ and 26 bundle OpenSSL 3.5 and pass. **Use Node 24 LTS as the target** — Node 25 is EOL (2026-06), do not provision it; the 22-series needs 22.20+, the 24-series 24.5+. Field-verified 2026-10 (the cctechstudio WAN line RSTs the 3.0 generation but not 3.5). The filter matches the full ClientHello fingerprint (stack + ALPN + extensions), not the OpenSSL version alone: in the same environment an h2-enabled curl was reset while a Node runtime — and even a plain `openssl s_client` — connected. If in doubt, verify with the runtime that will actually make the connection, and check the Node/OpenSSL generation first (`node -p "process.versions.openssl"`). **Model configuration.** `qwen` authenticates from `~/.qwen/settings.json` — `security.auth` with `selectedType` (`openai` / `openai-responses` / `anthropic` / `qwen-oauth` / `gemini` / `vertex-ai`) plus `apiKey` and, for OpenAI-compatible endpoints, `baseUrl` — the form headless delegation uses on self-hosted or gateway-backed deployments (or the `OPENAI_API_KEY` environment variable). The interactive `qwen auth` flow was removed in 0.25.0, so file/env configuration is the only path; `--auth-type <type>` selects the scheme per run. Any OpenAI-compatible endpoint is a valid `baseUrl` — including a **transparent local proxy**, which is the standard lever for keeping the model plane working behind a restrictive link. Per-run overrides: `-m <model>` to pick a model and `-o text|json|stream-json` for machine-readable output. **Restricted-network note.** If installing or reaching the model endpoint fails with connection resets while plain `curl` from the same machine succeeds, suspect middle-box filtering by TLS-stack fingerprint rather than a plain outage; running a current Node (OpenSSL 3.5 generation) or routing the model plane through the local proxy above is the working fix. (Field-verified 2026-10; see #1340 notes 4/5 for the full deployment matrix.) **OpenCode is a Bun binary, not Node.** Its TLS client is Bun's (a BoringSSL-lineage stack), not Node's OpenSSL, so on the restrictive lines above OpenCode's *own* connection can be reset by the middle box even where a Node/OpenSSL-3.5 runner (Qwen Code) on the same machine passes. Field-verified 2026-10-10 on the cctechstudio WAN line: `qwen` (Node 24) reached the endpoint and completed a task while `opencode 1.18.35` was RST ("socket connection closed unexpectedly") on the identical link, at the same moment — the only variable being the client's TLS stack. For OpenCode the "use a current Node" advice does not apply (it is not Node, and its TLS stack is not user-selectable); the working lever is the **transparent local relay/proxy** in front of the model endpoint — point OpenCode's `baseURL` (or `OPENAI_BASE_URL`) at the same-machine proxy that holds a working TLS stack. Re-verified 2026-10-11 with `opencode 1.19.0` inside an arm64 worker container (node 24 LTS): Bun binary RSTs the WAN link, same-container loopback relay (node 24) → gateway → full coding task green. **Config location (1.19.0, field-verified):** provider config is loaded from the **project-level** `<workspace>/.config/opencode/opencode.json` (or `.jsonc`); a global `~/.config/opencode/opencode.json` is not picked up by `opencode run --dir <workspace>` (log shows only the project paths loaded) — an unrecognized provider then fails as `ProviderModelNotFoundError`. For headless delegation, keep the provider config project-level next to the workspace. **Unattended semantics — read before enabling.** - `qwen --yolo` automatically approves **all** tool calls — file edits and shell commands included, with no further prompts. - `opencode run --auto` auto-approves permissions, but **explicit deny rules are still enforced**. - `qodercli --yolo` bypasses prompts **only in a trusted directory**: in an untrusted workspace it silently falls back to `default` mode, where every would-ask operation is **auto-denied in headless** — the run degrades to read-only with no error. Org policy `security.disableYoloMode` disables `--yolo` entirely. - **Neither changing the working directory nor adding a timeout establishes a permission boundary.** The workspace and the timeout shape scope and duration only; the runner keeps every capability of the delegating agent's process. --- ## Execution boundary The CLI process runs **as the delegating agent** (Manager, team Leader, or an authorized Worker). It therefore inherits that agent's filesystem visibility and its environment — including any credentials present as environment variables — and nothing in this skill changes that. When deciding whether to enable CLI delegation, assess at least: - **Workspace access scope** — the run is pinned to the task workspace, but a runner in auto-approve mode can reach anything the delegating agent's account can. - **Other teams' files** — anything on the shared filesystem the delegating agent can read or write (e.g. other tasks' directories). - **Delegating agent's credentials** — API keys and tokens in the agent's environment are visible to the CLI process. - **Mounted container sockets** — a mounted `docker.sock` (or equivalent) gives the CLI effective host-control capability. - **Admin-plane capability** — any orchestration/admin CLI or API the delegating agent can use is equally available to the runner. Mitigations, in three tiers: 1. **Approval tiers (native).** Qwen Code: `--approval-mode` levels (plan / default / auto-edit / auto / yolo); lower tiers keep prompts on destructive shell and outbound calls. Configurable from this wrapper: `run-coding-cli.sh --approval-mode <tier>` per run, or `approval_mode` in the config (per-run wins; default `yolo`, so an unchanged caller gets a byte-identical qwen argv). **One-shot usability boundary:** a non-interactive run has no approver, so only two tiers are usable there — `yolo` (approve everything, the default) and `plan` (the genuinely usable read-only tier: the run produces a plan and does not execute; field-verified on qwen 0.25.1 — and note the read scope stays pinned to the run's workspace: non-interactive reads of files outside `--workspace` are declined by the permission policy rather than prompted, so the prompt must reference workspace-relative paths or place inputs inside the workspace). `default` / `auto-edit` / `auto` route would-ask calls to an approver that never answers headless, so the run stalls; they are documented for interactive or supervised use and are deliberately **not** a wrapper default. The `plan` tier also satisfies the wrapper's UNGOVERNED detection: a read-only run is treated as governed even without a turn budget, sandbox, or tool allowlist. OpenCode: permission rules with `allow` / `ask` / `deny` actions, including command-prefix granularity (e.g. deny `rm ` while allowing `git ` / `npm `); `opencode agent create` can produce a scoped agent whose frontmatter denies everything not allowed. 2. **Native sandbox (opt-in).** Qwen Code ships a Docker-backed sandbox (`--sandbox` / `QWEN_SANDBOX=1`) that runs shell/write/edit tools inside a sandbox image — **it is NOT auto-enabled by `--yolo`**; an un-sandboxed yolo run prints a warning to stderr, which lands in the run log. It requires docker at the execution site; where there is none (as in many agent containers) the flag must stay off. OpenCode has no native sandbox — its boundary is tier 1 plus tier 3. 3. **Isolated execution environment (the baseline for skip-permissions-class flags).** Industry practice (Anthropic's own guidance for `--dangerously-skip-permissions`, and public incident reports from unsandboxed auto runs) is to run such sessions only in isolated environments — a dedicated container/VM/ephemeral runner — with budgets (`--max-session-turns` / wall time) so a stuck run cannot burn the host. In that case the delegating agent's ambient credentials and sockets should not be mounted into the environment at all. Both budget levers are configurable from this wrapper: the turn cap via `max_session_turns` (Config File above), and the wall budget via `max_wall_time` in the config or `--max-wall-time <val>` per run (qwen value formats `90` / `30s` / `5m` / `1h` / `1.5h`). qwen enforces the wall budget natively and aborts an over-budget run with **exit code 55**; the wrapper's outer `--timeout` (default 3600 s) remains the hard backstop for every runner, while the native budget is a tighter, runner-aware bound for qwen. No new approval subsystem is introduced by this skill.