oct_tools.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/tools/oct_tools.py
 
 
"""
oct toolchain integration — lint, health, typecheck, file generator, and git suite.
 
Purpose
-------
Wraps the ``oct`` CLI (Option C Tools) as callable agent tools so the
model can run ``oct lint``, ``oct health``, ``oct typecheck``,
``oct new``, and the full ``oct git`` subcommand suite (status, check,
init, add, commit, branch, restore, ignore, commit-msg, changelog,
hooks) inside a session.
 
The ``oct_git_*`` wrappers are the agent's only path to mutating git
operations — raw ``git add`` / ``git commit`` / ``git push`` are
blocked by ``oc_chat/tools/shell.py``'s whitelist, so every agent-
driven commit goes through the Option C quality gate (lint + format
+ secrets) by construction.
 
Requires: ``pip install -e .[option_c]`` (wires the sibling ``oct``
package). Returns ``{"missing_dependency": ...}`` when ``oct`` is not
installed, which the dependency healer can intercept and offer to
repair.
 
Responsibilities
----------------
- :func:`_oct_exe` / :func:`_run_oct` — locate the binary and invoke
  it with timeout/cwd controls.
- :func:`_note_activity_lines_of_one_stream` — build the per-stream
  status-bar observer, redaction and private-key armor state included.
- :func:`oct_lint`, :func:`oct_health`, :func:`oct_typecheck`,
  :func:`oct_new` — first-class agent tools (F.2a-i through iv).
- :func:`oct_test` — the Plan-187 consumer of the Plan-184 §20 test
  stand-in (``python -m oc_chat.testing``): a subprocess run returning
  a distilled ``oct-test/v0.4`` payload (closes F1). Unlike the oct
  passthrough wrappers it spawns ``sys.executable``, pins cwd to the
  oc_chat SUBPROJECT root (the stand-in's ADR-T-12 walk anchor), and
  returns the distilled report rather than ``CommandResult``.
- :func:`oct_git_*` — 11 wrappers around the ``oct git`` subcommand
  surface (F.2a-v).
- ``TOOLS`` and ``SCHEMAS`` exports for auto-registration.
 
Diagnostics
-----------
Domain: OC_CHAT.TOOLS
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- All wrappers are pass-throughs — the schemas and arg parsing live
  here, but the actual quality logic lives in ``oct``.
- Missing-binary returns are *structured* (``missing_dependency``)
  rather than raising, so the healer can offer to install.
- ``cwd`` is pinned to the effective sandbox root (:func:`oc_chat.tools.filesystem._sandbox_root`) so behaviour
  is independent of the user's shell CWD — except :func:`oct_test`,
  whose cwd is the oc_chat SUBPROJECT root (the stand-in's discovery
  anchor); only its report file uses the sandbox root.
- Every subprocess call honours an explicit ``timeout`` — defaults
  are conservative and tunable per-tool.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.core.tool_results (CommandResult, MissingDependency and ToolError - the wrappers' result shapes)
- oc_chat.tools.filesystem (_sandbox_root for the pinned cwd and report directory, and the oct_new write-approval gate)
- oc_chat.core.tool_activity (lazy; TOOL_ACTIVITY - the status-bar record each redacted output line is noted on)
- oc_chat.tools._proc (lazy; run_cancellable - the cancellable oct and stand-in subprocesses)
- oc_chat.tools._sandbox (lazy; scrubbed_env, LineRedactor and the write-path checks - the child environment, status-bar redaction and the oct_new gate)
- oct (not imported; the oct CLI found on PATH and run as a subprocess by every wrapper except oct_test)
- oc_chat.testing (not imported; run as python -m oc_chat.testing by oct_test)
 
See Also
--------
oc_chat/docs/conventions/CONTRACTS.md §3 Tool registry contract; §4 Tool return-
value conventions (oct_* outputs → §4.1; missing-dep hint → §4.6).
"""
import os
import json
import shutil
import subprocess
import sys
from collections.abc import Callable
from pathlib import Path
from typing import Optional
 
from oc_diagnostics import _dbg
 
from oc_chat.tools.filesystem import _sandbox_root
from oc_chat.core.tool_results import (
    CommandResult,
    MissingDependency,
    ToolError,
)
 
_OctResult = CommandResult | MissingDependency | ToolError
 
 
def _oct_exe() -> Optional[str]:
    """Return the path to the ``oct`` executable, or ``None`` if absent."""
    return shutil.which("oct")
 
 
def _note_activity_lines_of_one_stream() -> "Callable[[str], None]":
    """Return the observer that shows ONE stream's lines on the status bar.
 
    Each line is redacted with the same filter ``run_command`` applies to its
    result, even though these wrappers return ``result.stdout`` unredacted: what
    the terminal shows is a different surface from what the tool returns, and the
    one that is on screen for anyone walking past is the one worth filtering
    (plan 279). Terminal-only — nothing here reaches the result, the events, the
    session or the model.
 
    One :class:`~oc_chat.tools._sandbox.LineRedactor` per call of this factory,
    and the runner calls it once per pipe (plan 287), so the private-key armor
    state the filter carries between lines is this stream's and no other's.
    """
    from ._sandbox import LineRedactor
    from oc_chat.core.tool_activity import TOOL_ACTIVITY
 
    redactor = LineRedactor()
 
    def _note_activity_line(line: str) -> None:
        """Record *line* on the activity record, armor state included."""
        TOOL_ACTIVITY.note_line(redactor.redact_line(line))
 
    return _note_activity_line
 
 
