trusty-mpm 1.8.2

//! Miscellaneous command handlers that don't belong to a larger group.
//!
//! Why: `status`, `events`, `hook`, `coordinator`, `overseer`,
//! `optimizer`, and `attach` are small, loosely related commands that are
//! easier to find together than scattered across the codebase.
//! What: one public `async fn` per subcommand. `doctor` moved to
//! `doctor_local` when #6336 made it standalone — this file had 24 SLOC of
//! headroom under the 500-SLOC production cap.
//! Test: `cli_parses_*` parse tests for each command in `tests.rs`.

use crate::cli::{CliCompressionLevel, OptimizerAction, OverseerAction};
use crate::commands::hook_rewrite::{
    build_pretooluse_rewrite_response, hook_cwd, rewrite_bash_command_unless_isolated,
};
use crate::formatters::session::short_id;
use crate::types::EventRow;

/// Environment variable set by every MPM-spawned sub-agent process so its
/// nested Claude Code session can suppress hook traffic.
///
/// Why: a sub-agent is already running inside an MPM-supervised context;
/// re-emitting hook events from inside it just doubles every tool call in
/// the daemon's audit log without adding signal. Stamping the env var on
/// the spawn side and gating the hook handler on the same var keeps the
/// suppression cheap, explicit, and process-local. Re-exporting the shared
/// constant from `trusty_common::claude_config` ensures the spawn site
/// (`trusty-agents`) and this consumer never drift apart on the literal name.
/// What: thin alias for
/// [`trusty_common::claude_config::CLAUDE_MPM_SUB_AGENT_ENV_VAR`]. Presence
/// is what matters; the canonical value used by spawn helpers is `"1"`.
pub(crate) const SUB_AGENT_ENV: &str = trusty_common::claude_config::CLAUDE_MPM_SUB_AGENT_ENV_VAR;

/// Opt-out environment variable that disables the hook handler entirely.
///
/// Why: provides an escape hatch for any environment (CI, SAM deploys, custom
/// build shells) where the hook must not fire at all — without requiring the
/// user to uninstall it from `.claude/settings.json`. Sitting alongside the
/// `SUB_AGENT_ENV` guard makes the two opt-out mechanisms symmetric and
/// discoverable. Setting this in the build shell's env is sufficient; no
/// Claude Code restart is required (it is read per-invocation).
/// What: the literal env var name `"TRUSTY_MPM_DISABLE_HOOKS"`. Presence
/// (any value) causes the hook handler to short-circuit immediately.
/// Test: `hook_disable_env_short_circuits` in `tests_behavior_a_tests.rs`.
pub(crate) const DISABLE_HOOKS_ENV: &str = "TRUSTY_MPM_DISABLE_HOOKS";

/// Catalog status message shown when the catalog has never been synced.
///
/// Why: extracting this as a constant lets tests import the canonical string
/// rather than asserting against a hardcoded copy that could silently diverge
/// from the production output (#1839 review finding 4).
/// What: the `catalog:` line shown by `tm health` for a brand-new install.
/// Test: `health_catalog_stale_message_contains_action` in `tests.rs`.
pub(crate) const CATALOG_UNKNOWN_MSG: &str = "never synced (run 'tm catalog sync' to initialize)";

/// Catalog status message shown when the catalog is stale.
///
/// Why: same rationale as `CATALOG_UNKNOWN_MSG` — tests import the constant
/// so a string regression is caught by the test, not silently ignored.
/// What: the `catalog:` line shown by `tm health` when newer agents exist.
/// Test: `health_catalog_stale_message_contains_action` in `tests.rs`.
pub(crate) const CATALOG_STALE_MSG: &str = "updates available (run 'tm catalog sync' to update)";

/// Help hint printed to stderr when `tm` is invoked outside a git project.
///
/// Why: extracting this as a constant lets the test in `tests.rs` import the
/// actual production string rather than a hardcoded copy (#1839 review finding 4).
/// `guided.rs` is at the 500-SLOC cap, so the constant lives here and is
/// referenced from guided.rs via `super::misc::NON_GIT_FALLBACK_HINT`.
/// What: the one-line hint printed (to stderr) by `fallback_protected` when the
/// CWD is not inside any git working tree.
/// Test: `non_git_dir_fallback_prints_help_hint` in `tests.rs`.
pub(crate) const NON_GIT_FALLBACK_HINT: &str =
    "tm: not in a git project — run 'tm --help' for available commands";

/// Hard ceiling on the #2610 idle-parking detection.
///
/// Why: it bounds a transcript read on the turn-end hot path, so the hook never
/// blocks the prompt. Named at module scope since #6556 rather than inlined in
/// [`detect_idle_parking_from_payload_in`], because it is one of the four bounds
/// a `SubagentStop` invocation pays in series and the budget gate has to sum it.
/// Test: `the_stop_post_budget_stays_inside_the_registered_hook_timeout`.
pub(crate) const IDLE_PARK_DETECT_TIMEOUT: std::time::Duration =
    std::time::Duration::from_millis(300);

/// The turn-end event that reports a delegated subagent stopped.
///
/// Why (#6556): the one event whose POST is retried and parked on disk. Spelled
/// once so the retry branch and its tests name the same string.
pub(crate) const SUBAGENT_STOP_EVENT: &str = "SubagentStop";

/// `events` subcommand — print the recent hook-event feed.
///
/// Why: gives operators a quick tail of daemon activity without the TUI. The
/// daemon serves a live SSE stream at `/events`; this CLI command polls the
/// legacy snapshot at `/events/poll`, which mirrors the historical behaviour.
/// What: `GET /events/poll`, printing `{timestamp} {session_short} {event}`.
/// Test: run against a daemon that has ingested hook events.
pub(crate) async fn events(client: &reqwest::Client, url: &str) -> anyhow::Result<()> {
    use serde::Deserialize;
    #[derive(Deserialize)]
    struct Body {
        events: Vec<EventRow>,
    }
    let body: Body = client
        .get(format!("{url}/events/poll"))
        .send()
        .await?
        .error_for_status()?
        .json()
        .await?;
    for e in &body.events {
        println!("{} {} {}", e.at, short_id(&e.session), e.event);
    }
    Ok(())
}

