claudette 0.9.0

//! On-demand tool group registry.
//!
//! Claudette ships a minimal **core** of tools on every request — just
//! `enable_tools(group)` plus `get_current_time` — and gates everything
//! else behind `enable_tools`. When the model calls `enable_tools`, the
//! chosen group's tools are added to the registry and show up on the
//! next `/api/chat` call. The base schema stays under ~200 tokens
//! regardless of how many groups exist.
//!
//! Why it matters: every char of the `tools` field counts against `num_ctx`.
//! Pre-rewrite the baseline was ~2,500 tokens (43 tools shipped per turn
//! in TUI/Telegram). Now it's ~200 tokens, with each group adding only
//! the tools it owns when the model asks for it.
//!
//! Mutation model: the registry lives behind an `Arc<Mutex<_>>` shared by
//! [`OllamaApiClient`] (which reads it to build the `tools` field) and
//! [`crate::executor::SecretaryToolExecutor`] (which writes it when the
//! model invokes `enable_tools`). Both halves of the runtime see the same
//! registry, so an enable in one turn is visible on the next turn.

use std::collections::{BTreeMap, BTreeSet};

use serde_json::{json, Value};

/// Named tool groups that can be enabled on demand. Only `enable_tools`
/// and `get_current_time` ship in core — every other tool lives in one of
/// these groups.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub enum ToolGroup {
    /// Personal notes: create, list, read, update, delete.
    Notes,
    /// Todo list: add, list, complete, uncomplete, delete.
    Todos,
    /// File ops: read_file, write_file, list_dir.
    Files,
    /// Code generation via the specialised coder model: generate_code.
    Code,
    /// Self-introspection: get_capabilities (config, tool inventory, limits).
    Meta,
    /// Git workflow tools: status, diff, log, add, commit, branch, checkout, push.
    Git,
    /// IDE integration: open in editor, reveal in file manager, open URL.
    Ide,
    /// Search: web_search (Brave), web_fetch, glob_search, grep_search.
    Search,
    /// Power tools: bash, `edit_file`, `spawn_agent` (delegation).
    Advanced,
    /// Reference lookups: Wikipedia, Open-Meteo weather.
    Facts,
    /// Package registries: crates.io, npmjs.
    Registry,
    /// GitHub API (PRs, issues, code search). Requires `GITHUB_TOKEN`.
    Github,
    /// Market data: `TradingView` quotes/ratings/calendar + `vestige.fi` Algorand ASAs.
    Markets,
    /// Telegram bot: send messages, poll updates, send photos.
    Telegram,
    /// Google Calendar: list / create / update / delete events, RSVP.
    /// Requires `claudette --auth-google` one-time setup.
    Calendar,
    /// Proactive scheduler: one-shot + recurring reminders the agent can
    /// send itself later. Backed by `~/.claudette/schedule.jsonl`.
    Schedule,
    /// Gmail (read-only): list, search, read, list_labels. Requires
    /// `claudette --auth-google gmail` one-time setup. Scope separated from
    /// Calendar per AD-6; no send/modify in this group.
    Gmail,
    /// Cross-session semantic recall: search past conversations indexed in
    /// `~/.claudette/recall.sqlite`. One tool — `recall(query, k)`.
    Recall,
    /// Code-quality tools that close the gap with Claude Code / Aider on
    /// the engineering inner loop: `run_tests`, plus `diagnostics`
    /// (Phase 3.1b) and `apply_patch` (Phase 3.1c) coming in the same
    /// v0.6.0 sprint.
    Quality,
    /// Workspace-scoped semantic-ish search (v0.6.0 ships `semantic_grep`
    /// as a token-overlap MVP; embedding-backed variant is follow-up).
    Semantic,
    /// Vision tools (v0.6.0 Phase 3.2b): screenshot_capture + image_describe.
    /// image_describe requires a vision-language model loaded in LM Studio.
    Vision,
    /// Clipboard text I/O (v0.6.0 Phase 3.4b): clipboard_read + clipboard_write.
    /// Backed by arboard.
    Clipboard,
}