def _run_oct(args: list[str], cwd: str, timeout: int = 60) -> _OctResult:
    """Execute ``oct <args>`` and return ``{stdout, stderr, returncode}``."""
    func = "_run_oct"
    _dbg("OC_CHAT.TOOLS", func, f"args={args} cwd={cwd} timeout={timeout}", 3)
    exe = _oct_exe()
    if exe is None:
        return {
            "missing_dependency": "oct",
            "install_hint": "pip install -e .[option_c]",
        }
    try:
        # M8.0 WU-3c: minimal scrubbed env (drop poisonable GIT_*/PIP_*/proxy/
        # cert/... families, F25/F72/F78/F79); TMPDIR -> OC Chat's logs dir.
        from ._sandbox import scrubbed_env
        env = scrubbed_env({"TMPDIR": str(Path(cwd) / "logs")})
 
        from ._proc import run_cancellable
 
        # Cancellable: a Ctrl+C terminates the oct child process.
        result = run_cancellable(
            [exe, *args],
            timeout=timeout,
            cwd=cwd,
            env=env,
            on_line_factory=_note_activity_lines_of_one_stream,
        )
        return {
            "stdout": result.stdout,
            "stderr": result.stderr,
            "returncode": result.returncode,
        }
    except subprocess.TimeoutExpired:
        return {"error": f"oct command timed out after {timeout}s", "args": args}
    except Exception as exc:
        return {"error": str(exc), "args": args}
 
 
def _reject_operand(value: str, field: str) -> "ToolError | None":
    """Refuse a model-supplied oct/git operand that could smuggle an option into
    the argv (M8.0 WU-3 oct parity / argv-injection guard).
 
    The ``oct_*`` wrappers forward model-controlled path / pattern / identifier
    operands as positional args or option *values* -- never as options. A leading
    ``-`` would be reparsed by the oct/git argument parser as a flag (e.g.
    ``paths=["--all"]`` -> ``git add --all``; ``path="--help"``). Reject a
    non-string, empty, control-char-bearing, or leading-dash operand. Returns a
    ToolError dict to surface, or ``None`` if the operand is safe.
    """
    if not isinstance(value, str) or value == "":
        return {"error": f"oct {field}: empty or non-string operand"}
    if any(c in value for c in ("\x00", "\n", "\r")):
        return {"error": f"oct {field}: operand contains a control character"}
    if value.startswith("-"):
        return {"error": f"oct {field}: operand may not begin with '-' (option-smuggling guard): {value!r}"}
    return None
 
 
def _reject_operands(values: "list[str]", field: str) -> "ToolError | None":
    """Apply :func:`_reject_operand` to each value in a list operand."""
    for v in values:
        err = _reject_operand(v, field)
        if err:
            return err
    return None
 
 
def oct_lint(
    path: str = ".",
    fix_headers: bool = False,
    dry_run: bool = False,
    json_output: bool = False,
    changed_only: bool = False,
    timeout: int = 120,
) -> _OctResult:
    """Run ``oct lint`` on the project or a specific path.
 
    Parameters
    ----------
    path : str
        File or directory to lint (default: entire project).
    fix_headers : bool
        Auto-fix shebang, encoding, and path comment headers.
    dry_run : bool
        Preview fixes without writing (only meaningful with ``fix_headers``).
    json_output : bool
        Emit machine-readable JSON instead of human text.
    changed_only : bool
        Lint only git-modified Python files.
    timeout : int
        Seconds before the subprocess is killed (default 120).
    """
    root = str(_sandbox_root())
    args = ["lint"]
    if fix_headers:
        args.append("--fix-headers")
    if dry_run:
        args.append("--dry-run")
    if json_output:
        args.append("--json")
    if changed_only:
        args.append("--changed")
    if path and path != ".":
        err = _reject_operand(path, "lint path")
        if err:
            return err
        args.append(path)
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_health(
    json_output: bool = False,
    verbose: bool = False,
    timeout: int = 300,
) -> _OctResult:
    """Display the Option C project compliance dashboard.
 
    Parameters
    ----------
    json_output : bool
        Machine-readable JSON output.
    verbose : bool
        Detailed per-file breakdown.
    timeout : int
        Seconds before the subprocess is killed (default 300).
    """
    root = str(_sandbox_root())
    args = ["health"]
    if json_output:
        args.append("--json")
    if verbose:
        args.append("--verbose")
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_typecheck(
    json_output: bool = False,
    timeout: int = 120,
) -> _OctResult:
    """Run type checking on the project via ``oct typecheck``.
 
    Parameters
    ----------
    json_output : bool
        Machine-readable JSON summary.
    timeout : int
        Seconds before the subprocess is killed (default 120).
    """
    root = str(_sandbox_root())
    args = ["typecheck"]
    if json_output:
        args.append("--json")
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_new(
    path: str,
    force: bool = False,
    test: bool = False,
    dry_run: bool = False,
    verbose: bool = False,
    timeout: int = 30,
) -> _OctResult:
    """Create a new Option C-compliant Python file via ``oct new``.
 
    Generates a file with the mandatory 3-line header block (shebang,
    encoding, file identity), ``from oc_diagnostics import _dbg``, and
    a complete module docstring skeleton with Purpose, Responsibilities,
    Diagnostics, and Contracts sections.
 
    Parameters
    ----------
    path : str
        Target file path (required, must end in ``.py``).
    force : bool
        Overwrite the file if it already exists.
    test : bool
        Also generate a companion test file in ``tests/``.
    dry_run : bool
        Preview what would be created without writing anything.
    verbose : bool
        Print generated file content to stdout.
    timeout : int
        Seconds before the subprocess is killed (default 30).
    """
    root = str(_sandbox_root())
    err = _reject_operand(path, "new path")
    if err:
        return err
    # M8.0 WU-5 / F70: oct_new is a path sink that creates an importable .py — gate it
    # like write_file. Clamp to the sandbox, hard-deny the protected-write class, and
    # route the config-as-code / importable tier through the human-confirm relay
    # (re-dispatched under filesystem.human_confirmed_write). dry-run writes nothing.
    if not dry_run:
        from oc_chat.tools._sandbox import (
            SandboxViolation, is_human_confirm_write_path, is_importable_write_path,
            is_protected_write_path, require_inside_sandbox,
        )
        from oc_chat.tools.filesystem import _human_approved_write, _make_protected_write_block
        try:
            target = require_inside_sandbox(path, root=Path(root))
        except SandboxViolation as exc:
            return {"error": str(exc)}
        if is_protected_write_path(target):
            return {"error": "Creating this file is not permitted: it is in the protected-write class."}
        if _human_approved_write.get() != str(target):
            if is_importable_write_path(target):
                return _make_protected_write_block(str(target), "importable-tree write (oct new)")
            if is_human_confirm_write_path(target):
                return _make_protected_write_block(str(target), "config-as-code (oct new)")
    args = ["new", path]
    if force:
        args.append("--force")
    if test:
        args.append("--test")
    if dry_run:
        args.append("--dry-run")
    if verbose:
        args.append("--verbose")
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
# ── oct_test: the §20 stand-in consumer (Plan 187 / M4.4, closes F1) ─────────
 