/// `validate` subcommand — diff a workspace's deployed `.claude/{agents,skills}`
/// payload against the canonical bundled roster (issue #2158).
///
/// Why: this is the narrow deployment diff, where `tm doctor` is the whole
/// stack — it runs [`trusty_mpm::core::deploy_validate::validate_workspace`]
/// against one workspace and exits non-zero on a gap, which makes it usable
/// as a non-interactive CI gate (`tm validate --path <dir> || exit 1`).
/// Both run standalone against the local filesystem (#6336).
/// What: resolves `path` (default: the current directory) to a
/// `FrameworkPaths` via `FrameworkPaths::for_managed_workspace`, runs the
/// validator, and — when `repair` is set and gaps were found — re-runs
/// [`trusty_mpm::core::deploy_validate::validate_and_repair`] (which itself
/// calls `prepare_session_with_repo_url`, the same pipeline `spawn_managed`
/// uses) before printing the final verdict. Exits the process with status `1`
/// when the final report is incomplete, `0` otherwise.
/// Test: `cli_parses_validate`, `cli_parses_validate_with_path_and_repair`
/// cover parsing; the diff/repair logic itself is covered by
/// `core::deploy_validate`'s own unit tests.
pub(crate) async fn validate(path: Option<std::path::PathBuf>, repair: bool) -> anyhow::Result<()> {
    use trusty_mpm::core::deploy_validate::{validate_and_repair, validate_workspace};
    use trusty_mpm::core::paths::FrameworkPaths;

    let workspace = match path {
        Some(p) => p,
        None => std::env::current_dir()?,
    };
    let fw = FrameworkPaths::for_managed_workspace(&workspace);

    println!("tm validate: {}", workspace.display());

    let complete = if repair {
        let outcome = validate_and_repair(&fw, &workspace, None);
        // #4781: an attempt ran exactly when the pre-repair report had gaps;
        // `repaired` now reports whether it SUCCEEDED, so it can no longer gate
        // the attempt's own diagnostics — a failed repair used to print nothing.
        if !outcome.before.is_complete() {
            println!(
                "auto-repair ran ({} gap(s) found before repair)",
                outcome.before.gaps.len()
            );
            if let Some(err) = &outcome.repair_error {
                eprintln!("repair pipeline reported an error: {err}");
            }
            if !outcome.repaired {
                eprintln!("auto-repair did NOT restore the workspace");
            }
        }
        print_gaps(&outcome.after.gaps);
        outcome.is_complete()
    } else {
        let report = validate_workspace(&fw);
        print_gaps(&report.gaps);
        report.is_complete()
    };

    if complete {
        println!("deployment is complete");
    } else {
        eprintln!(
            "deployment is INCOMPLETE — run `tm validate --path {} --repair` to auto-repair",
            workspace.display()
        );
        std::process::exit(1);
    }

    Ok(())
}

/// Print each deployment gap as one `  - <description>` line, or a
/// "no gaps" line when the slice is empty.
///
/// Why: shared by both branches of [`validate`] so the report formatting
/// cannot drift between the plain and `--repair` paths.
/// What: thin formatting loop over [`trusty_mpm::core::deploy_validate::DeploymentGap::describe`].
/// Test: covered indirectly via `validate`'s own behaviour; the gap
/// descriptions themselves are unit-tested in `core::deploy_validate`.
fn print_gaps(gaps: &[trusty_mpm::core::deploy_validate::DeploymentGap]) {
    if gaps.is_empty() {
        println!("  no gaps found");
        return;
    }
    for gap in gaps {
        println!("  - {}", gap.describe());
    }
}

/// `health` subcommand — report daemon health through chat-core.
///
/// Why: the operator (and scripts) want a quick "is the daemon up, is the catalog
/// fresh, how big is the fleet?" probe. Routing it through the shared
/// `CommandExecutor` (rather than a bespoke `reqwest` call here) means the CLI
/// shares the exact `health` dispatch with every other adapter — a single source
/// of truth per the chat-core nucleus. The `resolved:` line tells operators
/// whether traffic is flowing via the trusty-console gateway or direct to the
/// daemon, making the resolution path transparent (#1849 Phase 2).
/// What: #6288 step 1 — probes `/health` over the daemon socket first; a
/// socket that is absent, refuses, or answers badly is an ERROR naming the
/// socket path (exit 1), never a TCP retry and never a healthy line. Then runs
/// `TrustyCommand::Health` through the executor and prints a compact,
/// scriptable summary whose `resolved:` line names the transport.
/// Test: `cli_parses_health` covers parsing;
/// `tm_health_over_an_absent_socket_fails_and_never_dials_tcp` and
/// `tm_health_status_and_doctor_work_over_the_socket_alone` cover both arms.
pub(crate) async fn health(daemon: &trusty_mpm::client::DaemonClient) -> anyhow::Result<()> {
    use trusty_mpm::client::{CommandExecutor, CommandResult, TrustyCommand};

    // #6288: a socket error is never downgraded to "unreachable" + exit 0.
    daemon
        .health_snapshot()
        .await
        .map_err(|e| anyhow::anyhow!("daemon: unreachable — {e:#}"))?;
    let executor = CommandExecutor::from_daemon_client(daemon.clone());
    match executor.execute(TrustyCommand::Health).await {
        CommandResult::Health(report) if !report.reachable => {
            anyhow::bail!("daemon: unreachable ({})", daemon.transport_label());
        }
        CommandResult::Health(report) => {
            let catalog = if report.catalog_unknown {
                CATALOG_UNKNOWN_MSG
            } else if report.catalog_stale {
                CATALOG_STALE_MSG
            } else {
                "up to date"
            };
            println!("daemon: {} ({})", report.status, report.url);
            println!("resolved: {}", daemon.transport_label());
            println!("catalog: {catalog}");
            println!(
                "fleet: {} session(s), {} awaiting a decision",
                report.managed_total, report.managed_pending_decisions
            );
        }
        CommandResult::Error(msg) => anyhow::bail!("health failed: {msg}"),
        other => anyhow::bail!("health: unexpected result {other:?}"),
    }
    Ok(())
}