impl ToolGroup {
    /// Canonical lowercase name the model uses in `enable_tools({group:...})`.
    #[must_use]
    pub fn name(self) -> &'static str {
        match self {
            Self::Notes => "notes",
            Self::Todos => "todos",
            Self::Files => "files",
            Self::Code => "code",
            Self::Meta => "meta",
            Self::Git => "git",
            Self::Ide => "ide",
            Self::Search => "search",
            Self::Advanced => "advanced",
            Self::Facts => "facts",
            Self::Registry => "registry",
            Self::Github => "github",
            Self::Markets => "markets",
            Self::Telegram => "telegram",
            Self::Calendar => "calendar",
            Self::Schedule => "schedule",
            Self::Gmail => "gmail",
            Self::Recall => "recall",
            Self::Quality => "quality",
            Self::Semantic => "semantic",
            Self::Vision => "vision",
            Self::Clipboard => "clipboard",
        }
    }

    /// One-line human summary. Used in the system prompt manifest so the 4b
    /// brain has the verb-level hints it needs to chain `enable_tools(group)`
    /// into the specific tool name. Brain100 on 4b regressed from 94% to 84%
    /// when we tried a terser variant — the verb decomposition is
    /// load-bearing on small models. Also shown by `get_capabilities`.
    #[must_use]
    pub fn summary(self) -> &'static str {
        match self {
            Self::Notes => "personal notes: create/list/read/delete. note_create is upsert — pass `id` from note_list to update an existing note.",
            Self::Todos => "todo list: add/list/set_status (done bool)/delete",
            Self::Files => "file ops: read_file, write_file, list_dir (under ~/)",
            Self::Code => "code generation via specialised coder model + validator",
            Self::Meta => "self-introspection: config, tool inventory, limits",
            Self::Git => "git workflows: status, diff, log, add, commit, branch, checkout, push",
            Self::Ide => "IDE integration: open_in_editor, reveal_in_explorer, open_url",
            Self::Search => "search: repo_map (localize code by concept — use first), grep_search (regex), glob_search, web_search (Brave), web_fetch",
            Self::Advanced => "power tools: bash (sync), bash_background + bash_status + bash_tail, apply_diff (fuzzy before/after edit), edit_file (legacy), spawn_agent, ask_user (turn-suspending clarifier)",
            Self::Facts => "reference lookups: wikipedia (summary or search via `mode`), weather (no API key needed)",
            Self::Registry => "package registries: crates.io and npm package metadata (version, downloads, homepage)",
            Self::Github => "github + brownfield missions: gh_inbox(scope=my_prs|assigned|repo_issues), issue+PR ops, code search, clone/fork, mission_start + mission_state(action=status|list|attach|exit) + mission_submit (requires GITHUB_TOKEN)",
            Self::Markets => "market data: TradingView quotes (stocks/crypto/forex/futures, bare or qualified tickers)",
            Self::Telegram => "telegram bot: tg_send (text, or photo via optional `photo` URL — caption becomes the text). Requires TELEGRAM_BOT_TOKEN.",
            Self::Calendar => "google calendar: list/create/update/delete events. calendar_update_event takes optional `rsvp` for RSVP-only edits. Requires claudette --auth-google.",
            Self::Schedule => "proactive reminders: one-shot + recurring schedules that fire prompts back at you",
            Self::Gmail => "gmail (read-only): list/search/read messages, list labels (requires claudette --auth-google gmail)",
            Self::Recall => "cross-session memory: recall past messages by semantic similarity (use when user references prior conversations)",
            Self::Quality => "code quality + edits: run_tests, diagnostics (cargo check / clippy / tsc / mypy / ruff), apply_patch (atomic multi-file unified diff).",
            Self::Semantic => "workspace search: semantic_grep (token-overlap ranking, fuzzier than grep).",
            Self::Vision => "vision: screenshot_capture (PNG to ~/.claudette/files/), image_describe (needs a VLM loaded in LM Studio).",
            Self::Clipboard => "OS clipboard: clipboard_read, clipboard_write (text only, 1 MB cap).",
        }
    }

    /// All groups in a stable order, for schema generation and tests.
    #[must_use]
    pub fn all() -> [ToolGroup; 22] {
        [
            Self::Notes,
            Self::Todos,
            Self::Files,
            Self::Code,
            Self::Meta,
            Self::Git,
            Self::Ide,
            Self::Search,
            Self::Advanced,
            Self::Facts,
            Self::Registry,
            Self::Github,
            Self::Markets,
            Self::Telegram,
            Self::Calendar,
            Self::Schedule,
            Self::Gmail,
            Self::Recall,
            Self::Quality,
            Self::Semantic,
            Self::Vision,
            Self::Clipboard,
        ]
    }

    /// The lean **coding core**: the actuation groups a coding session needs
    /// immediately — read/write/list (`Files`), grep/glob/repo_map (`Search`),
    /// edit_file/apply_diff/bash (`Advanced`), and run_tests/diagnostics/
    /// apply_patch (`Quality`). Pre-enabled when claudette is pointed at a
    /// workspace (see `run::build_runtime_with_brain_inner`) and used as the
    /// forgiving fallback when the model calls `enable_tools` with no group
    /// (see `executor::run_enable_tools`). Costs ~2.2k tokens of schema; the
    /// integration/long-tail groups (github, gmail, calendar, …) stay lazy.
    ///
    /// Why this exists: small local brains frequently emit
    /// `<function=enable_tools></function>` with the `group` arg dropped, then
    /// spiral on the error until timeout. Shipping these tools when a repo is
    /// in scope removes the round-trip the brain can't reliably win.
    #[must_use]
    pub fn coding_core() -> [ToolGroup; 4] {
        [Self::Files, Self::Search, Self::Advanced, Self::Quality]
    }

    /// Case-insensitive parse with a couple of common aliases.
    #[must_use]
    pub fn parse(s: &str) -> Option<Self> {
        match s.trim().to_lowercase().as_str() {
            "notes" | "note" => Some(Self::Notes),
            "todos" | "todo" | "tasks" | "task" => Some(Self::Todos),
            "files" | "file" | "fs" => Some(Self::Files),
            "code" | "codegen" | "coder" => Some(Self::Code),
            "meta" | "capabilities" | "info" | "status" => Some(Self::Meta),
            "git" => Some(Self::Git),
            "ide" | "editor" => Some(Self::Ide),
            "search" | "grep" | "glob" | "web" => Some(Self::Search),
            "advanced" | "shell" | "power" | "bash" => Some(Self::Advanced),
            "facts" | "wikipedia" | "weather" => Some(Self::Facts),
            "registry" | "crates" | "npm" => Some(Self::Registry),
            "github" | "gh" => Some(Self::Github),
            "markets" | "market" | "tradingview" | "tv" | "vestige" | "stocks" | "crypto" => {
                Some(Self::Markets)
            }
            "telegram" | "tg" | "tg_bot" => Some(Self::Telegram),
            "calendar" | "gcal" | "google-calendar" | "google_calendar" => Some(Self::Calendar),
            "schedule" | "scheduler" | "reminders" | "reminder" => Some(Self::Schedule),
            "gmail" | "mail" | "email" | "inbox" => Some(Self::Gmail),
            "recall" | "memory" | "remember" | "history" => Some(Self::Recall),
            "quality" | "tests" | "lint" | "diagnostics" => Some(Self::Quality),
            "semantic" | "smart-grep" | "concept" => Some(Self::Semantic),
            "vision" | "image" | "screenshot" | "vlm" => Some(Self::Vision),
            "clipboard" | "copy" | "paste" => Some(Self::Clipboard),
            _ => None,
        }
    }
}

