Python
"""The `explore` tool — a read-only research subagent with its own context window.
Broad questions ("where is retry logic handled?") burn the main session's context on
dozens of file reads. `explore` spawns a child TurnEngine over the same workspace with
read-only tools and a fresh context; only its final report returns to the caller.
The child runs in plan mode — the PermissionEngine hard-blocks writes/shell no matter
what the child decides — with no approver, so it never needs an approval round-trip.
That's what lets `explore` carry low-risk metadata, which in turn makes several explores
in one assistant turn eligible for the engine's parallel execution. No recursion: the
child registry has no `explore` tool.
"""
from __future__ import annotations
import asyncio
from pathlib import Path
from typing import Any, Optional
import aisuite as ai
from ..observability.engine_hooks import HelperRecording, current_tool_run
from ..observability.provider_view import tag as tag_provider
from ..engine import TurnEngine
from ..events import EventType
from ..permissions import Mode, PermissionEngine
from ..tools import ToolRegistry
from .files import file_tools
from .git import git_tools
from .search import search_tools
EXPLORER_INSTRUCTIONS = """You are a read-only code explorer working inside the user's workspace. \
Answer the research task you're given by searching and reading the code (`grep`, `read_file`, \
`list_files`, `git_log`, `git_status`, `git_diff`). You cannot write files or run commands.
Your final message is your report — it goes back to the agent that spawned you, not to the \
user. Make it self-contained: answer the task directly, reference code as path:line, quote the \
key snippets, and note anything surprising you found along the way. If you couldn't find \
something, say what you searched so the caller doesn't repeat the same searches."""
_CHILD_MAX_ITERATIONS = 10
def build_explorer_engine(
*,
workspace: str | Path,
provider: Any,
model: str,
model_settings: Optional[dict[str, Any]] = None,
max_iterations: int = _CHILD_MAX_ITERATIONS,
audit_sink: Optional[Any] = None,
) -> TurnEngine:
"""A child engine with the Code agent's read-only tools and a fresh context.
`audit_sink`: the parent's, so the child's reads land in the session's audit log
(the caller stamps `audit_context` with the child's identity)."""
ws = str(Path(workspace).resolve())
registry = ToolRegistry()
# Read-only slice of the Code agent's toolset, with the same toolkit replacements
# (our grep for search_files, our windowed read_file for read_file/read_file_lines).
replaced = {"search_files", "read_file", "read_file_lines", "list_files"}
registry.register_all(
[
t
for t in ai.toolkits.files(root=ws) # no allow_write → list/read only
if getattr(t, "__name__", "") not in replaced
]
)
registry.register_all(file_tools(ws))
registry.register_all(ai.toolkits.git(root=ws)) # git_status, git_diff
registry.register_all(git_tools(ws)) # git_log
registry.register_all(search_tools(ws)) # grep
permissions = PermissionEngine(workspace_root=Path(ws), mode=Mode.PLAN)
return TurnEngine(
provider=provider,
registry=registry,
permissions=permissions,
model=model,
instructions=EXPLORER_INSTRUCTIONS,
max_iterations=max_iterations,
model_settings=model_settings,
audit_sink=audit_sink,
)
def explorer_tools(
*,
workspace: str | Path,
provider: Any,
model: str,
model_settings: Optional[dict[str, Any]] = None,
) -> list:
def explore(task: str) -> dict:
"""Delegate a broad, read-only research task to a subagent with its own fresh
context window. It searches and reads the workspace, then returns only its final
report — the intermediate file reads never touch your context. Use it for
multi-file questions ("where is X handled?", "how does the Y flow work?"); for a
single known file, just read it yourself. Independent explore calls run in
parallel when requested together. State the task precisely and say what the
report should include.
Args:
task (str): The research question, with any constraints and the expected
shape of the report.
"""
# Observability E6: the helper's model and tool calls are recorded under this
# `explore` step, on the parent's turn, with purpose `helper`.
# Its model calls go through the helper's recording too, which counts them (E6b).
run = current_tool_run()
helper_provider = provider
helper: Optional[HelperRecording] = None
if run is not None and run.step_id is not None:
helper = HelperRecording(run.recording, run.step_id, run.turn_id)
helper_provider = tag_provider(run.view, purpose="helper", parent=run.step_id,
turn=run.turn_id, sink=helper)
engine = build_explorer_engine(
workspace=workspace,
provider=helper_provider,
model=model,
model_settings=model_settings,
)
if helper is not None:
engine._obs = helper
async def _run() -> tuple[str, str]:
report, status = "", "unknown"
async for event in engine.run(task):
if event.type == EventType.ASSISTANT_MESSAGE and event.data.get("text"):
report = event.data["text"]
elif event.type == EventType.TURN_END:
status = event.data.get("status", "unknown")
elif event.type == EventType.ERROR:
return report, f"error: {event.data.get('error', '')}"
return report, status
# Tools execute in a worker thread (no running loop), so asyncio.run is safe.
report, status = "", "error"
try:
report, status = asyncio.run(_run())
finally:
if helper is not None:
# E6b: what the helper did, on the explore step, for display only.
run.recording.update_step(run.step_id, attrs={"helper": helper.summary(status)})
if not report:
return {"error": f"explorer produced no report (status: {status})"}
result: dict[str, Any] = {"report": report}
if status != "completed":
result["note"] = (
f"explorer stopped early ({status}); the report may be partial"
)
return result
return [
ai.tool(
explore,
metadata=ai.ToolMetadata(
category="search",
risk_level="low",
capabilities=["search"],
requires_approval=False,
),
)
]