/// Best-effort read of Claude Code's hook stdin JSON payload, for a hook whose
/// result gates no tool call.
///
/// Why (issue #1956): Claude Code delivers the full hook payload —
/// `hook_event_name`/`session_id`/`tool_name`/`tool_input`/`tool_response` — on
/// the hook's stdin, and `hook()` needs it for the `PreToolUse` Bash rewrite and
/// daemon observability. Both degrade to a no-op without a payload, so an
/// `Option` is enough there. #7975: a hook whose decision gates a tool call must
/// not use this — `None` cannot tell a failed read from an absent payload — and
/// uses [`crate::commands::hook_stdin::read_stdin_hook_payload_strict`] instead.
/// What: that strict read, bounded by
/// [`crate::commands::hook_stdin::HOOK_STDIN_TIMEOUT`] — the 500 ms advisory
/// budget, kept here because a missed read costs this caller a no-op, not a
/// denied tool call — with the failure logged at `debug` so each kind stays
/// distinguishable (PR #1968 review) and mapped to `None`. `hook()` installs no
/// tracing subscriber by default, so the log costs nothing on the hot path.
/// Test: `read_hook_stdin_reports_a_read_error` and its siblings cover every
/// failure arm; `hook_rewrites_plain_bash_command_on_pretooluse` (in the
/// `tm_hook_pretooluse_rewrite` integration test) confirms the field names
/// consumed from this payload against the live Claude Code hooks reference
/// (<https://code.claude.com/docs/en/hooks>, confirmed 2026-07-03).
pub(crate) async fn read_stdin_hook_payload() -> Option<serde_json::Value> {
    use crate::commands::hook_stdin::{HOOK_STDIN_TIMEOUT, read_stdin_hook_payload_strict};

    read_stdin_hook_payload_strict(HOOK_STDIN_TIMEOUT)
        .await
        .inspect_err(|e| tracing::debug!("hook stdin payload unavailable: {e}"))
        .ok()
}

/// Best-effort, bounded read of the last `max_bytes` of a transcript file.
///
/// Why (#2610): the idle-parking detector needs the agent's final assistant
/// message, which lives at the END of Claude Code's JSONL transcript. #4837
/// added a second consumer with the same shape —
/// [`super::pm_guard_cost::evaluate_agent_cost`] needs the newest `usage`
/// block, also at the end — so this is `pub(crate)` rather than duplicated.
/// Reading
/// only the tail bounds both time and memory on a large session transcript, so
/// the Stop/SubagentStop hook can never block the user's prompt. A tail read may
/// slice mid-line; the detector tolerates a truncated leading line, so we accept
/// the boundary rather than paying to align it.
///
/// Code-critic finding (PR #2620): the caller wraps this whole function in
/// `tokio::time::timeout`, but that only bounds the `.await` — the underlying
/// `open()` syscall still runs to completion on a `spawn_blocking` worker
/// thread. If `transcript_path` ever pointed at a FIFO with no writer, `open()`
/// blocks the kernel thread indefinitely; the `timeout` future resolves (the
/// hook process still exits promptly), but the leaked blocking task pins a
/// worker thread forever. `stat()` (unlike `open()`) never blocks on a FIFO, so
/// checking the file type first — and refusing anything that is not a regular
/// file — closes that leak before the `open()` call can ever be reached.
/// What: `tokio::fs::metadata` (stat)-checks `path` first and returns `None`
/// immediately unless it names a regular file (rejects FIFOs, sockets, device
/// nodes, directories, and anything `stat` can't resolve). Only then opens
/// `path`, seeks to `len - max_bytes` (clamped at 0), reads up to `max_bytes`,
/// and returns the bytes as a lossy UTF-8 string. Any I/O error yields `None`
/// (fail-open — detection is advisory, never load-bearing).
/// Test: `rejects_fifo_without_blocking` (unix-only, `#[cfg(unix)]`) proves the
/// FIFO case returns promptly instead of hanging; also exercised end-to-end via
/// [`detect_idle_parking_from_payload`]'s callers and the `core::idle_parking`
/// unit tests that cover truncated tails.
pub(crate) async fn read_transcript_tail(path: &std::path::Path, max_bytes: u64) -> Option<String> {
    use tokio::io::{AsyncReadExt, AsyncSeekExt};

    let meta = tokio::fs::metadata(path).await.ok()?;
    if !meta.file_type().is_file() {
        return None;
    }

    let mut file = tokio::fs::File::open(path).await.ok()?;
    let len = file.metadata().await.ok()?.len();
    let start = len.saturating_sub(max_bytes);
    if start > 0 {
        file.seek(std::io::SeekFrom::Start(start)).await.ok()?;
    }
    let mut bytes = Vec::new();
    file.take(max_bytes).read_to_end(&mut bytes).await.ok()?;
    Some(String::from_utf8_lossy(&bytes).into_owned())
}