/// Names of the core tools — always advertised, never gated. Kept tiny by
/// design so the base payload stays under ~200 tokens. Everything else
/// (notes, todos, files, codegen, search, etc.) lives in a [`ToolGroup`]
/// and ships only after the model calls `enable_tools`.
///
/// The synthetic `enable_tools` meta-tool is added by [`ToolRegistry::new`]
/// and isn't pulled from `secretary_tools_json`. `get_current_time` is
/// kept in core because it's tiny (~25 tokens), used in nearly every
/// conversation, and asking the model to call `enable_tools(time)` first
/// would burn an unnecessary round-trip.
pub const CORE_TOOL_NAMES: &[&str] = &["enable_tools", "get_current_time", "load_workspace_rules"];

/// Classify a tool name into its group. Returns `None` for core tools, for
/// unknown names, and for `add_numbers` (kept in `dispatch_tool` for
/// backwards-compat but removed from the schema).
#[must_use]
pub fn group_of(tool: &str) -> Option<ToolGroup> {
    match tool {
        // note_create is a v0.6.0 upsert — pass `id` to update an existing
        // note (the standalone note_update tool was dropped).
        "note_create" | "note_list" | "note_read" | "note_delete" => Some(ToolGroup::Notes),
        // todo_set_status(done?) replaced the v0.6.0 todo_complete +
        // todo_uncomplete pair.
        "todo_add" | "todo_list" | "todo_set_status" | "todo_delete" => Some(ToolGroup::Todos),
        "read_file" | "write_file" | "list_dir" => Some(ToolGroup::Files),
        "generate_code" => Some(ToolGroup::Code),
        "get_capabilities" => Some(ToolGroup::Meta),
        "git_status" | "git_diff" | "git_log" | "git_add" | "git_commit" | "git_branch"
        | "git_checkout" | "git_push" | "git_clone" => Some(ToolGroup::Git),
        "open_in_editor" | "reveal_in_explorer" | "open_url" => Some(ToolGroup::Ide),
        "glob_search" | "grep_search" | "web_fetch" | "web_search" | "repo_map" => {
            Some(ToolGroup::Search)
        }
        "bash" | "edit_file" | "apply_diff" | "spawn_agent" | "bash_background" | "bash_status"
        | "bash_tail" | "ask_user" => Some(ToolGroup::Advanced),
        // wikipedia(mode?) and weather(days?) subsume the v0.6.0
        // wikipedia_search/summary and weather_current/forecast names.
        "wikipedia" | "weather" => Some(ToolGroup::Facts),
        "crate_info" | "npm_info" => Some(ToolGroup::Registry),
        // gh_inbox(scope=...) subsumes the v0.6.0 gh_list_my_prs +
        // gh_list_assigned_issues names; mission_state(action=...) subsumes
        // mission_status / mission_list / mission_attach / mission_exit.
        "gh_inbox"
        | "gh_get_issue"
        | "gh_create_issue"
        | "gh_comment_issue"
        | "gh_search_code"
        | "gh_list_repo_issues"
        | "gh_pr_status"
        | "gh_pr_view"
        | "gh_workflow_logs"
        | "gh_fork"
        | "gh_create_pr"
        | "mission_start"
        | "mission_state"
        | "mission_submit" => Some(ToolGroup::Github),
        "tv_get_quote" => Some(ToolGroup::Markets),
        // tg_send(photo?) subsumes the v0.6.0 tg_send_photo name.
        "tg_send" => Some(ToolGroup::Telegram),
        // calendar_update_event(rsvp=...) subsumes the v0.6.0
        // calendar_respond_to_event name.
        "calendar_list_events"
        | "calendar_create_event"
        | "calendar_update_event"
        | "calendar_delete_event" => Some(ToolGroup::Calendar),
        "schedule_once" | "schedule_recurring" | "schedule_list" | "schedule_cancel" => {
            Some(ToolGroup::Schedule)
        }
        "gmail_list" | "gmail_search" | "gmail_read" | "gmail_list_labels" => {
            Some(ToolGroup::Gmail)
        }
        "recall" => Some(ToolGroup::Recall),
        "run_tests" | "diagnostics" | "apply_patch" => Some(ToolGroup::Quality),
        "semantic_grep" => Some(ToolGroup::Semantic),
        "screenshot_capture" | "image_describe" => Some(ToolGroup::Vision),
        "clipboard_read" | "clipboard_write" => Some(ToolGroup::Clipboard),
        // forge_tail lives in the Github group alongside mission_* since
        // that's where the forge-mission lifecycle already lives.
        "forge_tail" => Some(ToolGroup::Github),
        _ => None,
    }
}

