alysis-code 0.13.0__py3-none-any.whl

alysis_code/tools/registry.py

@@ -0,0 +1,2936 @@
+from __future__ import annotations
+
+import copy
+import json
+import re
+from collections.abc import Callable, Collection
+from dataclasses import dataclass
+from difflib import SequenceMatcher
+from typing import Any
+
+from .availability import is_tool_unavailable_result
+
+ToolFormatter = Callable[[dict[str, Any]], str]
+ToolAliasTransform = Callable[[dict[str, Any]], dict[str, Any]]
+_PATH_BASE_ENUM = ["active_workdir", "workspace_root"]
+_UNKNOWN_TOOL_SUGGESTION_THRESHOLD = 0.72
+_UNKNOWN_TOOL_MAX_SUGGESTIONS = 3
+REPORT_BLOCKER_MAX_MESSAGE_CHARS = 16_384
+
+
+def _path_base_property(*, description: str | None = None) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "type": "string",
+        "enum": list(_PATH_BASE_ENUM),
+        "default": "active_workdir",
+    }
+    if description:
+        payload["description"] = description
+    return payload
+
+
+def _cwd_base_property() -> dict[str, Any]:
+    return _path_base_property(
+        description=(
+            "Resolve a relative cwd from the live active_workdir (default) or from the immutable "
+            "workspace_root."
+        )
+    )
+
+
+def _service_readiness_property() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "description": (
+            "Optional bounded readiness probe. type=process_alive, tcp, unix_socket, or command. "
+            "tcp uses host+port; unix_socket uses path; command uses a policy-checked command."
+        ),
+        "properties": {
+            "type": {
+                "type": "string",
+                "enum": ["process_alive", "tcp", "unix_socket", "command"],
+                "default": "process_alive",
+            },
+            "host": {"type": "string", "default": "localhost"},
+            "port": {"type": "integer", "minimum": 1, "maximum": 65535},
+            "path": {"type": "string"},
+            "command": {"type": "string"},
+            "timeout_s": {"type": "number", "default": 5.0, "minimum": 0, "maximum": 30},
+            "interval_s": {"type": "number", "default": 0.1, "minimum": 0.02, "maximum": 2},
+        },
+    }
+
+
+def _truncate_inline(text: str, *, max_chars: int = 96) -> str:
+    normalized = " ".join(str(text).split())
+    if len(normalized) <= max_chars:
+        return normalized
+    if max_chars <= 3:
+        return normalized[:max_chars]
+    return normalized[: max_chars - 3] + "..."
+
+
+def _preview_shell_run(args: dict[str, Any]) -> str:
+    cmd = str(args.get("cmd") or "").strip()
+    return _truncate_inline(cmd, max_chars=120) or "-"
+
+
+def _preview_shell_output(args: dict[str, Any]) -> str:
+    process_id = str(args.get("process_id") or "").strip()
+    since = args.get("since")
+    if since is None:
+        return _truncate_inline(process_id, max_chars=120) or "-"
+    return _truncate_inline(f"{process_id} since={since}", max_chars=120) or "-"
+
+
+def _preview_shell_kill(args: dict[str, Any]) -> str:
+    return _truncate_inline(str(args.get("process_id") or "").strip(), max_chars=120) or "-"
+
+
+def _preview_shell_service_id(args: dict[str, Any]) -> str:
+    return _truncate_inline(str(args.get("service_id") or "").strip(), max_chars=120) or "-"
+
+
+def _preview_fs_read_lines(args: dict[str, Any]) -> str:
+    path = str(args.get("path") or "").strip()
+    start_line = args.get("start_line")
+    end_line = args.get("end_line")
+    max_lines = args.get("max_lines")
+    if end_line is None:
+        line_part = f"{start_line}"
+    else:
+        line_part = f"{start_line}-{end_line}"
+    preview = f"{path}:{line_part}"
+    if max_lines is not None:
+        preview += f" (max {max_lines})"
+    return _truncate_inline(preview, max_chars=120) or "-"
+
+
+def _preview_verify_run(args: dict[str, Any]) -> str:
+    commands = args.get("commands")
+    if not isinstance(commands, list) or not commands:
+        return "configured commands"
+    first = str(commands[0]).strip()
+    if len(commands) == 1:
+        return _truncate_inline(first, max_chars=120) or "-"
+    return _truncate_inline(f"{first} (+{len(commands) - 1} more)", max_chars=120) or "-"
+
+
+def _preview_image_generate(args: dict[str, Any]) -> str:
+    output_path = str(args.get("output_path") or "").strip()
+    prompt = _truncate_inline(str(args.get("prompt") or ""), max_chars=72)
+    count = args.get("count", 1)
+    return _truncate_inline(f"{output_path} x{count} - {prompt}", max_chars=120) or "-"
+
+
+def _summary_image_generate(parsed: dict[str, Any]) -> str:
+    if is_tool_unavailable_result(parsed):
+        return "Image generation unavailable."
+    error = str(parsed.get("error") or "").strip()
+    if error:
+        return _truncate_inline(f"Image generation failed: {error}", max_chars=160)
+    paths = parsed.get("output_paths")
+    if isinstance(paths, list) and paths:
+        return _truncate_inline(
+            "Generated image asset(s): " + ", ".join(str(path) for path in paths),
+            max_chars=160,
+        )
+    return "Image generation finished."
+
+
+def _preview_git_history(args: dict[str, Any]) -> str:
+    mode = str(args.get("mode") or "").strip()
+    if mode == "log":
+        ref = str(args.get("ref") or "HEAD").strip() or "HEAD"
+        path = str(args.get("path") or "").strip()
+        grep = str(args.get("grep") or "").strip()
+        preview = f"log {ref}"
+        if path:
+            preview += f" -- {path}"
+        if grep:
+            preview += f" grep={grep}"
+        return _truncate_inline(preview, max_chars=120) or "-"
+    if mode == "show":
+        commit = str(args.get("commit") or args.get("ref") or "").strip()
+        path = str(args.get("path") or "").strip()
+        preview = f"show {commit}"
+        if path:
+            preview += f" -- {path}"
+        return _truncate_inline(preview, max_chars=120) or "-"
+    if mode == "blame":
+        path = str(args.get("path") or "").strip()
+        start_line = args.get("start_line")
+        end_line = args.get("end_line")
+        preview = f"blame {path}:{start_line}-{end_line}"
+        return _truncate_inline(preview, max_chars=120) or "-"
+    return _truncate_inline(mode, max_chars=120) or "-"
+
+
+def _preview_symbol_search(args: dict[str, Any]) -> str:
+    query = str(args.get("query") or "").strip()
+    kind = str(args.get("kind") or "").strip()
+    exact = bool(args.get("exact", False))
+    preview = query
+    if kind:
+        preview += f" kind={kind}"
+    if exact:
+        preview += " exact"
+    return _truncate_inline(preview, max_chars=120) or "-"
+
+
+def _preview_source_destination(args: dict[str, Any]) -> str:
+    source_path = str(args.get("source_path") or "").strip()
+    destination_path = str(args.get("destination_path") or "").strip()
+    preview = f"{source_path} -> {destination_path}"
+    return _truncate_inline(preview, max_chars=120) or "-"
+
+
+def _preview_single_path(args: dict[str, Any]) -> str:
+    path = str(args.get("path") or "").strip()
+    return _truncate_inline(path, max_chars=120) or "-"
+
+
+def _preview_pattern(args: dict[str, Any]) -> str:
+    pattern = str(args.get("pattern") or "").strip()
+    return _truncate_inline(pattern, max_chars=120) or "-"
+
+
+def _preview_web_fetch(args: dict[str, Any]) -> str:
+    url = str(args.get("url") or "").strip()
+    max_chars = args.get("max_chars")
+    if max_chars is None:
+        return _truncate_inline(url, max_chars=120) or "-"
+    return _truncate_inline(f"{url} (max_chars={max_chars})", max_chars=120) or "-"
+
+
+def _preview_web_search(args: dict[str, Any]) -> str:
+    query = str(args.get("query") or "").strip()
+    allowed_domains = args.get("allowed_domains")
+    if isinstance(allowed_domains, list) and allowed_domains:
+        preview = f"{query} domains={','.join(str(item).strip() for item in allowed_domains[:3])}"
+        if len(allowed_domains) > 3:
+            preview += f" (+{len(allowed_domains) - 3})"
+        return _truncate_inline(preview, max_chars=120) or "-"
+    return _truncate_inline(query, max_chars=120) or "-"
+
+
+def _preview_skill_read(args: dict[str, Any]) -> str:
+    name = str(args.get("name") or "").strip()
+    path = str(args.get("path") or "").strip()
+    preview = name
+    if path:
+        preview += f" :: {path}"
+    return _truncate_inline(preview, max_chars=120) or "-"
+
+
+def _summary_subagent_run(parsed: dict[str, Any]) -> str:
+    subagent_name = str(parsed.get("subagent") or parsed.get("name") or "?")
+    sandbox_obj = parsed.get("sandbox")
+    sandbox = sandbox_obj if isinstance(sandbox_obj, dict) else {}
+    mode = str(sandbox.get("mode") or "-")
+    tools_obj = sandbox.get("tools")
+    tool_count = len(tools_obj) if isinstance(tools_obj, list) else 0
+    result_text = str(parsed.get("result") or parsed.get("final_text") or "")
+    result_len = len(result_text)
+    if "error" in parsed:
+        msg = _truncate_inline(str(parsed.get("error") or ""), max_chars=130)
+        return f'Subagent "{subagent_name}" failed: {msg}'
+    details: list[str] = []
+    if tool_count > 0:
+        details.append(f"tools={tool_count}")
+    if result_len > 0:
+        details.append(f"result={result_len} chars")
+    suffix = f" ({', '.join(details)})" if details else ""
+    return f'Subagent "{subagent_name}" mode={mode}{suffix}.'
+
+
+def _summary_subagent_background(parsed: dict[str, Any]) -> str:
+    run_id = str(parsed.get("run_id") or "").strip()
+    state = str(parsed.get("state") or "").strip()
+    pending = parsed.get("pending_run_ids")
+    if run_id:
+        suffix = f" state={state}" if state else ""
+        return f"Background subagent {run_id[:12]}{suffix}."
+    if isinstance(pending, list) and pending:
+        return f"Background subagents: {len(pending)} still pending."
+    return "Background subagent operation completed."
+
+
+def _summary_fs_read(parsed: dict[str, Any]) -> str:
+    path = str(parsed.get("path") or "?")
+    content = str(parsed.get("content") or "")
+    truncated = bool(parsed.get("truncated"))
+    if parsed.get("derived_artifact"):
+        size_bytes = parsed.get("size_bytes")
+        size_note = f"; {size_bytes} bytes on disk" if isinstance(size_bytes, int) else ""
+        return f'Sampled derived artifact "{path}" (head only{size_note}; content withheld).'
+    trunc_note = ", truncated" if truncated else ""
+    return f'Loaded "{path}" ({len(content)} chars{trunc_note}).'
+
+
+def _summary_fs_read_lines(parsed: dict[str, Any]) -> str:
+    path = str(parsed.get("path") or "?")
+    start_line = parsed.get("start_line")
+    end_line = parsed.get("end_line")
+    truncated = bool(parsed.get("truncated"))
+    trunc_note = ", truncated" if truncated else ""
+    if isinstance(start_line, int) and isinstance(end_line, int) and end_line >= start_line:
+        count = end_line - start_line + 1
+        if count == 1:
+            return f'Loaded "{path}" line {start_line} (1 line{trunc_note}).'
+        return f'Loaded "{path}" lines {start_line}-{end_line} ({count} lines{trunc_note}).'
+    content = str(parsed.get("content") or "")
+    return f'Loaded "{path}" ({len(content)} chars{trunc_note}).'
+
+
+def _summary_fs_edit(parsed: dict[str, Any]) -> str:
+    path = str(parsed.get("path") or "?")
+    applied_edits = parsed.get("applied_edits")
+    changed = bool(parsed.get("changed"))
+    if changed:
+        size = parsed.get("bytes")
+        return f'Edited "{path}" ({applied_edits} edit(s), {size} bytes).'
+    return f'Edited "{path}" ({applied_edits} edit(s), no content change).'
+
+
+def _summary_fs_move(parsed: dict[str, Any]) -> str:
+    source_path = str(parsed.get("source_path") or "?")
+    destination_path = str(parsed.get("destination_path") or "?")
+    size = parsed.get("bytes")
+    overwritten = bool(parsed.get("overwritten"))
+    overwrite_note = ", replaced existing destination" if overwritten else ""
+    return f'Moved "{source_path}" -> "{destination_path}" ({size} bytes{overwrite_note}).'
+
+
+def _summary_fs_copy(parsed: dict[str, Any]) -> str:
+    source_path = str(parsed.get("source_path") or "?")
+    destination_path = str(parsed.get("destination_path") or "?")
+    size = parsed.get("bytes")
+    overwritten = bool(parsed.get("overwritten"))
+    overwrite_note = ", replaced existing destination" if overwritten else ""
+    return f'Copied "{source_path}" -> "{destination_path}" ({size} bytes{overwrite_note}).'
+
+
+def _summary_fs_delete(parsed: dict[str, Any]) -> str:
+    path = str(parsed.get("path") or "?")
+    size = parsed.get("bytes")
+    return f'Deleted "{path}" ({size} bytes).'
+
+
+def _summary_fs_write(parsed: dict[str, Any]) -> str:
+    path = str(parsed.get("path") or "?")
+    size = parsed.get("bytes")
+    return f'Updated "{path}" ({size} bytes).'
+
+
+def _summary_fs_mkdir(parsed: dict[str, Any]) -> str:
+    path = str(parsed.get("path") or "?")
+    if bool(parsed.get("already_exists")):
+        return f'Directory "{path}" already exists.'
+    return f'Created directory "{path}".'
+
+
+def _summary_fs_list(parsed: dict[str, Any]) -> str:
+    entries = parsed.get("entries")
+    count = len(entries) if isinstance(entries, list) else 0
+    truncated = bool(parsed.get("truncated"))
+    trunc_note = ", truncated" if truncated else ""
+    return f"Found {count} file(s){trunc_note}."
+
+
+def _summary_symbol_search(parsed: dict[str, Any]) -> str:
+    matches = parsed.get("matches")
+    count = len(matches) if isinstance(matches, list) else 0
+    query = _truncate_inline(str(parsed.get("query") or ""), max_chars=44)
+    truncated = bool(parsed.get("truncated"))
+    trunc_note = ", truncated" if truncated else ""
+    return f'Found {count} symbol match(es) for "{query}"{trunc_note}.'
+
+
+def _summary_test_discover(parsed: dict[str, Any]) -> str:
+    tests = parsed.get("candidate_tests")
+    commands = parsed.get("candidate_commands")
+    test_count = len(tests) if isinstance(tests, list) else 0
+    command_count = len(commands) if isinstance(commands, list) else 0
+    frameworks = parsed.get("frameworks")
+    framework_text = ""
+    if isinstance(frameworks, list) and frameworks:
+        framework_text = " (" + ", ".join(str(item) for item in frameworks[:3]) + ")"
+    return (
+        f"Found {test_count} likely test file(s) and "
+        f"{command_count} candidate command(s){framework_text}."
+    )
+
+
+def _summary_repo_map(parsed: dict[str, Any]) -> str:
+    related = parsed.get("related_files")
+    edges = parsed.get("import_edges")
+    tests = parsed.get("candidate_tests")
+    related_count = len(related) if isinstance(related, list) else 0
+    edge_count = len(edges) if isinstance(edges, list) else 0
+    test_count = len(tests) if isinstance(tests, list) else 0
+    return (
+        f"Mapped {related_count} related file(s), {edge_count} import edge(s), "
+        f"and {test_count} likely test file(s)."
+    )
+
+
+def _summary_search_rg(parsed: dict[str, Any]) -> str:
+    matches = parsed.get("matches")
+    count = len(matches) if isinstance(matches, list) else 0
+    pattern = _truncate_inline(str(parsed.get("pattern") or ""), max_chars=44)
+    return f'Found {count} matches for "{pattern}".'
+
+
+def _summary_history_search(parsed: dict[str, Any]) -> str:
+    matches = parsed.get("matches")
+    count = len(matches) if isinstance(matches, list) else 0
+    pattern = _truncate_inline(str(parsed.get("pattern") or ""), max_chars=44)
+    truncated = bool(parsed.get("truncated"))
+    trunc_note = ", truncated" if truncated else ""
+    return f'Found {count} history match(es) for "{pattern}"{trunc_note}.'
+
+
+def _summary_skill_read(parsed: dict[str, Any]) -> str:
+    name = str(parsed.get("name") or parsed.get("bundle_name") or "?")
+    path = str(parsed.get("path") or "SKILL.md")
+    content = str(parsed.get("content") or "")
+    return f'Loaded skill "{name}" file "{path}" ({len(content)} chars).'
+
+
+def _summary_web_fetch(parsed: dict[str, Any]) -> str:
+    final_url = _truncate_inline(
+        str(parsed.get("final_url") or parsed.get("url") or ""), max_chars=84
+    )
+    status_code = parsed.get("status_code")
+    content_type = _truncate_inline(str(parsed.get("content_type") or ""), max_chars=28)
+    content = str(parsed.get("content") or "")
+    truncated = bool(parsed.get("truncated"))
+    trunc_note = ", truncated" if truncated else ""
+    return (
+        f"Fetched {final_url} status={status_code} type={content_type} "
+        f"content={len(content)} chars{trunc_note}."
+    )
+
+
+def _summary_web_search(parsed: dict[str, Any]) -> str:
+    answer = str(parsed.get("answer") or "")
+    sources = parsed.get("sources")
+    source_count = len(sources) if isinstance(sources, list) else 0
+    truncated = bool(parsed.get("sources_truncated"))
+    trunc_note = ", truncated" if truncated else ""
+    backend = _truncate_inline(str(parsed.get("backend") or ""), max_chars=24)
+    model = _truncate_inline(str(parsed.get("model") or ""), max_chars=32)
+    details = []
+    if backend:
+        details.append(f"backend={backend}")
+    if model:
+        details.append(f"model={model}")
+    details_note = f" {' '.join(details)}" if details else ""
+    return (
+        f"Web search returned {source_count} source(s){trunc_note}; "
+        f"answer={len(answer)} chars.{details_note}"
+    )
+
+
+def _summary_verify_run(parsed: dict[str, Any]) -> str:
+    summary = _truncate_inline(str(parsed.get("summary") or ""), max_chars=120)
+    primary_failure = parsed.get("primary_failure")
+    hint = ""
+    if isinstance(primary_failure, dict):
+        snippet = str(primary_failure.get("snippet") or "").strip()
+        if snippet:
+            hint = f"Hint: {_truncate_inline(snippet, max_chars=110)}"
+    artifact_path = str(parsed.get("artifact_path") or "").strip()
+    if artifact_path:
+        prefix = " ".join(part for part in (summary, hint) if part)
+        if prefix:
+            return f"{prefix} Artifact: {artifact_path}"
+        return f"Artifact: {artifact_path}"
+    artifact_saved = bool(parsed.get("artifact_saved"))
+    artifact_readable_via_fs = bool(parsed.get("artifact_readable_via_fs"))
+    artifact_location = str(parsed.get("artifact_location") or "").strip()
+    if artifact_saved and not artifact_readable_via_fs:
+        if artifact_location == "external_session_store":
+            artifact_note = "Artifact saved externally (not readable via fs)."
+        else:
+            artifact_note = "Artifact saved outside the workspace (not readable via fs)."
+        prefix = " ".join(part for part in (summary, hint) if part)
+        if prefix:
+            return f"{prefix} {artifact_note}"
+        return artifact_note
+    if artifact_saved:
+        prefix = " ".join(part for part in (summary, hint) if part)
+        if prefix:
+            return f"{prefix} Artifact saved."
+        return "Artifact saved."
+    return " ".join(part for part in (summary, hint) if part) or "Verification finished."
+
+
+def _summary_shell_run(parsed: dict[str, Any]) -> str:
+    exit_code = parsed.get("exit_code")
+    stdout = str(parsed.get("stdout") or "")
+    stderr = str(parsed.get("stderr") or "")
+    summary = f"Command exited with code {exit_code}."
+    summary += f" stdout={len(stdout)} chars, stderr={len(stderr)} chars."
+    if stderr.strip():
+        first_err = _truncate_inline(stderr.strip().splitlines()[0], max_chars=90)
+        summary += f" stderr preview: {first_err}"
+    return summary
+
+
+def _summary_shell_background(parsed: dict[str, Any]) -> str:
+    process_id = str(parsed.get("process_id") or "?")
+    status = str(parsed.get("status") or "?")
+    return f'Started background process "{process_id}" (status={status}).'
+
+
+def _summary_shell_output(parsed: dict[str, Any]) -> str:
+    process_id = str(parsed.get("process_id") or "?")
+    status = str(parsed.get("status") or "?")
+    if status == "unknown_process_id" or bool(parsed.get("unknown_process_id")):
+        known = parsed.get("known_process_ids")
+        known_count = len(known) if isinstance(known, list) else 0
+        return (
+            f'Unknown background process "{process_id}"; '
+            f"{known_count} process id(s) currently tracked."
+        )
+    lines = parsed.get("lines")
+    line_count = len(lines) if isinstance(lines, list) else 0
+    dropped = int(parsed.get("dropped_lines") or 0)
+    drop_note = f", {dropped} dropped" if dropped > 0 else ""
+    return f'Read {line_count} new line(s) from "{process_id}" (status={status}{drop_note}).'
+
+
+def _summary_shell_wait(parsed: dict[str, Any]) -> str:
+    process_id = str(parsed.get("process_id") or "?")
+    status = str(parsed.get("status") or "?")
+    if status == "unknown_process_id" or bool(parsed.get("unknown_process_id")):
+        known = parsed.get("known_process_ids")
+        known_count = len(known) if isinstance(known, list) else 0
+        return (
+            f'Unknown background process "{process_id}"; '
+            f"{known_count} process id(s) currently tracked."
+        )
+    lines = parsed.get("lines")
+    line_count = len(lines) if isinstance(lines, list) else 0
+    timed_out = bool(parsed.get("timed_out"))
+    timeout_note = ", timed out" if timed_out else ""
+    return f'Waited for "{process_id}" and read {line_count} new line(s) (status={status}{timeout_note}).'
+
+
+def _summary_shell_kill(parsed: dict[str, Any]) -> str:
+    process_id = str(parsed.get("process_id") or "?")
+    status = str(parsed.get("status") or "?")
+    exit_code = parsed.get("exit_code")
+    code_note = f", exit_code={exit_code}" if exit_code is not None else ""
+    return f'Terminated background process "{process_id}" (status={status}{code_note}).'
+
+
+def _summary_shell_list(parsed: dict[str, Any]) -> str:
+    processes = parsed.get("processes")
+    count = len(processes) if isinstance(processes, list) else 0
+    if count == 0:
+        return "No background processes."
+    running = sum(
+        1
+        for process in (processes or [])
+        if isinstance(process, dict) and process.get("status") == "running"
+    )
+    return f"Listed {count} background process(es) ({running} running)."
+
+
+def _summary_shell_service(parsed: dict[str, Any]) -> str:
+    service_id = str(parsed.get("service_id") or "?")
+    status = str(parsed.get("status") or "?")
+    readiness = parsed.get("readiness") if isinstance(parsed.get("readiness"), dict) else {}
+    readiness_status = str(readiness.get("status") or "?")
+    return f'Durable service "{service_id}" status={status}, readiness={readiness_status}.'
+
+
+def _summary_session_set_workdir(parsed: dict[str, Any]) -> str:
+    relpath = str(parsed.get("active_workdir_relpath") or ".").strip() or "."
+    return f"Active workdir set to {relpath}."
+
+
+def _summary_git_status(parsed: dict[str, Any]) -> str:
+    status_text = str(parsed.get("status") or "")
+    lines = [line for line in status_text.splitlines() if line.strip()]
+    return f"Collected git status ({len(lines)} non-empty lines)."
+
+
+def _summary_git_history(parsed: dict[str, Any]) -> str:
+    mode = str(parsed.get("mode") or "")
+    if mode == "log":
+        commits = parsed.get("commits")
+        count = len(commits) if isinstance(commits, list) else 0
+        truncated = bool(parsed.get("truncated"))
+        trunc_note = ", truncated" if truncated else ""
+        return f"Loaded git history ({count} commit(s){trunc_note})."
+    if mode == "show":
+        commit_obj = parsed.get("commit")
+        short_commit = ""
+        if isinstance(commit_obj, dict):
+            short_commit = str(commit_obj.get("short_commit") or "")
+        patch_excerpt = str(parsed.get("patch_excerpt") or "")
+        truncated = bool(parsed.get("patch_truncated"))
+        trunc_note = ", truncated" if truncated else ""
+        label = short_commit or "commit"
+        return f"Loaded commit {label} ({len(patch_excerpt)} chars{trunc_note})."
+    if mode == "blame":
+        path = str(parsed.get("path") or "?")
+        start_line = parsed.get("start_line")
+        end_line = parsed.get("end_line")
+        lines = parsed.get("lines")
+        count = len(lines) if isinstance(lines, list) else 0
+        return f'Loaded blame for "{path}" lines {start_line}-{end_line} ({count} line(s)).'
+    return "Loaded git history."
+
+
+def _summary_git_diff(parsed: dict[str, Any]) -> str:
+    diff_text = str(parsed.get("diff") or "")
+    files = diff_text.count("diff --git")
+    return f"Collected git diff ({len(diff_text)} chars, about {files} file(s))."
+
+
+def _summary_git_apply_patch(parsed: dict[str, Any]) -> str:
+    if parsed.get("applied") is True:
+        return "Patch applied successfully."
+    keys = ", ".join(sorted(str(k) for k in parsed.keys())[:6])
+    return f"Output keys: {keys or '-'}."
+
+
+def _fs_edit_op_variant(
+    *,
+    ops: tuple[str, ...],
+    required: tuple[str, ...],
+    include_content: bool,
+    include_target: bool,
+    include_replacement: bool,
+    extra_properties: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    properties: dict[str, Any] = {
+        "op": {"type": "string", "enum": list(ops)},
+    }
+    if include_content:
+        properties["content"] = {"type": "string"}
+    if include_target:
+        properties["target"] = {"type": "string", "minLength": 1}
+        properties["expected_match_count"] = {"type": "integer", "minimum": 0}
+    if include_replacement:
+        properties["replacement"] = {"type": "string"}
+    if extra_properties:
+        properties.update(extra_properties)
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "properties": properties,
+        "required": list(required),
+    }
+
+
+def _fs_edit_parameters() -> dict[str, Any]:
+    return {
+        "type": "object",
+        "additionalProperties": False,
+        "properties": {
+            "path": {"type": "string"},
+            "path_base": _path_base_property(),
+            "edits": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                    "anyOf": [
+                        _fs_edit_op_variant(
+                            ops=("replace", "replace_exact"),
+                            required=("op", "target", "replacement"),
+                            include_content=False,
+                            include_target=True,
+                            include_replacement=True,
+                        ),
+                        _fs_edit_op_variant(
+                            ops=("insert_before_exact", "insert_after_exact"),
+                            required=("op", "target", "content"),
+                            include_content=True,
+                            include_target=True,
+                            include_replacement=False,
+                        ),
+                        _fs_edit_op_variant(
+                            ops=("append", "prepend"),
+                            required=("op", "content"),
+                            include_content=True,
+                            include_target=False,
+                            include_replacement=False,
+                        ),
+                        _fs_edit_op_variant(
+                            ops=("replace_lines",),
+                            required=("op", "start_line", "end_line", "replacement"),
+                            include_content=False,
+                            include_target=False,
+                            include_replacement=True,
+                            extra_properties={
+                                "start_line": {"type": "integer", "minimum": 1},
+                                "end_line": {"type": "integer", "minimum": 1},
+                                "expected_old": {
+                                    "type": "string",
+                                    "description": (
+                                        "Optional exact old text for replace_lines; the edit fails "
+                                        "closed if the selected line range no longer matches."
+                                    ),
+                                },
+                            },
+                        ),
+                        _fs_edit_op_variant(
+                            ops=("insert_before_line", "insert_after_line"),
+                            required=("op", "line", "content"),
+                            include_content=True,
+                            include_target=False,
+                            include_replacement=False,
+                            extra_properties={
+                                "line": {"type": "integer", "minimum": 1},
+                            },
+                        ),
+                    ]
+                },
+            },
+        },
+        "required": ["path", "edits"],
+    }
+
+
+@dataclass(frozen=True)
+class RichToolMetadata:
+    display_name: str
+    reasoning_hint: str
+    action_hint: str
+    fallback_hint: str
+    input_preview_formatter: ToolFormatter | None = None
+    output_summary_formatter: ToolFormatter | None = None
+
+
+@dataclass(frozen=True)
+class BuiltinToolMetadata:
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    categories: tuple[str, ...]
+    rich: RichToolMetadata
+    built_in_subagent_exposure: str = "hidden"
+    optional: bool = False
+    optional_unavailable_reason: str | None = None
+
+    def copied_parameters(self) -> dict[str, Any]:
+        return copy.deepcopy(self.parameters)
+
+
+_BUILTIN_TOOL_METADATA: tuple[BuiltinToolMetadata, ...] = (
+    BuiltinToolMetadata(
+        name="report_blocker",
+        description=(
+            "Report a concrete obstacle that prevents this top-level execute turn from "
+            "completing safely. Supply the user-facing explanation in message and use this "
+            "as the final tool call when no available tool can resolve the obstacle. The host "
+            "uses the successful tool result as a structured blocker signal; words in message "
+            "never control routing or completion."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": (
+                        "User-facing explanation of what prevents completion. Any language, "
+                        "script, or punctuation is allowed; maxLength is transport protection "
+                        "only."
+                    ),
+                    "maxLength": REPORT_BLOCKER_MAX_MESSAGE_CHARS,
+                },
+            },
+            "required": ["message"],
+        },
+        categories=("session",),
+        rich=RichToolMetadata(
+            display_name="Report Blocker",
+            reasoning_hint="A concrete obstacle prevents safe completion of this turn.",
+            action_hint="Report the obstacle as the final structured turn action.",
+            fallback_hint="Continue with available tools when the obstacle can still be resolved.",
+        ),
+        built_in_subagent_exposure="hidden",
+        optional=True,
+        optional_unavailable_reason="completion gating is not active for this runtime",
+    ),
+    BuiltinToolMetadata(
+        name="switch_mode",
+        description=(
+            "Propose switching this chat session to another persona mode: code, "
+            "architect, ask, or debug. The user must approve; an approved switch "
+            "applies when the current turn ends. Use only when the conversation "
+            "clearly calls for a different posture (e.g. pure explanation -> ask, "
+            "implementation after planning -> code). Never required for normal work."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "persona": {
+                    "type": "string",
+                    "enum": ["code", "architect", "ask", "debug"],
+                },
+                "reason": {
+                    "type": "string",
+                    "description": "One short sentence shown to the user in the approval prompt.",
+                },
+            },
+            "required": ["persona", "reason"],
+        },
+        categories=("session",),
+        rich=RichToolMetadata(
+            display_name="Switch Persona",
+            reasoning_hint="The requested work fits a different persona posture.",
+            action_hint="Ask the user to approve a persona switch.",
+            fallback_hint="If declined, continue in the current persona without asking again.",
+        ),
+        built_in_subagent_exposure="readonly",
+        optional=True,
+        optional_unavailable_reason="persona modes disabled or non-interactive runtime",
+    ),
+    BuiltinToolMetadata(
+        name="fs_read",
+        description=(
+            "Read a UTF-8 text file under the working root. Prefer after symbol_search or "
+            "search_rg for exact file contents. Derived artifacts (lockfiles, minified or "
+            "generated output) return size + head sample unless allow_derived=true. Truncation "
+            "reports total, returned, and next line ranges."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "path_base": _path_base_property(
+                    description=(
+                        "Resolve a relative path from the live active_workdir (default) or from the "
+                        "immutable workspace_root."
+                    )
+                ),
+                "max_bytes": {"type": "integer", "default": 12000},
+                "allow_derived": {
+                    "type": "boolean",
+                    "default": False,
+                    "description": (
+                        "Full content for derived artifacts; set only when the artifact "
+                        "itself is the subject of the task."
+                    ),
+                },
+                "force": {
+                    "type": "boolean",
+                    "default": False,
+                    "description": "Return content even if this unchanged range was read before.",
+                },
+            },
+            "required": ["path"],
+        },
+        categories=("read", "fs"),
+        rich=RichToolMetadata(
+            display_name="Read File",
+            reasoning_hint="Need exact file content before suggesting edits.",
+            action_hint="Read file text from the current workspace.",
+            fallback_hint="If read fails, adjust path or list files first.",
+            input_preview_formatter=_preview_single_path,
+            output_summary_formatter=_summary_fs_read,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="fs_read_lines",
+        description=(
+            "Read a precise 1-indexed line range from a UTF-8 text file. Prefer a narrow "
+            "confirmed range; truncation reports the exact next range."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "path_base": _path_base_property(),
+                "start_line": {"type": "integer"},
+                "end_line": {"type": "integer"},
+                "max_lines": {"type": "integer", "default": 200},
+                "include_line_numbers": {"type": "boolean", "default": True},
+                "max_bytes": {
+                    "type": "integer",
+                    "default": 48000,
+                    "description": "Byte ceiling for the returned range.",
+                },
+                "force": {
+                    "type": "boolean",
+                    "default": False,
+                    "description": "Return content even if this unchanged range was read before.",
+                },
+            },
+            "required": ["path", "start_line"],
+        },
+        categories=("read", "fs"),
+        rich=RichToolMetadata(
+            display_name="Read File Lines",
+            reasoning_hint="Inspect a precise file range without rereading the whole file.",
+            action_hint="Read a narrow 1-indexed line window from the current workspace.",
+            fallback_hint="If the range is wrong, adjust start/end lines or fall back to fs_read.",
+            input_preview_formatter=_preview_fs_read_lines,
+            output_summary_formatter=_summary_fs_read_lines,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="fs_edit",
+        description=(
+            "Apply deterministic edits to one UTF-8 text file. Prefer for localized edits to an "
+            "existing file. Prefer line-range edits after fs_read_lines; use exact-text ops when "
+            "matching known text."
+        ),
+        parameters=_fs_edit_parameters(),
+        categories=("write", "fs"),
+        rich=RichToolMetadata(
+            display_name="Edit File",
+            reasoning_hint="Apply deterministic exact-text or line-range edits to one file.",
+            action_hint=(
+                "Edit a localized file region with line-range or exact-match operations and review "
+                "the diff preview."
+            ),
+            fallback_hint=(
+                "If exact text is ambiguous or missing, re-read lines and use replace_lines with "
+                "expected_old; use git_apply_patch for broader multi-file patches."
+            ),
+            input_preview_formatter=_preview_single_path,
+            output_summary_formatter=_summary_fs_edit,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="fs_move",
+        description="Move or rename one file under the working root. Prefer over shell commands for routine file moves.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "source_path": {"type": "string"},
+                "source_path_base": _path_base_property(),
+                "destination_path": {"type": "string"},
+                "destination_path_base": _path_base_property(),
+                "overwrite": {"type": "boolean", "default": False},
+            },
+            "required": ["source_path", "destination_path"],
+        },
+        categories=("write", "fs"),
+        rich=RichToolMetadata(
+            display_name="Move File",
+            reasoning_hint="Rename or relocate one file without shell commands.",
+            action_hint=(
+                "Move a single file under the workspace root and confirm the source/destination preview."
+            ),
+            fallback_hint=(
+                "If the destination exists or the path is wrong, adjust the target or enable overwrite explicitly."
+            ),
+            input_preview_formatter=_preview_source_destination,
+            output_summary_formatter=_summary_fs_move,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="fs_copy",
+        description="Copy one file under the working root. Prefer over shell commands for routine file copies.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "source_path": {"type": "string"},
+                "source_path_base": _path_base_property(),
+                "destination_path": {"type": "string"},
+                "destination_path_base": _path_base_property(),
+                "overwrite": {"type": "boolean", "default": False},
+            },
+            "required": ["source_path", "destination_path"],
+        },
+        categories=("write", "fs"),
+        rich=RichToolMetadata(
+            display_name="Copy File",
+            reasoning_hint="Duplicate one file without shell commands.",
+            action_hint=(
+                "Copy a single file under the workspace root and confirm the destination preview."
+            ),
+            fallback_hint=(
+                "If the destination exists or the path is wrong, adjust the target or enable overwrite explicitly."
+            ),
+            input_preview_formatter=_preview_source_destination,
+            output_summary_formatter=_summary_fs_copy,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="fs_delete",
+        description="Delete one file under the working root. Prefer over shell commands for routine file deletes.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "path_base": _path_base_property(),
+            },
+            "required": ["path"],
+        },
+        categories=("write", "fs"),
+        rich=RichToolMetadata(
+            display_name="Delete File",
+            reasoning_hint="Remove one file without shell commands.",
+            action_hint=(
+                "Delete a single file under the workspace root and confirm the preview before continuing."
+            ),
+            fallback_hint="If the path is wrong or protected, adjust the target instead of forcing the delete.",
+            input_preview_formatter=_preview_single_path,
+            output_summary_formatter=_summary_fs_delete,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="fs_write",
+        description="Write a UTF-8 text file under the working root. Prefer for new/generated files or full-file replacements.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "path_base": _path_base_property(),
+                "content": {"type": "string"},
+            },
+            "required": ["path", "content"],
+        },
+        categories=("write", "fs"),
+        rich=RichToolMetadata(
+            display_name="Write File",
+            reasoning_hint="Apply a concrete code/content update.",
+            action_hint="Write new file content and verify patch preview.",
+            fallback_hint="If blocked, ask for approval or reduce scope.",
+            input_preview_formatter=_preview_single_path,
+            output_summary_formatter=_summary_fs_write,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="fs_mkdir",
+        description="Create one directory under the working root.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "path": {"type": "string"},
+                "path_base": _path_base_property(),
+                "parents": {"type": "boolean", "default": True},
+                "exist_ok": {"type": "boolean", "default": True},
+            },
+            "required": ["path"],
+        },
+        categories=("write", "fs"),
+        rich=RichToolMetadata(
+            display_name="Create Directory",
+            reasoning_hint="Create empty directories or explicit scaffolding without shell commands.",
+            action_hint="Create a workspace-bounded directory path with optional parent creation.",
+            fallback_hint=(
+                "If the target collides with a file or the path is protected, adjust the path or use fs_write for files."
+            ),
+            input_preview_formatter=_preview_single_path,
+            output_summary_formatter=_summary_fs_mkdir,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="fs_list",
+        description="List files under root_path (best-effort .gitignore support).",
+        parameters={
+            "type": "object",
+            "properties": {
+                "root_path": {"type": "string"},
+                "path_base": _path_base_property(
+                    description=(
+                        "Resolve a relative root_path from the live active_workdir (default) or from "
+                        "the immutable workspace_root."
+                    )
+                ),
+                "globs": {"type": "array", "items": {"type": "string"}},
+                "ignore": {"type": "array", "items": {"type": "string"}},
+            },
+            "required": [],
+        },
+        categories=("read", "fs"),
+        rich=RichToolMetadata(
+            display_name="List Files",
+            reasoning_hint="Discover relevant files for the task.",
+            action_hint="List workspace paths with optional filters.",
+            fallback_hint="If results are noisy, narrow globs and retry.",
+            output_summary_formatter=_summary_fs_list,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="web_fetch",
+        description=(
+            "Fetch one specific known HTTP(S) URL with SSRF-style safety checks and return readable text. "
+            "Prefer it only for a user-provided URL or one returned by web_search; the runtime rejects guessed "
+            "URLs. Do not use it for discovery and do not guess or invent URLs."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "url": {"type": "string"},
+                "max_chars": {"type": "integer", "default": 20000, "minimum": 1, "maximum": 50000},
+            },
+            "required": ["url"],
+        },
+        categories=("read", "web"),
+        rich=RichToolMetadata(
+            display_name="Fetch Web Page",
+            reasoning_hint="Read targeted external docs/spec pages without shelling out.",
+            action_hint="Fetch one URL and inspect extracted readable text and metadata.",
+            fallback_hint=(
+                "If blocked or unsupported, use a different public URL or request manual input."
+            ),
+            input_preview_formatter=_preview_web_fetch,
+            output_summary_formatter=_summary_web_fetch,
+        ),
+        built_in_subagent_exposure="hidden",
+    ),
+    BuiltinToolMetadata(
+        name="web_search",
+        description=(
+            "Search the public web and return grounded content with cited sources. Decide to use it "
+            "whenever a reliable answer depends on unstable external facts, authoritative current "
+            "sources, current high-stakes guidance, current product or service information, or "
+            "requested internet research. Every result includes `retrieved_at` — the UTC wall-clock "
+            "time the search executed; trust it over your training prior for what 'today'/'current' "
+            "means. Use web_fetch only after you have a URL the user provided or web_search returned. "
+            "`external_web_access=false` is only supported by the OpenAI Responses backend."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "query": {"type": "string"},
+                "allowed_domains": {"type": "array", "items": {"type": "string"}},
+                "max_sources": {"type": "integer", "default": 8, "minimum": 1, "maximum": 20},
+                "external_web_access": {"type": "boolean", "default": True},
+            },
+            "required": ["query"],
+        },
+        categories=("read", "web", "search"),
+        rich=RichToolMetadata(
+            display_name="Search Web",
+            reasoning_hint="Discover the right external docs/page/source before fetching a specific URL.",
+            action_hint="Run a bounded web search and return an answer with citations and source URLs.",
+            fallback_hint=(
+                "If unavailable, use a user-provided direct public URL with web_fetch or ask the user for a "
+                "target page."
+            ),
+            input_preview_formatter=_preview_web_search,
+            output_summary_formatter=_summary_web_search,
+        ),
+        built_in_subagent_exposure="hidden",
+    ),
+    BuiltinToolMetadata(
+        name="ide_task_list",
+        description=(
+            "List bounded workspace tasks from a capability-negotiated trusted VS Code host. "
+            "Returned task ids are opaque and must be passed unchanged to ide_task_run."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {"task_type": {"type": "string"}},
+            "required": [],
+        },
+        categories=("read", "ide", "task"),
+        rich=RichToolMetadata(
+            display_name="List IDE Tasks",
+            reasoning_hint="Discover the repository's canonical VS Code tasks before invoking one.",
+            action_hint="Ask the trusted IDE host for a bounded task inventory.",
+            fallback_hint="If unavailable, inspect task configuration or use policy-checked shell tools.",
+        ),
+        built_in_subagent_exposure="readonly",
+        optional=True,
+        optional_unavailable_reason="The trusted IDE host did not advertise tasks.list.",
+    ),
+    BuiltinToolMetadata(
+        name="ide_task_run",
+        description=(
+            "Start one VS Code workspace task by the opaque task id returned by ide_task_list. "
+            "The trusted IDE host owns task resolution and execution."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {"task_id": {"type": "string"}},
+            "required": ["task_id"],
+        },
+        categories=("write", "ide", "task"),
+        rich=RichToolMetadata(
+            display_name="Run IDE Task",
+            reasoning_hint="Use the workspace's canonical task graph, providers, and problem matchers.",
+            action_hint="Start one trusted-host task by opaque id.",
+            fallback_hint="List tasks again if the id is stale, or use a policy-checked shell command.",
+        ),
+        optional=True,
+        optional_unavailable_reason="The trusted IDE host did not advertise tasks.run.",
+    ),
+    BuiltinToolMetadata(
+        name="ide_task_status",
+        description=(
+            "Read bounded status for VS Code task executions owned by this IDE session, optionally "
+            "filtered by one opaque execution id."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {"execution_id": {"type": "string"}},
+            "required": [],
+        },
+        categories=("read", "ide", "task"),
+        rich=RichToolMetadata(
+            display_name="Read IDE Task Status",
+            reasoning_hint="Check whether a host-owned task is still running or has ended.",
+            action_hint="Read bounded status for one or all session-owned task executions.",
+            fallback_hint="Use VS Code's task controls if host status is unavailable.",
+        ),
+        built_in_subagent_exposure="readonly",
+        optional=True,
+        optional_unavailable_reason="The trusted IDE host did not advertise tasks.status.",
+    ),
+    BuiltinToolMetadata(
+        name="ide_task_terminate",
+        description=(
+            "Terminate one VS Code task execution by the opaque execution id returned by "
+            "ide_task_run."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {"execution_id": {"type": "string"}},
+            "required": ["execution_id"],
+        },
+        categories=("write", "ide", "task"),
+        rich=RichToolMetadata(
+            display_name="Terminate IDE Task",
+            reasoning_hint="Stop a host-owned task execution that is no longer needed.",
+            action_hint="Ask the trusted IDE host to terminate one opaque execution id.",
+            fallback_hint="List or inspect task state in VS Code if the execution id is stale.",
+        ),
+        optional=True,
+        optional_unavailable_reason="The trusted IDE host did not advertise tasks.terminate.",
+    ),
+    BuiltinToolMetadata(
+        name="ide_debug_list",
+        description=(
+            "List bounded launch configurations from a capability-negotiated trusted VS Code "
+            "host. Configuration ids are opaque and workspace scoped."
+        ),
+        parameters={"type": "object", "properties": {}, "required": []},
+        categories=("read", "ide", "debug"),
+        rich=RichToolMetadata(
+            display_name="List IDE Debug Configurations",
+            reasoning_hint="Discover repository-owned launch configurations before starting one.",
+            action_hint="Ask the trusted IDE host for a bounded launch configuration inventory.",
+            fallback_hint="If unavailable, inspect launch.json or use tests and shell verification.",
+        ),
+        built_in_subagent_exposure="readonly",
+        optional=True,
+        optional_unavailable_reason="The trusted IDE host did not advertise debug.list.",
+    ),
+    BuiltinToolMetadata(
+        name="ide_debug_start",
+        description=(
+            "Start one VS Code debug configuration by the opaque id returned by ide_debug_list. "
+            "The trusted IDE host resolves the actual launch configuration."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {"configuration_id": {"type": "string"}},
+            "required": ["configuration_id"],
+        },
+        categories=("write", "ide", "debug"),
+        rich=RichToolMetadata(
+            display_name="Start IDE Debug Session",
+            reasoning_hint="Launch a repository-owned debug configuration through VS Code.",
+            action_hint="Start one trusted-host debug configuration by opaque id.",
+            fallback_hint="List configurations again if the id is stale, or use tests and logs.",
+        ),
+        optional=True,
+        optional_unavailable_reason="The trusted IDE host did not advertise debug.start.",
+    ),
+    BuiltinToolMetadata(
+        name="ide_debug_stop",
+        description="Stop one VS Code debug session by the opaque id returned by ide_debug_start.",
+        parameters={
+            "type": "object",
+            "properties": {"debug_session_id": {"type": "string"}},
+            "required": ["debug_session_id"],
+        },
+        categories=("write", "ide", "debug"),
+        rich=RichToolMetadata(
+            display_name="Stop IDE Debug Session",
+            reasoning_hint="Stop a host-owned debug session that is no longer needed.",
+            action_hint="Ask the trusted IDE host to stop one opaque debug session id.",
+            fallback_hint="Inspect VS Code's debug controls if the session id is stale.",
+        ),
+        optional=True,
+        optional_unavailable_reason="The trusted IDE host did not advertise debug.stop.",
+    ),
+    BuiltinToolMetadata(
+        name="ide_debug_status",
+        description=(
+            "Read bounded VS Code debug-session status, optionally filtered by one opaque session "
+            "id. The trusted IDE host owns session discovery."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {"debug_session_id": {"type": "string"}},
+            "required": [],
+        },
+        categories=("read", "ide", "debug"),
+        rich=RichToolMetadata(
+            display_name="Read IDE Debug Status",
+            reasoning_hint="Check whether a trusted-host debug session is still running.",
+            action_hint="Read bounded status for one or all host-owned debug sessions.",
+            fallback_hint="Use VS Code's debug controls if host status is unavailable.",
+        ),
+        built_in_subagent_exposure="readonly",
+        optional=True,
+        optional_unavailable_reason="The trusted IDE host did not advertise debug.status.",
+    ),
+    BuiltinToolMetadata(
+        name="browser_start",
+        description=(
+            "Start one IDE-owned managed Chromium session, optionally at a public or "
+            "session-owned preview URL. Other local/private destinations remain blocked."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "url": {"type": "string"},
+                "timeout": {"type": "number", "minimum": 0.05, "maximum": 300},
+            },
+        },
+        categories=("write", "browser", "web"),
+        rich=RichToolMetadata(
+            display_name="Start Browser",
+            reasoning_hint="Open an isolated managed browser before interactive page inspection.",
+            action_hint="Start an approval-gated, IDE-owned Chromium session.",
+            fallback_hint="If approval or launch fails, use web_search/web_fetch or ask the user.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="hidden",
+    ),
+    BuiltinToolMetadata(
+        name="browser_navigate",
+        description=(
+            "Navigate an owned browser to a public URL or a live session-owned preview origin. "
+            "Redirects and subresources use the same policy."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "session_id": {"type": "string"},
+                "url": {"type": "string"},
+                "timeout": {"type": "number", "minimum": 0.05, "maximum": 300},
+            },
+            "required": ["session_id", "url"],
+        },
+        categories=("write", "browser", "web", "network"),
+        rich=RichToolMetadata(
+            display_name="Navigate Browser",
+            reasoning_hint="Open a public page in the isolated managed browser.",
+            action_hint="Navigate after explicit host approval and enforce the URL policy.",
+            fallback_hint="If blocked, use a public URL or web_fetch instead.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="hidden",
+    ),
+    BuiltinToolMetadata(
+        name="browser_snapshot",
+        description=(
+            "Read a bounded semantic, accessibility, DOM, or text snapshot from an owned "
+            "managed-browser session."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "session_id": {"type": "string"},
+                "kind": {
+                    "type": "string",
+                    "enum": ["semantic", "accessibility", "dom", "text"],
+                    "default": "semantic",
+                },
+                "timeout": {"type": "number", "minimum": 0.05, "maximum": 300},
+            },
+            "required": ["session_id"],
+        },
+        categories=("read", "browser", "web"),
+        rich=RichToolMetadata(
+            display_name="Snapshot Browser",
+            reasoning_hint="Inspect the current page structure or text before interacting.",
+            action_hint="Read a bounded browser snapshot.",
+            fallback_hint="Try a text snapshot or browser_screenshot if structure is unavailable.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="browser_screenshot",
+        description=(
+            "Capture a bounded PNG screenshot as an owner-scoped artifact. Returns only an "
+            "artifact id and metadata, never a filesystem path."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "session_id": {"type": "string"},
+                "full_page": {"type": "boolean", "default": False},
+                "timeout": {"type": "number", "minimum": 0.05, "maximum": 300},
+            },
+            "required": ["session_id"],
+        },
+        categories=("read", "browser", "web", "artifact"),
+        rich=RichToolMetadata(
+            display_name="Screenshot Browser",
+            reasoning_hint="Capture visual page evidence that snapshots cannot represent.",
+            action_hint="Create a private screenshot artifact and return its opaque id.",
+            fallback_hint="Use browser_snapshot when visual evidence is unnecessary.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="browser_artifact_read",
+        description=(
+            "Read one bounded base64 chunk of an owner-scoped browser screenshot artifact by "
+            "opaque artifact id. Caller-selected paths are not accepted."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "session_id": {"type": "string"},
+                "artifact_id": {"type": "string"},
+                "offset": {"type": "integer", "minimum": 0, "default": 0},
+                "max_bytes": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 1048576,
+                    "default": 262144,
+                },
+            },
+            "required": ["session_id", "artifact_id"],
+        },
+        categories=("read", "browser", "artifact"),
+        rich=RichToolMetadata(
+            display_name="Read Browser Artifact",
+            reasoning_hint="Read a bounded screenshot chunk using its opaque artifact id.",
+            action_hint="Return one base64 screenshot chunk without exposing its path.",
+            fallback_hint="Use a smaller chunk or the next_offset returned by the prior call.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="browser_diagnostics",
+        description=(
+            "Read bounded, redacted console and network diagnostic events from an owned "
+            "managed-browser session."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "session_id": {"type": "string"},
+                "max_events": {"type": "integer", "minimum": 1, "maximum": 500},
+                "timeout": {"type": "number", "minimum": 0.05, "maximum": 300},
+            },
+            "required": ["session_id"],
+        },
+        categories=("read", "browser", "web", "diagnostics"),
+        rich=RichToolMetadata(
+            display_name="Read Browser Diagnostics",
+            reasoning_hint="Inspect bounded console and network failures after reproducing a bug.",
+            action_hint="Read redacted browser diagnostics.",
+            fallback_hint="Reproduce the issue, then request a smaller diagnostic window.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="browser_click",
+        description="Click one CSS selector in an owned managed-browser session.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "session_id": {"type": "string"},
+                "selector": {"type": "string", "maxLength": 2000},
+                "timeout": {"type": "number", "minimum": 0.05, "maximum": 300},
+            },
+            "required": ["session_id", "selector"],
+        },
+        categories=("write", "browser", "web"),
+        rich=RichToolMetadata(
+            display_name="Click Browser Element",
+            reasoning_hint="Interact with a confirmed page element after inspecting the page.",
+            action_hint="Click a selector after explicit host approval.",
+            fallback_hint="Refresh the snapshot and use a more precise selector.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="hidden",
+    ),
+    BuiltinToolMetadata(
+        name="browser_type",
+        description=(
+            "Type text into one CSS selector in an owned managed-browser session. Input text is "
+            "never echoed in the result or approval preview."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "session_id": {"type": "string"},
+                "selector": {"type": "string", "maxLength": 2000},
+                "text": {"type": "string", "maxLength": 100000},
+                "replace": {"type": "boolean", "default": True},
+                "timeout": {"type": "number", "minimum": 0.05, "maximum": 300},
+            },
+            "required": ["session_id", "selector", "text"],
+        },
+        categories=("write", "browser", "web"),
+        rich=RichToolMetadata(
+            display_name="Type in Browser",
+            reasoning_hint="Enter user-approved text into a confirmed page field.",
+            action_hint="Type without exposing the text in tool summaries or approval previews.",
+            fallback_hint="Refresh the snapshot and confirm the selector before retrying.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="hidden",
+    ),
+    BuiltinToolMetadata(
+        name="browser_status",
+        description="Read the bounded public status of one owned managed-browser session.",
+        parameters={
+            "type": "object",
+            "properties": {"session_id": {"type": "string"}},
+            "required": ["session_id"],
+        },
+        categories=("read", "browser"),
+        rich=RichToolMetadata(
+            display_name="Browser Status",
+            reasoning_hint="Check whether a managed browser session is active and where it is.",
+            action_hint="Read browser status.",
+            fallback_hint="List owned sessions if the id is unknown.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="browser_list",
+        description="List bounded public statuses for managed-browser sessions owned by this IDE task.",
+        parameters={"type": "object", "properties": {}},
+        categories=("read", "browser"),
+        rich=RichToolMetadata(
+            display_name="List Browsers",
+            reasoning_hint="Discover managed browser sessions owned by this IDE task.",
+            action_hint="List owned browser sessions.",
+            fallback_hint="Start a browser if no owned session exists.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="browser_close",
+        description=(
+            "Close one owned managed-browser session and its exact process group. Artifacts are "
+            "retained unless the IDE lifecycle removes them."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {"session_id": {"type": "string"}},
+            "required": ["session_id"],
+        },
+        categories=("write", "browser"),
+        rich=RichToolMetadata(
+            display_name="Close Browser",
+            reasoning_hint="Release an owned managed browser when it is no longer needed.",
+            action_hint="Close the exact owned browser process group after approval.",
+            fallback_hint="Check browser_status if the session may already be closed.",
+        ),
+        optional=True,
+        optional_unavailable_reason="Managed browser service is not attached to this IDE session.",
+        built_in_subagent_exposure="hidden",
+    ),
+    BuiltinToolMetadata(
+        name="symbol_search",
+        description=(
+            "Search Python (AST), JavaScript/TypeScript (heuristic), and Java (heuristic) symbols "
+            "(functions, classes, methods, constants) under the working root. Prefer this before broad regex search when locating definitions."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "query": {"type": "string"},
+                "kind": {
+                    "type": "string",
+                    "enum": ["function", "class", "method", "constant"],
+                },
+                "root_path": {"type": "string"},
+                "path_base": _path_base_property(),
+                "globs": {"type": "array", "items": {"type": "string"}},
+                "max_results": {"type": "integer", "default": 100},
+                "exact": {"type": "boolean", "default": False},
+                "include_details": {"type": "boolean", "default": False},
+                "include_snippet": {"type": "boolean", "default": False},
+                "include_references": {"type": "boolean", "default": False},
+            },
+            "required": ["query"],
+        },
+        categories=("read", "search", "symbol"),
+        rich=RichToolMetadata(
+            display_name="Symbol Search",
+            reasoning_hint="Navigate Python or JS/TS definitions before broad regex search.",
+            action_hint=(
+                "Search parsed Python symbols plus pragmatic JS/TS symbols (class/function/method/constant)."
+            ),
+            fallback_hint="If results are sparse, relax exact/kind filters or fall back to search_rg.",
+            input_preview_formatter=_preview_symbol_search,
+            output_summary_formatter=_summary_symbol_search,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="test_discover",
+        description=(
+            "Find likely tests and focused test commands for changed files, symbols, or a "
+            "verification failure summary. Use for repair targeting before broad final verification."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "paths": {"type": "array", "items": {"type": "string"}},
+                "symbols": {"type": "array", "items": {"type": "string"}},
+                "changed_only": {"type": "boolean", "default": False},
+                "include_commands": {"type": "boolean", "default": True},
+                "max_results": {"type": "integer", "default": 20, "minimum": 1, "maximum": 100},
+                "failure_summary": {"type": "object"},
+            },
+        },
+        categories=("read", "search", "verification"),
+        rich=RichToolMetadata(
+            display_name="Discover Tests",
+            reasoning_hint="Map changed files or verification failures to likely focused tests.",
+            action_hint="Suggest likely test files and candidate targeted commands without running them.",
+            fallback_hint=(
+                "If no focused test is found, use broad_commands or the configured verify_run contract."
+            ),
+            output_summary_formatter=_summary_test_discover,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="repo_map",
+        description=(
+            "Build a compact heuristic map of files, imports, symbols, likely tests, and "
+            "repo-native commands related to paths or symbols. Use before broad exploration in unfamiliar repos."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "paths": {"type": "array", "items": {"type": "string"}},
+                "symbols": {"type": "array", "items": {"type": "string"}},
+                "include_tests": {"type": "boolean", "default": True},
+                "include_imports": {"type": "boolean", "default": True},
+                "include_references": {"type": "boolean", "default": False},
+                "depth": {"type": "integer", "default": 2, "minimum": 0, "maximum": 4},
+                "max_items": {"type": "integer", "default": 80, "minimum": 1, "maximum": 200},
+            },
+        },
+        categories=("read", "search", "symbol", "verification"),
+        rich=RichToolMetadata(
+            display_name="Map Repo",
+            reasoning_hint="Orient around changed paths/symbols before scattered file reads.",
+            action_hint="Return related implementation files, imports, tests, and candidate commands.",
+            fallback_hint="If the map is sparse, use symbol_search, search_rg, or test_discover directly.",
+            output_summary_formatter=_summary_repo_map,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="search_rg",
+        description=(
+            "Search for a regex or literal pattern under root_path using ripgrep when available. "
+            "Prefer this for fast text/code lookup before reading or patching files. "
+            "Use context options for edit planning."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string"},
+                "root_path": {"type": "string"},
+                "path_base": _path_base_property(),
+                "globs": {"type": "array", "items": {"type": "string"}},
+                "max_results": {"type": "integer", "default": 200, "minimum": 1, "maximum": 500},
+                "before_context": {"type": "integer", "default": 0, "minimum": 0, "maximum": 5},
+                "after_context": {"type": "integer", "default": 0, "minimum": 0, "maximum": 5},
+                "literal": {"type": "boolean", "default": False},
+                "case_sensitive": {"type": "boolean", "default": True},
+                "include_hidden": {"type": "boolean", "default": False},
+            },
+            "required": ["pattern"],
+        },
+        categories=("read", "search"),
+        rich=RichToolMetadata(
+            display_name="Search Workspace",
+            reasoning_hint="Locate exact code/text matches fast with optional surrounding context.",
+            action_hint="Run bounded text search and return matching lines plus requested context.",
+            fallback_hint="If no matches, broaden pattern and search scope.",
+            input_preview_formatter=_preview_pattern,
+            output_summary_formatter=_summary_search_rg,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="session_artifact_read",
+        description=(
+            "Read a bounded, redacted artifact from the current session using an exact "
+            "session_artifacts/... locator returned by another tool. This accepts a locator, "
+            "not a filesystem path."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "locator": {"type": "string"},
+                "offset": {"type": "integer", "default": 0, "minimum": 0},
+                "max_bytes": {
+                    "type": "integer",
+                    "default": 65536,
+                    "minimum": 1,
+                    "maximum": 1048576,
+                },
+            },
+            "required": ["locator"],
+        },
+        categories=("read", "history", "artifact"),
+        rich=RichToolMetadata(
+            display_name="Read Session Artifact",
+            reasoning_hint="Resolve an advertised current-session artifact locator directly.",
+            action_hint="Read a bounded, redacted page from the current session artifact store.",
+            fallback_hint="Use the exact locator returned by the producing tool.",
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="history_search",
+        description=(
+            "Search current session artifacts (history chunks, tool outputs, and memory files) for a regex pattern."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string"},
+                "max_results": {"type": "integer", "default": 50},
+                "max_file_bytes": {"type": "integer", "default": 200000},
+                "include_history": {"type": "boolean", "default": True},
+                "include_tool_outputs": {"type": "boolean", "default": True},
+                "include_memory": {"type": "boolean", "default": True},
+            },
+            "required": ["pattern"],
+        },
+        categories=("read", "history"),
+        rich=RichToolMetadata(
+            display_name="Search Session History",
+            reasoning_hint="Inspect current session artifacts without rereading every history file.",
+            action_hint="Search stored history chunks, tool outputs, and memory summaries for a pattern.",
+            fallback_hint="If results are sparse, widen the regex or include more artifact types.",
+            input_preview_formatter=_preview_pattern,
+            output_summary_formatter=_summary_history_search,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="knowledge_capture_json",
+        description=(
+            "Optional host-observed structured knowledge capture marker. This is not a "
+            "callable runtime tool; the host parses a final assistant fenced block when present."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "schema_version": {"type": "integer"},
+                "facts": {"type": "array"},
+                "decisions": {"type": "array"},
+                "open_questions": {"type": "array"},
+            },
+            "required": [],
+        },
+        categories=("knowledge", "optional"),
+        rich=RichToolMetadata(
+            display_name="Knowledge Capture",
+            reasoning_hint=(
+                "Record reusable repo knowledge only through the final assistant fenced block."
+            ),
+            action_hint=(
+                "Do not call this as a runtime tool; append the bounded fenced JSON block when useful."
+            ),
+            fallback_hint=(
+                "If unavailable, continue with the normal final response; missing capture is non-fatal."
+            ),
+            output_summary_formatter=lambda parsed: (
+                "Optional knowledge capture tool unavailable."
+                if is_tool_unavailable_result(parsed)
+                else "Knowledge capture metadata result."
+            ),
+        ),
+        optional=True,
+        optional_unavailable_reason=(
+            "not registered in active tool registry; knowledge capture is a final assistant "
+            "fenced block parsed by host"
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="skill_read",
+        description=(
+            "Read a discovered skill bundle entrypoint or one specific file within that skill bundle. "
+            "Use this to inspect SKILL.md or targeted references/scripts/assets before applying a skill."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "path": {"type": "string"},
+            },
+            "required": ["name"],
+        },
+        categories=("read", "skills"),
+        rich=RichToolMetadata(
+            display_name="Read Skill",
+            reasoning_hint="Inspect a discovered skill bundle before relying on its instructions.",
+            action_hint="Read SKILL.md or one bundle file by name from the discovered skills registry.",
+            fallback_hint="If the skill name or file path is wrong, list skills or retry with a bundle-relative path.",
+            input_preview_formatter=_preview_skill_read,
+            output_summary_formatter=_summary_skill_read,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="image_generate",
+        description=(
+            "Generate one to four raster image assets through the configured "
+            "OpenAI-compatible image provider and write them under the workspace root. "
+            "This is an external billable operation and is exposed only when "
+            "image_generation.enabled=true. Output paths must be new .png, .jpg, .jpeg, "
+            "or .webp files; existing files are never overwritten. The result includes "
+            "dimensions, format, alpha-channel presence, byte count, SHA-256, provider "
+            "request metadata, and technical validation status."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "prompt": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 32000,
+                    "description": (
+                        "Concrete production brief covering subject, composition, style, "
+                        "palette, lighting, negative constraints, and intended use."
+                    ),
+                },
+                "output_path": {
+                    "type": "string",
+                    "description": (
+                        "New workspace-root-relative .png, .jpg, .jpeg, or .webp path. "
+                        "For count > 1, -1, -2, etc. are appended before the extension."
+                    ),
+                },
+                "count": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 4,
+                    "default": 1,
+                },
+                "size": {
+                    "type": "string",
+                    "enum": ["auto", "1024x1024", "1536x1024", "1024x1536"],
+                    "default": "auto",
+                },
+                "quality": {
+                    "type": "string",
+                    "enum": ["auto", "low", "medium", "high"],
+                    "default": "auto",
+                },
+                "background": {
+                    "type": "string",
+                    "enum": ["auto", "opaque", "transparent"],
+                    "default": "auto",
+                },
+            },
+            "required": ["prompt", "output_path"],
+        },
+        categories=("write", "image", "generation", "network"),
+        rich=RichToolMetadata(
+            display_name="Generate Image",
+            reasoning_hint="Create a production raster asset from a precise visual brief.",
+            action_hint="Generate, validate, and atomically write a new image asset.",
+            fallback_hint=(
+                "If unavailable, report the missing image-generation configuration; do not "
+                "substitute placeholder bytes or claim an asset was generated."
+            ),
+            input_preview_formatter=_preview_image_generate,
+            output_summary_formatter=_summary_image_generate,
+        ),
+        optional=True,
+        optional_unavailable_reason="image_generation.enabled is false",
+    ),
+    BuiltinToolMetadata(
+        name="verify_run",
+        description=(
+            "Run configured verification commands. Prefer for tests/lint/build. "
+            "If overriding commands, pass one verifier per array item; do not join with "
+            "&&, ;, pipes, filters, list/build-only checks, or swapped build systems."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "commands": {"type": "array", "items": {"type": "string"}},
+            },
+            "required": [],
+        },
+        categories=("verify",),
+        rich=RichToolMetadata(
+            display_name="Run Verification",
+            reasoning_hint="Run structured verification before relying on raw shell commands.",
+            action_hint="Execute configured or targeted verification commands and inspect pass/fail results.",
+            fallback_hint="If using shell_run, run the same unfiltered verifier.",
+            input_preview_formatter=_preview_verify_run,
+            output_summary_formatter=_summary_verify_run,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="shell_run",
+        description="Run a shell command under the working root (policy-checked).",
+        parameters={
+            "type": "object",
+            "properties": {
+                "cmd": {"type": "string"},
+                "cwd": {"type": "string"},
+                "cwd_base": _cwd_base_property(),
+            },
+            "required": ["cmd"],
+        },
+        categories=("shell",),
+        rich=RichToolMetadata(
+            display_name="Run Command",
+            reasoning_hint="Validate assumptions with project commands.",
+            action_hint="Run command and inspect exit code/stdout/stderr.",
+            fallback_hint="If denied/failing, use safer command or ask approval.",
+            input_preview_formatter=_preview_shell_run,
+            output_summary_formatter=_summary_shell_run,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="shell_background",
+        description=(
+            "Start a long-running shell command in the background under the working root "
+            "(policy-checked). Returns a process_id you can use with shell_output, shell_kill, "
+            "and shell_list. It is terminated when the session closes. Use this for dev servers "
+            "you only need while this session is running, file watchers, log tailers, or any "
+            "command that should not block the agent loop."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "cmd": {"type": "string"},
+                "cwd": {"type": "string"},
+                "cwd_base": _cwd_base_property(),
+                "persist": {
+                    "type": "boolean",
+                    "default": False,
+                    "description": "Keep the process running after the session ends, as a durable service.",
+                },
+                "probe_port": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "maximum": 65535,
+                    "description": "TCP port to probe for liveness; inferred from cmd when omitted.",
+                },
+            },
+            "required": ["cmd"],
+        },
+        categories=("shell", "background"),
+        rich=RichToolMetadata(
+            display_name="Run Background Command",
+            reasoning_hint=(
+                "Spawn a non-blocking process for long-running work without holding the agent loop."
+            ),
+            action_hint="Start command and capture process_id; later read incrementally with shell_output.",
+            fallback_hint="If the command can complete fast, prefer shell_run for direct stdout.",
+            input_preview_formatter=_preview_shell_run,
+            output_summary_formatter=_summary_shell_background,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="shell_output",
+        description=(
+            "Read accumulated stdout/stderr from a background process started with shell_background. "
+            "Pass since=<next_seq> from the previous read to get only new lines. For a quiet "
+            "long-running process, prefer shell_wait instead of repeatedly polling shell_output. "
+            "Output is ring-buffered; very chatty processes may report dropped_lines > 0. "
+            "Use the process_id returned by shell_background or shell_list, not a tool_call_id; "
+            "unknown ids return structured recovery guidance."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "process_id": {"type": "string"},
+                "since": {"type": "integer", "default": 0},
+            },
+            "required": ["process_id"],
+        },
+        categories=("shell", "background", "read"),
+        rich=RichToolMetadata(
+            display_name="Read Background Output",
+            reasoning_hint="Inspect what a background process has emitted since the last read.",
+            action_hint="Fetch new output lines plus current status, exit_code, and runtime.",
+            fallback_hint="If process_id is unknown, list active processes with shell_list first.",
+            input_preview_formatter=_preview_shell_output,
+            output_summary_formatter=_summary_shell_output,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="shell_wait",
+        description=(
+            "Wait inside one bounded tool call for a background process to emit new output, exit, "
+            "or either condition. Use this instead of repeatedly polling shell_output when no new "
+            "output is available. Use the process_id returned by shell_background or shell_list, "
+            "not a tool_call_id; unknown ids return structured recovery guidance."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "process_id": {"type": "string"},
+                "since": {"type": "integer", "default": 0},
+                "wait_seconds": {"type": "number", "default": 5.0, "minimum": 0, "maximum": 60},
+                "until": {
+                    "type": "string",
+                    "enum": ["output_available", "process_exited", "either"],
+                    "default": "either",
+                },
+                "max_bytes": {"type": "integer", "default": 12000, "minimum": 1},
+            },
+            "required": ["process_id"],
+        },
+        categories=("shell", "background", "read"),
+        rich=RichToolMetadata(
+            display_name="Wait For Background Output",
+            reasoning_hint="Block briefly for useful output or process completion without busy polling.",
+            action_hint="Wait for new output, exit, or either; returns the same cursor/status fields as shell_output.",
+            fallback_hint="If the process_id is unknown, list active processes with shell_list first.",
+            input_preview_formatter=_preview_shell_output,
+            output_summary_formatter=_summary_shell_wait,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="shell_kill",
+        description=(
+            "Terminate a background process by process_id. Sends SIGTERM (or platform equivalent), "
+            "escalates to SIGKILL after the configured grace period. Idempotent - calling on an "
+            "already-terminated process returns the existing status."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "process_id": {"type": "string"},
+            },
+            "required": ["process_id"],
+        },
+        categories=("shell", "background"),
+        rich=RichToolMetadata(
+            display_name="Kill Background Process",
+            reasoning_hint="Stop a background process when no longer needed or to free a slot.",
+            action_hint="Signal the process; output remains readable after termination.",
+            fallback_hint="If kill fails, the session lifecycle reaps remaining processes on close.",
+            input_preview_formatter=_preview_shell_kill,
+            output_summary_formatter=_summary_shell_kill,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="shell_list",
+        description=(
+            "List all background processes from this session with their status, exit code, "
+            "command preview (truncated), cwd, and runtime. Includes both running and recently-"
+            "terminated processes that have not yet been pruned."
+        ),
+        parameters={"type": "object", "properties": {}, "required": []},
+        categories=("shell", "background", "read"),
+        rich=RichToolMetadata(
+            display_name="List Background Processes",
+            reasoning_hint="Audit current background activity before starting more work.",
+            action_hint="Enumerate active and recently-terminated bg processes.",
+            fallback_hint="If empty, no bg processes are tracked in this session.",
+            output_summary_formatter=_summary_shell_list,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="workspace_preview_start",
+        description=(
+            "Start Alysis Code's constrained static-file preview for a workspace directory. "
+            "The model chooses semantic access (auto, local, or lan); the runtime discovers a "
+            "suitable interface and allocates a free port when none is requested. LAN previews "
+            "require approval and temporary authentication. The server does not require Docker, "
+            "disables directory listing, blocks hidden files, and rejects symlink escapes."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "cwd": {"type": "string"},
+                "cwd_base": _cwd_base_property(),
+                "access": {
+                    "type": "string",
+                    "enum": ["auto", "local", "lan"],
+                    "default": "auto",
+                },
+                "port": {"type": "integer", "minimum": 1, "maximum": 65535},
+            },
+            "required": [],
+        },
+        categories=("shell", "background", "service"),
+        rich=RichToolMetadata(
+            display_name="Start Workspace Preview",
+            reasoning_hint=(
+                "Use auto unless the user explicitly asks for local-only or LAN access."
+            ),
+            action_hint=(
+                "Let the runtime allocate the endpoint, then use the returned access_url."
+            ),
+            fallback_hint=(
+                "If a requested port is occupied, omit it so the operating system chooses one."
+            ),
+            output_summary_formatter=_summary_shell_service,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="shell_service_start",
+        description=(
+            "Start an explicit durable service under the working root. Unlike shell_background, "
+            "this service keeps running after the session ends and must be stopped with "
+            "shell_service_stop when no longer needed. For static HTML/CSS/JS previews, use "
+            "workspace_preview_start instead. Provide readiness when another server or daemon "
+            "must remain available after finalization."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "cmd": {"type": "string"},
+                "cwd": {"type": "string"},
+                "cwd_base": _cwd_base_property(),
+                "readiness": _service_readiness_property(),
+            },
+            "required": ["cmd"],
+        },
+        categories=("shell", "background", "service"),
+        rich=RichToolMetadata(
+            display_name="Start Durable Service",
+            reasoning_hint="Use only when the task explicitly requires service persistence.",
+            action_hint="Start the service and check the returned readiness/status fields.",
+            fallback_hint=(
+                "Use workspace_preview_start for static sites, or shell_background for temporary "
+                "non-preview processes that should be reaped when the session closes."
+            ),
+            input_preview_formatter=_preview_shell_run,
+            output_summary_formatter=_summary_shell_service,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="shell_service_status",
+        description=(
+            "Check a durable service by service_id and re-run its readiness probe. Use before "
+            "finalization for tasks that require a persistent server or daemon."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "service_id": {"type": "string"},
+            },
+            "required": ["service_id"],
+        },
+        categories=("shell", "background", "service", "read"),
+        rich=RichToolMetadata(
+            display_name="Check Durable Service",
+            reasoning_hint="Verify a durable service is still alive and ready.",
+            action_hint="Re-check status/readiness for a previously started durable service.",
+            fallback_hint="If the service is stale or unknown, start it explicitly with readiness.",
+            input_preview_formatter=_preview_shell_service_id,
+            output_summary_formatter=_summary_shell_service,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="shell_service_stop",
+        description=(
+            "Stop a durable service by service_id. Uses stored PID/PGID identity metadata to avoid "
+            "killing unrelated processes if the PID has been reused."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "service_id": {"type": "string"},
+            },
+            "required": ["service_id"],
+        },
+        categories=("shell", "background", "service"),
+        rich=RichToolMetadata(
+            display_name="Stop Durable Service",
+            reasoning_hint="Clean up a durable service once persistence is no longer required.",
+            action_hint="Terminate the durable service and remove its runtime metadata.",
+            fallback_hint="If the service is unknown, inspect status or runtime logs first.",
+            input_preview_formatter=_preview_shell_service_id,
+            output_summary_formatter=_summary_shell_service,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="session_set_workdir",
+        description=(
+            "Change the live session active_workdir inside the bound workspace_root so later relative "
+            "file, search, and shell calls default there. Use this when the user says things like "
+            "'go to packages/app', 'work in apps/web', or 'switch to server/api and inspect package.json'."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "path": {
+                    "type": "string",
+                    "description": (
+                        "Target directory inside the current workspace_root. Relative values resolve "
+                        "from the current active_workdir."
+                    ),
+                },
+            },
+            "required": ["path"],
+        },
+        categories=("session", "navigation"),
+        rich=RichToolMetadata(
+            display_name="Set Session Workdir",
+            reasoning_hint=(
+                "Move the session's live default workdir before more file, search, or shell calls."
+            ),
+            action_hint=(
+                "Change the active workdir inside the current workspace_root when the user asks to "
+                "go to packages/app, work in apps/web, or switch to another directory."
+            ),
+            fallback_hint="If the path escapes the workspace or does not exist, report that blocker clearly.",
+            input_preview_formatter=_preview_single_path,
+            output_summary_formatter=_summary_session_set_workdir,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="git_status",
+        description="Run git status (porcelain) in the working root. Prefer before/after edits to inspect repo state.",
+        parameters={"type": "object", "properties": {}, "required": []},
+        categories=("read", "git"),
+        rich=RichToolMetadata(
+            display_name="Git Status",
+            reasoning_hint="Check repository state before/after edits.",
+            action_hint="Inspect tracked/untracked and dirty changes.",
+            fallback_hint="If unavailable, continue with file-based checks.",
+            output_summary_formatter=_summary_git_status,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="git_diff",
+        description="Run git diff in the working root. Prefer to review current repo changes before the final response.",
+        parameters={"type": "object", "properties": {}, "required": []},
+        categories=("read", "git"),
+        rich=RichToolMetadata(
+            display_name="Git Diff",
+            reasoning_hint="Review change impact before final response.",
+            action_hint="Collect current diff for inspection.",
+            fallback_hint="If unavailable, rely on patch/tool summaries.",
+            output_summary_formatter=_summary_git_diff,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="git_history",
+        description=(
+            "Inspect Git history: log lists commits, show reads one revision, and blame "
+            "maps lines. Use git_diff for uncommitted changes."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "mode": {"type": "string", "enum": ["log", "show", "blame"]},
+                "path": {"type": "string"},
+                "limit": {"type": "integer", "default": 10},
+                "ref": {
+                    "type": "string",
+                    "description": "Log revision; show alias for commit.",
+                },
+                "grep": {"type": "string"},
+                "author": {"type": "string"},
+                "commit": {
+                    "type": "string",
+                    "description": "Show revision; ref is an alias.",
+                },
+                "start_line": {"type": "integer"},
+                "end_line": {"type": "integer"},
+            },
+            "required": ["mode"],
+        },
+        categories=("read", "git", "history"),
+        rich=RichToolMetadata(
+            display_name="Git History",
+            reasoning_hint="Inspect repository history without dropping to shell commands.",
+            action_hint="Use one tool for commit logs, commit excerpts, or blame ranges.",
+            fallback_hint="If the commit/path/range is wrong, narrow the request and retry.",
+            input_preview_formatter=_preview_git_history,
+            output_summary_formatter=_summary_git_history,
+        ),
+        built_in_subagent_exposure="readonly",
+    ),
+    BuiltinToolMetadata(
+        name="git_apply_patch",
+        description="Apply a unified diff patch using git apply. Prefer for broader, multi-file, or context-heavy edits where unified diff context matters.",
+        parameters={
+            "type": "object",
+            "properties": {"patch": {"type": "string"}},
+            "required": ["patch"],
+        },
+        categories=("write", "git"),
+        rich=RichToolMetadata(
+            display_name="Apply Patch",
+            reasoning_hint="Apply multi-file edits atomically.",
+            action_hint="Run patch application and validate outcome.",
+            fallback_hint="If patch fails, retry with smaller focused patch.",
+            output_summary_formatter=_summary_git_apply_patch,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="subagent_run",
+        description=(
+            "Run a registered subagent in an isolated nested session and return its single "
+            "final report. Each call spawns a fresh subagent with its own system prompt, "
+            "tool sandbox, execution policy, and message history; the subagent does not see this "
+            "conversation's transcript and you do not see its intermediate steps -- only the "
+            "final text it produced plus structured metadata.\n"
+            "\n"
+            "Strategic guidance for when to delegate, parallelism, and trust-but-verify is "
+            "covered in the `Subagent delegation` section of the system prompt; this "
+            "description focuses on the tool contract.\n"
+            "\n"
+            "Parallel batch contract\n"
+            "- To run independent investigations concurrently, emit two or more "
+            "`subagent_run` calls in the same assistant response and emit no other tool call "
+            "in that response. Each call must be shared+readonly or isolated. The host "
+            "runs at most four children concurrently, queues any excess, and returns results "
+            "in original order; shared writes or mixed non-subagent calls run sequentially.\n"
+            "\n"
+            "Parameters\n"
+            "- name (required, string): registered subagent name. Built-in names include "
+            "`explorer`, `implementer`, `frontend-engineer`, `debugger`, "
+            "`code-reviewer`, `verifier`, and, when image generation is enabled, "
+            "`visual-designer`. Project-level custom subagents "
+            "from `.alysis_agents/*.md` and user-level ones from the user config dir are "
+            "also resolvable; manual-only roles remain host-resolvable but are omitted from "
+            "autonomous discovery surfaces. Names are case-insensitive "
+            "and a small alias table is applied "
+            "(e.g. `explore` -> `explorer`). Unknown names return an `error` field plus the "
+            "list of available names.\n"
+            "- task (required, string): the self-contained brief for the subagent. Treat the "
+            "subagent like a smart colleague who just walked into the room: it has no memory "
+            "of this conversation and has read no files yet. A good `task` includes (1) the "
+            "goal in one sentence, (2) exact repo-root-relative paths or symbols to start "
+            "from when known, (3) what you already learned or ruled out, and (4) the shape "
+            "of answer you want (e.g. `list 3-5 candidate files`, `verdict + blocking "
+            "issues`, `under 250 words`). Terse command-style prompts produce shallow output.\n"
+            "- mode (optional, string): one of `readonly`, `review`, `auto`, `fullaccess`. "
+            "Defaults to the subagent's declared mode. The effective mode is clamped to be "
+            "no more permissive than the parent session's mode, and is never raised above "
+            "`auto` unless the parent session itself is `fullaccess`. You cannot use this to "
+            "escalate privileges.\n"
+            "- max_steps (optional, integer): explicit safety limit on the subagent's "
+            "agentic iterations. If omitted, autonomous subagents continue until they finish, "
+            "are cancelled, become blocked, or encounter a fatal error.\n"
+            "\n"
+            "Output shape on success\n"
+            "Returns an object with: `subagent` (resolved name), `subagent_session_id`, "
+            "`result` (the subagent's final assistant text -- this is your primary signal), "
+            "`usage` (token/cost totals already merged into the parent session's usage), "
+            "and `sandbox` (the effective mode and the list of tools the "
+            "subagent had after allow/deny filtering).\n"
+            "\n"
+            "Output shape on failure\n"
+            "Returns an object with `error` (string) and, when applicable, `available_subagents`, "
+            "`subagent_session_id`, `exit_code`, `usage`, and `final_text` (best-effort partial "
+            "output). Common causes: unknown name, subagents disabled for the session, nested "
+            "delegation attempted outside the bounded helper contract, no tools "
+            "remained after sandbox filtering, the nested session raised, or the subagent ended "
+            "without an authoritative final-report signal. Plain assistant transcript text "
+            "without that final signal is treated as degraded rather than success.\n"
+            "Set `workspace_view=isolated` for a HEAD-based worktree retained for apply/discard.\n"
+            "\n"
+            "Sandboxing facts\n"
+            "- Each subagent definition declares an allow-list and/or deny-list of tools; "
+            "the resulting toolset may be smaller than your own. Do not assume the subagent "
+            "has every tool you have.\n"
+            "- Eligible depth-1 write-capable children may consult bounded read-only helpers; "
+            "helpers and all other recursive delegation are blocked.\n"
+            "- A subagent may run on a different model and temperature than this session, "
+            "controlled by its `model` / `model_role` definition fields.\n"
+            "\n"
+            "Examples of `task`\n"
+            'Good: "Map how API authentication flows from request ingress to user '
+            "resolution. Start from src/api/server.py and src/auth/. I have already "
+            "confirmed the JWT lib is PyJWT. Report: the call chain (file:line for each "
+            "step), where session state is stored, and any auth checks that look "
+            'inconsistent. Under 250 words."\n'
+            'Bad: "look at the auth code"'
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "description": (
+                        "Registered subagent name. Built-in: explorer, implementer, "
+                        "frontend-engineer, debugger, verifier, code-reviewer, "
+                        "dependency-scout; "
+                        "visual-designer is available when image generation is enabled. "
+                        "Project-defined custom names from "
+                        ".alysis_agents/ are also valid. "
+                        "Case-insensitive."
+                    ),
+                },
+                "task": {
+                    "type": "string",
+                    "description": (
+                        "Self-contained brief for the subagent. The "
+                        "subagent has no memory of this conversation "
+                        "and has read no files yet -- include the "
+                        "goal, exact paths or symbols to start from, "
+                        "what you have ruled out, and the form of "
+                        "answer you want. See tool description for "
+                        "full guidance."
+                    ),
+                },
+                "mode": {
+                    "type": "string",
+                    "enum": ["readonly", "review", "auto", "fullaccess"],
+                    "description": (
+                        "Optional mode override "
+                        "(readonly|review|auto|fullaccess). Clamped "
+                        "to the parent session's mode and never "
+                        "escalated above auto unless the parent is "
+                        "fullaccess."
+                    ),
+                },
+                "max_steps": {
+                    "type": "integer",
+                    "description": (
+                        "Optional safety limit on the subagent's agentic iterations. "
+                        "If omitted, autonomous execution has no step ceiling."
+                    ),
+                },
+                "workspace_view": {
+                    "type": "string",
+                    "enum": ["shared", "isolated"],
+                    "description": "Workspace view; isolated starts from parent HEAD.",
+                },
+                "workspace_from_run": {
+                    "type": "string",
+                    "description": "Completed isolated run id for a non-writing child.",
+                },
+            },
+            "required": ["name", "task"],
+        },
+        categories=("subagent",),
+        rich=RichToolMetadata(
+            display_name="Run Subagent",
+            reasoning_hint="Delegate focused repository analysis to a specialized subagent.",
+            action_hint="Run nested subagent session and consume the final summarized result.",
+            fallback_hint="If unclear or low confidence, verify claims with direct tools before continuing.",
+            output_summary_formatter=_summary_subagent_run,
+        ),
+    ),
+)
+
+_SUBAGENT_RUN_PARAMETERS = next(
+    spec.parameters for spec in _BUILTIN_TOOL_METADATA if spec.name == "subagent_run"
+)
+_SUBAGENT_SPAWN_PARAMETERS = copy.deepcopy(_SUBAGENT_RUN_PARAMETERS)
+_SUBAGENT_SPAWN_PARAMETERS["properties"]["run_id"] = {
+    "type": "string",
+    "maxLength": 64,
+    "description": "Optional caller-selected run id.",
+}
+_SUBAGENT_SPAWN_PARAMETERS["properties"]["depends_on"] = {
+    "type": "array",
+    "items": {"type": "string"},
+    "uniqueItems": True,
+    "description": "Run ids that must succeed first.",
+}
+_BUILTIN_TOOL_METADATA = (
+    *_BUILTIN_TOOL_METADATA,
+    BuiltinToolMetadata(
+        name="subagent_spawn",
+        description=(
+            "Start background work; shared is readonly-only, isolated may write, and excess "
+            "queues. Collect with subagent_wait before finalizing; subagent_run is synchronous. "
+            "Example: spawn impl isolated, then verifier with depends_on=[impl] and "
+            "workspace_from_run=impl."
+        ),
+        parameters=_SUBAGENT_SPAWN_PARAMETERS,
+        categories=("subagent",),
+        rich=RichToolMetadata(
+            display_name="Spawn Subagent",
+            reasoning_hint="Start independent readonly work without blocking the parent.",
+            action_hint="Spawn a background subagent and retain its run id for collection.",
+            fallback_hint="Use subagent_run when the result is needed immediately.",
+            output_summary_formatter=_summary_subagent_background,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="subagent_send",
+        description="Send one message to a queued or running background child.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "run_id": {"type": "string", "description": "Background run id."},
+                "message": {
+                    "type": "string",
+                    "maxLength": 4000,
+                    "description": "Message for the child.",
+                },
+            },
+            "required": ["run_id", "message"],
+        },
+        categories=("subagent",),
+        rich=RichToolMetadata(
+            display_name="Message Subagent",
+            reasoning_hint="Steer useful background work without restarting it.",
+            action_hint="Deliver guidance before the child's next model step.",
+            fallback_hint="Use subagent_status if the child may already be done.",
+            output_summary_formatter=_summary_subagent_background,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="subagent_resume",
+        description="Resume a failed, incomplete, or cancelled child as a new linked run.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "run_id": {"type": "string", "description": "Terminal background run id."},
+                "task": {"type": "string", "description": "Optional revised task."},
+                "workspace_view": {
+                    "type": "string",
+                    "enum": ["shared", "isolated"],
+                    "description": ("Optional workspace override for the linked background run."),
+                },
+                "reattach_workspace": {
+                    "type": "boolean",
+                    "default": True,
+                    "description": "Reuse a retained isolated worktree when available.",
+                },
+            },
+            "required": ["run_id"],
+        },
+        categories=("subagent",),
+        rich=RichToolMetadata(
+            display_name="Resume Subagent",
+            reasoning_hint="Continue a terminal child with its prior conversation.",
+            action_hint="Create a fresh linked run with current sandbox limits.",
+            fallback_hint="Successful and degraded runs cannot be resumed.",
+            output_summary_formatter=_summary_subagent_background,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="subagent_status",
+        description="List background child state, steps, elapsed time, and activity.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "run_id": {
+                    "type": "string",
+                    "description": "Optional background run id. Omit to list all runs.",
+                }
+            },
+        },
+        categories=("subagent",),
+        rich=RichToolMetadata(
+            display_name="Subagent Status",
+            reasoning_hint="Check background work without blocking for completion.",
+            action_hint="Read live background child states.",
+            fallback_hint="Use subagent_wait to collect completed reports.",
+            output_summary_formatter=_summary_subagent_background,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="subagent_wait",
+        description=(
+            "Collect one or all background results in spawn order. A timeout also returns "
+            "pending run ids; call again before finalizing."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "run_id": {
+                    "type": "string",
+                    "default": "all",
+                    "description": "Background run id or 'all' (default).",
+                },
+                "timeout_s": {
+                    "type": "number",
+                    "minimum": 0,
+                    "maximum": 3600,
+                    "description": "Optional maximum seconds to wait before returning pending ids.",
+                },
+            },
+        },
+        categories=("subagent",),
+        rich=RichToolMetadata(
+            display_name="Wait for Subagent",
+            reasoning_hint="Collect background reports before using them or finalizing.",
+            action_hint="Wait for selected background children and return completed results.",
+            fallback_hint="If time expires, continue useful work and wait again later.",
+            output_summary_formatter=_summary_subagent_background,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="subagent_cancel",
+        description=(
+            "Cancel one or all background runs. Queued children do not launch; running children "
+            "receive cooperative cancellation."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "run_id": {
+                    "type": "string",
+                    "default": "all",
+                    "description": "Background run id or 'all' (default).",
+                }
+            },
+        },
+        categories=("subagent",),
+        rich=RichToolMetadata(
+            display_name="Cancel Subagent",
+            reasoning_hint="Stop background work that is no longer useful.",
+            action_hint="Cancel queued or running background children.",
+            fallback_hint="Use subagent_status to confirm terminal states.",
+            output_summary_formatter=_summary_subagent_background,
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="subagent_apply",
+        description=(
+            "Apply one isolated run; non-successful runs require "
+            "acknowledge_incomplete=true and conflicts apply nothing."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "run_id": {"type": "string", "description": "Isolated run id."},
+                "acknowledge_incomplete": {
+                    "type": "boolean",
+                    "default": False,
+                    "description": "Accept a non-successful candidate's unfinished work.",
+                },
+            },
+            "required": ["run_id"],
+        },
+        categories=("subagent", "write", "git"),
+        rich=RichToolMetadata(
+            display_name="Apply Subagent Workspace",
+            reasoning_hint="Bring a reviewed isolated patch into the parent workspace.",
+            action_hint="Check and apply the captured patch without committing it.",
+            fallback_hint="Resolve parent conflicts or discard the isolated run.",
+        ),
+    ),
+    BuiltinToolMetadata(
+        name="subagent_discard",
+        description="Delete one retained isolated workspace without applying it.",
+        parameters={
+            "type": "object",
+            "properties": {"run_id": {"type": "string", "description": "Isolated run id."}},
+            "required": ["run_id"],
+        },
+        categories=("subagent",),
+        rich=RichToolMetadata(
+            display_name="Discard Subagent Workspace",
+            reasoning_hint="Release isolated work that should not enter the parent workspace.",
+            action_hint="Delete the retained worktree and mark it discarded.",
+            fallback_hint="Use subagent_apply when the captured patch should be kept.",
+        ),
+    ),
+)
+
+_BUILTIN_TOOL_METADATA_BY_NAME = {spec.name: spec for spec in _BUILTIN_TOOL_METADATA}
+if len(_BUILTIN_TOOL_METADATA_BY_NAME) != len(_BUILTIN_TOOL_METADATA):
+    raise RuntimeError("Duplicate built-in tool name detected in registry.")
+
+
+def iter_builtin_tool_metadata() -> tuple[BuiltinToolMetadata, ...]:
+    return _BUILTIN_TOOL_METADATA
+
+
+def get_builtin_tool_metadata(name: str) -> BuiltinToolMetadata | None:
+    return _BUILTIN_TOOL_METADATA_BY_NAME.get(name)
+
+
+def require_builtin_tool_metadata(name: str) -> BuiltinToolMetadata:
+    spec = get_builtin_tool_metadata(name)
+    if spec is None:
+        raise KeyError(f"Unknown built-in tool: {name}")
+    return spec
+
+
+def copied_tool_parameters(name: str) -> dict[str, Any]:
+    return require_builtin_tool_metadata(name).copied_parameters()
+
+
+def builtin_tool_names_with_category(category: str) -> tuple[str, ...]:
+    normalized = str(category or "").strip().lower()
+    return tuple(
+        spec.name
+        for spec in _BUILTIN_TOOL_METADATA
+        if normalized in {tag.lower() for tag in spec.categories}
+    )
+
+
+def built_in_subagent_tool_names(*, exposure: str = "readonly") -> tuple[str, ...]:
+    normalized = str(exposure or "").strip().lower()
+    return tuple(
+        spec.name
+        for spec in _BUILTIN_TOOL_METADATA
+        if spec.built_in_subagent_exposure.strip().lower() == normalized
+    )
+
+
+def tool_display_name(tool_name: str) -> str:
+    spec = get_builtin_tool_metadata(tool_name)
+    if spec is None:
+        return tool_name
+    return spec.rich.display_name
+
+
+def tool_input_preview(tool_name: str, args: dict[str, Any]) -> str:
+    spec = get_builtin_tool_metadata(tool_name)
+    if spec is None or spec.rich.input_preview_formatter is None:
+        return "-"
+    return spec.rich.input_preview_formatter(args)
+
+
+@dataclass(frozen=True)
+class CompatibilityToolAlias:
+    alias: str
+    target: str
+    transform: ToolAliasTransform
+    description: str
+
+
+def _identity_alias_transform(args: dict[str, Any]) -> dict[str, Any]:
+    return copy.deepcopy(args)
+
+
+_COMPATIBILITY_TOOL_ALIASES: dict[str, CompatibilityToolAlias] = {
+    "read_file": CompatibilityToolAlias(
+        alias="read_file",
+        target="fs_read",
+        transform=_identity_alias_transform,
+        description="read_file is a schema-compatible alias for fs_read.",
+    ),
+}
+_AMBIGUOUS_TOOL_ALIASES: dict[str, tuple[str, ...]] = {
+    "read": ("fs_read", "fs_read_lines", "web_fetch"),
+    "write": ("fs_write", "fs_edit", "shell_run"),
+    "search": ("search_rg", "web_search"),
+}
+
+
+def build_unknown_tool_recovery_payload(
+    *,
+    requested_tool_name: str,
+    arguments: dict[str, Any],
+    available_tool_names: Collection[str],
+) -> dict[str, Any]:
+    requested = str(requested_tool_name or "").strip()
+    available = _safe_available_tool_names(available_tool_names)
+    alias = compatibility_tool_alias_for(
+        requested_tool_name=requested,
+        arguments=arguments,
+        available_tool_names=available,
+    )
+    ambiguous_targets = _AMBIGUOUS_TOOL_ALIASES.get(_normalize_tool_alias_name(requested), ())
+    suggestions = nearest_tool_name_suggestions(
+        requested_tool_name=requested,
+        available_tool_names=available,
+    )
+    guidance = _unknown_tool_guidance(
+        requested=requested,
+        available=available,
+        suggestions=suggestions,
+        alias=alias,
+        ambiguous_targets=ambiguous_targets,
+    )
+    payload: dict[str, Any] = {
+        "error": f"Unknown tool: {requested}",
+        "error_code": "unknown_tool",
+        "requested_tool_name": requested,
+        "available_tool_names": available,
+        "nearest_tool_suggestions": suggestions,
+        "safe_compatibility_alias": alias is not None,
+        "guidance": guidance,
+    }
+    if alias is not None:
+        payload["compatibility_alias"] = {
+            "alias": alias.alias,
+            "target": alias.target,
+            "description": alias.description,
+        }
+    if ambiguous_targets:
+        payload["ambiguous_alias_targets"] = [
+            target for target in ambiguous_targets if target in available
+        ]
+        payload["alias_ambiguous"] = True
+    return payload
+
+
+def compatibility_tool_alias_for(
+    *,
+    requested_tool_name: str,
+    arguments: dict[str, Any],
+    available_tool_names: Collection[str],
+) -> CompatibilityToolAlias | None:
+    normalized = _normalize_tool_alias_name(requested_tool_name)
+    alias = _COMPATIBILITY_TOOL_ALIASES.get(normalized)
+    if alias is None:
+        return None
+    available = set(_safe_available_tool_names(available_tool_names))
+    if alias.target not in available:
+        return None
+    try:
+        transformed = alias.transform(arguments)
+    except Exception:  # noqa: BLE001 - bad alias input should stay non-executing.
+        return None
+    if not isinstance(transformed, dict):
+        return None
+    return alias
+
+
+def transform_compatibility_tool_alias(
+    alias: CompatibilityToolAlias,
+    arguments: dict[str, Any],
+) -> dict[str, Any]:
+    transformed = alias.transform(arguments)
+    if not isinstance(transformed, dict):
+        raise ValueError(f"Compatibility alias {alias.alias!r} did not return arguments.")
+    return transformed
+
+
+def nearest_tool_name_suggestions(
+    *,
+    requested_tool_name: str,
+    available_tool_names: Collection[str],
+) -> list[str]:
+    requested = _normalize_tool_alias_name(requested_tool_name)
+    scored: list[tuple[float, str]] = []
+    for name in _safe_available_tool_names(available_tool_names):
+        normalized = _normalize_tool_alias_name(name)
+        if not requested or not normalized:
+            continue
+        score = SequenceMatcher(a=requested, b=normalized).ratio()
+        if requested in normalized or normalized in requested:
+            score = max(score, 0.8)
+        if score >= _UNKNOWN_TOOL_SUGGESTION_THRESHOLD:
+            scored.append((score, name))
+    scored.sort(key=lambda item: (-item[0], item[1]))
+    return [name for _score, name in scored[:_UNKNOWN_TOOL_MAX_SUGGESTIONS]]
+
+
+def _safe_available_tool_names(available_tool_names: Collection[str]) -> list[str]:
+    return sorted(
+        {str(name or "").strip() for name in available_tool_names if str(name or "").strip()}
+    )
+
+
+def _normalize_tool_alias_name(name: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "_", str(name or "").strip().casefold()).strip("_")
+
+
+def _unknown_tool_guidance(
+    *,
+    requested: str,
+    available: list[str],
+    suggestions: list[str],
+    alias: CompatibilityToolAlias | None,
+    ambiguous_targets: tuple[str, ...],
+) -> str:
+    if alias is not None:
+        return (
+            f"Tool {requested!r} is not registered, but a reviewed compatibility alias "
+            f"can run {alias.target!r} with the same argument schema."
+        )
+    if ambiguous_targets:
+        valid_targets = [target for target in ambiguous_targets if target in available]
+        target_text = ", ".join(valid_targets) if valid_targets else ", ".join(ambiguous_targets)
+        return (
+            f"Tool {requested!r} is ambiguous. Retry with one exact available tool name "
+            f"and its schema; possible targets include: {target_text}."
+        )
+    if suggestions:
+        return (
+            f"Tool {requested!r} is unavailable. Retry with one available tool schema; "
+            f"nearest valid name: {suggestions[0]}."
+        )
+    preview = ", ".join(available[:8])
+    if len(available) > 8:
+        preview += ", ..."
+    return (
+        f"Tool {requested!r} is unavailable. Retry with one exact available tool name "
+        f"and required arguments. Available tools: {preview or '(none)'}."
+    )
+
+
+def summarize_tool_output_chunk(tool_name: str, chunk: str) -> str:
+    try:
+        parsed = json.loads(chunk)
+    except json.JSONDecodeError:
+        return _truncate_inline(chunk, max_chars=180)
+
+    if not isinstance(parsed, dict):
+        compact = json.dumps(parsed, ensure_ascii=True)
+        return _truncate_inline(compact, max_chars=180)
+
+    summary_text = _truncate_inline(str(parsed.get("summary") or ""), max_chars=160)
+    preview = _truncate_inline(str(parsed.get("preview") or ""), max_chars=96)
+
+    if is_tool_unavailable_result(parsed):
+        tool = _truncate_inline(parsed["tool"], max_chars=64)
+        reason = _truncate_inline(parsed["reason"], max_chars=140)
+        return f"Tool unavailable: {tool}: {reason}"
+
+    if parsed.get("transcript_shaped") is True:
+        if summary_text:
+            return summary_text + (f" Preview: {preview}" if preview else "")
+        if preview:
+            return f"Transcript retained a bounded preview. Preview: {preview}"
+        return "Tool output was summarized for transcript retention."
+
+    if parsed.get("offloaded") is True:
+        artifact_ref = str(
+            parsed.get("artifact_locator") or parsed.get("artifact_path") or ""
+        ).strip()
+        if artifact_ref:
+            if summary_text:
+                return f"{summary_text} Artifact: {artifact_ref}." + (
+                    f" Preview: {preview}" if preview else ""
+                )
+            return f"Output offloaded to {artifact_ref}." + (
+                f" Preview: {preview}" if preview else ""
+            )
+        if summary_text:
+            return summary_text + (f" Preview: {preview}" if preview else "")
+        return "Output offloaded into session artifacts."
+
+    spec = get_builtin_tool_metadata(tool_name)
+    if tool_name != "subagent_run" and "error" in parsed:
+        msg = _truncate_inline(str(parsed.get("error") or ""), max_chars=140)
+        return f"Error: {msg}"
+    if spec is not None and spec.rich.output_summary_formatter is not None:
+        return spec.rich.output_summary_formatter(parsed)
+    keys = ", ".join(sorted(str(k) for k in parsed.keys())[:6])
+    return f"Output keys: {keys or '-'}."