astra-cli-agent 0.1.0__py3-none-any.whl

astra/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

astra/agents/base.py

@@ -0,0 +1,44 @@
+"""Base contract every LangGraph agent node implements."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import Any
+
+from astra.core.state import AgentState
+from astra.llm.provider import LLMMessage, LLMResponse
+from astra.llm.router import FallbackRouter
+
+
+class BaseAgent(ABC):
+    name: str
+    description: str = ""
+    system_prompt: str = ""
+
+    def __init__(self, router: FallbackRouter) -> None:
+        self._router = router
+
+    def complete(self, user_content: str, *, temperature: float = 0.2) -> LLMResponse:
+        messages = [
+            LLMMessage(role="system", content=self.system_prompt),
+            LLMMessage(role="user", content=user_content),
+        ]
+        return self._router.complete(messages, temperature=temperature)
+
+    def stream(
+        self,
+        user_content: str,
+        *,
+        temperature: float = 0.2,
+        on_chunk: Callable[[str], None] | None = None,
+    ) -> LLMResponse:
+        messages = [
+            LLMMessage(role="system", content=self.system_prompt),
+            LLMMessage(role="user", content=user_content),
+        ]
+        return self._router.stream_complete(messages, temperature=temperature, on_chunk=on_chunk)
+
+    @abstractmethod
+    def run(self, state: AgentState) -> dict[str, Any]:
+        """Return a partial AgentState update — the LangGraph node contract."""

astra/agents/coder_agent.py

@@ -0,0 +1,39 @@
+"""Coder Agent: general-purpose coding assistant, executes plan steps assigned to it."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from astra.agents.base import BaseAgent
+from astra.core.events import record
+from astra.core.state import AgentState
+
+
+class CoderAgent(BaseAgent):
+    name = "coder"
+    description = (
+        "General-purpose coding assistant: explains code, writes code, and reasons about "
+        "software design and general development questions. For root-causing errors, stack "
+        "traces, or failing tests, prefer the debug agent instead."
+    )
+    system_prompt = (
+        "You are Astra's coding agent, an expert software engineer. Answer the instruction "
+        "directly and concisely, with code blocks where helpful. Do not restate the question."
+    )
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        updated_plan = list(state.plan)
+        events = state.events
+        total_cost = state.total_cost_usd
+
+        for i, step in enumerate(updated_plan):
+            if step.agent != self.name or step.status != "pending":
+                continue
+            response = self.complete(step.instruction)
+            updated_plan[i] = step.model_copy(
+                update={"result": response.content, "status": "done"}
+            )
+            total_cost += response.estimated_cost_usd
+            events = record(events, self.name, f"executed step {step.step_id}")
+
+        return {"plan": updated_plan, "events": events, "total_cost_usd": total_cost}

astra/agents/debug_agent.py