/// Mutable tool registry shared between [`crate::api::OllamaApiClient`] and
/// [`crate::executor::SecretaryToolExecutor`]. Holds the core tools (always
/// included) plus the optional groups keyed by [`ToolGroup`], and the set of
/// currently-enabled groups.
pub struct ToolRegistry {
    /// Core tools — always in the output of [`Self::current_tools`].
    /// Includes the synthetic `enable_tools` meta-tool at index 0.
    core: Vec<Value>,
    /// Group → list of tool JSON objects. Populated once at construction.
    groups: BTreeMap<ToolGroup, Vec<Value>>,
    /// Currently enabled groups. Starts empty.
    enabled: BTreeSet<ToolGroup>,
}

impl ToolRegistry {
    /// Build the registry from the full tool list in [`crate::tools`].
    ///
    /// The `enable_tools` meta-tool is **synthesized** here (not loaded from
    /// `secretary_tools_json`) because it's stateful — its implementation
    /// lives in the executor, not in [`crate::tools::dispatch_tool`], so we
    /// don't want it in the stateless tool list.
    #[must_use]
    pub fn new() -> Self {
        let full = crate::tools::secretary_tools_json();
        let arr = full.as_array().cloned().unwrap_or_default();

        let mut core: Vec<Value> = Vec::with_capacity(CORE_TOOL_NAMES.len());
        let mut groups: BTreeMap<ToolGroup, Vec<Value>> = BTreeMap::new();

        // Always-on meta-tool goes first so the model sees it at the top of
        // the schema.
        core.push(enable_tools_schema());

        for tool in arr {
            let Some(name) = tool
                .pointer("/function/name")
                .and_then(Value::as_str)
                .map(str::to_string)
            else {
                continue;
            };
            if CORE_TOOL_NAMES.contains(&name.as_str()) {
                core.push(tool);
            } else if let Some(group) = group_of(&name) {
                groups.entry(group).or_default().push(tool);
            }
            // Any tool that is neither core nor in a group (currently none)
            // is dropped from the advertised schema. Dispatch still works if
            // the model somehow calls it by name.
        }

        Self {
            core,
            groups,
            enabled: BTreeSet::new(),
        }
    }

    /// Merge `core` + all currently-enabled groups into the JSON array that
    /// ships to Ollama in the `tools` field.
    #[must_use]
    pub fn current_tools(&self) -> Value {
        let mut out: Vec<Value> = Vec::with_capacity(self.current_len());
        out.extend(self.core.iter().cloned());
        for group in &self.enabled {
            if let Some(tools) = self.groups.get(group) {
                out.extend(tools.iter().cloned());
            }
        }
        Value::Array(out)
    }

    /// How many tools [`current_tools`] would emit right now.
    #[must_use]
    pub fn current_len(&self) -> usize {
        self.core.len()
            + self
                .enabled
                .iter()
                .map(|g| self.groups.get(g).map_or(0, Vec::len))
                .sum::<usize>()
    }

    /// Char-count of the JSON-serialized current tool array. Useful for the
    /// `/tools` slash command to surface the schema size impact of enabling
    /// a group.
    #[must_use]
    pub fn current_schema_chars(&self) -> usize {
        self.current_tools().to_string().len()
    }

    /// Enable `group`. Returns `true` if this is the first time the group has
    /// been enabled in this registry's lifetime (useful for reporting).
    pub fn enable(&mut self, group: ToolGroup) -> bool {
        self.enabled.insert(group)
    }

    /// Enable every group in the lean [`ToolGroup::coding_core`]. Returns the
    /// number of groups newly enabled by this call (idempotent — re-enabling
    /// already-active groups counts zero).
    pub fn enable_coding_core(&mut self) -> usize {
        ToolGroup::coding_core()
            .into_iter()
            .filter(|g| self.enable(*g))
            .count()
    }