#: The oc_chat SUBPROJECT root, resolved from this file (tools → package →
#: subproject). The stand-in's ADR-T-12 upward walk must start here — the
#: session sandbox root is operator-movable (/cwd, env override) and is NOT
#: guaranteed to be the oc_chat package root, so the tool always tests its
#: own tree (decision 2). The sandbox root still hosts the report file.
_OC_CHAT_SUBPROJECT_ROOT = Path(__file__).resolve().parents[2]
 
#: Tool-level wall-clock cap for ``oct_test`` (the strict live run measures
#: ~8 min; default 900 s, silently clamped to [1, 1800] mirroring the
#: family's clamp discipline — local cap, since resource_caps.MAX_TIMEOUT_S
#: is the run_command shell cap).
_OCT_TEST_TIMEOUT_CAP = 1800
 
#: Distillation cap for the non-passed slice (decision 4 — no silent
#: truncation: the cap is always accompanied by ``non_passed_total`` and
#: ``non_passed_truncated``).
_OCT_TEST_NON_PASSED_CAP = 50
 
 
def oct_test(
    profile: str = "strict",
    seed: "int | None" = None,
    workers: "int | str | None" = None,
    marker: "str | None" = None,
    nodeids: "list[str] | None" = None,
    dry_run: bool = False,
    per_test_timeout: "int | None" = None,
    timeout: int = 900,
) -> dict:
    """Run the oc_chat test suite via the Plan-184 §20 stand-in
    (``python -m oc_chat.testing``) and return a distilled
    ``oct-test/v0.4`` payload.
 
    The FULL report is written to ``<sandbox_root>/logs/oct_test-<run_id>.json``
    (``report_path`` in the payload); the payload itself carries the report's
    top-level fields MINUS ``tests[]``, PLUS ``non_passed_tests[]`` (every
    entry with ``outcome != "passed"``) capped at 50 with explicit
    ``non_passed_total`` / ``non_passed_truncated`` fields. Stand-in exit
    codes (0 passed / 1 failed / 2 contract violation / 4 configuration
    error) surface as the payload's ``exit_code`` — structured data, never a
    raised error (the family's CommandResult philosophy).
 
    Parameters
    ----------
    profile : str
        ``strict`` (default) | ``smoke`` | ``full`` — validated by the
        stand-in (a bad value returns an exit-4 payload).
    seed : int | None
        Pin pytest-randomly ordering (``--seed N``); unseeded runs are
        order-stable with seed 0 reported.
    workers : int | str | None
        Forwarded verbatim (``auto`` or a count); the serial stand-in
        reports ``workers.actual: 1`` truthfully.
    marker : str | None
        Extra marker expression, AND-composed with the profile expression.
    nodeids : list[str] | None
        Individual pytest nodeids (repeatable ``--nodeid``).
    dry_run : bool
        Collection + static checks only; no test executes.
    per_test_timeout : int | None
        Per-test wall-clock bound in seconds (stand-in watchdog).
    timeout : int
        Tool-level wall clock (default 900 s; clamped to [1, 1800]).
    """
    func = "oct_test"
    _dbg("OC_CHAT.TOOLS", func,
         f"profile={profile} dry_run={dry_run} nodeids={len(nodeids or [])}", 3)
 
    for value, field in ((profile, "oct_test profile"),
                         (marker, "oct_test marker")):
        if value is not None:
            err = _reject_operand(value, field)
            if err:
                return err
    if isinstance(workers, str) and workers != "auto":
        err = _reject_operand(workers, "oct_test workers")
        if err:
            return err
    if nodeids:
        err = _reject_operands(nodeids, "oct_test nodeid")
        if err:
            return err
 
    clamped = max(1, min(int(timeout), _OCT_TEST_TIMEOUT_CAP))
 
    sandbox_logs = Path(_sandbox_root()) / "logs"
    try:
        sandbox_logs.mkdir(parents=True, exist_ok=True)
    except OSError as exc:
        return {"error": f"oct_test: cannot create the report directory "
                         f"{sandbox_logs}: {exc}"}
 
    args = [sys.executable, "-m", "oc_chat.testing",
            "--package", "oc_chat", "--json",
            "--profile", profile]
    if seed is not None:
        args += ["--seed", str(seed)]
    if workers is not None:
        args += ["--workers", str(workers)]
    if marker is not None:
        args += ["--marker", marker]
    for nodeid in nodeids or []:
        args += ["--nodeid", nodeid]
    if per_test_timeout is not None:
        args += ["--per-test-timeout", str(per_test_timeout)]
    if dry_run:
        args.append("--dry-run")
 
    try:
        from ._sandbox import scrubbed_env
        env = scrubbed_env({"TMPDIR": str(sandbox_logs)})
 
        from ._proc import run_cancellable
 
        result = run_cancellable(
            args,
            timeout=clamped,
            cwd=str(_OC_CHAT_SUBPROJECT_ROOT),
            env=env,
            on_line_factory=_note_activity_lines_of_one_stream,
        )
    except subprocess.TimeoutExpired:
        return {"error": f"oct_test timed out after {clamped}s",
                "args": args}
    except Exception as exc:
        return {"error": str(exc), "args": args}
 
    cancelled = (
        result.returncode == -2
        or (result.stderr or "").rstrip().endswith("[cancelled by user]")
    )
    if cancelled:
        # Cooperative cancel: pass the family marker through untouched.
        # The marker is the authoritative signal — _proc appends it and
        # reports the terminated child's real returncode (1 under Windows
        # TerminateProcess; -2 only when no code was collected).
        return {"stdout": result.stdout, "stderr": result.stderr,
                "returncode": result.returncode}
 
    stripped = (result.stdout or "").strip()
    if not stripped.startswith("{"):
        tail = (result.stderr or "")[-2000:]
        return {"error": (f"oct_test: stand-in produced no JSON report "
                          f"(exit {result.returncode}): {tail}")}
    try:
        report = json.loads(stripped)
    except (json.JSONDecodeError, ValueError) as exc:
        tail = (result.stderr or "")[-2000:]
        return {"error": (f"oct_test: stand-in stdout is not valid JSON "
                          f"({exc}); stderr tail: {tail}")}
 
    run_id = report.get("run_id") or "unidentified"
    report_path = sandbox_logs / f"oct_test-{run_id}.json"
    try:
        report_path.write_text(json.dumps(report, indent=2),
                               encoding="utf-8")
    except OSError as exc:
        return {"error": f"oct_test: cannot write the full report to "
                         f"{report_path}: {exc}"}
 
    all_tests = report.get("tests") or []
    non_passed = [t for t in all_tests if t.get("outcome") != "passed"]
    payload = {k: v for k, v in report.items() if k != "tests"}
    payload["non_passed_tests"] = non_passed[:_OCT_TEST_NON_PASSED_CAP]
    payload["non_passed_total"] = len(non_passed)
    payload["non_passed_truncated"] = (
        len(non_passed) > _OCT_TEST_NON_PASSED_CAP
    )
    payload["report_path"] = str(report_path)
    _dbg("OC_CHAT.TOOLS", func,
         f"status={payload.get('status')} exit={payload.get('exit_code')} "
         f"non_passed={len(non_passed)}", 3)
    return payload
 
 