@@ -0,0 +1,41 @@
+"""Debug Agent: root-causes errors, stack traces, and failing-test output."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from astra.agents.base import BaseAgent
+from astra.core.events import record
+from astra.core.state import AgentState
+
+
+class DebugAgent(BaseAgent):
+    name = "debug"
+    description = (
+        "Debugging specialist: analyzes error messages, stack traces, and failing test output "
+        "to find the root cause and propose a concrete fix."
+    )
+    system_prompt = (
+        "You are Astra's debugging agent, an expert at root-causing software failures. Given "
+        "an error, stack trace, or description of unexpected behavior, identify the most "
+        "likely root cause and propose a concrete fix. Be direct and specific — name the "
+        "failing component and the exact change needed, with a code block if helpful. Do not "
+        "restate the question or list generic troubleshooting steps unrelated to this case."
+    )
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        updated_plan = list(state.plan)
+        events = state.events
+        total_cost = state.total_cost_usd
+
+        for i, step in enumerate(updated_plan):
+            if step.agent != self.name or step.status != "pending":
+                continue
+            response = self.complete(step.instruction)
+            updated_plan[i] = step.model_copy(
+                update={"result": response.content, "status": "done"}
+            )
+            total_cost += response.estimated_cost_usd
+            events = record(events, self.name, f"executed step {step.step_id}")
+
+        return {"plan": updated_plan, "events": events, "total_cost_usd": total_cost}

astra/agents/docker_agent.py

@@ -0,0 +1,139 @@
+"""Docker Agent: translates an instruction into one docker tool call, executes it, reports
+back. Same one-LLM-call JSON tool-selection dispatch `GitAgent`/`FileAgent` use, plus two
+behaviors specific to this domain:
+
+- **Ambient build path**: `docker_build` takes a `path` arg (the Dockerfile's directory); if
+  the LLM omits it, the agent defaults to the current project directory rather than inventing
+  one — same "ambient root, not LLM-chosen" trust level `tools/code/backend.py` gives its
+  `root` arg.
+- **The interactive confirm gate** (§8 of the architecture doc): a confirm-required tool call
+  (`docker_rm`, `docker_rmi`, `docker_exec`, `docker_prune` — permanent deletion or arbitrary
+  in-container command execution) is blocked on `self._confirm` before it runs, unless
+  `state.assume_yes` is set. Declining cancels the step without ever calling the tool — same
+  gate `GitAgent`/`FileAgent` apply to their own confirm-required tools.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from astra.agents.base import BaseAgent
+from astra.core.confirm import ConfirmFn, interactive_confirm
+from astra.core.events import Event, record
+from astra.core.state import AgentState, PlanStep
+from astra.llm.provider import LLMResponse
+from astra.llm.router import FallbackRouter
+from astra.tools.registry import ToolRegistry
+
+
+def _strip_code_fence(text: str) -> str:
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        lines = lines[1:] if lines else lines
+        if lines and lines[-1].strip().startswith("```"):
+            lines = lines[:-1]
+        text = "\n".join(lines).strip()
+    return text
+
+
+class DockerAgent(BaseAgent):
+    name = "docker"
+    description = (
+        "Manages docker containers and images in the current project: list, inspect, build, "
+        "run, start, stop, restart, remove, exec into, prune, and pull."
+    )
+
+    def __init__(
+        self,
+        router: FallbackRouter,
+        tool_registry: ToolRegistry,
+        confirm: ConfirmFn = interactive_confirm,
+    ) -> None:
+        super().__init__(router)
+        self._tools = tool_registry
+        self._confirm = confirm
+        catalog_lines = "\n".join(f"- {t.name}: {t.description}" for t in tool_registry.by_tag(self.name))
+        self.system_prompt = (
+            "You are Astra's docker agent. Given a developer instruction, choose exactly one "
+            "tool from the catalog and the arguments to call it with. Reply with ONLY a single "
+            'JSON object: {"tool": "<tool_name>", "args": {"<arg>": "<value>", ...}}. Omit an '
+            "arg entirely rather than inventing a value you weren't given — in particular, "
+            'omit "path" for docker_build if no build context directory was specified.\n\n'
+            f"Catalog:\n{catalog_lines}"
+        )
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        updated_plan = list(state.plan)
+        events = state.events
+        total_cost = state.total_cost_usd
+        root = Path.cwd().resolve()
+
+        for i, step in enumerate(updated_plan):
+            if step.agent != self.name or step.status != "pending":
+                continue
+            new_step, cost, events = self._execute_step(step, root, events, state.assume_yes)
+            updated_plan[i] = new_step
+            total_cost += cost
+
+        return {"plan": updated_plan, "events": events, "total_cost_usd": total_cost}
+
+    def _execute_step(
+        self, step: PlanStep, root: Path, events: list[Event], assume_yes: bool
+    ) -> tuple[PlanStep, float, list[Event]]:
+        selection_response = self.complete(step.instruction, temperature=0.0)
+        cost = selection_response.estimated_cost_usd
+
+        try:
+            tool_name, args = self._parse_selection(selection_response)
+        except ValueError as exc:
+            events = record(events, self.name, f"could not parse tool selection: {exc}")
+            return step.model_copy(update={"status": "failed", "result": str(exc)}), cost, events
+
+        tool = self._tools.get(tool_name)
+        if tool is None:
+            error = f"selected unknown docker tool: {tool_name}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        if tool_name == "docker_build" and not args.get("path"):
+            args["path"] = str(root)
+
+        is_risky = "confirm-required" in tool.tags
+        if is_risky and not assume_yes:
+            approved = self._confirm(f"Allow risky docker operation ({tool_name}) with args={args}?")
+            if not approved:
+                message = f"cancelled by user (risky operation not confirmed): {tool_name}"
+                events = record(events, self.name, message)
+                return step.model_copy(update={"status": "failed", "result": message}), cost, events
+
+        try:
+            result = tool.func(**args)
+        except Exception as exc:  # LLM-supplied tool args are untrusted input; never crash the graph
+            error = f"docker agent call to {tool_name} failed: {exc}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        output = result.output or result.error or "(no output)"
+        if is_risky:
+            output = f"⚠️ risky operation ({tool_name}): {output}"
+            events = record(events, self.name, f"risky operation executed: {tool_name}")
+        events = record(events, self.name, f"executed step {step.step_id} via {tool_name}")
+
+        status = "done" if result.success else "failed"
+        return step.model_copy(update={"status": status, "result": output}), cost, events
+
+    def _parse_selection(self, response: LLMResponse) -> tuple[str, dict[str, Any]]:
+        raw = _strip_code_fence(response.content)
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"docker agent produced non-JSON tool selection: {raw!r}") from exc
+
+        tool_name = parsed.get("tool")
+        args = parsed.get("args") or {}
+        if not isinstance(tool_name, str) or not isinstance(args, dict):
+            raise ValueError(f"docker agent produced a malformed tool selection: {parsed!r}")
+        return tool_name, dict(args)

