pcli-agent 0.1.0__py3-none-any.whl

pcli/tools/builtin/pip_tool.py

@@ -0,0 +1,106 @@
+"""pip_install: install Python packages via `python -m pip install`, given
+either package names/specifiers, a requirements-style file, or both."""
+
+from __future__ import annotations
+
+import sys
+
+from pcli.sandbox.base import ExecRequest
+from pcli.sandbox.subprocess_backend import RestrictedSubprocessSandbox
+from pcli.tools.base import ToolContext, ToolResult, ToolSpec
+
+_MAX_OUTPUT_CHARS = 100_000
+_DEFAULT_TIMEOUT_S = 120.0
+
+
+async def _pip_install(arguments: dict, ctx: ToolContext) -> ToolResult:
+    packages = arguments.get("packages") or []
+    requirements_file = arguments.get("requirements_file")
+    if not packages and not requirements_file:
+        return ToolResult(
+            output="Nothing to install: provide 'packages' (a list of package names/specifiers) "
+            "and/or 'requirements_file' (a path to a requirements-style file).",
+            is_error=True,
+        )
+
+    # sys.executable is pcli's own host interpreter, which only exists on the
+    # filesystem run_shell-style commands land in when the sandbox is the
+    # subprocess backend (same machine, no containment). Under the Docker
+    # backend that path doesn't resolve inside the container at all - fall
+    # back to whatever "python" the image itself provides, same as any other
+    # command sent through ctx.sandbox for that backend.
+    python_bin = sys.executable if isinstance(ctx.sandbox, RestrictedSubprocessSandbox) else "python"
+    argv = [python_bin, "-m", "pip", "install"]
+    if requirements_file:
+        argv += ["-r", requirements_file]
+    argv += list(packages)
+
+    requested_timeout_s = float(arguments.get("timeout_s", _DEFAULT_TIMEOUT_S))
+    max_timeout_s = float(ctx.guardrails.max_shell_timeout_s)
+    timeout_s = min(requested_timeout_s, max_timeout_s)
+
+    # Installing packages inherently needs network access - under the Docker
+    # backend, ExecRequest.network=False (the default everywhere else in this
+    # package) maps to --network none, which would make every install fail.
+    result = await ctx.sandbox.execute(
+        ExecRequest(command=argv, cwd=ctx.cwd, timeout_s=timeout_s, network=True)
+    )
+
+    output = result.stdout
+    if result.stderr:
+        output += f"\n--- stderr ---\n{result.stderr}"
+    if len(output) > _MAX_OUTPUT_CHARS:
+        output = output[:_MAX_OUTPUT_CHARS] + "\n[...output truncated...]"
+    if requested_timeout_s > max_timeout_s:
+        output += (
+            f"\n[pcli] Requested timeout_s={requested_timeout_s:g} was clamped to the "
+            f"guardrail limit of {max_timeout_s:g}s."
+        )
+
+    is_error = result.exit_code != 0 or result.timed_out
+    if result.timed_out:
+        output += (
+            f"\n[pcli] Suggestion: pip install timed out at timeout_s={timeout_s:g}s — retry "
+            "with a higher timeout_s (up to the guardrail ceiling) if it just needs more time "
+            "to download/build."
+        )
+
+    summary = f"[exit_code={result.exit_code}, backend={result.backend_used}]\n{output}"
+    return ToolResult(output=summary, is_error=is_error)
+
+
+PIP_INSTALL = ToolSpec(
+    name="pip_install",
+    description="Install Python package(s) via 'python -m pip install' (never a bare 'pip', "
+    "which can silently target the wrong interpreter). Give 'packages' (names/specifiers like "
+    "'requests' or 'requests==2.31.0'), 'requirements_file' (a path to a requirements.txt-style "
+    "file, passed as pip's -r), or both.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "packages": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Package names or specifiers to install, e.g. "
+                "['requests', 'numpy>=1.26'].",
+            },
+            "requirements_file": {
+                "type": "string",
+                "description": "Path to a requirements-style file (one package per line). "
+                "Relative paths resolve against the working directory.",
+            },
+            "timeout_s": {
+                "type": "number",
+                "description": f"Timeout in seconds (default {_DEFAULT_TIMEOUT_S:g}). Raise this "
+                "for large/slow installs, up to the guardrail ceiling (guardrails.toml's "
+                "limits.max_shell_timeout_s).",
+            },
+        },
+    },
+    handler=_pip_install,
+    needs_permission=True,
+    needs_sandbox=True,
+    risk_description="Installs Python package(s) via pip.",
+    guardrail_path_arg="requirements_file",
+    read_only=False,
+)