/// Detect an idle-parking final message from a Stop/SubagentStop hook payload.
///
/// Why (#2610): prompt-level prohibitions did not fully stop delegated agents
/// from ending their turn to "wait" for a self-spawned monitor. This is the
/// mechanical back-stop: on a turn-end event, check what the agent actually said
/// last and flag the stall so it can be surfaced (and later auto-nudged).
/// What: resolves the Claude config directory this session runs under via
/// [`trusty_mpm::core::session_record::claude_config_dir`] and delegates to
/// [`detect_idle_parking_from_payload_in`].
/// Test: the pure detection is covered by `core::idle_parking` tests;
/// `hook_flags_idle_parking_final_message_on_subagent_stop` (integration)
/// drives this end to end.
async fn detect_idle_parking_from_payload(
    payload: Option<&serde_json::Value>,
) -> Option<&'static str> {
    // #7278: the payload's `transcript_path` is attacker-influenceable, so the
    // boundary it is screened against is resolved here and threaded in.
    detect_idle_parking_from_payload_in(
        payload,
        trusty_mpm::core::session_record::claude_config_dir().as_deref(),
    )
    .await
}

/// [`detect_idle_parking_from_payload`] against an explicit config directory.
///
/// Why (#7278): the payload's `transcript_path` arrives from the Stop /
/// SubagentStop hook's stdin JSON and was handed to `read_transcript_tail`
/// verbatim, so `{"hook_event_name":"Stop","transcript_path":"/etc/passwd"}`
/// read any regular file the `tm` user could read. The screen belongs on the
/// value, and the directory it is screened against is resolved from the
/// process environment — which this bin target may not write (#5544), so the
/// rule is only assertable when that directory arrives as an argument.
/// What: refuses the path unless
/// [`trusty_mpm::core::session_record::contained_transcript_path`] accepts it
/// against `claude_config_dir` — absolute, no `..`, canonicalizing under the
/// canonicalized config directory — and reads nothing at all when it does not.
/// A `None` `claude_config_dir` refuses outright: with no directory to contain
/// the path there is nothing to screen against. Only the accepted CANONICAL
/// path is opened, so the read cannot re-resolve to a different file than the
/// one that was checked. On acceptance, tail-reads the transcript (bounded to
/// `MAX_TRANSCRIPT_TAIL`) under a short `DETECT_TIMEOUT` so the hook stays
/// within its non-blocking budget, then runs
/// [`trusty_mpm::core::idle_parking::detect_idle_parking_in_transcript`].
/// Returns the matched phrase, or `None` on a refused path / missing field /
/// timeout / I/O error / clean message. Entirely fail-open: detection is
/// advisory, so a refusal costs a warning that would have been shown, never a
/// blocked prompt.
/// Test: `refuses_a_transcript_path_outside_the_config_dir`,
/// `refuses_a_relative_transcript_path`,
/// `refuses_a_traversing_transcript_path`,
/// `refuses_every_transcript_path_without_a_config_dir`,
/// `detects_parking_in_a_transcript_under_the_config_dir`.
async fn detect_idle_parking_from_payload_in(
    payload: Option<&serde_json::Value>,
    claude_config_dir: Option<&std::path::Path>,
) -> Option<&'static str> {
    /// Cap on transcript bytes read from the tail (256 KiB is far more than one
    /// final assistant turn, yet bounds cost on a multi-MB session transcript).
    const MAX_TRANSCRIPT_TAIL: u64 = 256 * 1024;

    let raw = payload?.get("transcript_path")?.as_str()?;
    // #7278: screen before any read — a refused path is never opened.
    let path =
        trusty_mpm::core::session_record::contained_transcript_path(claude_config_dir?, raw)?;
    let jsonl = tokio::time::timeout(
        IDLE_PARK_DETECT_TIMEOUT,
        read_transcript_tail(&path, MAX_TRANSCRIPT_TAIL),
    )
    .await
    .ok()??;
    trusty_mpm::core::idle_parking::detect_idle_parking_in_transcript(&jsonl)
}

/// The `PreToolUse` Bash rewrite `tm hook` prints, if any.
///
/// Why (#8261): `tm hook --pm-guard` wraps heavy builds in `tm build-lease`,
/// and both hooks run on the same call in parallel. For a heavy build this hook
/// therefore emits the SAME response the guard does — compression inside the
/// lease — so whichever one Claude Code applies, the build is leased. A heavy
/// build the guard refuses gets no rewrite here; the guard's deny decides it.
/// What: the lease response for a heavy build, the compression-only response
/// (#1956) otherwise, `None` when neither applies. Inside an isolation
/// worktree, or with an unreadable cwd, neither response compresses (#7477) —
/// the lease itself still applies there.
/// Test: `hook_emits_the_guards_lease_rewrite_for_a_heavy_build` in
/// `tests/tm_hook_pm_guard_build_lease.rs`.
fn pretooluse_bash_rewrite(
    cmd: &str,
    tool_input: Option<&serde_json::Value>,
    cwd: Option<&std::path::Path>,
) -> Option<String> {
    use super::pm_guard_bash::build_lease_rewrite::LeaseRewrite;
    let cwd = cwd.unwrap_or(std::path::Path::new(""));
    match super::pm_guard_build_lease::decide_rewrite(cmd, tool_input, cwd) {
        (LeaseRewrite::Rewrite(new), permission) => Some(
            super::pm_guard_build_lease::rewrite_response(tool_input, &new, permission),
        ),
        (LeaseRewrite::Refuse(_), _) => None,
        // #7477: never inside an isolation worktree, whose classifier refuses the wrap.
        (LeaseRewrite::None, _) => rewrite_bash_command_unless_isolated(cmd, Some(cwd))
            .map(|rewritten| build_pretooluse_rewrite_response(&rewritten).to_string()),
    }
}