astra/agents/documentation_agent.py

@@ -0,0 +1,41 @@
+"""Documentation Agent: writes and improves docstrings, READMEs, and usage guides."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from astra.agents.base import BaseAgent
+from astra.core.events import record
+from astra.core.state import AgentState
+
+
+class DocumentationAgent(BaseAgent):
+    name = "documentation"
+    description = (
+        "Documentation specialist: writes and improves docstrings, README sections, API docs, "
+        "and usage guides for code."
+    )
+    system_prompt = (
+        "You are Astra's documentation agent, an expert technical writer for software "
+        "projects. Given a request to document code or a project, produce clear, accurate "
+        "documentation in the requested format (docstring, README section, API reference, or "
+        "usage guide). Match the style conventions implied by any provided context. Do not "
+        "invent behavior the code doesn't have, and do not restate the question."
+    )
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        updated_plan = list(state.plan)
+        events = state.events
+        total_cost = state.total_cost_usd
+
+        for i, step in enumerate(updated_plan):
+            if step.agent != self.name or step.status != "pending":
+                continue
+            response = self.complete(step.instruction)
+            updated_plan[i] = step.model_copy(
+                update={"result": response.content, "status": "done"}
+            )
+            total_cost += response.estimated_cost_usd
+            events = record(events, self.name, f"executed step {step.step_id}")
+
+        return {"plan": updated_plan, "events": events, "total_cost_usd": total_cost}

astra/agents/file_agent.py

@@ -0,0 +1,176 @@
+"""File Agent: translates an instruction into one filesystem-, code-, or shell-tool call,
+executes it, reports back. Owns Phase 8's two tool domains (filesystem read/write/list/
+search/delete, and code lint/format/test/symbol-search) plus Phase 9's shell domain behind
+a single LLM tool-selection step — the same JSON dispatch pattern `GitAgent` uses, since all
+three domains are small and closely related (they all operate on the current project tree).
+
+Two extra behaviors beyond plain dispatch, both part of the §8 safety model:
+- **Sandbox-escape detection**. Every filesystem tool takes a path-shaped arg ("path",
+  "src", "dst"); those are resolved against the current working directory before the tool
+  runs, and if resolution lands outside the project root the call is treated as risky.
+  Code and shell tools pass their (non-path) args straight through to a subprocess the same
+  way git's branch/path args do, so they aren't sandbox-resolved.
+- **The interactive confirm gate**. Any risky call (a statically `confirm-required` tool —
+  `fs_delete_file`, `shell_run` — or a sandbox-escaping path) is blocked on `self._confirm`
+  before it runs, unless `state.assume_yes` is set (`astra run --yes`). Declining cancels
+  the step without ever calling the tool. `shell_run` additionally has its own hard denylist
+  in `tools/shell/backend.py` that runs regardless of confirmation.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from astra.agents.base import BaseAgent
+from astra.core.confirm import ConfirmFn, interactive_confirm
+from astra.core.events import Event, record
+from astra.core.state import AgentState, PlanStep
+from astra.llm.provider import LLMResponse
+from astra.llm.router import FallbackRouter
+from astra.tools.code.tools import CODE_TOOLS
+from astra.tools.filesystem.tools import FILESYSTEM_TOOLS
+from astra.tools.registry import ToolRegistry
+from astra.tools.shell.tools import SHELL_TOOLS
+
+_PATH_ARGS = frozenset({"path", "src", "dst"})
+_AMBIENT_ROOT_TAGS = frozenset({"code", "shell"})
+
+
+def _strip_code_fence(text: str) -> str:
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        lines = lines[1:] if lines else lines
+        if lines and lines[-1].strip().startswith("```"):
+            lines = lines[:-1]
+        text = "\n".join(lines).strip()
+    return text
+
+
+def build_file_registry() -> ToolRegistry:
+    registry = ToolRegistry()
+    for tool in [*FILESYSTEM_TOOLS, *CODE_TOOLS, *SHELL_TOOLS]:
+        registry.register(tool)
+    return registry
+
+
+class FileAgent(BaseAgent):
+    name = "file"
+    description = (
+        "Reads, writes, lists, searches, and deletes files in the current project directory, "
+        "runs code-quality tools against it (lint, format, run tests, find symbols), and runs "
+        "arbitrary shell commands in it."
+    )
+
+    def __init__(
+        self,
+        router: FallbackRouter,
+        tool_registry: ToolRegistry,
+        confirm: ConfirmFn = interactive_confirm,
+    ) -> None:
+        super().__init__(router)
+        self._tools = tool_registry
+        self._confirm = confirm
+        catalog_lines = "\n".join(f"- {t.name}: {t.description}" for t in tool_registry.by_tag(self.name))
+        self.system_prompt = (
+            "You are Astra's file agent. Given a developer instruction, choose exactly one tool "
+            "from the catalog and the arguments to call it with. Reply with ONLY a single JSON "
+            'object: {"tool": "<tool_name>", "args": {"<arg>": "<value>", ...}}. Paths are always '
+            "relative to the current project directory. Omit an arg entirely rather than "
+            "inventing a value you weren't given.\n\n"
+            f"Catalog:\n{catalog_lines}"
+        )
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        updated_plan = list(state.plan)
+        events = state.events
+        total_cost = state.total_cost_usd
+        root = Path.cwd().resolve()
+
+        for i, step in enumerate(updated_plan):
+            if step.agent != self.name or step.status != "pending":
+                continue
+            new_step, cost, events = self._execute_step(step, root, events, state.assume_yes)
+            updated_plan[i] = new_step
+            total_cost += cost
+
+        return {"plan": updated_plan, "events": events, "total_cost_usd": total_cost}
+
+    def _execute_step(
+        self, step: PlanStep, root: Path, events: list[Event], assume_yes: bool
+    ) -> tuple[PlanStep, float, list[Event]]:
+        selection_response = self.complete(step.instruction, temperature=0.0)
+        cost = selection_response.estimated_cost_usd
+
+        try:
+            tool_name, args = self._parse_selection(selection_response)
+        except ValueError as exc:
+            events = record(events, self.name, f"could not parse tool selection: {exc}")
+            return step.model_copy(update={"status": "failed", "result": str(exc)}), cost, events
+
+        tool = self._tools.get(tool_name)
+        if tool is None:
+            error = f"selected unknown file tool: {tool_name}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        if tool.tags & _AMBIENT_ROOT_TAGS:
+            escaped = False
+            call_kwargs: dict[str, Any] = {"root": root, **args}
+        else:
+            call_kwargs, escaped = self._resolve_paths(root, args)
+
+        is_risky = "confirm-required" in tool.tags or escaped
+        reason = "confirm-required" if "confirm-required" in tool.tags else "path escapes project root"
+
+        if is_risky and not assume_yes:
+            approved = self._confirm(f"Allow risky operation ({tool_name}, {reason}) with args={args}?")
+            if not approved:
+                message = f"cancelled by user (risky operation not confirmed): {tool_name}"
+                events = record(events, self.name, message)
+                return step.model_copy(update={"status": "failed", "result": message}), cost, events
+
+        try:
+            result = tool.func(**call_kwargs)
+        except Exception as exc:  # LLM-supplied tool args are untrusted input; never crash the graph
+            error = f"file agent call to {tool_name} failed: {exc}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        output = result.output or result.error or "(no output)"
+        if is_risky:
+            output = f"⚠️ risky operation ({tool_name}, {reason}): {output}"
+            events = record(events, self.name, f"risky operation executed: {tool_name}")
+        events = record(events, self.name, f"executed step {step.step_id} via {tool_name}")
+
+        status = "done" if result.success else "failed"
+        return step.model_copy(update={"status": status, "result": output}), cost, events
+
+    def _resolve_paths(self, root: Path, args: dict[str, Any]) -> tuple[dict[str, Any], bool]:
+        resolved: dict[str, Any] = dict(args)
+        escaped = False
+        for key in _PATH_ARGS & resolved.keys():
+            value = resolved[key]
+            if not isinstance(value, str) or not value:
+                continue
+            candidate = Path(value)
+            absolute = (candidate if candidate.is_absolute() else root / candidate).resolve()
+            if absolute != root and root not in absolute.parents:
+                escaped = True
+            resolved[key] = absolute
+        return resolved, escaped
+
+    def _parse_selection(self, response: LLMResponse) -> tuple[str, dict[str, Any]]:
+        raw = _strip_code_fence(response.content)
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"file agent produced non-JSON tool selection: {raw!r}") from exc
+
+        tool_name = parsed.get("tool")
+        args = parsed.get("args") or {}
+        if not isinstance(tool_name, str) or not isinstance(args, dict):
+            raise ValueError(f"file agent produced a malformed tool selection: {parsed!r}")
+        return tool_name, dict(args)