pcli/tools/builtin/shell_tool.py

@@ -0,0 +1,240 @@
+"""The builtin tools that go through the Sandbox: run_shell (blocking, the
+common case) and run_shell_background/read_background_output/
+stop_background_process (for commands with no natural end, or long enough
+that blocking the turn on them isn't worth it — see
+sandbox/subprocess_backend.py's BackgroundJob)."""
+
+from __future__ import annotations
+
+from pcli.sandbox.base import ExecRequest, SandboxSecurityError
+from pcli.sandbox.subprocess_backend import RestrictedSubprocessSandbox
+from pcli.tools.base import ToolContext, ToolResult, ToolSpec
+
+_MAX_OUTPUT_CHARS = 100_000
+_BACKGROUND_UNSUPPORTED = (
+    "Background execution is only supported by the 'subprocess' sandbox backend "
+    "(not available with the current backend)."
+)
+_UNKNOWN_JOB_SUGGESTION = (
+    "check the \"Started background job '...'\" message from when run_shell_background was "
+    "called — job ids aren't recoverable any other way."
+)
+
+
+def _timeout_suggestion(timeout_s: float, max_timeout_s: float) -> str:
+    if timeout_s < max_timeout_s:
+        return (
+            f"the command timed out at timeout_s={timeout_s:g}s. Try raising timeout_s (up to "
+            f"the guardrail ceiling of {max_timeout_s:g}s) if it just needs more time, or use "
+            "run_shell_background if it has no natural end (a dev server, a watcher) or you'd "
+            "rather keep working while it runs."
+        )
+    return (
+        f"the command timed out even at the guardrail ceiling of {max_timeout_s:g}s. Use "
+        "run_shell_background instead — it starts the command without blocking the turn, and "
+        "read_background_output lets you check on it."
+    )
+
+
+def _shell_failure_suggestion(output: str) -> str | None:
+    """Pattern-matched against a small set of failure signatures confirmed
+    from a real debugged session: the identical Windows "'pip' is not
+    recognized" and "Python was not found" (python3-vs-python) errors each
+    got hit twice in a row before the model self-corrected by trial and
+    error, and a ModuleNotFoundError happened despite an earlier pip
+    install having reported "already satisfied" - for a different Python
+    interpreter than the one actually running the script."""
+    lowered = output.lower()
+    if "'pip' is not recognized" in lowered or "pip: command not found" in lowered:
+        return "'pip' isn't directly on PATH here — use 'python -m pip' instead."
+    if "python was not found" in lowered and "microsoft store" in lowered:
+        return "this system's Python launcher is 'python', not 'python3' — retry with 'python'."
+    if "modulenotfounderror" in lowered:
+        return (
+            'a prior "pip install" succeeding doesn\'t guarantee it targeted the same '
+            'interpreter running this script — check which one is actually active: '
+            'python -c "import sys; print(sys.executable)".'
+        )
+    return None
+
+
+async def _run_shell(arguments: dict, ctx: ToolContext) -> ToolResult:
+    command = arguments["command"]
+    requested_timeout_s = float(arguments.get("timeout_s", 30))
+    max_timeout_s = float(ctx.guardrails.max_shell_timeout_s)
+    timeout_s = min(requested_timeout_s, max_timeout_s)
+    request = ExecRequest(command=command, cwd=ctx.cwd, timeout_s=timeout_s)
+    result = await ctx.sandbox.execute(request)
+
+    output = result.stdout
+    if result.stderr:
+        output += f"\n--- stderr ---\n{result.stderr}"
+    if len(output) > _MAX_OUTPUT_CHARS:
+        output = output[:_MAX_OUTPUT_CHARS] + "\n[...output truncated...]"
+    if requested_timeout_s > max_timeout_s:
+        output += (
+            f"\n[pcli] Requested timeout_s={requested_timeout_s:g} was clamped to the "
+            f"guardrail limit of {max_timeout_s:g}s. For longer-running commands, use "
+            "run_shell_background instead."
+        )
+
+    is_error = result.exit_code != 0 or result.timed_out
+    if result.timed_out:
+        output += f"\n[pcli] Suggestion: {_timeout_suggestion(timeout_s, max_timeout_s)}"
+    elif is_error:
+        suggestion = _shell_failure_suggestion(output)
+        if suggestion:
+            output += f"\n[pcli] Suggestion: {suggestion}"
+
+    summary = f"[exit_code={result.exit_code}, backend={result.backend_used}]\n{output}"
+    return ToolResult(output=summary, is_error=is_error)
+
+
+RUN_SHELL = ToolSpec(
+    name="run_shell",
+    description="Run a shell command in a sandboxed working directory and wait for it to "
+    "finish. Use for builds, tests, git, package managers, etc. For commands with no natural "
+    "end (dev servers, watchers) or that may run longer than a few minutes, use "
+    "run_shell_background instead of a very large timeout_s.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "command": {"type": "string", "description": "The shell command to run."},
+            "timeout_s": {
+                "type": "number",
+                "description": "Timeout in seconds (default 30). Raise this for commands "
+                "known to take longer, up to the guardrail ceiling (see guardrails.toml's "
+                "limits.max_shell_timeout_s).",
+            },
+        },
+        "required": ["command"],
+    },
+    handler=_run_shell,
+    needs_permission=True,
+    needs_sandbox=True,
+    risk_description="Executes an arbitrary shell command.",
+    guardrail_command_arg="command",
+    read_only=False,
+)
+
+
+async def _run_shell_background(arguments: dict, ctx: ToolContext) -> ToolResult:
+    if not isinstance(ctx.sandbox, RestrictedSubprocessSandbox):
+        return ToolResult(output=_BACKGROUND_UNSUPPORTED, is_error=True)
+    command = arguments["command"]
+    try:
+        job_id = await ctx.sandbox.start_background(
+            command=command, cwd=ctx.cwd, max_jobs=ctx.guardrails.max_background_jobs
+        )
+    except SandboxSecurityError as exc:
+        return ToolResult(output=str(exc), is_error=True)
+    return ToolResult(
+        output=f"Started background job '{job_id}': {command}\n"
+        f"Use read_background_output(job_id='{job_id}') to check on it, and "
+        f"stop_background_process(job_id='{job_id}') when you're done with it."
+    )
+
+
+RUN_SHELL_BACKGROUND = ToolSpec(
+    name="run_shell_background",
+    description="Starts a shell command in the background and returns immediately with a "
+    "job_id, instead of blocking until it finishes like run_shell. Use for long-running "
+    "commands (dev servers, watchers, long builds/installs/test suites) where you want to "
+    "keep working and check on progress later via read_background_output. Only available "
+    "when the sandbox backend is 'subprocess'.",
+    parameters={
+        "type": "object",
+        "properties": {"command": {"type": "string", "description": "The shell command to run."}},
+        "required": ["command"],
+    },
+    handler=_run_shell_background,
+    needs_permission=True,
+    needs_sandbox=True,
+    risk_description="Starts a shell command that keeps running in the background.",
+    guardrail_command_arg="command",
+    read_only=False,
+)
+
+
+async def _read_background_output(arguments: dict, ctx: ToolContext) -> ToolResult:
+    if not isinstance(ctx.sandbox, RestrictedSubprocessSandbox):
+        return ToolResult(output=_BACKGROUND_UNSUPPORTED, is_error=True)
+    job_id = arguments["job_id"]
+    max_chars = int(arguments.get("max_chars", 4000))
+    reset = bool(arguments.get("reset", False))
+    read = ctx.sandbox.read_background(job_id, max_chars=max_chars, reset=reset)
+    if read is None:
+        return ToolResult(
+            output=f"No background job with id '{job_id}'.\n[pcli] Suggestion: {_UNKNOWN_JOB_SUGGESTION}",
+            is_error=True,
+        )
+    job, new_stdout, new_stderr, has_more = read
+
+    status = "running" if job.running else f"exited (exit_code={job.exit_code})"
+    lines = [f"status: {status}"]
+    if new_stdout:
+        lines.append(f"--- new stdout ---\n{new_stdout}")
+    if new_stderr:
+        lines.append(f"--- new stderr ---\n{new_stderr}")
+    if not new_stdout and not new_stderr:
+        lines.append("(no new output since your last read)")
+    if has_more:
+        lines.append("[pcli] More output is available — call again to keep reading.")
+    return ToolResult(output="\n".join(lines))
+
+
+READ_BACKGROUND_OUTPUT = ToolSpec(
+    name="read_background_output",
+    description="Reads the stdout/stderr a background job (started via run_shell_background) "
+    "has produced since your last read of it, and whether it's still running or has exited. "
+    "Only returns new output each call — call again if the result says more is available.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "job_id": {"type": "string"},
+            "max_chars": {
+                "type": "integer",
+                "description": "Cap on characters returned per stream this call (default 4000).",
+            },
+            "reset": {
+                "type": "boolean",
+                "description": "Re-read from the beginning instead of continuing where you left off.",
+            },
+        },
+        "required": ["job_id"],
+    },
+    handler=_read_background_output,
+    needs_permission=False,
+    needs_sandbox=True,
+    plan_mode_safe=True,
+    read_only=True,
+)
+
+
+async def _stop_background_process(arguments: dict, ctx: ToolContext) -> ToolResult:
+    if not isinstance(ctx.sandbox, RestrictedSubprocessSandbox):
+        return ToolResult(output=_BACKGROUND_UNSUPPORTED, is_error=True)
+    job_id = arguments["job_id"]
+    stopped = await ctx.sandbox.stop_background(job_id)
+    if not stopped:
+        return ToolResult(
+            output=f"No background job with id '{job_id}'.\n[pcli] Suggestion: {_UNKNOWN_JOB_SUGGESTION}",
+            is_error=True,
+        )
+    return ToolResult(output=f"Stopped background job '{job_id}'.")
+
+
+STOP_BACKGROUND_PROCESS = ToolSpec(
+    name="stop_background_process",
+    description="Kills a background process started via run_shell_background.",
+    parameters={
+        "type": "object",
+        "properties": {"job_id": {"type": "string"}},
+        "required": ["job_id"],
+    },
+    handler=_stop_background_process,
+    needs_permission=True,
+    needs_sandbox=True,
+    risk_description="Kills a running background process.",
+    read_only=False,
+)