# ── oct git subcommand wrappers ──────────────────────────────────────────────
#
# All ``oct_git_*`` wrappers take the workspace root as cwd and delegate to
# ``_run_oct``. They are the agent's only path to mutating git operations.
 
 
def oct_git_status(
    json_output: bool = False,
    no_check: bool = False,
    scope: Optional[str] = None,
    timeout: int = 30,
) -> _OctResult:
    """Show git status with Option C compliance annotations.
 
    Preferred over raw ``git status`` because it annotates each file with
    its compliance state (lint/format/secrets) on top of the standard
    staged/modified/untracked breakdown.
 
    Parameters
    ----------
    json_output : bool
        Machine-readable JSON output.
    no_check : bool
        Skip compliance annotations (plain status).
    scope : str | None
        File scope: ``"project"`` (default), ``"repo"``, or ``"auto"``.
    timeout : int
        Seconds before the subprocess is killed (default 30).
    """
    root = str(_sandbox_root())
    args = ["git", "status"]
    if json_output:
        args.append("--json")
    if no_check:
        args.append("--no-check")
    if scope:
        err = _reject_operand(scope, "git status --scope")
        if err:
            return err
        args.extend(["--scope", scope])
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_git_check(
    staged_only: bool = False,
    all_files: bool = False,
    include_tests: bool = False,
    fix: bool = False,
    profile: Optional[str] = None,
    json_output: bool = False,
    sandbox: bool = False,
    timeout: int = 120,
) -> _OctResult:
    """Run the unified Option C quality gate (lint + format + secrets).
 
    Preferred over running ``oct lint`` and ``oct format`` separately
    because it bundles secrets scanning and applies the same gate that
    ``oct git commit`` enforces.
 
    Parameters
    ----------
    staged_only : bool
        Check only staged files (default scope).
    all_files : bool
        Check every Python file in the project.
    include_tests : bool
        Also run pytest (exit 4 on failure).
    fix : bool
        Attempt auto-fix of lint/format violations, then re-check.
    profile : str | None
        Override lint profile: ``"proto"``, ``"compact"``, or ``"strict"``.
    json_output : bool
        Machine-readable JSON output.
    sandbox : bool
        Run pytest under MCP sandbox (strips PYTHONPATH and secret env vars).
    timeout : int
        Seconds before the subprocess is killed (default 120).
    """
    root = str(_sandbox_root())
    args = ["git", "check"]
    if staged_only:
        args.append("--staged-only")
    if all_files:
        args.append("--all")
    if include_tests:
        args.append("--include-tests")
    if fix:
        args.append("--fix")
    if profile:
        err = _reject_operand(profile, "git check --profile")
        if err:
            return err
        args.extend(["--profile", profile])
    if json_output:
        args.append("--json")
    if sandbox:
        args.append("--sandbox")
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_git_init(
    dry_run: bool = False,
    github: bool = False,
    no_hooks: bool = False,
    timeout: int = 60,
) -> _OctResult:
    """Initialize / enhance a git repo with Option C conventions.
 
    Preferred over manually editing ``.gitignore`` / ``.gitattributes`` /
    ``.pre-commit-config.yaml`` because it applies the canonical Option C
    templates and merges idempotently.
 
    Parameters
    ----------
    dry_run : bool
        Show what would be created/modified without writing.
    github : bool
        Also generate ``.github/workflows/option-c.yml``.
    no_hooks : bool
        Skip ``.pre-commit-config.yaml`` creation.
    timeout : int
        Seconds before the subprocess is killed (default 60).
    """
    root = str(_sandbox_root())
    args = ["git", "init"]
    if dry_run:
        args.append("--dry-run")
    if github:
        args.append("--github")
    if no_hooks:
        args.append("--no-hooks")
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_git_add(
    paths: Optional[list[str]] = None,
    patch: bool = False,
    update: bool = False,
    all_files: bool = False,
    dry_run: bool = False,
    json_output: bool = False,
    timeout: int = 60,
) -> _OctResult:
    """Stage files for commit, with optional post-stage quality-gate summary.
 
    Preferred over raw ``git add`` because it scopes to the project (vs. the
    whole repo) and runs a quality-gate summary on the staged set.
 
    Parameters
    ----------
    paths : list[str] | None
        Files / directories to stage.
    patch : bool
        Interactive hunk-level staging (passthrough to ``git add -p``).
    update : bool
        Stage all already-tracked modified files.
    all_files : bool
        Stage all changes (tracked + untracked) within project scope.
    dry_run : bool
        Show what would be staged without staging.
    json_output : bool
        Machine-readable JSON output.
    timeout : int
        Seconds before the subprocess is killed (default 60).
    """
    root = str(_sandbox_root())
    args = ["git", "add"]
    if patch:
        args.append("--patch")
    if update:
        args.append("--update")
    if all_files:
        args.append("--all")
    if dry_run:
        args.append("--dry-run")
    if json_output:
        args.append("--json")
    if paths:
        err = _reject_operands(paths, "git add path")
        if err:
            return err
        args.extend(paths)
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_git_commit(
    message: list[str],
    force: bool = False,
    no_verify: bool = False,
    profile: Optional[str] = None,
    json_output: bool = False,
    ignore_unstaged_mutation: bool = False,
    timeout: int = 180,
) -> _OctResult:
    """Commit staged changes with the Option C quality gate enforced.
 
    Preferred over raw ``git commit`` because the quality gate (lint +
    format + secrets) runs before the commit; secrets detection is
    non-bypassable even with ``force=True``.
 
    Parameters
    ----------
    message : list[str]
        One or more commit message paragraphs (each becomes a ``-m TEXT``).
        Required. Must follow Conventional Commits format.
    force : bool
        Skip lint/format checks (secrets still enforced).
    no_verify : bool
        Forward ``--no-verify`` to ``git commit`` (skips git hooks; does
        NOT skip oct's quality checks).
    profile : str | None
        Override lint profile: ``"proto"``, ``"compact"``, or ``"strict"``.
    json_output : bool
        Machine-readable JSON output.
    ignore_unstaged_mutation : bool
        Downgrade unstaged-tracked-file mutation detection from block to warn.
    timeout : int
        Seconds before the subprocess is killed (default 180).
    """
    root = str(_sandbox_root())
    args = ["git", "commit"]
    for m in message:
        args.extend(["-m", m])
    if force:
        args.append("--force")
    if no_verify:
        args.append("--no-verify")
    if profile:
        err = _reject_operand(profile, "git commit --profile")
        if err:
            return err
        args.extend(["--profile", profile])
    if json_output:
        args.append("--json")
    if ignore_unstaged_mutation:
        args.append("--ignore-unstaged-mutation")
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_git_branch(
    create: Optional[str] = None,
    switch: Optional[str] = None,
    json_output: bool = False,
    timeout: int = 30,
) -> _OctResult:
    """Create or switch branches with Option C naming enforcement.
 
    Preferred over raw ``git branch`` / ``git checkout -b`` because it
    enforces the project's branch-naming convention (``feat/``, ``fix/``,
    ``chore/`` prefixes).
 
    Pass exactly one of ``create`` or ``switch``.
 
    Parameters
    ----------
    create : str | None
        Create a new branch from HEAD with this name.
    switch : str | None
        Switch to an existing branch with this name.
    json_output : bool
        Machine-readable JSON output.
    timeout : int
        Seconds before the subprocess is killed (default 30).
    """
    root = str(_sandbox_root())
    args = ["git", "branch"]
    if create:
        err = _reject_operand(create, "git branch --create")
        if err:
            return err
        args.extend(["--create", create])
    if switch:
        err = _reject_operand(switch, "git branch --switch")
        if err:
            return err
        args.extend(["--switch", switch])
    if json_output:
        args.append("--json")
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_git_restore(
    paths: Optional[list[str]] = None,
    staged: bool = False,
    all_files: bool = False,
    yes: bool = False,
    json_output: bool = False,
    timeout: int = 30,
) -> _OctResult:
    """Restore working-tree edits or unstage paths.
 
    Preferred over raw ``git restore`` / ``git checkout --`` because it
    scopes to the project and requires explicit confirmation when
    discarding all staged changes.
 
    Parameters
    ----------
    paths : list[str] | None
        Files / directories to restore.
    staged : bool
        Unstage from index (leaves working tree intact). Without this,
        discards working-tree edits.
    all_files : bool
        Restore all in-scope paths (requires ``yes=True`` if also ``staged``).
    yes : bool
        Skip the confirmation prompt for ``staged=True, all_files=True``.
    json_output : bool
        Machine-readable JSON output.
    timeout : int
        Seconds before the subprocess is killed (default 30).
    """
    root = str(_sandbox_root())
    args = ["git", "restore"]
    if staged:
        args.append("--staged")
    if all_files:
        args.append("--all")
    if yes:
        args.append("--yes")
    if json_output:
        args.append("--json")
    if paths:
        err = _reject_operands(paths, "git restore path")
        if err:
            return err
        args.extend(paths)
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_git_ignore(
    patterns: Optional[list[str]] = None,
    remove: Optional[str] = None,
    list_patterns: bool = False,
    scope: Optional[str] = None,
    json_output: bool = False,
    timeout: int = 30,
) -> _OctResult:
    """Manage ``.gitignore`` patterns within the OCT-managed block.
 
    Preferred over manually editing ``.gitignore`` because OCT manages a
    delimited block that survives ``oct git init`` re-runs.
 
    Pass exactly one of ``patterns``, ``remove``, or ``list_patterns``.
 
    Parameters
    ----------
    patterns : list[str] | None
        Patterns to add to ``.gitignore``.
    remove : str | None
        Pattern to remove from the OCT-managed block.
    list_patterns : bool
        List currently active ignore patterns.
    scope : str | None
        Which ``.gitignore`` to target: ``"workspace"``, ``"project"``,
        or ``"nearest"`` (default).
    json_output : bool
        Machine-readable JSON output.
    timeout : int
        Seconds before the subprocess is killed (default 30).
    """
    root = str(_sandbox_root())
    args = ["git", "ignore"]
    if remove:
        err = _reject_operand(remove, "git ignore --remove")
        if err:
            return err
        args.extend(["--remove", remove])
    if list_patterns:
        args.append("--list")
    if scope:
        err = _reject_operand(scope, "git ignore --scope")
        if err:
            return err
        args.extend(["--scope", scope])
    if json_output:
        args.append("--json")
    if patterns:
        err = _reject_operands(patterns, "git ignore pattern")
        if err:
            return err
        args.extend(patterns)
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_git_commit_msg(
    message_file: str,
    json_output: bool = False,
    timeout: int = 30,
) -> _OctResult:
    """Validate a Conventional Commit message file.
 
    Intended as the entry for the ``commit-msg`` pre-commit-framework
    stage. Preferred over hand-rolled regex validation because it matches
    exactly what ``oct git commit`` enforces.
 
    Parameters
    ----------
    message_file : str
        Path to the commit-message file (e.g. ``.git/COMMIT_EDITMSG``).
    json_output : bool
        Machine-readable JSON output.
    timeout : int
        Seconds before the subprocess is killed (default 30).
    """
    root = str(_sandbox_root())
    err = _reject_operand(message_file, "git commit-msg file")
    if err:
        return err
    args = ["git", "commit-msg", message_file]
    if json_output:
        args.append("--json")
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_git_changelog(
    release: Optional[str] = None,
    since: Optional[str] = None,
    dry_run: bool = False,
    json_output: bool = False,
    timeout: int = 60,
) -> _OctResult:
    """Generate a changelog from Conventional Commits history.
 
    Preferred over hand-writing ``CHANGELOG.md`` entries because output is
    aligned with Option C's CHANGELOG-format spec.
 
    Parameters
    ----------
    release : str | None
        Release version tag (e.g. ``"v0.13.0"``). When set (and not
        ``dry_run``), writes/appends to ``CHANGELOG.md``.
    since : str | None
        Git ref to start from (default: last tag).
    dry_run : bool
        Print to stdout without writing.
    json_output : bool
        Machine-readable JSON output.
    timeout : int
        Seconds before the subprocess is killed (default 60).
    """
    root = str(_sandbox_root())
    args = ["git", "changelog"]
    if release:
        err = _reject_operand(release, "git changelog --release")
        if err:
            return err
        args.extend(["--release", release])
    if since:
        err = _reject_operand(since, "git changelog --since")
        if err:
            return err
        args.extend(["--since", since])
    if dry_run:
        args.append("--dry-run")
    if json_output:
        args.append("--json")
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
def oct_git_hooks(
    action: str,
    force: bool = False,
    timeout: int = 30,
) -> _OctResult:
    """Manage Option C pre-commit hooks (install / status / remove).
 
    Preferred over hand-editing ``.pre-commit-config.yaml`` because it
    installs the canonical Option C hook set and preserves any non-OCT
    hooks already present.
 
    Parameters
    ----------
    action : str
        One of ``"install"``, ``"status"``, or ``"remove"``.
    force : bool
        For ``action="install"``: overwrite existing configuration.
    timeout : int
        Seconds before the subprocess is killed (default 30).
    """
    root = str(_sandbox_root())
    err = _reject_operand(action, "git hooks action")
    if err:
        return err
    args = ["git", "hooks", action]
    if action == "install" and force:
        args.append("--force")
    return _run_oct(args, cwd=root, timeout=timeout)
 
 
