tsugite-cli 0.14.3__tar.gz → 0.15.0__tar.gz

{tsugite_cli-0.14.3 → tsugite_cli-0.15.0}/AGENTS.md

@@ -24,6 +24,9 @@ uv run pytest --cov=tsugite --cov-report=html
 uv run black .
 uv run ruff check .
 uv run pylint tsugite
+
+# One-time: enable repo pre-commit hook (lint + format on commit)
+git config core.hooksPath .githooks
 ```
 
 ### Testing Agents

{tsugite_cli-0.14.3 → tsugite_cli-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tsugite-cli
-Version: 0.14.3
+Version: 0.15.0
 Summary: Micro-agent runner for task automation using markdown definitions
 Author: Justyn Shull
 License: GNU AFFERO GENERAL PUBLIC LICENSE

{tsugite_cli-0.14.3 → tsugite_cli-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tsugite-cli"
-version = "0.14.3"
+version = "0.15.0"
 description = "Micro-agent runner for task automation using markdown definitions"
 authors = [{ name = "Justyn Shull" }]
 requires-python = ">=3.11"
@@ -67,6 +67,7 @@ members = ["plugins/*"]
 tsugite-cli = { workspace = true }
 tsugite-tmux = { workspace = true }
 tsugite-acp = { workspace = true }
+tsugite-codex-cli = { workspace = true }
 
 [tool.ruff]
 target-version = "py311"
@@ -142,4 +143,5 @@ dev = [
   "vulture>=2.14",
   "tsugite-tmux",
   "tsugite-acp",
+  "tsugite-codex-cli",
 ]

{tsugite_cli-0.14.3 → tsugite_cli-0.15.0}/tsugite/agent_inheritance.py

@@ -1,11 +1,38 @@
 """Agent inheritance resolution for Tsugite."""
 
+import importlib.metadata
+import importlib.util
+import logging
 import os
+from dataclasses import dataclass
+from enum import Enum
+from functools import lru_cache
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set
 
 from tsugite.utils import ensure_file_exists
 
+logger = logging.getLogger(__name__)
+
+
+class AgentDirSource(Enum):
+    """Origin of an agent search directory."""
+
+    WORKSPACE = "workspace"  # caller-passed workspace agents/ (mutable)
+    PROJECT = "project"  # caller-passed project agents/ (mutable; today only http.py)
+    BUILTIN = "builtin"  # tsugite/builtin_agents/ (read-only)
+    PLUGIN = "plugin"  # plugin <pkg>/agents/ via tsugite.plugins entry-points (read-only)
+    GLOBAL = "global"  # XDG global agents/ (mutable)
+
+
+@dataclass(frozen=True)
+class AgentDir:
+    """A directory that may contain agent .md files."""
+
+    path: Path
+    source: AgentDirSource
+    readonly: bool
+
 
 def get_builtin_agents_path() -> Path:
     """Get the built-in agents directory path.
@@ -37,6 +64,113 @@ def get_global_agents_paths() -> List[Path]:
     return paths
 
 
+@lru_cache(maxsize=1)
+def get_plugin_agents_paths() -> List[Path]:
+    """Get agent directory paths contributed by installed plugins.
+
+    Scans the ``tsugite.plugins`` entry-point group; each plugin's package
+    may ship an ``agents/`` directory next to its top-level module. Plugin
+    agent dirs are treated as read-only.
+
+    Returns:
+        List of plugin-supplied agent directories (deduped, only existing dirs)
+    """
+    from tsugite.plugins import GROUP_PLUGINS
+
+    paths: List[Path] = []
+    seen: set[Path] = set()
+    try:
+        eps = importlib.metadata.entry_points(group=GROUP_PLUGINS)
+    except Exception as e:  # pragma: no cover - defensive
+        logger.debug("Failed to scan plugin entry points: %s", e)
+        return paths
+
+    for ep in eps:
+        module_name = ep.value.split(":")[0].strip()
+        top_level = module_name.split(".")[0]
+        try:
+            spec = importlib.util.find_spec(top_level)
+        except Exception:
+            spec = None
+        if spec is None or not spec.origin:
+            continue
+        agents_dir = Path(spec.origin).parent / "agents"
+        resolved = agents_dir.resolve()
+        if resolved in seen:
+            continue
+        if not agents_dir.is_dir():
+            continue
+        seen.add(resolved)
+        paths.append(agents_dir)
+    return paths
+
+
+def iter_agent_search_paths(
+    *,
+    current_agent_dir: Optional[Path] = None,
+    workspace: Optional[Any] = None,
+    extra_project_dirs: Optional[List[Path]] = None,
+    include_local_roots: bool = True,
+) -> List[AgentDir]:
+    """Yield the canonical agent-search order, deduped by resolved path.
+
+    Order:
+
+      1. workspace.agents_dir (if workspace given)
+      2. current_agent_dir / ".tsugite"
+      3. current_agent_dir / ".tsugite" / "agents"
+      4. current_agent_dir / "agents"
+      5. current_agent_dir itself (for `<name>.md` directly in cwd)
+      6. caller-supplied extra project dirs (HTTP adapter feeds per-agent dirs here)
+      7. builtin agents
+      8. XDG global agents (user agents beat plugin agents of the same name)
+      9. plugin-supplied agents
+
+    include_local_roots: when False, skip entries 2 and 5 (the bare .tsugite/
+    and cwd roots). Name-resolution callers want them so `extends: foo` finds a
+    sibling foo.md; discovery callers that glob *.md must skip them, otherwise
+    every frontmattered note in a docs/notes workspace lists as an agent.
+
+    Callers that only care about a subset filter on ``AgentDir.source``.
+    """
+    results: List[AgentDir] = []
+    seen: set[Path] = set()
+
+    def _add(path: Path, source: AgentDirSource, readonly: bool) -> None:
+        try:
+            resolved = path.resolve()
+        except (OSError, RuntimeError):
+            return
+        if resolved in seen:
+            return
+        seen.add(resolved)
+        results.append(AgentDir(path=path, source=source, readonly=readonly))
+
+    if workspace is not None and hasattr(workspace, "agents_dir"):
+        _add(workspace.agents_dir, AgentDirSource.WORKSPACE, readonly=False)
+
+    if current_agent_dir is not None:
+        if include_local_roots:
+            _add(current_agent_dir / ".tsugite", AgentDirSource.PROJECT, readonly=False)
+        _add(current_agent_dir / ".tsugite" / "agents", AgentDirSource.PROJECT, readonly=False)
+        _add(current_agent_dir / "agents", AgentDirSource.PROJECT, readonly=False)
+        if include_local_roots:
+            _add(current_agent_dir, AgentDirSource.PROJECT, readonly=False)
+
+    for extra in extra_project_dirs or []:
+        _add(extra, AgentDirSource.PROJECT, readonly=False)
+
+    _add(get_builtin_agents_path(), AgentDirSource.BUILTIN, readonly=True)
+
+    for global_dir in get_global_agents_paths():
+        _add(global_dir, AgentDirSource.GLOBAL, readonly=False)
+
+    for plugin_path in get_plugin_agents_paths():
+        _add(plugin_path, AgentDirSource.PLUGIN, readonly=True)
+
+    return results
+
+
 def find_agent_file(
     agent_ref: str,
     current_agent_dir: Path,
@@ -52,14 +186,8 @@ def find_agent_file(
     Returns:
         Path to agent file if found, None otherwise
 
-    Search order:
-    1. If path-like (contains / or .md), resolve relative to current agent
-    2. Workspace agents directory (if workspace provided)
-    3. .tsugite/{name}.md (project-local shared)
-    4. ./agents/{name}.md (project convention)
-    5. ./{name}.md (current directory)
-    6. Built-in agents directory (tsugite/builtin_agents/)
-    7. Global agent directories (XDG order)
+    Search order matches `iter_agent_search_paths`: workspace agents,
+    project-local (.tsugite/, agents/, current dir), builtin, global, plugin.
     """
     # If it looks like a path, resolve it relative to current agent
     if "/" in agent_ref or agent_ref.endswith(".md"):
@@ -71,38 +199,12 @@ def find_agent_file(
             return abs_path.resolve()
         return None
 
-    # Ensure .md extension for name-based lookup
     agent_name = agent_ref if agent_ref.endswith(".md") else f"{agent_ref}.md"
 
-    search_paths = []
-
-    # Workspace agents directory (highest priority)
-    if workspace and hasattr(workspace, "agents_dir"):
-        workspace_agents = workspace.agents_dir
-        if workspace_agents.exists():
-            search_paths.append(workspace_agents / agent_name)
-
-    # Project-local locations
-    search_paths.extend(
-        [
-            current_agent_dir / ".tsugite" / agent_name,
-            current_agent_dir / "agents" / agent_name,
-            current_agent_dir / agent_name,
-        ]
-    )
-
-    # Built-in agents directory
-    builtin_path = get_builtin_agents_path() / agent_name
-    search_paths.append(builtin_path)
-
-    # Global locations
-    for global_dir in get_global_agents_paths():
-        search_paths.append(global_dir / agent_name)
-
-    # Return first existing path
-    for path in search_paths:
-        if path.exists():
-            return path.resolve()
+    for entry in iter_agent_search_paths(current_agent_dir=current_agent_dir, workspace=workspace):
+        candidate = entry.path / agent_name
+        if candidate.exists():
+            return candidate.resolve()
 
     return None
 

{tsugite_cli-0.14.3 → tsugite_cli-0.15.0}/tsugite/agent_runner/runner.py

@@ -14,7 +14,7 @@ from tsugite.core.agent import TsugiteAgent  # noqa: E402
 from tsugite.core.executor import LocalExecutor  # noqa: E402
 from tsugite.exceptions import AgentExecutionError, is_prompt_too_long_error  # noqa: E402
 from tsugite.md_agents import AgentConfig, parse_agent_file  # noqa: E402
-from tsugite.models import resolve_effective_model  # noqa: E402
+from tsugite.models import resolve_effective_model, strip_reserved_model_kwargs  # noqa: E402
 from tsugite.options import ExecutionOptions  # noqa: E402
 from tsugite.renderer import AgentRenderer  # noqa: E402
 from tsugite.utils import is_interactive  # noqa: E402
@@ -411,6 +411,7 @@ async def _execute_agent_with_prompt(
     hook_vars: Optional[Dict[str, str]] = None,
     continue_conversation_id: Optional[str] = None,
     user_input_for_history: Optional[str] = None,
+    channel_metadata: Optional[Dict[str, Any]] = None,
 ) -> str | AgentExecutionResult:
     """Execute agent with a prepared agent.
 
@@ -491,13 +492,29 @@ async def _execute_agent_with_prompt(
     # Get model string
     model_string = _get_model_string(exec_options.model_override, agent_config)
 
-    # Merge reasoning_effort. Resolution order: explicit kwargs > override > agent config.
-    final_model_kwargs = dict(model_kwargs or {})
+    # Merge model_kwargs from the agent frontmatter first (lowest precedence), then
+    # explicit caller kwargs override. This lets agents declare e.g.
+    # `model_kwargs: {response_format: {type: json_object}}` once and have every
+    # invocation get structured output without each caller threading it through.
+    final_model_kwargs = {}
+    if hasattr(agent_config, "model_kwargs") and agent_config.model_kwargs:
+        final_model_kwargs.update(agent_config.model_kwargs)
+    final_model_kwargs.update(model_kwargs or {})
+    # Reject provider-call args (messages/model/stream) that would collide with the
+    # explicit keywords splatted alongside **model_kwargs in core/agent.py.
+    final_model_kwargs = strip_reserved_model_kwargs(final_model_kwargs)
+
+    # Resolve reasoning_effort. Precedence (highest wins): exec_options override >
+    # caller-supplied model_kwargs > agent.model_kwargs > agent.reasoning_effort field.
+    # The override is a user-facing CLI/daemon knob - it MUST beat any agent default,
+    # including one baked into agent.model_kwargs (which would otherwise shadow it).
+    # Caller kwargs and agent.model_kwargs are already in final_model_kwargs from the merge
+    # above, so only the override and the agent.reasoning_effort fallback resolve here.
     effort_override = getattr(exec_options, "reasoning_effort_override", None)
-    if "reasoning_effort" not in final_model_kwargs:
-        if effort_override:
-            final_model_kwargs["reasoning_effort"] = effort_override
-        elif hasattr(agent_config, "reasoning_effort") and agent_config.reasoning_effort:
+    if effort_override:
+        final_model_kwargs["reasoning_effort"] = effort_override
+    elif "reasoning_effort" not in final_model_kwargs:
+        if hasattr(agent_config, "reasoning_effort") and agent_config.reasoning_effort:
             final_model_kwargs["reasoning_effort"] = agent_config.reasoning_effort
 
     from tsugite.models import resolve_reasoning_effort
@@ -573,7 +590,12 @@ async def _execute_agent_with_prompt(
             # model_request event; replaying the whole thing here would clog the
             # chat bubble with noise the user never wrote.
             display_prompt = user_input_for_history or prepared.original_prompt or prepared.rendered_prompt
-            record_user_input(session_storage, display_prompt, attachments=prepared.attachments)
+            record_user_input(
+                session_storage,
+                display_prompt,
+                attachments=prepared.attachments,
+                channel_metadata=channel_metadata,
+            )
     except Exception as e:
         logger.debug("Could not open session storage for live event recording: %s", e)
         session_storage = None
@@ -743,6 +765,7 @@ def run_agent(
     attachments: Optional[List[Any]] = None,
     path_context: Optional[Any] = None,
     user_input_for_history: Optional[str] = None,
+    channel_metadata: Optional[Dict[str, Any]] = None,
 ) -> str | AgentExecutionResult:
     """Run a Tsugite agent (sync wrapper around run_agent_async).
 
@@ -793,6 +816,7 @@ def run_agent(
             attachments=attachments,
             path_context=path_context,
             user_input_for_history=user_input_for_history,
+            channel_metadata=channel_metadata,
         )
     )
 
@@ -976,6 +1000,7 @@ async def run_agent_async(
                 hook_vars=hook_vars,
                 continue_conversation_id=continue_conversation_id,
                 user_input_for_history=user_input_for_history,
+                channel_metadata=channel_metadata,
             )
         except (RuntimeError, AgentExecutionError) as e:
             err_str = str(e).lower()
@@ -1001,6 +1026,7 @@ async def run_agent_async(
                     hook_vars=hook_vars,
                     continue_conversation_id=continue_conversation_id,
                     user_input_for_history=user_input_for_history,
+                    channel_metadata=channel_metadata,
                 )
             raise
     finally:
@@ -1026,6 +1052,8 @@ _MULTISTEP_FRAMEWORK_FLAG_DEFAULTS: Dict[str, Any] = {
     "has_notify_tool": False,
     "agent_name": "",
     "can_spawn_sessions": False,
+    "can_spawn_jobs": False,
+    "can_use_pty": False,
     "is_channel_session": False,
     "active_sessions": [],
     "recent_completions": [],

{tsugite_cli-0.14.3 → tsugite_cli-0.15.0}/tsugite/agent_utils.py

@@ -134,34 +134,48 @@ def list_local_agents(base_path: Path = None) -> dict[str, List[Path]]:
         base_path: Base directory to search from (defaults to cwd)
 
     Returns:
-        Dictionary mapping location names to list of agent paths
+        Dictionary mapping location names to list of agent paths,
+        ordered: Built-in, Plugins, Current directory, .tsugite/, agents/.
     """
-    from .agent_inheritance import get_builtin_agents_path
+    from .agent_inheritance import AgentDirSource, iter_agent_search_paths
 
     if base_path is None:
         base_path = Path.cwd()
 
-    results = {}
-
-    # Add built-in agents first
-    builtin_path = get_builtin_agents_path()
-    if builtin_path.exists() and builtin_path.is_dir():
-        builtin_agents = sorted(builtin_path.glob("*.md"))
-        if builtin_agents:
-            results["Built-in"] = builtin_agents
-
-    locations = [
-        ("Current directory", base_path),
-        (".tsugite/", base_path / ".tsugite"),
-        ("agents/", base_path / "agents"),
-    ]
+    project_labels = {
+        (base_path / ".tsugite").resolve(): ".tsugite/",
+        (base_path / ".tsugite" / "agents").resolve(): ".tsugite/agents/",
+        (base_path / "agents").resolve(): "agents/",
+        base_path.resolve(): "Current directory",
+    }
+    source_labels = {
+        AgentDirSource.BUILTIN: "Built-in",
+        AgentDirSource.PLUGIN: "Plugins",
+    }
+    grouped: dict[str, List[Path]] = {}
+
+    for entry in iter_agent_search_paths(current_agent_dir=base_path):
+        if entry.source == AgentDirSource.GLOBAL:
+            continue
+        if not entry.path.exists() or not entry.path.is_dir():
+            continue
+
+        if entry.source == AgentDirSource.PROJECT:
+            label = project_labels.get(entry.path.resolve())
+        else:
+            label = source_labels.get(entry.source)
+        if label is None:
+            continue
 
-    for location_name, location_path in locations:
-        if location_path.exists() and location_path.is_dir():
-            all_md_files = sorted(location_path.glob("*.md"))
+        all_md_files = sorted(entry.path.glob("*.md"))
+        if entry.source == AgentDirSource.PROJECT:
             agent_files = [f for f in all_md_files if _is_valid_agent_file(f)]
+        else:
+            agent_files = all_md_files
 
-            if agent_files:
-                results[location_name] = agent_files
+        if agent_files:
+            grouped.setdefault(label, []).extend(agent_files)
 
-    return results
+    # Preserve historical display order: Built-in, Plugins, then project labels.
+    label_order = ["Built-in", "Plugins", "Current directory", ".tsugite/", ".tsugite/agents/", "agents/"]
+    return {label: grouped[label] for label in label_order if label in grouped}

{tsugite_cli-0.14.3 → tsugite_cli-0.15.0}/tsugite/builtin_agents/default.md

@@ -33,6 +33,8 @@ tools:
   - "@schedule"
   - "@scratchpad"
   - "@sessions"
+  - "@jobs"
+  - "@terminal"
   - "@tmux"
 auto_load_skills:
   - response-patterns
@@ -133,6 +135,59 @@ Avoid prose in `status_text` - something like "topic and status now being update
 You are managing a shared channel. When a user asks for something that would benefit from its own workstream (investigation, coding task, long-running operation), use `spawn_session()` to create a dedicated session rather than handling everything inline.
 {% endif %}
 {% endif %}
+{% if can_spawn_jobs | default(false) %}
+
+**Background Jobs**: A Job is a background sub-session with a verification loop. Use it when you want the work *checked*, not just done.
+
+- `spawn_job(prompt, acceptance_criteria=[...], max_attempts=3, notify_when="never")` — Spawn a verified Job. The worker runs in its own session pinned to your current model by default. After it finishes, a reasoning-blind verifier sub-agent grades the result against each criterion. On failure, the worker retries (up to `max_attempts`, default 3), then transitions to `stuck` for user attention.
+- `get_job(job_id)` — Snapshot any Job's state, including per-criterion verdicts (`result.ac_results`) and the worker/verifier session ids you can navigate into via `session_status`.
+- `list_jobs(session_id=..., state=..., limit=10)` — Survey Jobs across the workspace or filtered to the current session.
+
+**When to use what:**
+- **Inline** — single edit, one-shot read, small calculation. Don't spawn anything.
+- **`spawn_session`** — fire-and-forget background work; no judgment is applied to the result.
+- **`spawn_job`** — when "done" has a checkable shape (tests pass, copy satisfies criteria, refactor preserves behavior). The verification loop is the value.
+
+**Acceptance criteria**: pass each criterion as a plain string. The verifier reads them verbatim and returns per-criterion pass/fail in `result.ac_results`:
+```python
+spawn_job(
+    prompt="Refactor the agent loop to handle nested tool calls",
+    acceptance_criteria=[
+        "All existing tests still pass",
+        "Adds at least 2 new tests for nested calls",
+        "No new dependencies",
+    ],
+)
+```
+
+**Notification cost**: `notify_when` defaults to `"never"`. Set it to `"stuck"` for a wake-up only when the Job needs user intervention, or `"terminal"` for any final state. Every notification adds a turn to this conversation — prefer polling `get_job` over `notify_when="terminal"` for routine tracking.
+
+**When a Job goes `stuck`** (max_attempts verifier rejections), the user can retry-with-hint or mark-done-anyway from the UI; you usually don't need to act. If asked to diagnose, `get_job(job_id)` returns the worker session id and each `ac_results[].reason` — read those, suggest a different approach, or open the worker session via `session_status` to inspect what went wrong.
+
+**A Job spawned by the user via `/job`** appears in your conversation's job list once it resolves. You don't create the Job in that case — the user did. Your role is to make use of its result when relevant.
+{% endif %}
+{% if can_use_pty | default(false) %}
+
+## Driving PTYs
+
+A PTY is a live, interactive terminal you can spawn and drive. The session appears in the web UI's sidebar and streams output via SSE, so the user can watch what's happening too. Use it for *interactive* programs that expect a real terminal (ssh, psql, python REPL, claude, vim).
+
+- **`run()`** — one-shot commands that exit on their own (`ls`, `git status`, `python script.py`). Captures stdout/stderr/exit code in a single call. Use this 99% of the time.
+- **`pty_create()`** — interactive programs that need stdin keystrokes over time (REPLs, ssh sessions, `claude` itself). The PTY stays alive across turns until you `pty_kill` it.
+- **`tmux_*` skill** — same niche as PTY but a separate tmux server; prefer `pty_*` for new work since it has a live web UI surface. `tmux` is still appropriate for multi-pane / persistent-window workflows.
+
+Tools: `pty_create`, `pty_send_keys`, `pty_capture`, `pty_kill`, `pty_list`.
+
+Typical loop:
+```python
+term = pty_create("python3 -i")
+pty_send_keys(term["terminal_id"], "print(2 + 2)")
+print(pty_capture(term["terminal_id"], lines=5))  # see the prompt + result
+pty_kill(term["terminal_id"])
+```
+
+For escape sequences pass raw bytes with `enter=False`: `pty_send_keys(id, "\x03", enter=False)` sends Ctrl+C.
+{% endif %}
 {% if active_sessions | default([]) %}
 
 **Active Sessions:**

tsugite_cli-0.15.0/tsugite/builtin_agents/job_verifier.md

@@ -0,0 +1,58 @@
+---
+name: job_verifier
+description: Reasoning-blind verifier — judges a Job's structured summary against its acceptance criteria. Returns strict JSON. Spawned fresh per round with no parent context.
+extends: none
+max_turns: 5
+tools: [read_file, run]
+model_kwargs:
+  response_format:
+    type: json_object
+---
+
+# Job Verifier
+
+You are a reasoning-blind verifier. You receive a list of acceptance criteria
+and a work-output blob (the worker's structured summary, optionally with a
+`git diff`). You evaluate each criterion strictly: addressed by the visible
+artifacts, or not.
+
+You do not see the worker's reasoning. You do not see the parent chat. If the
+worker claims something but the artifacts don't show it, mark that criterion as
+failed.
+
+## Task
+
+{{ user_prompt }}
+
+## Output contract
+
+Your final reply MUST be strictly-valid JSON matching this schema. NO prose
+outside the JSON. NO markdown fences.
+
+```
+{
+  "ac_results": [
+    {"ac_text": "<verbatim AC>", "pass": true|false, "reason": "<one sentence>"}
+  ],
+  "overall_pass": true|false
+}
+```
+
+`overall_pass` is `true` only if every `ac_results[i].pass` is `true`.
+
+## How to verify
+
+- Read the worker's `## Summary`, `## Output` (if present), `## Acceptance
+  criteria`, and `## Artifacts` sections.
+- When the deliverable is inline text (poem, snippet, written answer), it
+  lives in `## Output`. Judge ACs about the content (length, format, contains
+  word X, syllable count, etc.) against the verbatim Output text.
+- If a PR URL or commit SHA is provided, you may inspect it via `run` (e.g.
+  `git show <sha>`, `gh pr view <url>`) when that materially affects the
+  verdict.
+- If a file path is mentioned and you doubt the change, use `read_file` to
+  confirm.
+- Do not run long-running commands or perform setup; you have a turn budget.
+- Be skeptical, not pedantic. A criterion like "tests pass" is met if the
+  worker reports a passing test run; you don't need to re-run unless evidence
+  is contradictory.