pcli/tools/builtin/subagent_tool.py

@@ -0,0 +1,146 @@
+"""spawn_subagent: lets the LLM delegate a focused sub-task to a fresh,
+independent agent loop that shares the parent's gateway/sandbox/permissions.
+
+Subagents can never spawn further subagents — this tool is always filtered
+out of the tool registry a subagent runs with, so nesting is capped at one
+level by construction, not by a runtime counter that could be bypassed.
+
+Only the subagent's final answer and tool-call count are reported back to
+the parent; its own intermediate tool calls are not individually recorded
+in the parent session (they still go through the same permission/guardrail
+gates, just aren't logged as top-level ToolInvocations). Its LLM usage IS
+folded back into cost tracking via ToolResult.extra_usage, since it's real
+spend the session total must reflect.
+"""
+
+from __future__ import annotations
+
+from pcli.tools._nested_agent import context_usage_note, run_nested_agent
+from pcli.tools.base import ToolContext, ToolResult, ToolSpec
+from pcli.tools.builtin.todo_tool import WRITE_TODOS
+
+SPAWN_SUBAGENT_TOOL_NAME = "spawn_subagent"
+
+_SUBAGENT_SYSTEM_PROMPT = (
+    "You are a subagent spawned by another AI agent (pcli) to handle one focused task. "
+    "Use the tools available to you to complete it, then give a clear, self-contained final "
+    "answer — the parent agent only sees your final text, not your intermediate steps. You "
+    "have no memory of the parent conversation beyond the task description you were given."
+)
+
+
+async def _spawn_subagent(arguments: dict, ctx: ToolContext) -> ToolResult:
+    if ctx.gateway_client is None or ctx.tool_registry is None or ctx.permission_manager is None:
+        return ToolResult(
+            output="Subagents aren't available in this context "
+            "(no gateway/tools/permissions configured).\n"
+            "[pcli] Suggestion: handle this task directly with the tools you already have "
+            "instead of delegating it.",
+            is_error=True,
+        )
+
+    task = arguments["task"]
+    allowed_tool_names = arguments.get("allowed_tools")
+    requested_max_iterations = arguments.get("max_iterations")
+    # Subagents keep this structural safety cap even in local-api mode
+    # (ctx.max_tool_iterations may be None there, meaning "unlimited" for the
+    # parent) — nesting depth/iteration count is a distinct concern from
+    # turn/cost limiting, see this module's own docstring.
+    if requested_max_iterations:
+        max_iterations = min(int(requested_max_iterations), ctx.subagent_max_iterations)
+    else:
+        max_iterations = ctx.subagent_max_iterations
+
+    def _allowed(tool: ToolSpec) -> bool:
+        if tool.name == SPAWN_SUBAGENT_TOOL_NAME:
+            return False  # subagents can never spawn further subagents
+        if (
+            allowed_tool_names is not None
+            and tool.name not in allowed_tool_names
+            and tool.name != WRITE_TODOS.name
+        ):
+            # write_todos is always let through regardless of what the calling
+            # model's allowed_tools argument specifies (same kind of
+            # structural guarantee as the spawn_subagent exclusion above) -
+            # the "use write_todos for multi-step work" instruction
+            # (_TODO_DISCIPLINE, tools/_nested_agent.py) would otherwise only
+            # ever apply when the calling model happens to remember to
+            # include it, which a small/unreliable model can't be counted on
+            # to do consistently. Harmless even when the model never touches
+            # it. Always plan_mode_safe, so this never bypasses plan mode.
+            return False
+        return not (ctx.plan_mode and not tool.plan_mode_safe)
+
+    try:
+        result = await run_nested_agent(
+            ctx,
+            system_prompt=_SUBAGENT_SYSTEM_PROMPT,
+            task=task,
+            activity_label=task,
+            allowed=_allowed,
+            max_iterations=max_iterations,
+        )
+    except Exception as exc:  # noqa: BLE001 - surface subagent failure, don't crash the parent turn
+        return ToolResult(
+            output=f"Subagent failed: {exc}\n"
+            "[pcli] Suggestion: retry with a narrower, more specific task description, or "
+            "handle it directly yourself instead of delegating.",
+            is_error=True,
+        )
+
+    result_text = result.final_text or "(subagent produced no final text output)"
+    summary = f"[subagent made {result.tool_call_count} tool call(s)]\n{result_text}"
+    if result.terminated_early:
+        summary = (
+            "[pcli] SUBAGENT DID NOT FINISH — it hit its tool-call iteration limit "
+            f"({max_iterations}) before completing the task below. Treat this as INCOMPLETE: "
+            "do not report the task as done, and verify what (if anything) was actually "
+            "produced (e.g. list_dir/read_file the expected output) before telling the user it "
+            "succeeded. If the task genuinely needs more tool calls, either raise "
+            "subagent_max_iterations via PCLI_SUBAGENT_MAX_ITERATIONS/config.toml, or split the "
+            "work into a narrower follow-up task.\n\n" + summary
+        )
+    note = context_usage_note(result)
+    if note:
+        summary += "\n\n" + note
+    return ToolResult(output=summary, is_error=result.terminated_early, extra_usage=result.usages)
+
+
+SPAWN_SUBAGENT = ToolSpec(
+    name=SPAWN_SUBAGENT_TOOL_NAME,
+    description="Delegate a focused sub-task to a fresh subagent, which runs its own "
+    "independent tool-calling loop and reports back a final answer. Use this to isolate "
+    "exploratory or multi-step work (e.g. 'research how X is implemented in this repo') "
+    "without cluttering the main conversation with intermediate tool calls. The subagent "
+    "has no memory of this conversation — give it a fully self-contained task description.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "task": {
+                "type": "string",
+                "description": "A clear, self-contained description of what the subagent should "
+                "do and what it should report back.",
+            },
+            "allowed_tools": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Optional: restrict the subagent to only these tool names. Omit "
+                "to give it the same tools available to you (it can never spawn further subagents).",
+            },
+            "max_iterations": {
+                "type": "integer",
+                "description": "Optional cap on the subagent's own tool-call iterations. There "
+                "is always a hard built-in ceiling regardless of this value (configurable via "
+                "subagent_max_iterations) - if a task genuinely needs many tool calls (running "
+                "several scripts, iterating on errors, generating a report), request a "
+                "generous number here rather than assuming the default is enough.",
+            },
+        },
+        "required": ["task"],
+    },
+    handler=_spawn_subagent,
+    needs_permission=True,
+    risk_description="Spawns a subagent that can call tools (including sandboxed ones) on its own.",
+    plan_mode_safe=True,
+    read_only=False,
+)