/// `hook` subcommand — handle a Claude Code lifecycle hook event.
///
/// Why: Claude Code invokes the configured hook command on every PreToolUse /
/// PostToolUse / Stop event. The handler posts a minimal `hook_event` to the
/// daemon so the circuit breaker, audit log, and dashboard can react. To keep
/// nested MPM sub-agents from doubling every tool call in the audit feed, the
/// very first thing the handler does is check `CLAUDE_MPM_SUB_AGENT`; when
/// that env var is present the handler exits 0 immediately without contacting
/// the daemon. `TRUSTY_MPM_DISABLE_HOOKS` provides an additional escape hatch
/// for any environment (SAM deploys, CI, stripped-PATH build shells) where
/// the hook must not fire at all.
///
/// Issue #1956 (Option 0 spike) widens this beyond the original env-var-only
/// relay: it now also reads Claude Code's stdin JSON payload (see
/// [`read_stdin_hook_payload`]) so `hook_event_name`/`tool_name`/`tool_input`
/// can be forwarded to the daemon for observability, AND — for `PreToolUse`
/// events where `tool_name == "Bash"` — attempts to rewrite the command to
/// pipe through `tm compress --tool "<effective tool name>"` (see
/// `commands::hook_rewrite`, which derives a dispatch-relevant tool name
/// from the command rather than a hardcoded `"bash"`), printing the
/// resulting `hookSpecificOutput.updatedInput` JSON to stdout when a safe
/// rewrite is constructed and returning immediately afterward. Per the live
/// Claude Code hooks reference (<https://code.claude.com/docs/en/hooks>,
/// confirmed 2026-07-03): "your hook's stdout must contain only the JSON
/// object" on a successful (`exit 0`) `PreToolUse` response — so the early
/// return after printing is load-bearing, not cosmetic; it guarantees no
/// further code in this function can ever interleave additional bytes onto
/// stdout for that invocation (trusty-review finding, PR #1968). When no
/// rewrite applies (excluded command, unsafe composition, or no stdin
/// payload at all) nothing is printed and execution falls through to the
/// observability POST below — a silent no-op, matching this handler's
/// existing fail-open posture.
/// What: reads `hook_event_name`/`session_id` from the stdin JSON payload
/// first, falling back to the legacy `CLAUDE_HOOK_EVENT`/`CLAUDE_SESSION_ID`
/// environment variables (kept for back-compat with any caller that still
/// sets them) and finally to placeholders. The stdin fields are the
/// authoritative source: per the same live hooks reference, Claude Code does
/// **not** set `CLAUDE_HOOK_EVENT`/`CLAUDE_SESSION_ID` as environment
/// variables for hook subprocesses — `hook_event_name` and `session_id` are
/// only ever delivered via stdin JSON, alongside `tool_name`/`tool_input`.
/// Without this stdin-first fix, `event` would always resolve to the
/// `"Unknown"` placeholder against a real Claude Code instance, and the
/// `event == "PreToolUse"` gate below — and therefore the entire rewrite
/// spike — would never fire (trusty-review finding, PR #1968). POSTs to
/// `<url>/hooks` with a 500 ms connect timeout and a 2-second total timeout.
/// Every failure path returns `Ok(())` — failing the hook would block the
/// user's prompt.
/// Issue #7245 adds one more read of the same stdin `session_id`: on
/// `SessionStart` it emits the instruction-compression savings row the compiling
/// `tm` process staged, which that process could not key because Claude Code
/// exports `CLAUDE_CODE_SESSION_ID` into its own children only — see
/// `trusty_mpm::core::savings_sidecar`. It appends nothing when nothing is
/// staged, writes no stdout, and cannot fail the hook.
/// Issue #6556 splits the delivery in two. A `SubagentStop` — the only event
/// whose loss strands a delegation `Running` for `RUNNING_STALE_AFTER_SECS` —
/// goes through [`super::hook_post::post_hook_with_retry`], which retries a
/// transient failure inside the hook's registered budget, logs every attempt to
/// stderr, and parks a permanently undelivered stop where the daemon's reap loop
/// replays it. Every other event keeps the single fire-and-forget attempt: a lost
/// `PreToolUse` observation costs an audit row, and retrying it would put a
/// backoff on the hot path of every tool call.
/// Test: `cli_parses_hook` covers parse routing; the guard branches are
/// exercised via `hook_guard_short_circuits` and
/// `hook_disable_env_short_circuits` in `tests_behavior_a_tests.rs`. The rewrite
/// decision logic itself is covered by `commands::hook_rewrite`'s unit
/// tests; `hook_rewrites_plain_bash_command_on_pretooluse` and
/// `hook_stays_silent_for_non_bash_tool_on_pretooluse` in the
/// `tm_hook_pretooluse_rewrite` integration test exercise the stdin-driven
/// event detection end to end through the real binary. The #6556 delivery split
/// is covered by `a_stop_delivered_on_the_third_attempt_logs_every_one` and
/// `a_daemon_that_never_answers_exhausts_the_attempts`.
pub(crate) async fn hook(client: &reqwest::Client, url: &str) -> anyhow::Result<()> {
    // Guard 1: suppress inside MPM-spawned sub-agents.
    if std::env::var_os(SUB_AGENT_ENV).is_some() {
        return Ok(());
    }
    // Guard 2: universal opt-out for build shells / CI that can't remove the
    // hook from settings.json without a restart.
    if std::env::var_os(DISABLE_HOOKS_ENV).is_some() {
        return Ok(());
    }

    // #1956: read the stdin JSON payload Claude Code delivers on every hook
    // invocation. This is the authoritative source for `hook_event_name` and
    // `session_id` — Claude Code does not set these as environment
    // variables (see doc comment above) — as well as `tool_name`/
    // `tool_input`, used both for the PreToolUse Bash rewrite below and for
    // daemon observability.
    let stdin_payload = read_stdin_hook_payload().await;
    let event = stdin_payload
        .as_ref()
        .and_then(|v| v.get("hook_event_name"))
        .and_then(|v| v.as_str())
        .map(str::to_string)
        .or_else(|| std::env::var("CLAUDE_HOOK_EVENT").ok())
        .unwrap_or_else(|| "Unknown".to_string());
    let session_id = stdin_payload
        .as_ref()
        .and_then(|v| v.get("session_id"))
        .and_then(|v| v.as_str())
        .map(str::to_string)
        .or_else(|| std::env::var("CLAUDE_SESSION_ID").ok())
        .unwrap_or_default();
    // #7245: the `tm` process that compiled this session's prompt ran before
    // `claude` existed, so it could not key its instruction-compression savings
    // row by the id the statusline folds by, and staged the row instead. This is
    // the first process that knows that id. Scoped to `SessionStart` because it
    // fires once per session and the claim resolves a git-owned project root.
    if event == "SessionStart" && !session_id.is_empty() {
        trusty_mpm::core::savings_sidecar::emit_staged_row_for_session(&session_id);
    }

    let tool_name = stdin_payload
        .as_ref()
        .and_then(|v| v.get("tool_name"))
        .and_then(|v| v.as_str());
    let tool_input = stdin_payload.as_ref().and_then(|v| v.get("tool_input"));
    let bash_command = tool_input
        .and_then(|v| v.get("command"))
        .and_then(|v| v.as_str());

    // #1956 Option 0: PreToolUse Bash command-rewrite spike. Printed to
    // stdout and returned immediately — per the live hooks protocol, stdout
    // must contain *only* the JSON object on a successful response, so
    // nothing else in this function may run afterward for this invocation
    // (see the doc comment above; trusty-review finding, PR #1968). No
    // output — and no early return — when no safe rewrite applies, so
    // control falls through to the observability POST unchanged.
    if event == "PreToolUse"
        && tool_name == Some("Bash")
        && let Some(cmd) = bash_command
        && let Some(response) =
            pretooluse_bash_rewrite(cmd, tool_input, hook_cwd(stdin_payload.as_ref()).as_deref())
    {
        println!("{response}");
        return Ok(());
    }

    // #2610: on turn-end events (main agent Stop / delegated SubagentStop),
    // flag a final message that "parks" the agent — one that ends the turn to
    // wait on a monitor/watcher/notification that can never re-wake a stopped
    // agent. Fail-open and bounded so this never blocks the user's prompt.
    let idle_parking = if matches!(event.as_str(), "Stop" | "SubagentStop") {
        detect_idle_parking_from_payload(stdin_payload.as_ref()).await
    } else {
        None
    };
    if let Some(phrase) = idle_parking {
        // Loud, greppable structured warning to stderr so operators and session
        // logs see the stall even before the daemon/dashboard surfaces it.
        eprintln!(
            "trusty-mpm: IDLE-PARKING WARNING (#2610) event={event} session={session_id} \
             phrase={phrase:?} — the agent ended its turn with parking language; a stopped \
             agent cannot be re-woken by a self-spawned monitor. It needs a foreground nudge."
        );
    }

    // Include the caller's cwd so the daemon can correlate this SessionStart
    // event to the right managed session by workspace_path (issue #1744).
    let cwd = std::env::current_dir()
        .ok()
        .and_then(|p| p.to_str().map(str::to_owned))
        .unwrap_or_default();
    // #8392: push a `Notification` to the configured inbox; bounded, never fails the hook.
    super::hook_notify::forward_notification(&event, stdin_payload.as_ref(), &cwd);
    // #2610 (idle-parking flags), #1956 (tool/input), #2864 (subagent
    // correlation keys: tool_use_id / agent_id / transcript paths). Built by
    // `commands::hook_payload` — a pure, unit-tested function that performs no
    // I/O and never writes to stdout, so the PreToolUse stdout-purity contract
    // documented above is preserved.
    let payload =
        super::hook_payload::build_hook_payload(&cwd, stdin_payload.as_ref(), idle_parking);
    let body = serde_json::json!({
        "session_id": session_id,
        "event": event,
        "payload": payload
    });

    // #6556: the one event whose loss costs more than an audit row. A lost
    // `SubagentStop` leaves the delegation `Running` for the six hours of
    // `RUNNING_STALE_AFTER_SECS`, holding a builder slot and a checkout, so it
    // is retried inside the hook's budget and parked on disk when the daemon is
    // down. Every other event keeps the single best-effort attempt below.
    if event == SUBAGENT_STOP_EVENT {
        let outcome = super::hook_post::post_hook_with_retry(url, &body).await;
        super::hook_post::emit_hook_post_log(&outcome);
        if !outcome.delivered {
            super::hook_post::spool_undelivered_stop(&body);
        }
        return Ok(());
    }

    // #8392: moved to `hook_notify` (this file is over the SLOC cap); same
    // 500 ms connect / 2 s total bounds, every failure dropped.
    // #8531: SessionStart over the socket, so the daemon can bind its claude.
    // #8980: SessionEnd too — only a socket SessionEnd from that claude stales
    // the session's live delegations.
    if event == "SessionStart" || event == "SessionEnd" {
        super::hook_notify::post_lifecycle_via_socket(client, url, &body).await;
        return Ok(());
    }
    super::hook_notify::post_best_effort(client, url, &body).await;
    Ok(())
}