astra/agents/git_agent.py

@@ -0,0 +1,163 @@
+"""Git Agent: translates an instruction into one git tool call, executes it, reports back.
+
+Three extra behaviors beyond plain tool dispatch:
+- **Commit-message generation**: if a plan step wants a commit but doesn't supply a message,
+  the agent looks at the staged diff and asks the LLM for a concise one before committing.
+- **Risky-change detection**: if the selected tool is tagged "confirm-required" (touches a
+  remote or can discard/rewrite history), the result is prefixed with a warning and the event
+  log records it.
+- **The interactive confirm gate** (Phase 9, §8 of the architecture doc): a confirm-required
+  tool call is blocked on `self._confirm` before it runs, unless `state.assume_yes` is set
+  (`astra run --yes`). Declining cancels the step without ever calling the tool — same gate
+  `FileAgent` applies to its own confirm-required/sandbox-escaping tools.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from astra.agents.base import BaseAgent
+from astra.core.confirm import ConfirmFn, interactive_confirm
+from astra.core.events import Event, record
+from astra.core.state import AgentState, PlanStep
+from astra.llm.provider import LLMMessage, LLMResponse
+from astra.llm.router import FallbackRouter
+from astra.tools.registry import ToolRegistry
+
+
+def _strip_code_fence(text: str) -> str:
+    text = text.strip()
+    if text.startswith("```"):
+        lines = text.splitlines()
+        lines = lines[1:] if lines else lines
+        if lines and lines[-1].strip().startswith("```"):
+            lines = lines[:-1]
+        text = "\n".join(lines).strip()
+    return text
+
+
+class GitAgent(BaseAgent):
+    name = "git"
+    description = (
+        "Performs git operations against the repository in the current directory: status, "
+        "diff, log, blame, branch, commit, push, pull, merge, stash, and checkout."
+    )
+
+    def __init__(
+        self,
+        router: FallbackRouter,
+        tool_registry: ToolRegistry,
+        confirm: ConfirmFn = interactive_confirm,
+    ) -> None:
+        super().__init__(router)
+        self._tools = tool_registry
+        self._confirm = confirm
+        catalog_lines = "\n".join(f"- {t.name}: {t.description}" for t in tool_registry.by_tag(self.name))
+        self.system_prompt = (
+            "You are Astra's git agent. Given a developer instruction, choose exactly one tool "
+            "from the catalog and the arguments to call it with. Reply with ONLY a single JSON "
+            'object: {"tool": "<tool_name>", "args": {"<arg>": "<value>", ...}}. Omit an arg '
+            "entirely rather than inventing a value you weren't given — in particular, omit "
+            '"message" for git_commit if no commit message was specified.\n\n'
+            f"Catalog:\n{catalog_lines}"
+        )
+
+    def run(self, state: AgentState) -> dict[str, Any]:
+        updated_plan = list(state.plan)
+        events = state.events
+        total_cost = state.total_cost_usd
+        repo_path = Path.cwd()
+
+        for i, step in enumerate(updated_plan):
+            if step.agent != self.name or step.status != "pending":
+                continue
+            new_step, cost, events = self._execute_step(step, repo_path, events, state.assume_yes)
+            updated_plan[i] = new_step
+            total_cost += cost
+
+        return {"plan": updated_plan, "events": events, "total_cost_usd": total_cost}
+
+    def _execute_step(
+        self, step: PlanStep, repo_path: Path, events: list[Event], assume_yes: bool
+    ) -> tuple[PlanStep, float, list[Event]]:
+        selection_response = self.complete(step.instruction, temperature=0.0)
+        cost = selection_response.estimated_cost_usd
+
+        try:
+            tool_name, args = self._parse_selection(selection_response)
+        except ValueError as exc:
+            events = record(events, self.name, f"could not parse tool selection: {exc}")
+            return step.model_copy(update={"status": "failed", "result": str(exc)}), cost, events
+
+        tool = self._tools.get(tool_name)
+        if tool is None:
+            error = f"selected unknown git tool: {tool_name}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        if tool_name == "git_commit" and not args.get("message"):
+            message, message_cost = self._generate_commit_message(repo_path)
+            args["message"] = message
+            cost += message_cost
+
+        is_risky = "confirm-required" in tool.tags
+        if is_risky and not assume_yes:
+            approved = self._confirm(f"Allow risky git operation ({tool_name}) with args={args}?")
+            if not approved:
+                message = f"cancelled by user (risky operation not confirmed): {tool_name}"
+                events = record(events, self.name, message)
+                return step.model_copy(update={"status": "failed", "result": message}), cost, events
+
+        try:
+            result = tool.func(repo_path=repo_path, **args)
+        except Exception as exc:  # LLM-supplied tool args are untrusted input; never crash the graph
+            error = f"git agent call to {tool_name} failed: {exc}"
+            events = record(events, self.name, error)
+            return step.model_copy(update={"status": "failed", "result": error}), cost, events
+
+        output = result.output or result.error or "(no output)"
+        if is_risky:
+            output = f"⚠️ risky operation ({tool_name}): {output}"
+            events = record(events, self.name, f"risky operation executed: {tool_name}")
+        events = record(events, self.name, f"executed step {step.step_id} via {tool_name}")
+
+        status = "done" if result.success else "failed"
+        return step.model_copy(update={"status": status, "result": output}), cost, events
+
+    def _parse_selection(self, response: LLMResponse) -> tuple[str, dict[str, Any]]:
+        raw = _strip_code_fence(response.content)
+        try:
+            parsed = json.loads(raw)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"git agent produced non-JSON tool selection: {raw!r}") from exc
+
+        tool_name = parsed.get("tool")
+        args = parsed.get("args") or {}
+        if not isinstance(tool_name, str) or not isinstance(args, dict):
+            raise ValueError(f"git agent produced a malformed tool selection: {parsed!r}")
+        return tool_name, dict(args)
+
+    def _generate_commit_message(self, repo_path: Path) -> tuple[str, float]:
+        diff_tool = self._tools.get("git_diff")
+        assert diff_tool is not None
+        diff_result = diff_tool.func(repo_path=repo_path, staged=True)
+        diff_text = diff_result.output or "(no staged diff available)"
+
+        response = self._router.complete(
+            [
+                LLMMessage(
+                    role="system",
+                    content=(
+                        "You write concise, conventional git commit messages (one line, "
+                        "imperative mood, no trailing period) from a diff. Reply with only "
+                        "the commit message."
+                    ),
+                ),
+                LLMMessage(role="user", content=diff_text[:4000]),
+            ],
+            temperature=0.1,
+        )
+        message = response.content.strip().strip('"') or "update"
+        return message, response.estimated_cost_usd