pcli/tools/builtin/todo_tool.py

@@ -0,0 +1,122 @@
+"""write_todos: lets the LLM maintain a structured task list for the current
+session. Each call replaces the whole list (like Claude Code's own TodoWrite)
+rather than applying incremental deltas — simpler for the model to get right
+and impossible to desync. The list lives on Session.todos, so it persists,
+exports/imports, and survives resuming a session, same as everything else."""
+
+from __future__ import annotations
+
+import difflib
+
+from pcli.session.models import TodoItem
+from pcli.tools.base import ToolContext, ToolResult, ToolSpec
+
+_STATUS_ICONS = {"pending": "[ ]", "in_progress": "[~]", "completed": "[x]"}
+
+# Below this similarity ratio, a new todo's content is treated as a
+# different task from an old one, not a reworded version of the same task —
+# see _dropped_completed_items. Threshold picked to tolerate ordinary
+# rewording (e.g. tightening a task's phrasing as it's understood better)
+# while still catching wholesale replacement with an unrelated task.
+_SIMILARITY_THRESHOLD = 0.45
+
+
+def render_todos(todos: list[TodoItem]) -> str:
+    """Real Markdown ("- " bullets) - one caller (the "resuming with
+    existing todos" system message in chat.py) renders this through
+    rich.markdown.Markdown, which needs actual list-item syntax or it
+    collapses multiple "\\n"-joined lines into one run-on paragraph. The
+    other caller (this tool's own ToolResult output) renders it as plain
+    text instead, where "- " reads fine as a literal bullet too."""
+    if not todos:
+        return "Todo list is empty."
+    lines = [f"- {_STATUS_ICONS.get(t.status, '[ ]')} {t.content}" for t in todos]
+    return "\n".join(lines)
+
+
+def _still_represented(old_content: str, new_contents: list[str]) -> bool:
+    return any(
+        difflib.SequenceMatcher(None, old_content.lower(), nc.lower()).ratio() >= _SIMILARITY_THRESHOLD
+        for nc in new_contents
+    )
+
+
+def _dropped_completed_items(old: list[TodoItem], new: list[TodoItem]) -> list[TodoItem]:
+    """Old 'completed' items with no reasonably-similar counterpart in the
+    new list — a real debugged case: a model silently replaced a todo list
+    that had 4 completed items (real, already-verified work) with 3 brand
+    new pending ones for a superficially similar but different task,
+    without any explanation, and proceeded to redo the finished work. This
+    doesn't block the update (a genuine restart is sometimes correct) — it
+    just surfaces the loss so the model can catch its own mistake."""
+    new_contents = [t.content for t in new]
+    return [t for t in old if t.status == "completed" and not _still_represented(t.content, new_contents)]
+
+
+async def _write_todos(arguments: dict, ctx: ToolContext) -> ToolResult:
+    if ctx.session is None:
+        return ToolResult(output="No session available to store todos in.", is_error=True)
+
+    raw_todos = arguments.get("todos")
+    if not isinstance(raw_todos, list):
+        return ToolResult(output="'todos' must be a list.", is_error=True)
+
+    try:
+        todos = [TodoItem(content=item["content"], status=item.get("status", "pending")) for item in raw_todos]
+    except (KeyError, TypeError) as exc:
+        return ToolResult(output=f"Invalid todo entry: {exc}", is_error=True)
+
+    in_progress_count = sum(1 for t in todos if t.status == "in_progress")
+    if in_progress_count > 1:
+        return ToolResult(
+            output="Only one todo can be 'in_progress' at a time — mark the others "
+            "'pending' or 'completed'.",
+            is_error=True,
+        )
+
+    dropped = _dropped_completed_items(ctx.session.todos, todos)
+    ctx.session.todos = todos
+    output = f"Todo list updated:\n{render_todos(todos)}"
+    if dropped:
+        lost = "; ".join(f'"{t.content}"' for t in dropped[:5])
+        output += (
+            f"\n\n[pcli] Note: {len(dropped)} previously completed item(s) no longer appear "
+            f"in this list ({lost}). If you're deliberately restarting or changing approach, "
+            "that's fine — record_decision helps track why. If not, the underlying work may "
+            "already be done and doesn't need redoing."
+        )
+    return ToolResult(output=output)
+
+
+WRITE_TODOS = ToolSpec(
+    name="write_todos",
+    description="Create or update your task list for this session. Submit the FULL current "
+    "list every time (this replaces it, it doesn't append). Use this for any multi-step "
+    "task: write the plan as pending todos before starting, mark exactly one 'in_progress' "
+    "while working on it, mark it 'completed' immediately when done, then move to the next. "
+    "This keeps the user able to see your progress and keeps you from losing track of steps.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "todos": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "content": {"type": "string", "description": "The task, in imperative form."},
+                        "status": {
+                            "type": "string",
+                            "enum": ["pending", "in_progress", "completed"],
+                        },
+                    },
+                    "required": ["content", "status"],
+                },
+            }
+        },
+        "required": ["todos"],
+    },
+    handler=_write_todos,
+    needs_permission=False,
+    plan_mode_safe=True,
+    read_only=False,
+)