TOOLS = {
    "oct_lint":           oct_lint,
    "oct_health":         oct_health,
    "oct_typecheck":      oct_typecheck,
    "oct_new":            oct_new,
    "oct_test":           oct_test,
    "oct_git_status":     oct_git_status,
    "oct_git_check":      oct_git_check,
    "oct_git_init":       oct_git_init,
    "oct_git_add":        oct_git_add,
    "oct_git_commit":     oct_git_commit,
    "oct_git_branch":     oct_git_branch,
    "oct_git_restore":    oct_git_restore,
    "oct_git_ignore":     oct_git_ignore,
    "oct_git_commit_msg": oct_git_commit_msg,
    "oct_git_changelog":  oct_git_changelog,
    "oct_git_hooks":      oct_git_hooks,
}
 
SCHEMAS = [
    {
        "type": "function",
        "function": {
            "name": "oct_lint",
            "description": (
                "Run the Option C linter on the project or a specific file/directory. "
                "Returns violations with rule IDs and line numbers. "
                "Use fix_headers=true to auto-repair shebang, encoding, and path comment "
                "headers (add dry_run=true to preview without writing)."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "File or directory to lint (default: entire project '.')",
                    },
                    "fix_headers": {
                        "type": "boolean",
                        "description": "Auto-fix shebang, encoding, and path comment headers",
                    },
                    "dry_run": {
                        "type": "boolean",
                        "description": "Preview fixes without writing (combine with fix_headers)",
                    },
                    "json_output": {
                        "type": "boolean",
                        "description": "Emit machine-readable JSON instead of human text",
                    },
                    "changed_only": {
                        "type": "boolean",
                        "description": "Lint only git-modified Python files",
                    },
                    "timeout": {
                        "type": "integer",
                        "description": "Subprocess timeout in seconds (default 120)",
                    },
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_health",
            "description": (
                "Display the Option C project compliance dashboard — lint, tests, type "
                "checking, and coverage rolled into a single summary. Use json_output=true "
                "for machine-readable data."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "json_output": {
                        "type": "boolean",
                        "description": "Machine-readable JSON output",
                    },
                    "verbose": {
                        "type": "boolean",
                        "description": "Detailed per-file breakdown",
                    },
                    "timeout": {
                        "type": "integer",
                        "description": "Subprocess timeout in seconds (default 300)",
                    },
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_typecheck",
            "description": (
                "Run type checking on the project via oct typecheck (delegates to pyright or mypy). "
                "Use json_output=true for machine-readable summary."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "json_output": {
                        "type": "boolean",
                        "description": "Machine-readable JSON summary",
                    },
                    "timeout": {
                        "type": "integer",
                        "description": "Subprocess timeout in seconds (default 120)",
                    },
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_new",
            "description": (
                "Create a new Option C-compliant Python file via oct new. "
                "Generates the mandatory 3-line header, from oc_diagnostics import _dbg, "
                "and a complete docstring skeleton (Purpose, Responsibilities, Diagnostics, "
                "Contracts). Preferred over write_file for creating new .py files."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "description": "Target file path (required, must end in .py)",
                    },
                    "force": {
                        "type": "boolean",
                        "description": "Overwrite the file if it already exists",
                    },
                    "test": {
                        "type": "boolean",
                        "description": "Also generate a companion test file in tests/",
                    },
                    "dry_run": {
                        "type": "boolean",
                        "description": "Preview what would be created without writing anything",
                    },
                    "verbose": {
                        "type": "boolean",
                        "description": "Show generated file content",
                    },
                    "timeout": {
                        "type": "integer",
                        "description": "Subprocess timeout in seconds (default 30)",
                    },
                },
                "required": ["path"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_test",
            "description": (
                "Run the oc_chat test suite through the Option C test stand-in "
                "and return a distilled oct-test/v0.4 payload: summary counts, "
                "contract violations, errors, and the non-passed tests (capped "
                "at 50 with explicit truncation fields). The full report with "
                "every test entry is written to logs/ and returned as "
                "report_path. Preferred over run_command pytest: structured "
                "result, no Tier-2 confirmation. A full strict run takes "
                "several minutes; use dry_run=true for a fast collection-only "
                "check, or nodeids/marker to narrow the selection."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "profile": {
                        "type": "string",
                        "enum": ["strict", "smoke", "full"],
                        "description": "Test profile (default: strict)",
                    },
                    "seed": {
                        "type": "integer",
                        "description": "Pin randomized test ordering (pytest-randomly seed)",
                    },
                    "workers": {
                        "type": ["integer", "string"],
                        "description": "Worker count or 'auto' (the stand-in runs serially and reports actual: 1)",
                    },
                    "marker": {
                        "type": "string",
                        "description": "Extra pytest marker expression, AND-composed with the profile",
                    },
                    "nodeids": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Individual pytest nodeids to run",
                    },
                    "dry_run": {
                        "type": "boolean",
                        "description": "Collection and static checks only; no test executes",
                    },
                    "per_test_timeout": {
                        "type": "integer",
                        "description": "Per-test wall-clock bound in seconds",
                    },
                    "timeout": {
                        "type": "integer",
                        "description": "Tool-level wall clock in seconds (default 900, max 1800)",
                    },
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_status",
            "description": (
                "Show git status with Option C compliance annotations. "
                "Preferred over raw `git status` because it annotates files with "
                "lint/format/secrets state on top of the standard "
                "staged/modified/untracked breakdown."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "json_output": {"type": "boolean", "description": "Machine-readable JSON output"},
                    "no_check": {"type": "boolean", "description": "Skip compliance annotations (plain status)"},
                    "scope": {
                        "type": "string",
                        "enum": ["project", "repo", "auto"],
                        "description": "File scope (default: project)",
                    },
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 30)"},
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_check",
            "description": (
                "Run the unified Option C quality gate (lint + format + secrets). "
                "Preferred over running oct_lint and oct_format separately because it "
                "applies the same gate that oct_git_commit enforces. Use fix=true to "
                "auto-fix lint/format violations."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "staged_only": {"type": "boolean", "description": "Check only staged files"},
                    "all_files": {"type": "boolean", "description": "Check every Python file in the project"},
                    "include_tests": {"type": "boolean", "description": "Also run pytest (exit 4 on failure)"},
                    "fix": {"type": "boolean", "description": "Attempt auto-fix of lint/format violations, then re-check"},
                    "profile": {
                        "type": "string",
                        "enum": ["proto", "compact", "strict"],
                        "description": "Override lint profile",
                    },
                    "json_output": {"type": "boolean", "description": "Machine-readable JSON output"},
                    "sandbox": {"type": "boolean", "description": "Run pytest under MCP sandbox"},
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 120)"},
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_init",
            "description": (
                "Initialize / enhance a git repo with Option C conventions "
                "(.gitignore, .gitattributes, .pre-commit-config.yaml, optional GitHub "
                "Actions workflow). Preferred over manually editing those files because "
                "it applies the canonical Option C templates and merges idempotently."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "dry_run": {"type": "boolean", "description": "Show what would be created/modified without writing"},
                    "github": {"type": "boolean", "description": "Also generate .github/workflows/option-c.yml"},
                    "no_hooks": {"type": "boolean", "description": "Skip .pre-commit-config.yaml creation"},
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 60)"},
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_add",
            "description": (
                "Stage files for commit. Preferred over raw `git add` because it scopes "
                "to the project (vs. the whole repo) and runs a quality-gate summary on "
                "the staged set."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "paths": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Files / directories to stage",
                    },
                    "patch": {"type": "boolean", "description": "Interactive hunk-level staging (-p)"},
                    "update": {"type": "boolean", "description": "Stage all already-tracked modified files (-u)"},
                    "all_files": {"type": "boolean", "description": "Stage all changes within project scope (-A)"},
                    "dry_run": {"type": "boolean", "description": "Show what would be staged without staging"},
                    "json_output": {"type": "boolean", "description": "Machine-readable JSON output"},
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 60)"},
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_commit",
            "description": (
                "Commit staged changes with the Option C quality gate enforced. "
                "Preferred over raw `git commit` because lint + format + secrets run "
                "before the commit; secrets detection is non-bypassable even with "
                "force=true. Message must follow Conventional Commits format."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "message": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": (
                            "One or more commit message paragraphs (each becomes a "
                            "separate -m TEXT). First paragraph is the title; subsequent "
                            "paragraphs become the body."
                        ),
                    },
                    "force": {"type": "boolean", "description": "Skip lint/format checks (secrets still enforced)"},
                    "no_verify": {"type": "boolean", "description": "Forward --no-verify to git commit (skips git hooks only)"},
                    "profile": {
                        "type": "string",
                        "enum": ["proto", "compact", "strict"],
                        "description": "Override lint profile",
                    },
                    "json_output": {"type": "boolean", "description": "Machine-readable JSON output"},
                    "ignore_unstaged_mutation": {
                        "type": "boolean",
                        "description": "Downgrade unstaged-tracked-file mutation detection from block to warn",
                    },
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 180)"},
                },
                "required": ["message"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_branch",
            "description": (
                "Create or switch branches with Option C naming enforcement. Preferred "
                "over raw `git branch` / `git checkout -b` because it enforces the "
                "branch-naming convention (feat/, fix/, chore/ prefixes). Pass exactly "
                "one of create or switch."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "create": {"type": "string", "description": "Create a new branch from HEAD with this name"},
                    "switch": {"type": "string", "description": "Switch to an existing branch with this name"},
                    "json_output": {"type": "boolean", "description": "Machine-readable JSON output"},
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 30)"},
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_restore",
            "description": (
                "Restore working-tree edits or unstage paths. Preferred over raw "
                "`git restore` / `git checkout --` because it scopes to the project "
                "and requires explicit confirmation when discarding all staged changes."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "paths": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Files / directories to restore",
                    },
                    "staged": {
                        "type": "boolean",
                        "description": "Unstage from index (leaves working tree intact); without this, discards working-tree edits",
                    },
                    "all_files": {"type": "boolean", "description": "Restore all in-scope paths"},
                    "yes": {"type": "boolean", "description": "Skip confirmation prompt for staged + all_files"},
                    "json_output": {"type": "boolean", "description": "Machine-readable JSON output"},
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 30)"},
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_ignore",
            "description": (
                "Manage .gitignore patterns within the OCT-managed block. Preferred over "
                "manually editing .gitignore because OCT manages a delimited block that "
                "survives oct_git_init re-runs. Pass exactly one of patterns, remove, or "
                "list_patterns."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "patterns": {
                        "type": "array",
                        "items": {"type": "string"},
                        "description": "Patterns to add to .gitignore",
                    },
                    "remove": {"type": "string", "description": "Pattern to remove from the OCT-managed block"},
                    "list_patterns": {"type": "boolean", "description": "List currently active ignore patterns"},
                    "scope": {
                        "type": "string",
                        "enum": ["workspace", "project", "nearest"],
                        "description": "Which .gitignore to target (default: nearest)",
                    },
                    "json_output": {"type": "boolean", "description": "Machine-readable JSON output"},
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 30)"},
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_commit_msg",
            "description": (
                "Validate a Conventional Commit message file. Intended as the entry for "
                "the commit-msg pre-commit-framework stage. Preferred over hand-rolled "
                "regex validation because it matches exactly what oct_git_commit enforces."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "message_file": {
                        "type": "string",
                        # OCT-LINT: disable=no_hardcoded_secrets reason="Pre-existing schema description prose (changelog/hooks tool descriptions) mis-flagged as high-entropy; model-facing help text, not credentials"
                        "description": "Path to the commit-message file (e.g. .git/COMMIT_EDITMSG)",
                    },
                    "json_output": {"type": "boolean", "description": "Machine-readable JSON output"},
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 30)"},
                },
                "required": ["message_file"],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_changelog",
            "description": (
                # OCT-LINT: disable=no_hardcoded_secrets reason="Pre-existing schema description prose (changelog/hooks tool descriptions) mis-flagged as high-entropy; model-facing help text, not credentials"
                "Generate a changelog from Conventional Commits history. Preferred over "
                "hand-writing CHANGELOG.md entries because output is aligned with Option "
                "C's CHANGELOG-format spec. With release set (and not dry_run), writes "
                "to CHANGELOG.md."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "release": {"type": "string", "description": "Release version tag (e.g. 'v0.13.0')"},
                    "since": {"type": "string", "description": "Git ref to start from (default: last tag)"},
                    "dry_run": {"type": "boolean", "description": "Print to stdout without writing"},
                    "json_output": {"type": "boolean", "description": "Machine-readable JSON output"},
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 60)"},
                },
                "required": [],
            },
        },
    },
    {
        "type": "function",
        "function": {
            "name": "oct_git_hooks",
            "description": (
                # OCT-LINT: disable=no_hardcoded_secrets reason="Pre-existing schema description prose (changelog/hooks tool descriptions) mis-flagged as high-entropy; model-facing help text, not credentials"
                "Manage Option C pre-commit hooks: action='install' generates "
                ".pre-commit-config.yaml with the canonical hook set; action='status' "
                "shows installed hook state; action='remove' removes Option C hooks "
                "while preserving any non-OCT hooks. Preferred over hand-editing "
                ".pre-commit-config.yaml."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "action": {
                        "type": "string",
                        "enum": ["install", "status", "remove"],
                        "description": "Hook subcommand to run",
                    },
                    "force": {
                        "type": "boolean",
                        "description": "For action='install': overwrite existing configuration",
                    },
                    "timeout": {"type": "integer", "description": "Subprocess timeout in seconds (default 30)"},
                },
                "required": ["action"],
            },
        },
    },
]