briar-cli 1.1.1__py3-none-any.whl

briar/agent/_llms/gemini.py

@@ -0,0 +1,152 @@
+"""Google Gemini `LLMProvider`.
+
+Lazy-imports ``google.generativeai``; opt-in via ``pip install
+briar-cli[gemini]``. Gemini's tool-call shape lives inside
+``response.candidates[0].content.parts[].function_call`` (no separate
+"tool_calls" array)."""
+
+from __future__ import annotations
+
+import importlib
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+from briar.agent._llm import LLMProvider, LLMResponse, LLMToolCall
+
+
+log = logging.getLogger(__name__)
+
+
+def _import_genai() -> Optional[Any]:
+    try:
+        return importlib.import_module("google.generativeai")
+    except ImportError:
+        return None
+
+
+class GeminiLLM(LLMProvider):
+    kind = "gemini"
+    DEFAULT_MODEL = "gemini-2.5-pro"
+
+    def __init__(self, *, model: str = "") -> None:
+        self._model_name = model or self.DEFAULT_MODEL
+        self._api_key = os.environ.get("GEMINI_API_KEY", "")
+        self._model = None
+
+    def is_available(self) -> bool:
+        return bool(self._api_key) and _import_genai() is not None
+
+    def _build_model(self, system: str, tools: List[Dict[str, Any]]):
+        genai = _import_genai()
+        if genai is None:
+            raise RuntimeError("google-generativeai not installed — run `pip install briar-cli[gemini]`")
+        if not self._api_key:
+            raise RuntimeError("GEMINI_API_KEY env var is required for GeminiLLM")
+        genai.configure(api_key=self._api_key)
+        # Gemini's `tools` argument accepts a list of dicts in OpenAPI shape;
+        # genai converts internally.
+        gemini_tools = self._to_gemini_tools(tools) if tools else None
+        return genai.GenerativeModel(
+            model_name=self._model_name,
+            system_instruction=system or None,
+            tools=gemini_tools,
+        )
+
+    def complete(
+        self,
+        *,
+        system: str,
+        messages: List[Dict[str, Any]],
+        tools: List[Dict[str, Any]],
+        max_tokens: int,
+    ) -> LLMResponse:
+        model = self._build_model(system, tools)
+        contents = self._to_gemini_contents(messages)
+        resp = model.generate_content(
+            contents=contents,
+            generation_config={"max_output_tokens": max_tokens},
+        )
+        return self._normalise(resp)
+
+    def format_tool_result(self, tool_call_id: str, output: str, is_error: bool = False) -> Dict[str, Any]:
+        # Gemini correlates tool results by *function name*, not by id —
+        # callers pass the function name as `tool_call_id`.
+        content = {"function_response": {"name": tool_call_id, "response": {"content": output, "is_error": is_error}}}
+        return {"role": "user", "parts": [content]}
+
+    # ---- shape translation ------------------------------------------------
+
+    @staticmethod
+    def _to_gemini_tools(tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        # Gemini expects a list of `Tool` objects; each contains
+        # `function_declarations` with `{name, description, parameters}`.
+        return [
+            {
+                "function_declarations": [
+                    {
+                        "name": t.get("name", ""),
+                        "description": t.get("description", ""),
+                        "parameters": t.get("input_schema", {}),
+                    }
+                    for t in tools
+                ]
+            }
+        ]
+
+    @staticmethod
+    def _to_gemini_contents(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        """Anthropic uses role ``user``/``assistant``; Gemini uses
+        ``user``/``model``. Plain-text content gets wrapped in parts."""
+        out: List[Dict[str, Any]] = []
+        for m in messages:
+            role = m.get("role", "user")
+            if role == "assistant":
+                role = "model"
+            content = m.get("content")
+            if isinstance(content, str):
+                out.append({"role": role, "parts": [{"text": content}]})
+            else:
+                out.append({"role": role, "parts": content or []})
+        return out
+
+    @staticmethod
+    def _normalise(resp: Any) -> LLMResponse:
+        candidates = getattr(resp, "candidates", None) or []
+        if not candidates:
+            return LLMResponse(text="", tool_calls=[], stop_reason="", input_tokens=0, output_tokens=0)
+        candidate = candidates[0]
+        parts = getattr(candidate.content, "parts", None) or []
+        text_parts: List[str] = []
+        tool_calls: List[LLMToolCall] = []
+        for part in parts:
+            text = getattr(part, "text", None)
+            if text:
+                text_parts.append(text)
+            fc = getattr(part, "function_call", None)
+            if fc is not None:
+                tool_calls.append(
+                    LLMToolCall(
+                        id=fc.name,  # Gemini has no native id — use name
+                        name=fc.name,
+                        arguments=dict(fc.args or {}),
+                    )
+                )
+        # Gemini `finish_reason`: STOP / MAX_TOKENS / SAFETY / RECITATION / OTHER
+        finish = getattr(candidate, "finish_reason", None)
+        finish_name = getattr(finish, "name", str(finish or ""))
+        if tool_calls:
+            stop = "tool_use"
+        elif finish_name == "STOP":
+            stop = "end_turn"
+        else:
+            stop = finish_name.lower()
+        usage = getattr(resp, "usage_metadata", None)
+        return LLMResponse(
+            text="".join(text_parts),
+            tool_calls=tool_calls,
+            stop_reason=stop,
+            input_tokens=int(getattr(usage, "prompt_token_count", 0) or 0),
+            output_tokens=int(getattr(usage, "candidates_token_count", 0) or 0),
+            raw_assistant_message={"role": "model", "parts": [getattr(p, "to_dict", lambda: {})() for p in parts]},
+        )

briar/agent/_llms/openai_llm.py

@@ -0,0 +1,129 @@
+"""OpenAI `LLMProvider`.
+
+Lazy-imports ``openai`` so the package is an opt-in extra
+(``pip install briar-cli[openai]``). ``is_available()`` reports False
+when the SDK isn't installed; ``complete()`` raises a clear message
+pointing at the right install command."""
+
+from __future__ import annotations
+
+import importlib
+import json
+import logging
+import os
+from typing import Any, Dict, List, Optional
+
+from briar.agent._llm import LLMProvider, LLMResponse, LLMToolCall
+
+
+log = logging.getLogger(__name__)
+
+
+def _import_openai() -> Optional[Any]:
+    try:
+        return importlib.import_module("openai")
+    except ImportError:
+        return None
+
+
+class OpenAILLM(LLMProvider):
+    kind = "openai"
+    DEFAULT_MODEL = "gpt-4o"
+
+    def __init__(self, *, model: str = "") -> None:
+        self._model = model or self.DEFAULT_MODEL
+        self._api_key = os.environ.get("OPENAI_API_KEY", "")
+        self._client = None
+
+    def is_available(self) -> bool:
+        return bool(self._api_key) and _import_openai() is not None
+
+    def _build_client(self):
+        if self._client is not None:
+            return self._client
+        openai = _import_openai()
+        if openai is None:
+            raise RuntimeError("openai package not installed — run `pip install briar-cli[openai]`")
+        if not self._api_key:
+            raise RuntimeError("OPENAI_API_KEY env var is required for OpenAILLM")
+        self._client = openai.OpenAI(api_key=self._api_key)
+        return self._client
+
+    def complete(
+        self,
+        *,
+        system: str,
+        messages: List[Dict[str, Any]],
+        tools: List[Dict[str, Any]],
+        max_tokens: int,
+    ) -> LLMResponse:
+        client = self._build_client()
+        api_messages: List[Dict[str, Any]] = []
+        if system:
+            api_messages.append({"role": "system", "content": system})
+        api_messages.extend(messages)
+
+        kwargs: Dict[str, Any] = {
+            "model": self._model,
+            "messages": api_messages,
+            "max_tokens": max_tokens,
+        }
+        if tools:
+            kwargs["tools"] = self._to_openai_tools(tools)
+
+        resp = client.chat.completions.create(**kwargs)
+        return self._normalise(resp)
+
+    def format_tool_result(self, tool_call_id: str, output: str, is_error: bool = False) -> Dict[str, Any]:
+        # OpenAI's echo-back shape: a top-level "tool" message with the call id.
+        # `is_error` is signalled via content prefix since the API has no native flag.
+        content = f"[ERROR] {output}" if is_error else output
+        return {"role": "tool", "tool_call_id": tool_call_id, "content": content}
+
+    @staticmethod
+    def _to_openai_tools(tools: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+        out: List[Dict[str, Any]] = []
+        for t in tools:
+            out.append(
+                {
+                    "type": "function",
+                    "function": {
+                        "name": t.get("name", ""),
+                        "description": t.get("description", ""),
+                        "parameters": t.get("input_schema", {}),
+                    },
+                }
+            )
+        return out
+
+    @staticmethod
+    def _normalise(resp: Any) -> LLMResponse:
+        choice = resp.choices[0]
+        message = choice.message
+        text = message.content or ""
+        tool_calls: List[LLMToolCall] = []
+        for tc in (message.tool_calls or []) if hasattr(message, "tool_calls") else []:
+            # OpenAI delivers `arguments` as a JSON string — parse it for the caller.
+            raw_args = getattr(tc.function, "arguments", "") or "{}"
+            try:
+                args = json.loads(raw_args)
+            except (ValueError, TypeError):
+                args = {}
+            tool_calls.append(LLMToolCall(id=tc.id, name=tc.function.name, arguments=args))
+        # Map OpenAI's `finish_reason` onto the abstraction's vocabulary.
+        finish_reason = choice.finish_reason or ""
+        if finish_reason == "stop":
+            stop = "end_turn"
+        elif finish_reason == "tool_calls":
+            stop = "tool_use"
+        else:
+            stop = finish_reason
+        usage = getattr(resp, "usage", None)
+        return LLMResponse(
+            text=text,
+            tool_calls=tool_calls,
+            stop_reason=stop,
+            input_tokens=int(getattr(usage, "prompt_tokens", 0) or 0),
+            output_tokens=int(getattr(usage, "completion_tokens", 0) or 0),
+            raw_assistant_message=message.model_dump() if hasattr(message, "model_dump") else {"role": "assistant", "content": text},
+        )

briar/agent/runner.py

@@ -0,0 +1,364 @@
+"""Agent runner — LLM-provider-driven tool-use loop.
+
+Loads the archetype's system prompt, splices in the company's
+knowledge, and drives an `LLMProvider.complete` loop until the model
+returns `end_turn` (or we hit guardrails). Tool calls dispatch to the
+`BashTool` / `ReadFileTool` / `WriteFileTool` / `EditFileTool` primitives
+in `briar.agent.tools`.
+
+Provider-agnostic: selecting Anthropic / OpenAI / Gemini / Bedrock is a
+constructor arg. The runner reads normalised `LLMResponse` shapes so
+this file doesn't grow per-vendor branches.
+"""
+
+from __future__ import annotations
+
+import logging
+import textwrap
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List
+
+from briar.agent._llm import LLMProvider, LLMToolCall
+from briar.agent._llms import make_llm
+from briar.agent.tools import BashTool, EditFileTool, ReadFileTool, SendMessageTool, ToolError, WriteFileTool
+from briar.iac.scaffold.archetypes import ARCHETYPES
+from briar.log_context import log_context
+
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class AgentRunResult:
+    """Outcome of one agent run — what happened, what to report."""
+
+    company: str
+    task: str
+    iterations: int = 0
+    stop_reason: str = ""
+    final_text: str = ""
+    tool_calls: int = 0
+    input_tokens: int = 0
+    output_tokens: int = 0
+    commits: List[str] = field(default_factory=list)
+    error: str = ""
+
+    def cost_summary(self) -> str:
+        # Sonnet 4.5 list pricing as of 2026-05: $3/M input, $15/M output.
+        cost = (self.input_tokens / 1_000_000) * 3.0 + (self.output_tokens / 1_000_000) * 15.0
+        return f"in={self.input_tokens:,} out={self.output_tokens:,} ≈${cost:.3f}"
+
+
+class AgentRunner:
+    """One-shot agent execution against a single (company, task) target.
+
+    Loads the archetype's persona + the spliced knowledge for the company,
+    builds the system prompt, then drives the Anthropic API tool-use loop
+    until the model is done or we hit a guardrail. All tool side effects
+    are confined to the worktree the caller hands us.
+    """
+
+    DEFAULT_MAX_ITERATIONS = 30
+    DEFAULT_MAX_TOKENS_PER_TURN = 8_000
+
+    def __init__(
+        self,
+        *,
+        company: str,
+        task: str,
+        archetype_name: str,
+        workdir: Path,
+        knowledge_store: Any,
+        target: str,
+        oauth_token: str = "",  # kept for back-compat; ignored — Anthropic adapter reads env directly
+        model: str = "",
+        max_iterations: int = 0,
+        extra_user_instructions: str = "",
+        llm_kind: str = "anthropic",
+        llm: LLMProvider = None,  # type: ignore[assignment] — tests inject; runtime falls through
+        task_context_sections: List[Any] = None,  # type: ignore[assignment]
+        dry_run: bool = False,
+        messages: Dict[str, Any] = None,  # type: ignore[assignment] — runbook messages: block
+    ) -> None:
+        self._company = company
+        self._task = task
+        self._workdir = workdir.resolve()
+        self._archetype = ARCHETYPES[archetype_name]
+        self._store = knowledge_store
+        self._target = target
+        self._llm: LLMProvider = llm or make_llm(llm_kind, model=model)
+        self._max_iterations = max_iterations or self.DEFAULT_MAX_ITERATIONS
+        self._extra = extra_user_instructions
+        # JIT context fetched by the caller (FetchTicketContext /
+        # FetchPrReviewContext output sections, etc.). Spliced into the
+        # system prompt below the archetype's persona — sits next to the
+        # scheduled knowledge sections so the agent treats them the same.
+        self._task_context_sections = list(task_context_sections or [])
+        self._dry_run = dry_run
+        # Tools share the same root list so the agent can read/write
+        # inside the worktree but nowhere else.
+        roots = [self._workdir]
+        self._bash = BashTool(base_cwd=self._workdir)
+        self._read = ReadFileTool(allowed_roots=roots)
+        self._write = WriteFileTool(allowed_roots=roots)
+        self._edit = EditFileTool(allowed_roots=roots)
+        # Only bind the SendMessageTool when the runbook actually has
+        # message channels configured for this company. Empty messages
+        # dict → tool not registered → LLM falls back to bash.
+        self._send = SendMessageTool(messages=messages or {}, company=company) if messages else None
+
+    def run(self) -> AgentRunResult:
+        with log_context(company=self._company, task=self._task, agent=self._archetype.name):
+            # Dry-run path: build the same prompts the LLM would see,
+            # print them, and return. Don't gate on LLM creds (the
+            # whole point is to validate the prompt rendering without
+            # an LLM call) — but DO gate on JIT extractor / archetype
+            # construction having succeeded, which happens at __init__.
+            if self._dry_run:
+                return self._dry_run_report()
+            if not self._llm.is_available():
+                return AgentRunResult(
+                    company=self._company,
+                    task=self._task,
+                    error=f"LLM ({self._llm.kind}) credentials missing — see env_vars.py for the required vars",
+                )
+            system = self._build_system_prompt()
+            initial_user = self._build_initial_user_message()
+            log.info(
+                "agent-start: archetype=%s llm=%s max_iter=%d workdir=%s",
+                self._archetype.name,
+                self._llm.kind,
+                self._max_iterations,
+                self._workdir,
+            )
+            log.debug("agent-system-prompt-bytes=%d initial-user-bytes=%d", len(system), len(initial_user))
+            messages: List[Dict[str, Any]] = [{"role": "user", "content": initial_user}]
+            result = AgentRunResult(company=self._company, task=self._task)
+            for iteration in range(1, self._max_iterations + 1):
+                result.iterations = iteration
+                try:
+                    response = self._llm.complete(
+                        system=system,
+                        messages=messages,
+                        tools=self._tool_specs(),
+                        max_tokens=self.DEFAULT_MAX_TOKENS_PER_TURN,
+                    )
+                except Exception:  # noqa: BLE001
+                    log.exception("agent-failed: LLM raised on iteration %d", iteration)
+                    result.error = "api: LLM call failed (see traceback in log)"
+                    return result
+
+                result.input_tokens += response.input_tokens
+                result.output_tokens += response.output_tokens
+                stop = response.stop_reason
+                result.stop_reason = stop
+                log.info(
+                    "agent-turn iter=%d stop=%s tool_calls=%d in=%d out=%d",
+                    iteration,
+                    stop,
+                    len(response.tool_calls),
+                    response.input_tokens,
+                    response.output_tokens,
+                )
+                if stop == "end_turn":
+                    result.final_text = response.text
+                    log.info("agent-done iter=%d %s", iteration, result.cost_summary())
+                    return result
+                if stop != "tool_use":
+                    result.error = f"unexpected stop_reason={stop}"
+                    log.warning("agent-stopped: %s", result.error)
+                    return result
+                tool_results = self._execute_all_tool_uses(response.tool_calls, result)
+                messages.append(response.raw_assistant_message)
+                messages.append({"role": "user", "content": tool_results})
+            result.error = f"hit iteration ceiling ({self._max_iterations})"
+            log.warning("agent-ceiling: %d iterations exhausted %s", self._max_iterations, result.cost_summary())
+            return result
+
+    def _build_system_prompt(self) -> str:
+        persona = self._archetype.build_persona(self._target)
+        from briar.iac.scaffold._knowledge import KnowledgeSplicer
+
+        try:
+            splicer = KnowledgeSplicer(self._store, self._company)
+            prologue = splicer.prologue(self._archetype)
+        except Exception:  # noqa: BLE001
+            log.exception("agent-system: KnowledgeSplicer failed — continuing without prologue")
+            prologue = ""
+
+        body = textwrap.dedent(
+            f"""\
+            You are: {persona['role']}.
+
+            Goal: {persona['goal']}
+
+            {persona['backstory']}
+
+            ---
+            Working directory: {self._workdir}
+            All file operations (read_file, write_file, edit_file) and shell
+            commands (bash) must operate inside this directory. The
+            scheduler set the human git identity already; verify with
+            `git config user.name` before your first commit.
+            """
+        )
+        sections: List[str] = []
+        if prologue:
+            sections.append(prologue)
+        # Task-scoped sections (ticket-context, pr-review-context, …)
+        # render with their own `## <title>` heading + body, mirroring
+        # the format the scheduled KnowledgeSplicer emits. The agent
+        # treats both layers as one continuous context block.
+        for section in self._task_context_sections:
+            if getattr(section, "is_empty", False):
+                continue
+            sections.append(f"## {section.title}\n\n{section.body}")
+        if not sections:
+            return body
+        return body + "\n\n" + "\n\n".join(sections)
+
+    def _build_initial_user_message(self) -> str:
+        intro = textwrap.dedent(
+            f"""\
+            Run the {self._archetype.name} workflow for company {self._company!r}
+            in repo {self._target!r}. The working directory at {self._workdir}
+            is a clean git worktree on the PR branch you should fix.
+
+            Procedure (follow exactly):
+              1. `bash`: `cd <workdir> && gh pr view <N> --json reviewDecision,headRefName,statusCheckRollup`
+              2. Skip the PR if reviewDecision=APPROVED AND every required check is green AND every
+                 open review thread has only positive comments. Report 'skipped' and end.
+              3. Otherwise, list every open inline review-thread comment + every PR-level issue comment.
+              4. For each thread requesting a code change: apply the smallest correct fix via edit_file,
+                 then commit (one commit per thread; subject ≤72 chars; body cites the comment id).
+              5. After all fixes, push fast-forward to the PR's branch.
+              6. Reply to each thread you addressed via `gh api .../comments/{{id}}/replies` with
+                 one sentence citing the commit SHA.
+              7. Report a short summary of commits made + threads replied to. Then stop.
+
+            Strict constraints:
+              - NEVER --force, --amend, rebase, squash, or filter-branch.
+              - NEVER commit as a bot identity. Run `git config user.name` first to verify it's a human.
+              - NEVER touch files outside the diff already under review unless the fix needs it.
+              - If a thread is subjective ('did you consider X?'), reply with clarification, no commit.
+              - If you cannot resolve a thread safely, leave a comment explaining why and skip it.
+            """
+        )
+        if self._extra:
+            intro = intro + "\n\nAdditional instructions:\n" + self._extra
+        return intro
+
+    def _tool_specs(self) -> List[Dict[str, Any]]:
+        specs: List[Dict[str, Any]] = [
+            {"name": self._bash.name, "description": self._bash.description, "input_schema": self._bash.INPUT_SCHEMA},
+            {"name": self._read.name, "description": self._read.description, "input_schema": self._read.INPUT_SCHEMA},
+            {"name": self._write.name, "description": self._write.description, "input_schema": self._write.INPUT_SCHEMA},
+            {"name": self._edit.name, "description": self._edit.description, "input_schema": self._edit.INPUT_SCHEMA},
+        ]
+        if self._send is not None:
+            # Append the channel list to the description so the LLM sees
+            # the actual handles at agent-start time.
+            channels = self._send.channels()
+            description = self._send.description + (f"\n\nAvailable channels: {', '.join(channels)}" if channels else "")
+            specs.append({"name": self._send.name, "description": description, "input_schema": self._send.INPUT_SCHEMA})
+        return specs
+
+    def _dry_run_report(self) -> AgentRunResult:
+        """Build the same prompts the LLM would see, print them to
+        stdout, and return without a single API call.
+
+        Goal: let the operator validate the JIT context wiring
+        (ticket-context / pr-review-context renders correctly, the
+        archetype's consumes order is what they expect, the tool
+        specs look right) WITHOUT spending tokens. Skips both LLM
+        availability checks and the iteration loop entirely."""
+        system = self._build_system_prompt()
+        initial_user = self._build_initial_user_message()
+        tools = self._tool_specs()
+
+        sep = "=" * 78
+        print(sep)
+        print(f"DRY RUN — archetype={self._archetype.name} task={self._task} target={self._target}")
+        print(f"company={self._company} llm={self._llm.kind}  (LLM call SKIPPED)")
+        print(sep)
+        print()
+        print("─── SYSTEM PROMPT ───────────────────────────────────────────────────────")
+        print(system)
+        print()
+        print("─── INITIAL USER MESSAGE ────────────────────────────────────────────────")
+        print(initial_user)
+        print()
+        print("─── TOOLS BOUND ─────────────────────────────────────────────────────────")
+        for t in tools:
+            print(f"  - {t['name']}: {t['description']}")
+        print()
+        print("─── TASK-SCOPED SECTIONS (count + titles) ───────────────────────────────")
+        if self._task_context_sections:
+            for section in self._task_context_sections:
+                title = getattr(section, "title", "(no title)")
+                body_bytes = len(getattr(section, "body", "") or "")
+                print(f"  - {title}  ({body_bytes} bytes)")
+        else:
+            print("  (none — pass --ticket-key / --pr to populate)")
+        print()
+        print(sep)
+        print(f"system_prompt_bytes={len(system)}  initial_user_bytes={len(initial_user)}  tool_count={len(tools)}")
+        print(sep)
+
+        return AgentRunResult(
+            company=self._company,
+            task=self._task,
+            iterations=0,
+            stop_reason="dry_run",
+            final_text="(dry run — no LLM call)",
+        )
+
+    def _execute_all_tool_uses(self, tool_calls: List[LLMToolCall], result: AgentRunResult) -> List[Dict[str, Any]]:
+        """Dispatch each tool call from the LLM, then format the result
+        in the provider's echo-back shape via `LLMProvider.format_tool_result`.
+        Keeps the runner free of any vendor-specific result shape."""
+        tool_results: List[Dict[str, Any]] = []
+        for call in tool_calls:
+            result.tool_calls += 1
+            outcome = self._dispatch_tool(call.name, call.arguments, result)
+            tool_results.append(
+                self._llm.format_tool_result(
+                    tool_call_id=call.id,
+                    output=outcome["content"],
+                    is_error=outcome["is_error"],
+                )
+            )
+        return tool_results
+
+    def _dispatch_tool(self, name: str, raw_input: Any, result: AgentRunResult) -> Dict[str, Any]:
+        try:
+            if name == self._bash.name:
+                out = self._bash.run(**raw_input)
+                self._record_commit_if_any(out, result)
+                return {"content": out, "is_error": False}
+            if name == self._read.name:
+                return {"content": self._read.run(**raw_input), "is_error": False}
+            if name == self._write.name:
+                return {"content": self._write.run(**raw_input), "is_error": False}
+            if name == self._edit.name:
+                return {"content": self._edit.run(**raw_input), "is_error": False}
+            if self._send is not None and name == self._send.name:
+                return {"content": self._send.run(**raw_input), "is_error": False}
+            return {"content": f"unknown tool {name!r}", "is_error": True}
+        except ToolError as exc:
+            log.warning("tool %s error: %s", name, exc)
+            return {"content": str(exc), "is_error": True}
+        except Exception as exc:  # noqa: BLE001
+            log.exception("tool %s raised unexpectedly", name)
+            return {"content": f"unexpected {type(exc).__name__}: {exc}", "is_error": True}
+
+    @staticmethod
+    def _record_commit_if_any(bash_output: str, result: AgentRunResult) -> None:
+        # `git commit` prints `[branch sha] subject` on the first line of stdout.
+        import re
+
+        match = re.search(r"\[[^\]]+\s+([a-f0-9]{7,40})\]", bash_output)
+        if match:
+            result.commits.append(match.group(1))
+