/// `coordinator` / `coord` subcommand — message the cross-session coordinator.
///
/// Why: a scriptable, one-shot entry point to the coordinator so Telegram, cron
/// jobs, and shell scripts can ask "what is happening across my sessions?" or
/// route a `@session:` command without the TUI.
/// What: dispatches a `TrustyCommand::CoordinatorChat` through the shared
/// `CommandExecutor` and prints the reply (or the routed command's output);
/// a daemon/LLM failure becomes a non-zero-exit error line.
/// Test: covered by the executor's coordinator wire-shape tests.
pub(crate) async fn coordinator(url: &str, message: String) -> anyhow::Result<()> {
    use trusty_mpm::client::{CommandExecutor, CommandResult, TrustyCommand};
    let executor = CommandExecutor::new(url.to_string());
    match executor
        .execute(TrustyCommand::CoordinatorChat { message })
        .await
    {
        CommandResult::ChatReply { reply } => println!("{reply}"),
        CommandResult::Error(msg) => {
            eprintln!("coordinator: {msg}");
            std::process::exit(1);
        }
        other => eprintln!("unexpected coordinator result: {other:?}"),
    }
    Ok(())
}

/// `overseer` subcommand — inspect the session overseer.
///
/// Why: operators need to see whether oversight is active without the TUI.
/// What: `Status` calls `GET /overseer` and prints the enabled flag and
/// handler type.
/// Test: `cli_parses_overseer_status`.
pub(crate) async fn overseer(
    client: &reqwest::Client,
    url: &str,
    action: OverseerAction,
) -> anyhow::Result<()> {
    match action {
        OverseerAction::Status => {
            let body: serde_json::Value = client
                .get(format!("{url}/overseer"))
                .send()
                .await?
                .error_for_status()?
                .json()
                .await?;
            let overseer = &body["overseer"];
            let enabled = overseer
                .get("enabled")
                .and_then(|v| v.as_bool())
                .unwrap_or(false);
            let handler = overseer
                .get("handler")
                .and_then(|v| v.as_str())
                .unwrap_or("unknown");
            println!(
                "overseer: {} (handler: {handler})",
                if enabled { "enabled" } else { "disabled" }
            );
        }
    }
    Ok(())
}