    /// Whether `group` is currently enabled.
    #[must_use]
    pub fn is_enabled(&self, group: ToolGroup) -> bool {
        self.enabled.contains(&group)
    }

    /// Snapshot of enabled groups in stable order.
    #[must_use]
    pub fn enabled_groups(&self) -> Vec<ToolGroup> {
        self.enabled.iter().copied().collect()
    }

    /// List the tool names in `group`, in schema order. Used by `run_enable_tools`
    /// to tell the model what's newly available.
    #[must_use]
    pub fn group_tool_names(&self, group: ToolGroup) -> Vec<String> {
        self.groups
            .get(&group)
            .map(|tools| {
                tools
                    .iter()
                    .filter_map(|t| {
                        t.pointer("/function/name")
                            .and_then(Value::as_str)
                            .map(String::from)
                    })
                    .collect()
            })
            .unwrap_or_default()
    }

    /// List of core tool names (for `/tools` display). Returns the synthesized
    /// `enable_tools` first, followed by the core tools pulled from
    /// `secretary_tools_json`.
    #[must_use]
    pub fn core_tool_names(&self) -> Vec<String> {
        self.core
            .iter()
            .filter_map(|t| {
                t.pointer("/function/name")
                    .and_then(Value::as_str)
                    .map(String::from)
            })
            .collect()
    }
}

impl Default for ToolRegistry {
    fn default() -> Self {
        Self::new()
    }
}

/// Build the JSON schema for the `enable_tools` meta-tool.
///
/// Description and parameter description list every group name (no
/// per-group summaries) so the base payload stays under ~200 tokens.
/// The model has enough training-data prior on names like `git`,
/// `calendar`, `gmail` to pick correctly; the few non-obvious groups
/// (`meta`, `facts`, `advanced`) cost at most one extra round-trip
/// when the model picks wrong, which is dwarfed by the per-turn token
/// savings versus shipping verbose summaries every request.
fn enable_tools_schema() -> Value {
    let names_csv = ToolGroup::all()
        .iter()
        .map(|g| g.name())
        .collect::<Vec<_>>()
        .join(", ");
    let description = format!("Enable a tool group (available next turn). Groups: {names_csv}.");

    // No `enum` constraint on `group` — the description above lists every
    // valid name, and `run_enable_tools` returns a clear "unknown group"
    // error with the full list on typos. The enum was costing ~37 tokens
    // per turn for a duplicate name list; server-side validation is enough
    // and lets the brain typo-recover via the error message.
    json!({
        "type": "function",
        "function": {
            "name": "enable_tools",
            "description": description,
            "parameters": {
                "type": "object",
                "properties": {
                    "group": { "type": "string" }
                },
                "required": ["group"]
            }
        }
    })
}