tsugite_cli-0.15.0/tsugite/builtin_agents/job_worker.md

@@ -0,0 +1,93 @@
+---
+name: job_worker
+description: Executes a Job spawned from a chat session. Drives work to a structured summary that a separate verifier grades against the Job's acceptance criteria.
+max_turns: 40
+---
+
+# Job Worker
+
+You are executing a **Job** spawned from a chat session. The user's prompt is the
+goal. A separate verifier sub-agent will judge your work against the listed
+acceptance criteria using ONLY the structured summary you produce in your final
+reply — it does not see your reasoning or this conversation. Be honest in your
+summary; the verifier sees the same artifacts you do.
+
+## Do the work BEFORE writing the summary
+
+The structured-summary contract below describes the FORMAT of your final reply,
+not a substitute for doing the work. Before composing any Summary text:
+
+- If the task requires reading, listing, executing, fetching, or modifying
+  anything, **call tools to do those things**. Do not describe work you
+  haven't actually performed.
+- If the task is purely generative (write a haiku, draft an email, answer a
+  question from existing knowledge), no tool calls are needed — the work IS
+  the text you produce, and it goes in the `## Output` section.
+- If you write a Summary like "I listed the files…" but you never called
+  `list_files`/`run`, you have fabricated the work. The verifier will catch
+  this and stuck you. For jobs with no AC the verifier is skipped, but the
+  user reads your transcript and will notice.
+
+When in doubt: use a tool. A short tool call beats a fabricated claim.
+
+## Task
+
+{{ user_prompt }}
+
+## Final-reply contract
+
+Your final reply MUST be a markdown document with these sections, in this
+order. Do not include anything outside them.
+
+```
+## Summary
+
+<2-4 lines: what you did and the outcome.>
+
+## Output
+
+<Only when the deliverable IS the content of your reply (a haiku, a written
+answer, a snippet, an analysis) rather than a file/PR/commit. Include the
+verbatim deliverable here — verbatim text, code in fenced blocks, etc.
+Omit this section entirely if the work was a file change / PR / commit.>
+
+## Acceptance criteria
+
+- <verbatim AC text>: <addressed | not addressed> — <one-line evidence (file changed, command output, link)>
+- <next AC>: ...
+
+## Artifacts
+
+- PR: <url or "none">
+- Commits: <short SHAs or "none">
+- Files changed: <comma-separated paths or "none">
+```
+
+If no acceptance criteria were provided, write the literal text `- (none)`
+under that section and nothing else. **Do NOT invent AC entries by treating
+the user's prompt as an AC** — the prompt is the goal, not a criterion.
+
+## When to use `## Output` vs `## Artifacts`
+
+- **`## Output`** — the deliverable is your written text itself. Examples:
+  poem, haiku, short story, written answer to a question, generated code
+  snippet that the user wants to read inline, summary / analysis text.
+  Include the deliverable verbatim — fenced code blocks for code, plain
+  text otherwise. The verifier evaluates this as the work product.
+- **`## Artifacts`** — the deliverable is a file change, a PR, or a commit
+  on disk. List the URLs / SHAs / paths so the verifier can find them.
+
+If a job produces both (e.g. wrote a poem AND committed it to a file),
+include both sections.
+
+## Discipline
+
+- **Do the work first, summarize second.** Never write a Summary describing
+  actions you did not actually take.
+- Do not declare an AC `addressed` you did not actually address. The verifier
+  will catch you and loop you back, wasting turns.
+- Do not invent artifacts (PR URLs, commit SHAs). If you did not commit, say so.
+- Do not invent AC entries from the prompt. Write `- (none)` when none given.
+- Keep the Summary tight — verifier reads it byte-for-byte.
+- If your deliverable is text, put it in `## Output` — the Summary alone is
+  too tight a slot for the work product, and dropping it loses information.