/// Inspect or configure the token-use optimizer.
///
/// Why: the optimizer policy is framework-managed on disk; `Status` reads the
/// daemon's live view via `GET /optimizer`, while `Set` rewrites the policy
/// file itself (`~/.trusty-mpm/framework/hooks/optimizer.toml`) — the daemon's
/// watcher then reloads it.
/// What: `Status` prints the current config plus an honest scope note (which
/// sessions the level actually affects — issue #1944); `Set` writes a new
/// `[default]` level into the policy file, creating the `hooks/` dir if needed.
/// Test: `cli_parses_optimizer_status`, `cli_parses_optimizer_set`.
pub(crate) async fn optimizer(
    client: &reqwest::Client,
    url: &str,
    action: OptimizerAction,
) -> anyhow::Result<()> {
    match action {
        OptimizerAction::Status => {
            let body: serde_json::Value = client
                .get(format!("{url}/optimizer"))
                .send()
                .await?
                .json()
                .await?;
            println!("{}", serde_json::to_string_pretty(&body["optimizer"])?);
            // Print the scope note so operators are not misled into thinking a
            // non-Off level compresses their live native session (issue #1944).
            if let Some(scope) = body["scope"].as_str() {
                println!("\nscope: {scope}");
            }
        }
        OptimizerAction::Set { level } => {
            let level_name = match level {
                CliCompressionLevel::Off => "Off",
                CliCompressionLevel::Trim => "Trim",
                CliCompressionLevel::Summarise => "Summarise",
                CliCompressionLevel::Caveman => "Caveman",
            };
            let paths = trusty_mpm::core::paths::FrameworkPaths::default();
            let path = paths.optimizer_config();
            std::fs::create_dir_all(&paths.hooks)?;
            let contents = format!(
                "# trusty-mpm token optimizer — framework hook configuration\n\
                 # Edited by: trusty-mpm optimizer set\n\n\
                 [default]\nlevel = \"{level_name}\"\n\n\
                 [tools]\n"
            );
            std::fs::write(&path, contents)?;
            println!("optimizer level set to {level_name} ({})", path.display());
        }
    }
    Ok(())
}

/// Resolve `target` to a session and either print JSON or open the TUI.
///
/// Why: `tm attach` is the ergonomic entry point for an *existing* session —
/// operators type a short name or path rather than a full UUID.
/// What: Fetches `/sessions`, resolves via `resolve_target`, then either
/// serialises to JSON (`--json`) or launches the TUI pre-focused on the match.
/// #6483: that TUI is the multipane `project_ctl` dashboard by default;
/// `--single-pane` (threaded in as `single_pane`) opts back into the
/// coordinator chat.
/// Test: Resolution logic is tested in `trusty-mpm-core::connect`;
/// `cli_parses_attach_single_pane_opt_in` covers the flag.
pub(crate) async fn attach_cmd(
    client: &reqwest::Client,
    url: &str,
    target: &str,
    json: bool,
    single_pane: bool,
    explicit: Option<&str>,
) -> anyhow::Result<()> {
    use trusty_mpm::core::{ResolveResult, SessionSummary, resolve_target};

    // The daemon wraps the session array in a `{ "sessions": [...] }` envelope.
    let resp: serde_json::Value = client
        .get(format!("{url}/sessions"))
        .send()
        .await?
        .json()
        .await?;
    let empty = vec![];
    let raw = resp
        .get("sessions")
        .and_then(|v| v.as_array())
        .unwrap_or(&empty);

    // Parse sessions array — be tolerant of missing fields. `SessionId` is
    // serialized as a bare UUID string; the friendly name is `tmux_name`.
    let sessions: Vec<SessionSummary> = raw
        .iter()
        .filter_map(|v| {
            Some(SessionSummary {
                id: v["id"].as_str()?.to_string(),
                name: v["tmux_name"].as_str().map(str::to_string),
                workdir: v["workdir"].as_str().unwrap_or("").to_string(),
                last_active: v["last_seen"]["secs_since_epoch"].as_u64().unwrap_or(0),
            })
        })
        .collect();

    match resolve_target(target, &sessions) {
        ResolveResult::Found(id) => {
            if json {
                // Find the full session JSON and print it.
                if let Some(s) = raw.iter().find(|v| v["id"].as_str() == Some(&id)) {
                    println!("{}", serde_json::to_string_pretty(s)?);
                }
                return Ok(());
            }
            // Launch the TUI focused on this session. #6483: the multipane
            // dashboard is the default; the single-pane chat is opt-in.
            let resolved_url = trusty_mpm::core::resolve_daemon_url(Some(url));
            // #9556: an explicit `--url` / `TRUSTY_MPM_URL` survives a failed poll.
            let daemon = trusty_mpm::client::DaemonClient::new(resolved_url)
                .with_pinned_base_url(explicit.is_some_and(|u| !u.is_empty()));
            trusty_mpm::tui::run_initial_view_with(daemon, 1000, Some(id), single_pane).await
        }
        ResolveResult::Ambiguous(ids) => {
            eprintln!(
                "Ambiguous target '{target}' — matched {} sessions:",
                ids.len()
            );
            for id in &ids {
                eprintln!("  {id}");
            }
            std::process::exit(1);
        }
        ResolveResult::NotFound => {
            eprintln!("No session matched '{target}'.");
            if !sessions.is_empty() {
                eprintln!("Available sessions:");
                for s in &sessions {
                    let name = s.name.as_deref().unwrap_or("-");
                    eprintln!("  {} ({})  {}", s.id, name, s.workdir);
                }
            }
            std::process::exit(1);
        }
    }
}