// ────────────────────────────────────────────────────────────────────────────
// Tests
// ────────────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn parse_group_canonical() {
        assert_eq!(ToolGroup::parse("git"), Some(ToolGroup::Git));
        assert_eq!(ToolGroup::parse("ide"), Some(ToolGroup::Ide));
        assert_eq!(ToolGroup::parse("search"), Some(ToolGroup::Search));
        assert_eq!(ToolGroup::parse("advanced"), Some(ToolGroup::Advanced));
        assert_eq!(ToolGroup::parse("facts"), Some(ToolGroup::Facts));
        assert_eq!(ToolGroup::parse("registry"), Some(ToolGroup::Registry));
        assert_eq!(ToolGroup::parse("github"), Some(ToolGroup::Github));
        assert_eq!(ToolGroup::parse("markets"), Some(ToolGroup::Markets));
        assert_eq!(ToolGroup::parse("tradingview"), Some(ToolGroup::Markets));
        assert_eq!(ToolGroup::parse("vestige"), Some(ToolGroup::Markets));
        assert_eq!(ToolGroup::parse("telegram"), Some(ToolGroup::Telegram));
    }

    #[test]
    fn parse_group_aliases() {
        assert_eq!(ToolGroup::parse("GIT"), Some(ToolGroup::Git));
        assert_eq!(ToolGroup::parse("  git "), Some(ToolGroup::Git));
        assert_eq!(ToolGroup::parse("editor"), Some(ToolGroup::Ide));
        assert_eq!(ToolGroup::parse("grep"), Some(ToolGroup::Search));
        assert_eq!(ToolGroup::parse("shell"), Some(ToolGroup::Advanced));
        assert_eq!(ToolGroup::parse("bash"), Some(ToolGroup::Advanced));
        assert_eq!(ToolGroup::parse("wikipedia"), Some(ToolGroup::Facts));
        assert_eq!(ToolGroup::parse("weather"), Some(ToolGroup::Facts));
        assert_eq!(ToolGroup::parse("crates"), Some(ToolGroup::Registry));
        assert_eq!(ToolGroup::parse("npm"), Some(ToolGroup::Registry));
        assert_eq!(ToolGroup::parse("gh"), Some(ToolGroup::Github));
        assert_eq!(ToolGroup::parse("tg"), Some(ToolGroup::Telegram));
    }

    #[test]
    fn parse_group_unknown() {
        assert_eq!(ToolGroup::parse(""), None);
        assert_eq!(ToolGroup::parse("unknown"), None);
        assert_eq!(ToolGroup::parse("core"), None);
    }

    #[test]
    fn group_of_classifies_known_tools() {
        assert_eq!(group_of("git_status"), Some(ToolGroup::Git));
        assert_eq!(group_of("git_push"), Some(ToolGroup::Git));
        assert_eq!(group_of("open_in_editor"), Some(ToolGroup::Ide));
        assert_eq!(group_of("glob_search"), Some(ToolGroup::Search));
        assert_eq!(group_of("web_fetch"), Some(ToolGroup::Search));
        assert_eq!(group_of("bash"), Some(ToolGroup::Advanced));
        assert_eq!(group_of("spawn_agent"), Some(ToolGroup::Advanced));
        // Sprint 9 Phase 0a additions.
        assert_eq!(group_of("wikipedia"), Some(ToolGroup::Facts));
        assert_eq!(group_of("weather"), Some(ToolGroup::Facts));
        // v0.6.0: these merged into wikipedia(mode?)/weather(days?) and
        // are no longer tool names.
        assert_eq!(group_of("wikipedia_search"), None);
        assert_eq!(group_of("wikipedia_summary"), None);
        assert_eq!(group_of("weather_current"), None);
        assert_eq!(group_of("weather_forecast"), None);
        assert_eq!(group_of("crate_info"), Some(ToolGroup::Registry));
        assert_eq!(group_of("npm_info"), Some(ToolGroup::Registry));
        assert_eq!(group_of("gh_inbox"), Some(ToolGroup::Github));
        assert_eq!(group_of("gh_create_issue"), Some(ToolGroup::Github));
        assert_eq!(group_of("mission_state"), Some(ToolGroup::Github));
        // v0.6.0: these merged into gh_inbox/mission_state and are no
        // longer tool names.
        assert_eq!(group_of("gh_list_my_prs"), None);
        assert_eq!(group_of("gh_list_assigned_issues"), None);
        assert_eq!(group_of("mission_status"), None);
        assert_eq!(group_of("mission_list"), None);
        assert_eq!(group_of("mission_attach"), None);
        assert_eq!(group_of("mission_exit"), None);
        assert_eq!(group_of("tv_get_quote"), Some(ToolGroup::Markets));
        assert_eq!(group_of("tg_send"), Some(ToolGroup::Telegram));
        // v0.6.0: tg_send_photo merged into tg_send(photo?) — no longer a tool name.
        assert_eq!(group_of("tg_send_photo"), None);
        // v0.6.0 decom: these tools no longer exist anywhere.
        assert_eq!(group_of("crate_search"), None);
        assert_eq!(group_of("npm_search"), None);
        assert_eq!(group_of("tv_technical_rating"), None);
        assert_eq!(group_of("tv_search_symbol"), None);
        assert_eq!(group_of("tv_economic_calendar"), None);
        assert_eq!(group_of("vestige_asa_info"), None);
        assert_eq!(group_of("vestige_search_asa"), None);
        assert_eq!(group_of("vestige_top_movers"), None);
        assert_eq!(group_of("tg_get_updates"), None);
    }

    #[test]
    fn group_of_returns_none_for_core() {
        for &name in CORE_TOOL_NAMES {
            assert_eq!(
                group_of(name),
                None,
                "core tool {name} should not map to a group"
            );
        }
    }

    #[test]
    fn every_advertised_tool_is_classified() {
        // Catches the class of bug where a new tool gets added to
        // `crate::tools::secretary_tools_json` (so it shows up in the schema)
        // but the maintainer forgets to add it to either CORE_TOOL_NAMES or
        // the `group_of` match arms — the registry's `for tool in arr`
        // loop silently drops such tools, so the brain never sees them in
        // an `enable_tools(group)` advertise. Exactly how `note_update`
        // shipped to v0.2.2-line `[Unreleased]` invisibly until v0.2.3
        // reconciliation.
        let full = crate::tools::secretary_tools_json();
        let arr = full.as_array().cloned().unwrap_or_default();
        let mut unclassified: Vec<String> = Vec::new();
        for tool in arr {
            let Some(name) = tool
                .pointer("/function/name")
                .and_then(Value::as_str)
                .map(str::to_string)
            else {
                continue;
            };
            let is_core = CORE_TOOL_NAMES.contains(&name.as_str());
            let is_grouped = group_of(&name).is_some();
            if !is_core && !is_grouped {
                unclassified.push(name);
            }
        }
        assert!(
            unclassified.is_empty(),
            "tool(s) advertised but not classified into core/group — \
             will be silently dropped by ToolRegistry::new: {unclassified:?}. \
             Add to CORE_TOOL_NAMES or to a `group_of` arm."
        );
    }

    #[test]
    fn registry_starts_with_only_core() {
        let reg = ToolRegistry::new();
        assert!(reg.enabled_groups().is_empty());
        // Core: enable_tools (synthesised) + get_current_time +
        // load_workspace_rules. Everything else (notes, todos, files, code,
        // meta, search, etc.) must be enabled on demand. `describe_group`
        // was tried briefly but removed — qwen3.5-4b couldn't figure out
        // how to call it and the manifest already carries the verb hints.
        let core_names = reg.core_tool_names();
        assert_eq!(
            core_names.len(),
            3,
            "core should be exactly 3 tools, got {core_names:?}"
        );
        assert!(core_names.contains(&"enable_tools".to_string()));
        assert!(core_names.contains(&"get_current_time".to_string()));
        assert!(core_names.contains(&"load_workspace_rules".to_string()));
        // The previously-core tools must now live in their groups.
        assert!(!core_names.contains(&"read_file".to_string()));
        assert!(!core_names.contains(&"generate_code".to_string()));
        assert!(!core_names.contains(&"note_create".to_string()));
        assert!(!core_names.contains(&"web_search".to_string()));
    }

    #[test]
    fn registry_current_tools_starts_at_core_size() {
        let reg = ToolRegistry::new();
        let tools = reg.current_tools();
        let arr = tools.as_array().expect("tools should be an array");
        assert_eq!(arr.len(), reg.core.len());
        assert_eq!(arr.len(), reg.current_len());
    }

    #[test]
    fn enable_group_adds_tools_to_current() {
        let mut reg = ToolRegistry::new();
        let base = reg.current_len();

        let newly_enabled = reg.enable(ToolGroup::Git);
        assert!(newly_enabled);
        assert!(reg.is_enabled(ToolGroup::Git));

        let after = reg.current_len();
        assert!(
            after > base,
            "enabling git should add tools (base={base}, after={after})"
        );

        // Contains git_status now.
        let arr = reg.current_tools();
        let names: Vec<&str> = arr
            .as_array()
            .unwrap()
            .iter()
            .filter_map(|t| t.pointer("/function/name").and_then(Value::as_str))
            .collect();
        assert!(names.contains(&"git_status"));
        assert!(names.contains(&"enable_tools"));
    }

    #[test]
    fn enable_group_idempotent() {
        let mut reg = ToolRegistry::new();
        let first = reg.enable(ToolGroup::Ide);
        let second = reg.enable(ToolGroup::Ide);
        assert!(first, "first enable reports new");
        assert!(!second, "second enable reports already-on");
        assert_eq!(reg.enabled_groups(), vec![ToolGroup::Ide]);
    }

    #[test]
    fn enable_multiple_groups_combines_tools() {
        let mut reg = ToolRegistry::new();
        reg.enable(ToolGroup::Git);
        reg.enable(ToolGroup::Search);

        let names: Vec<String> = reg
            .current_tools()
            .as_array()
            .unwrap()
            .iter()
            .filter_map(|t| {
                t.pointer("/function/name")
                    .and_then(Value::as_str)
                    .map(String::from)
            })
            .collect();
        assert!(names.contains(&"git_commit".to_string()));
        assert!(names.contains(&"grep_search".to_string()));
        // Advanced not enabled.
        assert!(!names.contains(&"bash".to_string()));
    }

    #[test]
    fn group_tool_names_returns_schema_order() {
        let reg = ToolRegistry::new();
        let git = reg.group_tool_names(ToolGroup::Git);
        assert!(git.contains(&"git_status".to_string()));
        assert!(git.contains(&"git_push".to_string()));
        assert!(git.contains(&"git_clone".to_string()));
        // All Git group tools should be non-empty.
        assert_eq!(git.len(), 9);
    }

    #[test]
    fn github_group_includes_brownfield_tools() {
        let reg = ToolRegistry::new();
        let gh = reg.group_tool_names(ToolGroup::Github);
        for name in [
            "gh_inbox",
            "gh_list_repo_issues",
            "gh_pr_status",
            "gh_pr_view",
            "gh_workflow_logs",
            "gh_fork",
            "gh_create_pr",
            "mission_start",
            "mission_state",
            "mission_submit",
        ] {
            assert!(gh.contains(&name.to_string()), "missing {name} in {gh:?}");
        }
        // v0.6.0: gh_list_my_prs + gh_list_assigned_issues collapsed into
        // gh_inbox(scope=...); mission_status/list/attach/exit collapsed
        // into mission_state(action=...). gh_pr_view + gh_workflow_logs
        // added in Phase 3.3. forge_tail joins via Phase 3.4c (lives in
        // the Github group with the mission_* lifecycle). Group is now 15.
        assert!(gh.contains(&"forge_tail".to_string()), "forge_tail missing");
        assert_eq!(gh.len(), 15);
    }

    #[test]
    fn schema_chars_grows_with_enables() {
        let mut reg = ToolRegistry::new();
        let core_only = reg.current_schema_chars();
        reg.enable(ToolGroup::Git);
        let with_git = reg.current_schema_chars();
        assert!(
            with_git > core_only,
            "enabling git should grow schema (core={core_only}, with_git={with_git})"
        );
    }

    #[test]
    fn enable_tools_schema_mentions_every_group() {
        let schema = enable_tools_schema();
        let desc = schema
            .pointer("/function/description")
            .and_then(Value::as_str)
            .unwrap_or("");
        for g in ToolGroup::all() {
            assert!(
                desc.contains(g.name()),
                "description should mention {}: {desc}",
                g.name()
            );
        }
    }

    #[test]
    fn enable_tools_group_param_has_no_redundant_description() {
        // The function-level description already lists every valid group
        // name; a per-property description would duplicate that. Keep
        // the parameter schema bare to stay under the token budget.
        let schema = enable_tools_schema();
        let desc = schema.pointer("/function/parameters/properties/group/description");
        assert!(
            desc.is_none(),
            "group param must not carry a description (token budget): {desc:?}"
        );
    }

    #[test]
    fn enable_tools_schema_has_no_enum() {
        // The `enum` was removed to save ~37 tokens per turn — server-side
        // validation in `run_enable_tools` returns a clear error listing
        // every valid group on typos, which is enough for the model to
        // recover. Re-adding the enum here would silently undo the saving.
        let schema = enable_tools_schema();
        let enum_node = schema.pointer("/function/parameters/properties/group/enum");
        assert!(
            enum_node.is_none(),
            "group param must not carry an enum (token budget): {enum_node:?}"
        );
    }

    /// Report the concrete schema-size numbers so the author (and anyone
    /// reading the memory doc) can cite them without rerunning by hand.
    /// Run with `cargo test -p claudette schema_size_report -- --nocapture`.
    #[test]
    fn schema_size_report() {
        let old_full = crate::tools::secretary_tools_json().to_string().len();

        let reg = ToolRegistry::new();
        let core_only = reg.current_schema_chars();
        let core_count = reg.core_tool_names().len();

        let mut git_only = ToolRegistry::new();
        git_only.enable(ToolGroup::Git);
        let with_git = git_only.current_schema_chars();

        let mut all = ToolRegistry::new();
        for g in ToolGroup::all() {
            all.enable(g);
        }
        let with_all = all.current_schema_chars();
        let all_count = all.current_len();

        eprintln!("─── schema size report ───");
        eprintln!("old flat registry (30 tools):  {old_full} chars");
        eprintln!("core only ({core_count} tools):                {core_only} chars");
        eprintln!("core + git:                    {with_git} chars");
        eprintln!("core + all groups ({all_count} tools):     {with_all} chars");
        eprintln!(
            "savings vs old, core-only:     {} chars (~{}%)",
            old_full.saturating_sub(core_only),
            100 * (old_full.saturating_sub(core_only)) / old_full.max(1),
        );

        // Core-only should be strictly smaller than the old flat schema.
        assert!(core_only < old_full);
        // And core + all groups should be close to (but not exactly) the
        // old flat schema — it's larger by the enable_tools meta-tool
        // (synthesized, not in the old list).
        assert!(with_all >= old_full);
    }

    #[test]
    fn advanced_group_contains_spawn_agent() {
        let reg = ToolRegistry::new();
        let advanced = reg.group_tool_names(ToolGroup::Advanced);
        assert!(advanced.contains(&"bash".to_string()));
        assert!(advanced.contains(&"edit_file".to_string()));
        assert!(advanced.contains(&"apply_diff".to_string()));
        assert!(advanced.contains(&"spawn_agent".to_string()));
    }

    #[test]
    fn coding_core_is_the_lean_actuation_set() {
        let core = ToolGroup::coding_core();
        assert_eq!(
            core,
            [
                ToolGroup::Files,
                ToolGroup::Search,
                ToolGroup::Advanced,
                ToolGroup::Quality
            ]
        );
        // Sanity: the integration long-tail must NOT be in the lean core.
        assert!(!core.contains(&ToolGroup::Github));
        assert!(!core.contains(&ToolGroup::Git)); // git is reached on demand
        assert!(!core.contains(&ToolGroup::Calendar));
    }

    #[test]
    fn enable_coding_core_enables_exactly_the_core_groups() {
        let mut reg = ToolRegistry::new();
        let newly = reg.enable_coding_core();
        assert_eq!(newly, 4, "all four coding-core groups newly enabled");
        for g in ToolGroup::coding_core() {
            assert!(reg.is_enabled(g), "{g:?} should be enabled");
        }
        // The actuation tools the brain needs are now advertised.
        let tools = reg.current_tools().to_string();
        for t in [
            "read_file",
            "write_file",
            "edit_file",
            "grep_search",
            "run_tests",
        ] {
            assert!(tools.contains(t), "coding core should advertise {t}");
        }
        // Idempotent: re-enabling reports zero newly-enabled.
        assert_eq!(reg.enable_coding_core(), 0);
    }

    #[test]
    fn coding_core_schema_stays_lean() {
        // Guardrail: the pre-enabled coding core must stay well under the
        // "+all" weight (~37k chars). Keeps the workspace-mode base prompt
        // affordable on a 32k window. ~14k chars headroom is generous.
        let mut reg = ToolRegistry::new();
        reg.enable_coding_core();
        let chars = reg.current_schema_chars();
        assert!(
            chars < 16_000,
            "coding-core schema grew to {chars} chars (>16k) — re-check the bundle"
        );
    }
}