@agxnte/reidx 2.0.2

package/src/reidx/tools/file_tools.py

@@ -0,0 +1,222 @@
+"""File tools: read, write, patch, list, find, grep.
+
+All file tools confine access to the workspace root plus any additional writable
+roots via _safe_path(). Path traversal outside the workspace is denied. patch_file
+is exact single-match string replacement — honest scaffolding; structured edits
+and diff generation are TODO (see roadmap Phase 5).
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+
+from reidx.policy.models import PermissionDecision, RiskLevel
+from reidx.tools.base import BaseTool, ToolContext, ToolDefinition, ToolResult
+
+_READ_PARAMS = {
+    "type": "object",
+    "properties": {"path": {"type": "string", "description": "Path relative to workspace root."}},
+    "required": ["path"],
+}
+_WRITE_PARAMS = {
+    "type": "object",
+    "properties": {
+        "path": {"type": "string"},
+        "content": {"type": "string"},
+    },
+    "required": ["path", "content"],
+}
+_PATCH_PARAMS = {
+    "type": "object",
+    "properties": {
+        "path": {"type": "string"},
+        "find": {"type": "string", "description": "Exact substring to locate (single match)."},
+        "replace": {"type": "string"},
+    },
+    "required": ["path", "find", "replace"],
+}
+_LIST_PARAMS = {
+    "type": "object",
+    "properties": {"path": {"type": "string", "description": "Subdirectory relative to root. Defaults to root."}},
+}
+_FIND_PARAMS = {
+    "type": "object",
+    "properties": {
+        "pattern": {"type": "string", "description": "glob pattern, e.g. '**/*.py'"},
+        "path": {"type": "string"},
+    },
+    "required": ["pattern"],
+}
+_GREP_PARAMS = {
+    "type": "object",
+    "properties": {
+        "pattern": {"type": "string", "description": "regex pattern"},
+        "path": {"type": "string"},
+    },
+    "required": ["pattern"],
+}
+
+
+def _resolve(path_str: str, ctx: ToolContext) -> Path:
+    p = Path(path_str)
+    if not p.is_absolute():
+        p = ctx.workspace_root / p
+    return p
+
+
+def _safe_read(path: Path, ctx: ToolContext) -> ToolResult | None:
+    decision = ctx.policy.check_path(path, write=False)
+    if decision is PermissionDecision.DENY:
+        return ToolResult.fail(f"path outside workspace: {path}")
+    if decision is PermissionDecision.PROMPT:
+        if ctx.resolve_decision(f"Allow reading {path}?") is PermissionDecision.DENY:
+            return ToolResult.fail(f"read denied by user: {path}")
+    return None
+
+
+def _safe_write(path: Path, ctx: ToolContext) -> ToolResult | None:
+    decision = ctx.policy.check_path(path, write=True)
+    if decision is PermissionDecision.DENY:
+        return ToolResult.fail(f"write outside workspace: {path}")
+    if decision is PermissionDecision.PROMPT:
+        if ctx.resolve_decision(f"Allow writing {path}?") is PermissionDecision.DENY:
+            return ToolResult.fail(f"write denied by user: {path}")
+    return None
+
+
+class ReadFileTool(BaseTool):
+    @property
+    def definition(self) -> ToolDefinition:
+        return ToolDefinition(name="read_file", description="Read a file's text content.", parameters=_READ_PARAMS, risk=RiskLevel.LOW)
+
+    def execute(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        path = _resolve(str(args.get("path", "")), ctx)
+        blocked = _safe_read(path, ctx)
+        if blocked:
+            return blocked
+        if not path.exists() or not path.is_file():
+            return ToolResult.fail(f"not a file: {path}")
+        try:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        except OSError as exc:
+            return ToolResult.fail(f"read error: {exc}")
+        return ToolResult.ok_(text, path=str(path), bytes=len(text))
+
+
+class WriteFileTool(BaseTool):
+    @property
+    def definition(self) -> ToolDefinition:
+        return ToolDefinition(name="write_file", description="Create or overwrite a file.", parameters=_WRITE_PARAMS, risk=RiskLevel.MEDIUM)
+
+    def execute(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        path = _resolve(str(args.get("path", "")), ctx)
+        blocked = _safe_write(path, ctx)
+        if blocked:
+            return blocked
+        content = str(args.get("content", ""))
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+        except OSError as exc:
+            return ToolResult.fail(f"write error: {exc}")
+        return ToolResult.ok_(f"wrote {len(content)} bytes to {path}", path=str(path))
+
+
+class PatchFileTool(BaseTool):
+    @property
+    def definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name="patch_file",
+            description="Replace one exact substring occurrence in a file.",
+            parameters=_PATCH_PARAMS,
+            risk=RiskLevel.MEDIUM,
+        )
+
+    def execute(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        path = _resolve(str(args.get("path", "")), ctx)
+        blocked = _safe_write(path, ctx)
+        if blocked:
+            return blocked
+        find = str(args.get("find", ""))
+        replace = str(args.get("replace", ""))
+        if not find:
+            return ToolResult.fail("find string is empty")
+        if not path.exists():
+            return ToolResult.fail(f"not a file: {path}")
+        text = path.read_text(encoding="utf-8", errors="replace")
+        count = text.count(find)
+        if count == 0:
+            return ToolResult.fail("find string not present")
+        if count > 1:
+            return ToolResult.fail(f"find string matches {count} times; patch requires a unique match (TODO: structured edits)")
+        new_text = text.replace(find, replace, 1)
+        path.write_text(new_text, encoding="utf-8")
+        return ToolResult.ok_("patched", path=str(path))
+
+
+class ListDirTool(BaseTool):
+    @property
+    def definition(self) -> ToolDefinition:
+        return ToolDefinition(name="list_dir", description="List entries in a directory.", parameters=_LIST_PARAMS, risk=RiskLevel.LOW)
+
+    def execute(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        rel = str(args.get("path", ""))
+        path = _resolve(rel, ctx) if rel else ctx.workspace_root
+        blocked = _safe_read(path, ctx)
+        if blocked:
+            return blocked
+        if not path.is_dir():
+            return ToolResult.fail(f"not a directory: {path}")
+        entries = sorted(p.name + ("/" if p.is_dir() else "") for p in path.iterdir())
+        return ToolResult.ok_("\n".join(entries), count=len(entries))
+
+
+class FindFilesTool(BaseTool):
+    @property
+    def definition(self) -> ToolDefinition:
+        return ToolDefinition(name="find_files", description="Find files matching a glob pattern.", parameters=_FIND_PARAMS, risk=RiskLevel.LOW)
+
+    def execute(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        pattern = str(args.get("pattern", "*"))
+        base = _resolve(str(args.get("path", "")), ctx) if args.get("path") else ctx.workspace_root
+        blocked = _safe_read(base, ctx)
+        if blocked:
+            return blocked
+        matches = sorted(str(p.relative_to(ctx.workspace_root)) for p in base.glob(pattern) if p.is_file())
+        return ToolResult.ok_("\n".join(matches), count=len(matches))
+
+
+class GrepFilesTool(BaseTool):
+    @property
+    def definition(self) -> ToolDefinition:
+        return ToolDefinition(name="grep_files", description="Search file contents with a regex.", parameters=_GREP_PARAMS, risk=RiskLevel.LOW)
+
+    def execute(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        pattern = str(args.get("pattern", ""))
+        base = _resolve(str(args.get("path", "")), ctx) if args.get("path") else ctx.workspace_root
+        blocked = _safe_read(base, ctx)
+        if blocked:
+            return blocked
+        try:
+            rx = re.compile(pattern)
+        except re.error as exc:
+            return ToolResult.fail(f"bad regex: {exc}")
+        hits: list[str] = []
+        for p in base.rglob("*"):
+            if not p.is_file():
+                continue
+            try:
+                for i, line in enumerate(p.read_text(encoding="utf-8", errors="ignore").splitlines(), 1):
+                    if rx.search(line):
+                        hits.append(f"{p.relative_to(ctx.workspace_root)}:{i}: {line.strip()}")
+            except OSError:
+                continue
+            if len(hits) >= 200:
+                break
+        return ToolResult.ok_("\n".join(hits), count=len(hits))
+
+
+def register_file_tools(registry) -> None:  # type: ignore[no-untyped-def]
+    for tool in (ReadFileTool(), WriteFileTool(), PatchFileTool(), ListDirTool(), FindFilesTool(), GrepFilesTool()):
+        registry.register(tool)

package/src/reidx/tools/registry.py

@@ -0,0 +1,45 @@
+"""Tool registry: registers tools, lists definitions, dispatches calls.
+
+Policy gating is owned by each tool (via ctx.policy.check_path / check_command /
+evaluate) so action-specific checks happen in one place. The registry only routes
+and converts exceptions to ToolResult failures.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from reidx.diagnostics.logger import get_logger
+from reidx.tools.base import BaseTool, ToolContext, ToolDefinition, ToolResult
+
+log = get_logger("reidx.tools")
+
+
+class ToolRegistry:
+    def __init__(self) -> None:
+        self._tools: dict[str, BaseTool] = {}
+
+    def register(self, tool: BaseTool) -> None:
+        name = tool.definition.name
+        if name in self._tools:
+            raise ValueError(f"tool '{name}' already registered")
+        self._tools[name] = tool
+        log.debug("registered tool: %s", name)
+
+    def get(self, name: str) -> BaseTool | None:
+        return self._tools.get(name)
+
+    def definitions(self) -> list[ToolDefinition]:
+        return [t.definition for t in self._tools.values()]
+
+    def schemas(self) -> list[dict[str, Any]]:
+        return [t.schema() for t in self._tools.values()]
+
+    def dispatch(self, name: str, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        tool = self.get(name)
+        if tool is None:
+            return ToolResult.fail(f"unknown tool: {name}")
+        try:
+            return tool.execute(args, ctx)
+        except Exception as exc:  # noqa: BLE001 - tools must not crash the runtime
+            log.exception("tool %s raised", name)
+            return ToolResult.fail(f"tool '{name}' crashed: {exc}")

package/src/reidx/tools/shell_tool.py

@@ -0,0 +1,75 @@
+"""Shell tool: controlled command execution.
+
+Gated by the policy engine (command allowlist/denylist + mode). Uses subprocess with
+a timeout, captures stdout/stderr, and returns a structured ToolResult. Shell is
+treated as HIGH risk by default — in balanced/strict modes the user is prompted.
+"""
+from __future__ import annotations
+
+import subprocess
+from typing import Any
+
+from reidx.policy.models import PermissionDecision, RiskLevel
+from reidx.tools.base import BaseTool, ToolContext, ToolDefinition, ToolResult
+
+_PARAMS = {
+    "type": "object",
+    "properties": {
+        "command": {"type": "string", "description": "Shell command to execute."},
+        "cwd": {"type": "string", "description": "Working directory. Defaults to workspace root."},
+    },
+    "required": ["command"],
+}
+
+
+class RunCommandTool(BaseTool):
+    @property
+    def definition(self) -> ToolDefinition:
+        return ToolDefinition(
+            name="run_command",
+            description="Run a shell command with policy approval and timeout.",
+            parameters=_PARAMS,
+            risk=RiskLevel.HIGH,
+        )
+
+    def execute(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        command = str(args.get("command", "")).strip()
+        if not command:
+            return ToolResult.fail("empty command")
+        decision = ctx.policy.check_command(command)
+        if decision is PermissionDecision.DENY:
+            return ToolResult.fail(f"command blocked by policy: {command}")
+        if decision is PermissionDecision.PROMPT:
+            if ctx.resolve_decision(f"Run command? `{command}`") is PermissionDecision.DENY:
+                return ToolResult.fail("command denied by user")
+
+        cwd = str(args.get("cwd", "")) or str(ctx.workspace_root)
+        timeout = ctx.policy.config.policy.shell_timeout_seconds
+        try:
+            proc = subprocess.run(
+                command,
+                shell=True,
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            return ToolResult.fail(f"command timed out after {timeout}s")
+        except OSError as exc:
+            return ToolResult.fail(f"failed to spawn: {exc}")
+        out = proc.stdout
+        if proc.stderr:
+            out += ("\n--- stderr ---\n" + proc.stderr) if out else proc.stderr
+        ok = proc.returncode == 0
+        return ToolResult(
+            ok=ok,
+            output=out.rstrip(),
+            error="" if ok else f"exit code {proc.returncode}",
+            data={"exit_code": proc.returncode},
+        )
+
+
+def register_shell_tool(registry) -> None:  # type: ignore[no-untyped-def]
+    registry.register(RunCommandTool())

package/src/reidx/tools/spawn_agent.py

@@ -0,0 +1,185 @@
+"""spawn_agent tool: run a child Agent with an inline system prompt and a
+scoped tool allowlist.
+
+Design (see README): child gets its own Agent + PolicyEngine, sharing the
+parent's ToolRegistry but wrapped so only the allowlisted tools are visible.
+No provider swap by default — the child inherits the parent's provider so
+switching to a local model at the top level (via `/use`) applies to child
+agents too. Optionally the caller can override provider and/or model.
+
+Lifecycle is reported to `orchestrator.subagents` (a SubagentManager) so the
+TUI panel below the status line renders one live row per active child.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from reidx.diagnostics.logger import get_logger
+from reidx.policy.engine import PolicyEngine
+from reidx.provider.base import Message
+from reidx.runtime.state import RuntimeState
+from reidx.session.models import Session
+from reidx.tools.base import BaseTool, ToolContext, ToolDefinition, ToolResult
+from reidx.tools.registry import ToolRegistry
+
+log = get_logger("reidx.tools.spawn_agent")
+
+MAX_CHILD_STEPS = 6
+DEFAULT_ALLOWED = ("read_file", "list_dir", "find_files", "grep_files")
+
+
+class SpawnAgentTool(BaseTool):
+    @property
+    def definition(self) -> ToolDefinition:
+        from reidx.policy.models import RiskLevel
+        return ToolDefinition(
+            name="spawn_agent",
+            description=(
+                "Run a specialized child agent with an inline system prompt and a "
+                "restricted tool set. Blocks until the child returns its final "
+                "text. Use for parallel research, focused review, or any task that "
+                "shouldn't pollute the main conversation. Child cannot spawn its "
+                "own subagents."
+            ),
+            parameters={
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "Short label shown in the subagent panel (e.g. 'researcher').",
+                    },
+                    "system_prompt": {
+                        "type": "string",
+                        "description": "System prompt that fully specifies the child's role and constraints.",
+                    },
+                    "task": {
+                        "type": "string",
+                        "description": "The task/user message for the child to work on.",
+                    },
+                    "tool_allowlist": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": (
+                            "Names of tools the child may call. Omit for a "
+                            "read-only default (read_file, list_dir, find_files, "
+                            "grep_files). spawn_agent itself is never available "
+                            "to the child."
+                        ),
+                    },
+                    "model": {
+                        "type": "string",
+                        "description": "Optional model override for the child (defaults to parent's).",
+                    },
+                    "provider": {
+                        "type": "string",
+                        "description": (
+                            "Optional provider name override (must be registered; "
+                            "see /providers)."
+                        ),
+                    },
+                    "max_steps": {
+                        "type": "integer",
+                        "description": f"Max tool-calling steps for the child (default {MAX_CHILD_STEPS}).",
+                    },
+                },
+                "required": ["name", "system_prompt", "task"],
+            },
+            risk=RiskLevel.MEDIUM,
+        )
+
+    def execute(self, args: dict[str, Any], ctx: ToolContext) -> ToolResult:
+        orch = ctx.extra.get("orchestrator")
+        if orch is None:
+            return ToolResult.fail("spawn_agent unavailable (no orchestrator in context)")
+
+        name = str(args.get("name") or "subagent").strip() or "subagent"
+        system_prompt = str(args.get("system_prompt") or "").strip()
+        task = str(args.get("task") or "").strip()
+        if not system_prompt or not task:
+            return ToolResult.fail("spawn_agent requires both 'system_prompt' and 'task'")
+
+        allowlist = args.get("tool_allowlist") or list(DEFAULT_ALLOWED)
+        if not isinstance(allowlist, list):
+            return ToolResult.fail("tool_allowlist must be a list of tool names")
+        # Prevent recursive spawning — deep chains of nested subagents amplify
+        # errors and blow up the panel. One layer only.
+        allowlist = [t for t in allowlist if t != "spawn_agent"]
+
+        # Build a filtered ToolRegistry so the child provider only sees the
+        # allowlisted schemas *and* the registry rejects unknown-name calls.
+        parent_tools: ToolRegistry = orch.tools
+        child_tools = ToolRegistry()
+        for tool_name in allowlist:
+            tool = parent_tools.get(tool_name)
+            if tool is None:
+                log.debug("skipping unknown tool in allowlist: %s", tool_name)
+                continue
+            child_tools.register(tool)
+
+        # Provider override (optional). Defaults to parent's active provider.
+        provider = orch.provider
+        provider_name_override = args.get("provider")
+        if provider_name_override:
+            if orch.providers is None or not orch.providers.has(provider_name_override):
+                return ToolResult.fail(f"provider '{provider_name_override}' is not registered")
+            provider = orch.providers.get(provider_name_override)
+
+        # Child policy engine is its own instance so a child in a stricter mode
+        # doesn't mutate the parent's mode. Same config, same denylist.
+        child_policy = PolicyEngine(orch.config)
+        child_policy.set_mode(orch.policy.mode)
+
+        # Lazy import to avoid the runtime→tools→runtime cycle.
+        from reidx.runtime.agent import Agent  # noqa: PLC0415
+
+        child_agent = Agent(
+            provider,
+            child_tools,
+            child_policy,
+            base_system_prompt=system_prompt,
+            context_extras={},  # child cannot see the orchestrator: no nested spawn
+        )
+
+        parent_workspace = ctx.workspace_root
+        child_session = Session(
+            title=f"subagent:{name}",
+            workspace=parent_workspace,
+            provider=getattr(provider, "name", "unknown"),
+            model=args.get("model") or (orch.state.session.model if orch.state else ""),
+            permission_mode=orch.policy.mode,
+        )
+        child_state = RuntimeState(session=child_session)
+
+        max_steps = int(args.get("max_steps") or MAX_CHILD_STEPS)
+
+        subagents = orch.subagents
+        agent_id = subagents.start(name)
+        subagents.update(agent_id, last_action=f"provider={provider.name} model={child_session.model or 'default'}")
+
+        try:
+            final_text, tool_log = child_agent.run_turn(
+                child_state,
+                task,
+                writable_roots=[r.resolve() for r in orch.config.policy.additional_writable_roots],
+                approver=ctx.approver,
+                max_steps=max_steps,
+            )
+        except Exception as exc:  # noqa: BLE001 - errors surface as tool-result failures
+            log.exception("subagent '%s' crashed", name)
+            subagents.finish(agent_id, status="error", error=str(exc))
+            return ToolResult.fail(f"subagent '{name}' crashed: {exc}")
+
+        subagents.update(agent_id, last_action=f"finished after {len(tool_log)} tool call(s)")
+        subagents.finish(agent_id, status="done")
+
+        # Return a compact summary; the panel already showed live progress.
+        header = f"[subagent:{name}] provider={provider.name} tools_used={len(tool_log)}"
+        return ToolResult.ok_(output=f"{header}\n\n{final_text}", subagent_id=agent_id, tools=tool_log)
+
+
+def register_spawn_agent(reg: ToolRegistry) -> None:
+    reg.register(SpawnAgentTool())
+
+
+# Preserve Message import in case future callers want to inspect state.messages.
+__all__ = ["SpawnAgentTool", "register_spawn_agent", "Message"]