// #7278: the parking detector opens a path the hook payload chose, so these
// cover the screen that decides whether it opens anything at all. Temp dirs
// come from `crate::test_support::hermetic_temp_dir`, never a bare
// `tempfile::tempdir()` — the bare constructor honors `$TMPDIR`, which a
// sibling test may repoint.
#[cfg(test)]
mod tests {
    use std::path::{Path, PathBuf};

    /// One assistant turn whose text is unambiguous parking language, so any
    /// `None` these tests see comes from the screen and not the detector.
    const PARKING_TEXT: &str =
        "I've started a background polling monitor for the checks and will report back once green.";

    /// Write a one-line transcript under `dir` and return its path.
    fn parking_transcript(dir: &Path) -> PathBuf {
        let path = dir.join("session.jsonl");
        let line = serde_json::json!({
            "type": "assistant",
            "message": { "content": [{ "type": "text", "text": PARKING_TEXT }] }
        });
        std::fs::write(&path, format!("{line}\n")).expect("write transcript");
        path
    }

    fn payload(transcript_path: &str) -> serde_json::Value {
        serde_json::json!({
            "hook_event_name": "Stop",
            "session_id": "sess-7278",
            "transcript_path": transcript_path,
        })
    }

    /// Why (#7278): the positive control. Every refusal below is only evidence
    /// of a screen if the same fixture, moved inside the boundary, is still
    /// detected — otherwise a broken detector would read as a passing screen.
    /// Test: itself.
    #[tokio::test]
    async fn detects_parking_in_a_transcript_under_the_config_dir() {
        let config = crate::test_support::hermetic_temp_dir();
        let transcript = parking_transcript(config.path());
        let payload = payload(&transcript.to_string_lossy());
        assert!(
            super::detect_idle_parking_from_payload_in(Some(&payload), Some(config.path()))
                .await
                .is_some(),
            "an in-boundary transcript must still be scanned"
        );
    }

    /// Why (#7278): the reported attack. A `transcript_path` naming a file the
    /// `tm` user can read but that Claude Code never wrote must not be opened.
    /// Test: itself.
    #[tokio::test]
    async fn refuses_a_transcript_path_outside_the_config_dir() {
        let config = crate::test_support::hermetic_temp_dir();
        let elsewhere = crate::test_support::hermetic_temp_dir();
        let transcript = parking_transcript(elsewhere.path());
        let payload = payload(&transcript.to_string_lossy());
        assert_eq!(
            super::detect_idle_parking_from_payload_in(Some(&payload), Some(config.path())).await,
            None,
            "a transcript outside the config directory must never be read"
        );
    }

    /// Why (#7278): a relative path resolves against the hook process's cwd,
    /// which the payload's author does not control but also cannot be screened
    /// against a fixed boundary — it is refused before canonicalization.
    /// Test: itself.
    #[tokio::test]
    async fn refuses_a_relative_transcript_path() {
        let config = crate::test_support::hermetic_temp_dir();
        let _ = parking_transcript(config.path());
        let payload = payload("session.jsonl");
        assert_eq!(
            super::detect_idle_parking_from_payload_in(Some(&payload), Some(config.path())).await,
            None,
            "a relative transcript_path must be refused"
        );
    }

    /// Why (#7278): `..` is the shape that walks out of a boundary the prefix
    /// check would otherwise accept, so it is refused on its own.
    /// Test: itself.
    #[tokio::test]
    async fn refuses_a_traversing_transcript_path() {
        let config = crate::test_support::hermetic_temp_dir();
        let elsewhere = crate::test_support::hermetic_temp_dir();
        let transcript = parking_transcript(elsewhere.path());
        let traversing = config
            .path()
            .join("..")
            .join(elsewhere.path().file_name().expect("temp dir name"))
            .join(transcript.file_name().expect("file name"));
        let payload = payload(&traversing.to_string_lossy());
        assert_eq!(
            super::detect_idle_parking_from_payload_in(Some(&payload), Some(config.path())).await,
            None,
            "a `..` component must be refused before the path is resolved"
        );
    }

    /// Why (#7290): with no config directory there is no boundary, and a
    /// resolver that fell back to `FrameworkPaths::default()` would silently
    /// re-scope containment to `<cwd>/.claude`. The refusal must be total.
    /// Test: itself.
    #[tokio::test]
    async fn refuses_every_transcript_path_without_a_config_dir() {
        let config = crate::test_support::hermetic_temp_dir();
        let transcript = parking_transcript(config.path());
        let payload = payload(&transcript.to_string_lossy());
        assert_eq!(
            super::detect_idle_parking_from_payload_in(Some(&payload), None).await,
            None,
            "no boundary means no read, even for a path that would have passed"
        );
    }
}