Skip to main content

mur_common/
cli_backend.rs

1//! CLI-spawn backend registry.
2//!
3//! One row per coding CLI MUR can drive. The registry is data, not code
4//! paths: Gemini CLI was replaced by Antigravity inside a year, and the
5//! design records that hardcoding per-CLI flags guarantees rewriting this on
6//! the next replacement.
7//!
8//! A row exists only when every field is known. `agy`'s home env var and the
9//! `codex` / `agy` streaming envelopes are still open questions in
10//! `docs/superpowers/specs/2026-09-16-cli-spawn-backends-design.md`, so those
11//! rows are absent rather than half-filled — an unknown field here would be
12//! read as fact by every consumer.
13//!
14//! Nothing in this module spawns a process or reads the user's CLI config.
15
16/// How a backend's MCP configuration reaches the CLI.
17#[derive(Debug, Clone, Copy, PartialEq, Eq)]
18pub enum McpMount {
19    /// Flags on every invocation; nothing is written to disk.
20    PerCall,
21    /// Written once into the backend's private home.
22    Persistent,
23}
24
25/// Whether MUR may actually drive this backend.
26///
27/// Separate from binary presence on purpose. The spec's activation gate reads:
28/// "Failure or unknown results keep the backend disabled; binary presence is
29/// insufficient." A disabled backend is still listed and still rendered — it
30/// is the panel that carries the explanation and the controls, so hiding it
31/// would strand the user exactly as hiding a subscription provider did.
32#[derive(Debug, Clone, Copy, PartialEq, Eq)]
33pub enum Activation {
34    Enabled,
35    /// `reason` is shown to the user. It names the unmet requirement.
36    Disabled {
37        reason: &'static str,
38    },
39}
40
41/// One CLI-spawn backend, as data.
42#[derive(Debug, Clone, PartialEq, Eq)]
43pub struct CliBackend {
44    /// Stable identifier used in paths and UI keys.
45    pub key: &'static str,
46    /// Executable name, resolved against the user's shell PATH by the caller.
47    pub binary: &'static str,
48    /// Flags that put the CLI in headless mode.
49    pub headless_invocation: &'static [&'static str],
50    /// Flags that select a machine-readable streaming envelope.
51    pub stream_flags: &'static [&'static str],
52    /// Flags that disable the CLI's own built-in tools.
53    pub tool_disable_flags: &'static [&'static str],
54    pub mcp_mount: McpMount,
55    /// Environment variable that relocates this CLI's home.
56    pub home_env_var: &'static str,
57    pub activation: Activation,
58    /// Free text for the panel: what is known, and what is not.
59    pub capability_notes: &'static str,
60}
61
62/// `claude`, measured at 2.1.273 by running it, not only by reading `--help`.
63///
64/// `tool_disable_flags` is `--tools ""`, not `--disallowedTools`: the latter
65/// is a named deny list, and denying `Bash` merely sent the model to `Glob`.
66///
67/// Both halves of the disable are required. `--tools ""` alone left 44 tools
68/// mounted — every MCP server in the user's own config — so the flags below
69/// are the pair, and `--strict-mcp-config` is load-bearing. Verified from the
70/// `system init` event's `tools` array, which reported `[]`.
71///
72/// Enabled as of the CLI-spawn backend. The reason moved three times before
73/// it could be: the tool probe, then serving tools over MCP, then the spawn. The
74/// probe is answered; MUR does now serve its tools over MCP (`tools/list`,
75/// `tools/call`, and the shim that forwards to them). What is missing is the
76/// other half: nothing writes the per-turn `--mcp-config` and nothing runs
77/// the CLI, so this row describes a backend that could work rather than one
78/// that does.
79///
80/// Keep this sentence true. A row whose stated reason outlives the thing it
81/// described is worse than a bare `false` — it explains itself confidently
82/// and wrongly, and a user reading the panel has no way to tell.
83pub const CLAUDE: CliBackend = CliBackend {
84    key: "claude",
85    binary: "claude",
86    headless_invocation: &["-p"],
87    stream_flags: &["--output-format", "stream-json"],
88    tool_disable_flags: &["--tools", "", "--strict-mcp-config"],
89    mcp_mount: McpMount::PerCall,
90    home_env_var: "CLAUDE_CONFIG_DIR",
91    activation: Activation::Enabled,
92    capability_notes: "--tools \"\" disables built-ins but NOT the user's own MCP \
93                       servers; --strict-mcp-config is what empties the tool list",
94};
95
96/// `codex`, measured at 0.154.0 by running it (#1339).
97///
98/// Disabled, and for a reason no probe can close. Its shell is core — there
99/// is no flag that removes it, and `-s read-only` restricts the filesystem
100/// rather than establishing action safety — so a spawned `codex` can execute
101/// commands that never pass MUR's handler, entitlements or HITL gate. The
102/// design admits it only behind a *verified* process sandbox inherited by
103/// child processes, and no such sandbox exists yet.
104///
105/// It has a row rather than being absent because absence says nothing. A
106/// user who has `codex` installed should see it listed with this reason, not
107/// silently missing — the same lesson as the subscription rail in #1334.
108///
109/// `stream_flags` is `--json`, not `--output-format stream-json`: measured,
110/// and it carries completed items only, so a codex-backed turn cannot stream
111/// partial output even once the sandbox exists.
112pub const CODEX: CliBackend = CliBackend {
113    key: "codex",
114    binary: "codex",
115    headless_invocation: &["exec"],
116    stream_flags: &["--json"],
117    tool_disable_flags: &[],
118    mcp_mount: McpMount::Persistent,
119    home_env_var: "CODEX_HOME",
120    activation: Activation::Disabled {
121        reason: "codex's built-in shell cannot be disabled and the spawn path does not yet apply MUR's sandbox to it",
122    },
123    capability_notes: "prompt arrives on stdin; --json emits completed items \
124                       with no incremental deltas; MCP mounts persistently, so \
125                       a per-turn config must be written into the private home",
126};
127
128/// `agy`, measured at 1.2.3 by running it (#1339, #1340).
129///
130/// Disabled for the same reason as `codex` and not a different one: it has
131/// execution it cannot be asked to give up — 57 built-in tools, enumerated by
132/// its own `init` event, including `run_command`, `write_to_file` and a full
133/// browser-control set — and the spawn path does not yet apply MUR's sandbox.
134/// Containment does not care whether a tool is "disabled"; it cares what the
135/// process can do. So this is the same blocker, not a worse one.
136///
137/// Its own `--sandbox` is not a mitigation. Probed with the approval layer
138/// removed, it still read outside the workspace, read `$HOME`, wrote outside
139/// the workspace and reached the public internet.
140///
141/// `home_env_var` is `HOME`, and that is an honest value rather than a
142/// missing one — an earlier note here called it "no honest value", conflating
143/// "no dedicated variable" with "no usable value". Setting `HOME` does
144/// relocate agy's config, measured. What it also does is relocate everything
145/// else that process resolves under `HOME`, which is a blunter instrument
146/// than `CODEX_HOME` and is the one way this row is genuinely worse than
147/// `codex`'s.
148pub const AGY: CliBackend = CliBackend {
149    key: "agy",
150    binary: "agy",
151    headless_invocation: &["-p"],
152    stream_flags: &["--output-format", "stream-json"],
153    tool_disable_flags: &[],
154    mcp_mount: McpMount::Persistent,
155    home_env_var: "HOME",
156    activation: Activation::Disabled {
157        reason: "agy's 57 built-in tools cannot be disabled and the spawn path does not yet apply MUR's sandbox to it",
158    },
159    capability_notes: "HOME is the only lever and it moves everything, not just \
160                       config; `-p` swallows a following flag as its prompt, so \
161                       use `-p=<prompt>`; MCP mounts persistently at \
162                       $HOME/.gemini/config/mcp_config.json",
163};
164
165/// Every backend whose record is complete. Absence is a statement: a CLI
166/// missing here has an unanswered probe, not a missing implementation.
167pub const REGISTRY: &[CliBackend] = &[CLAUDE, CODEX, AGY];
168
169/// Look up a backend by key.
170pub fn backend(key: &str) -> Option<&'static CliBackend> {
171    REGISTRY.iter().find(|b| b.key == key)
172}
173
174/// A backend whose binary was found, plus whether MUR may drive it.
175///
176/// `usable == false` is a backend that is present and listed but must not be
177/// spawned; the caller renders it with `Activation::Disabled`'s reason. It is
178/// deliberately not filtered out — the disabled entry is what carries the
179/// explanation.
180#[derive(Debug, Clone, PartialEq, Eq)]
181pub struct BackendAvailability {
182    pub backend: &'static CliBackend,
183    pub path: std::path::PathBuf,
184    pub usable: bool,
185}
186
187/// Which backends the user actually has, given a binary resolver.
188///
189/// `resolve` is injected rather than calling a `which` helper directly: this
190/// crate is consumed by the Hub, the runtime and the CLI, each of which
191/// resolves binaries differently (the Hub must ask an interactive login shell,
192/// because a Finder-launched app inherits a bare PATH). Injection also makes
193/// every case below testable without touching the real PATH.
194pub fn available<F>(resolve: F) -> Vec<BackendAvailability>
195where
196    F: Fn(&str) -> Option<std::path::PathBuf>,
197{
198    REGISTRY
199        .iter()
200        .filter_map(|b| {
201            resolve(b.binary).map(|path| BackendAvailability {
202                backend: b,
203                path,
204                usable: matches!(b.activation, Activation::Enabled),
205            })
206        })
207        .collect()
208}
209
210/// `<mur_home>/cli-homes/<key>/` — this backend's private CLI home.
211///
212/// `mur_home` is a parameter rather than a call to `trust::mur_home()` so the
213/// path is a pure function of its inputs and every test runs against a temp
214/// dir. Same shape as `local_llm::local_model_dir`.
215pub fn home_dir(mur_home: &std::path::Path, key: &str) -> std::path::PathBuf {
216    mur_home.join("cli-homes").join(key)
217}
218
219/// Create this backend's private home if absent and return the environment
220/// variable that points the CLI at it.
221///
222/// The home starts empty and stays MUR's: the user authenticates once inside
223/// it, and their own `~/.claude` / `~/.codex` is never read or written. We do
224/// not copy `auth.json` — two holders of one refresh-token lineage each
225/// rotating would log the user out of their own CLI, which is why the gateway
226/// is the sole token holder on the other track.
227pub fn ensure_home(
228    mur_home: &std::path::Path,
229    b: &CliBackend,
230) -> std::io::Result<(&'static str, std::path::PathBuf)> {
231    let dir = home_dir(mur_home, b.key);
232    std::fs::create_dir_all(&dir)?;
233    Ok((b.home_env_var, dir))
234}
235
236/// The flags that make a spawned CLI see MUR's tools and nothing else.
237///
238/// One constant, not three arguments assembled at the call site. Measured
239/// 2026-09-16: `--tools ""` alone still left 44 tools mounted — every MCP
240/// server in the user's own config — and none of those pass MUR's handler,
241/// entitlements or HITL gate. `--strict-mcp-config` is what empties the
242/// list, so the three travel together or the isolation is not there.
243pub const ISOLATION_FLAGS: &[&str] = &["--tools", "", "--strict-mcp-config"];
244
245/// The `--mcp-config` document for one turn.
246///
247/// Names the shim, the agent socket it dials back on, and the task it
248/// belongs to. `task_id` is what binds a spawned `bash` job to an owner and
249/// routes an approval prompt, so it is an argument rather than something the
250/// shim could infer.
251pub fn mcp_config_json(
252    shim_bin: &str,
253    socket: &std::path::Path,
254    task_id: &str,
255) -> serde_json::Value {
256    serde_json::json!({
257        "mcpServers": {
258            "mur": {
259                "command": shim_bin,
260                "args": [
261                    "mcp-shim",
262                    "--socket", socket.to_string_lossy(),
263                    "--task-id", task_id,
264                ],
265            }
266        }
267    })
268}
269
270/// Marks a model registry `provider` as naming the CLI-spawn track.
271///
272/// The gateway track already selects on `provider` (`claude` and `codex`
273/// dispatch to loopback clients), so the CLI track uses the same field
274/// rather than inventing a second way to say which track an agent is on.
275/// The prefix keeps the two readable side by side — `claude` is the
276/// gateway, `cli:claude` is the spawn — and cannot be confused with a
277/// vendor slug, which a `-cli` suffix would have to be parsed off a name
278/// that may itself contain dashes.
279pub const PROVIDER_PREFIX: &str = "cli:";
280
281/// The backend a registry `provider` names, if it names one.
282///
283/// Returns the row whether or not it is enabled. Activation is the caller's
284/// gate to apply and to report: a disabled backend must produce a turn that
285/// explains itself, which it cannot do if this returns `None` and the
286/// provider merely looks unknown.
287pub fn from_provider(provider: &str) -> Option<&'static CliBackend> {
288    let key = provider.strip_prefix(PROVIDER_PREFIX)?;
289    backend(key)
290}
291
292#[cfg(test)]
293mod tests {
294    use super::*;
295
296    #[test]
297    fn claude_row_matches_the_measured_capabilities() {
298        assert_eq!(CLAUDE.binary, "claude");
299        assert_eq!(CLAUDE.headless_invocation, &["-p"]);
300        assert_eq!(CLAUDE.stream_flags, &["--output-format", "stream-json"]);
301        assert_eq!(
302            CLAUDE.tool_disable_flags,
303            &["--tools", "", "--strict-mcp-config"]
304        );
305        assert_eq!(CLAUDE.mcp_mount, McpMount::PerCall);
306        assert_eq!(CLAUDE.home_env_var, "CLAUDE_CONFIG_DIR");
307    }
308
309    #[test]
310    fn claude_is_enabled_once_the_spawn_path_exists() {
311        // The gate is not "a probe answered"; it is that every isolation
312        // requirement was demonstrated. The boxes are in the plan.
313        assert!(matches!(CLAUDE.activation, Activation::Enabled));
314    }
315
316    #[test]
317    fn the_tool_disable_carries_both_halves() {
318        // Regression guard for the measured hazard: `--tools ""` on its own
319        // left 44 of the user's own MCP tools mounted. Dropping
320        // --strict-mcp-config here would silently reopen that hole.
321        assert!(CLAUDE.tool_disable_flags.contains(&"--tools"));
322        assert!(CLAUDE.tool_disable_flags.contains(&"--strict-mcp-config"));
323        assert!(
324            !CLAUDE.tool_disable_flags.contains(&"--disallowedTools"),
325            "--disallowedTools is a named deny list, not a disable"
326        );
327    }
328
329    #[test]
330    fn every_row_is_fully_specified() {
331        // The rule the registry exists to enforce: no half-filled row. A
332        // backend with an unknown field belongs outside the registry, not
333        // inside it with a plausible-looking guess.
334        for b in REGISTRY {
335            assert!(!b.key.is_empty(), "{}: empty key", b.key);
336            assert!(!b.binary.is_empty(), "{}: empty binary", b.key);
337            assert!(
338                !b.headless_invocation.is_empty(),
339                "{}: no headless flags",
340                b.key
341            );
342            assert!(!b.stream_flags.is_empty(), "{}: no stream flags", b.key);
343            assert!(!b.home_env_var.is_empty(), "{}: no home env var", b.key);
344        }
345    }
346
347    #[test]
348    fn unprobed_backends_are_absent_rather_than_guessed() {
349        // Both probes are answered (#1339); what differs is what the answers
350        // did. `codex`'s made a row possible — it has all five required
351        // fields — so it is registered and disabled, not absent.
352        //
353        // `agy`'s answer is what keeps it out, and structurally: it has no
354        // home environment variable at all, only `HOME`, so there is no
355        // honest value for `home_env_var` and the completeness rule above
356        // would reject the row. Absence here is the measurement, not a gap.
357        // Every probed backend now has a row. Absence is reserved for a CLI
358        // nobody has measured — it is a statement about knowledge, not about
359        // safety, and both of these are disabled rather than missing.
360        assert!(backend("agy").is_some(), "agy's record is complete");
361        assert!(backend("codex").is_some(), "codex's record is complete");
362        assert!(backend("nope").is_none());
363    }
364
365    #[test]
366    fn lookup_finds_claude_and_rejects_unknown_keys() {
367        assert_eq!(backend("claude"), Some(&CLAUDE));
368        assert!(backend("nope").is_none());
369    }
370
371    use std::path::PathBuf;
372
373    fn found(_: &str) -> Option<PathBuf> {
374        Some(PathBuf::from("/opt/homebrew/bin/claude"))
375    }
376
377    fn missing(_: &str) -> Option<PathBuf> {
378        None
379    }
380
381    #[test]
382    fn an_absent_binary_produces_no_entry() {
383        // "Backends whose binary is absent do not appear in the UI at all."
384        assert!(available(missing).is_empty());
385    }
386
387    #[test]
388    fn a_present_binary_is_listed_with_the_path_that_was_resolved() {
389        // Every registered backend, each carrying the path the resolver gave
390        // for it. Asserted over the whole registry rather than over a count,
391        // so adding a row does not break a test about path plumbing.
392        let got = available(found);
393        assert_eq!(got.len(), REGISTRY.len());
394        for a in &got {
395            assert_eq!(a.path, PathBuf::from("/opt/homebrew/bin/claude"));
396        }
397        assert!(got.iter().any(|a| a.backend.key == "claude"));
398    }
399
400    #[test]
401    fn a_disabled_backend_would_be_listed_and_not_usable() {
402        // The distinction `available()` exists to hold: absent means gone,
403        // disabled means shown-and-not-usable. It used to be asserted through
404        // the `claude` row, which was disabled at the time; now that `claude`
405        // is enabled there is no disabled row to borrow, so the mapping is
406        // asserted directly rather than deleted along with its example.
407        let disabled = CliBackend {
408            activation: Activation::Disabled {
409                reason: "for the test",
410            },
411            ..CLAUDE
412        };
413        let entry = BackendAvailability {
414            backend: &CLAUDE,
415            path: PathBuf::from("/opt/homebrew/bin/claude"),
416            usable: matches!(disabled.activation, Activation::Enabled),
417        };
418        assert!(!entry.usable, "a disabled backend must never be usable");
419    }
420
421    #[test]
422    fn usable_tracks_activation_and_nothing_else() {
423        // Guards against a future row being enabled by the mere fact that its
424        // binary resolved.
425        for a in available(found) {
426            assert_eq!(
427                a.usable,
428                matches!(a.backend.activation, Activation::Enabled)
429            );
430        }
431    }
432
433    #[test]
434    fn home_dir_is_namespaced_under_cli_homes() {
435        let got = home_dir(std::path::Path::new("/tmp/murhome"), "claude");
436        assert_eq!(got, PathBuf::from("/tmp/murhome/cli-homes/claude"));
437    }
438
439    #[test]
440    fn ensure_home_creates_the_dir_and_returns_the_env_var() {
441        let tmp = std::env::temp_dir().join(format!("mur-cli-home-{}", std::process::id()));
442        let _ = std::fs::remove_dir_all(&tmp);
443        let (var, dir) = ensure_home(&tmp, &CLAUDE).expect("create");
444        assert_eq!(var, "CLAUDE_CONFIG_DIR");
445        assert_eq!(dir, tmp.join("cli-homes").join("claude"));
446        assert!(dir.is_dir());
447        std::fs::remove_dir_all(&tmp).ok();
448    }
449
450    #[test]
451    fn ensure_home_is_idempotent() {
452        let tmp = std::env::temp_dir().join(format!("mur-cli-home-idem-{}", std::process::id()));
453        let _ = std::fs::remove_dir_all(&tmp);
454        ensure_home(&tmp, &CLAUDE).expect("first");
455        let marker = home_dir(&tmp, "claude").join("settings.json");
456        std::fs::write(&marker, b"{}").expect("write marker");
457        ensure_home(&tmp, &CLAUDE).expect("second");
458        assert_eq!(std::fs::read(&marker).expect("read marker"), b"{}");
459        std::fs::remove_dir_all(&tmp).ok();
460    }
461
462    #[test]
463    fn ensure_home_never_touches_the_users_own_cli_config() {
464        // The Global Constraint, asserted rather than assumed. A stand-in for
465        // ~/.claude sits OUTSIDE the mur home; creating the private home must
466        // leave its bytes untouched.
467        let base = std::env::temp_dir().join(format!("mur-cli-iso-{}", std::process::id()));
468        let _ = std::fs::remove_dir_all(&base);
469        let user_cfg = base.join("user-claude");
470        std::fs::create_dir_all(&user_cfg).expect("user cfg");
471        let cred = user_cfg.join(".credentials.json");
472        std::fs::write(&cred, b"user-token").expect("seed");
473
474        ensure_home(&base.join("murhome"), &CLAUDE).expect("create");
475
476        assert_eq!(std::fs::read(&cred).expect("still there"), b"user-token");
477        assert!(
478            !base
479                .join("murhome")
480                .join("cli-homes")
481                .join("claude")
482                .join(".credentials.json")
483                .exists()
484        );
485        std::fs::remove_dir_all(&base).ok();
486    }
487
488    #[test]
489    fn the_isolation_flags_stay_together() {
490        // Each of the three is load-bearing and the middle row of the table
491        // in the plan is why: dropping --strict-mcp-config re-mounts the
492        // user's own MCP servers, and the spawn still looks correct.
493        assert_eq!(ISOLATION_FLAGS, &["--tools", "", "--strict-mcp-config"]);
494    }
495
496    #[test]
497    fn the_mcp_config_names_the_shim_the_socket_and_the_task() {
498        let v = mcp_config_json(
499            "/usr/local/bin/mur_agent_x",
500            std::path::Path::new("/tmp/x/agent.sock"),
501            "t-9",
502        );
503        let s = &v["mcpServers"]["mur"];
504        assert_eq!(s["command"], "/usr/local/bin/mur_agent_x");
505        let args: Vec<String> = s["args"]
506            .as_array()
507            .expect("args")
508            .iter()
509            .map(|a| a.as_str().unwrap_or_default().to_string())
510            .collect();
511        assert_eq!(args[0], "mcp-shim");
512        assert!(args.contains(&"/tmp/x/agent.sock".to_string()));
513        assert!(args.contains(&"t-9".to_string()));
514    }
515
516    #[test]
517    fn the_config_declares_exactly_one_server() {
518        // `--strict-mcp-config` means this document is the whole tool
519        // surface. A second entry here would be a second unaudited source.
520        let v = mcp_config_json("bin", std::path::Path::new("/s"), "t");
521        assert_eq!(v["mcpServers"].as_object().expect("obj").len(), 1);
522    }
523
524    #[test]
525    fn a_prefixed_provider_names_the_backend() {
526        assert_eq!(from_provider("cli:claude").map(|b| b.key), Some("claude"));
527    }
528
529    #[test]
530    fn the_gateway_providers_are_not_the_cli_track() {
531        // `claude` and `codex` already mean the loopback gateway. If this
532        // ever matched them, putting an agent on the gateway would silently
533        // spawn a CLI instead.
534        assert!(from_provider("claude").is_none());
535        assert!(from_provider("codex").is_none());
536        assert!(from_provider("openai").is_none());
537    }
538
539    #[test]
540    fn an_unknown_backend_is_none_even_when_prefixed() {
541        // `cli:agy` resolves now that agy has a row — that is the point of
542        // giving it one. An agent pointed there gets "disabled, and here is
543        // why" instead of the unknown-provider path, which reads as a typo.
544        assert_eq!(from_provider("cli:agy").map(|b| b.key), Some("agy"));
545        assert!(from_provider("cli:nope").is_none());
546    }
547
548    #[test]
549    fn a_disabled_backend_still_resolves() {
550        // The caller needs the row to report *why* it is off. Returning
551        // `None` would make a disabled backend indistinguishable from a typo.
552        let disabled = CliBackend {
553            activation: Activation::Disabled {
554                reason: "for the test",
555            },
556            ..CLAUDE
557        };
558        assert!(matches!(disabled.activation, Activation::Disabled { .. }));
559        assert!(from_provider("cli:claude").is_some());
560    }
561
562    #[test]
563    fn codex_is_listed_and_never_usable() {
564        // The distinction the registry exists to express: present, so a user
565        // with `codex` installed sees it and its reason; not usable, because
566        // its shell cannot be disabled and no verified sandbox exists.
567        let c = backend("codex").expect("codex is registered");
568        match c.activation {
569            Activation::Disabled { reason } => {
570                assert!(reason.contains("sandbox"), "{reason}");
571                // Not "no sandbox exists" — one does, in
572                // `mur-agent-runtime/src/sandbox/`. What is missing is its
573                // application to the spawn path, and the reason must say
574                // which, or it sends the next reader off to build one.
575                assert!(reason.contains("does not yet apply"), "{reason}");
576                assert!(reason.contains("shell"), "{reason}");
577            }
578            Activation::Enabled => panic!("codex must not be enabled without a verified sandbox"),
579        }
580        assert!(
581            available(found)
582                .iter()
583                .any(|a| a.backend.key == "codex" && !a.usable)
584        );
585    }
586
587    #[test]
588    fn cli_codex_resolves_so_the_refusal_can_name_itself() {
589        // An agent pointed at `cli:codex` must get "disabled, and here is
590        // why" — not the unknown-provider path, which reads as a typo. This
591        // is the guard that was deferred while `from_provider` lived on an
592        // unmerged branch; it belongs beside the row it protects.
593        assert_eq!(from_provider("cli:codex").map(|b| b.key), Some("codex"));
594    }
595
596    #[test]
597    fn agy_is_listed_and_never_usable() {
598        // Same shape as codex's guard. The reason must name the blocker, not
599        // the absence of one, or the next reader is told to solve the wrong
600        // problem — which is what "no honest value for home_env_var" did.
601        let a = backend("agy").expect("agy is registered");
602        match a.activation {
603            Activation::Disabled { reason } => {
604                assert!(reason.contains("built-in tools"), "{reason}");
605                assert!(reason.contains("does not yet apply"), "{reason}");
606            }
607            Activation::Enabled => panic!("agy must not be enabled: 57 built-ins, none disablable"),
608        }
609        assert!(
610            available(found)
611                .iter()
612                .any(|a| a.backend.key == "agy" && !a.usable)
613        );
614    }
615
616    #[test]
617    fn home_is_a_real_lever_for_agy_not_a_placeholder() {
618        // Measured (#1339): setting HOME relocates agy's config. The row says
619        // `HOME` because that works, not because nothing else would fit.
620        assert_eq!(AGY.home_env_var, "HOME");
621        let (var, dir) = ensure_home(std::path::Path::new("/tmp/mur-agy-x"), &AGY).expect("home");
622        assert_eq!(var, "HOME");
623        assert!(dir.ends_with("cli-homes/agy"));
624        std::fs::remove_dir_all("/tmp/mur-agy-x").ok();
625    }
626}