python-agent-harness 1.5.6.6__tar.gz → 1.5.6.8__tar.gz

{python_agent_harness-1.5.6.6/python_agent_harness.egg-info → python_agent_harness-1.5.6.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-agent-harness
-Version: 1.5.6.6
+Version: 1.5.6.8
 Summary: A lightweight, hackable mini-OpenCode written in Python.
 Author-email: Huming Chen <chenhuming@gmail.com>
 License-Expression: MIT
@@ -72,7 +72,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 ## Features
 
 - **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early; failed tool calls are sanitized. Transient API failures (`429` / `5xx`) retry with exponential backoff. Auth-expired codes (configurable via `AUTH_REFRESH_STATUS_CODES` in `config.py`; defaults to `[401, 502]`) trigger automatic API key re-read from config/env.
-- **Context management** — CJK-aware token estimation, per-model context windows, automatic compaction at 70% usage.
+- **Context management** — CJK-aware token estimation, per-model context windows, automatic compaction at 80% usage.
 - **Image & text attachments** — attach with `@path` (e.g. `@screenshot.png`, `@README.md`): images (PNG/JPEG/GIF/WebP, up to 20 MB) become multimodal `image_url` parts; text files are inlined. Web URLs supported for images.
 - **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Edit` (incl. unified diffs), `Write`, `Bash`, `Skill`, `Question`, `PlanExit`. Read-only tool rounds (`Read`, `Glob`, `Grep`, `Skill`) dispatch concurrently; async tools (`Bash`, `Agent`) can also run concurrently. Results always delivered in emitted order.
 - **Plan / Build modes** — plan mode is read-only except for the per-session plan file.
@@ -81,6 +81,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 - **MCP support** — optional via `[mcp]` extra. MCP tools become ordinary agent tools (`mcp__<server>__<tool>`). Supports `stdio`, `streamable-http`, and `sse` transports.
 - **Slash commands** — built-in `/init`, `/review`, `/explain`, etc., plus custom commands from `prompts/commands/*.md`.
 - **Custom agents** — switch the main agent's system prompt at runtime with `/agent`. Agent files live in `prompts/agents/*.md` and support `name:` and `exclude_tools:` frontmatter.
+- **Hooks** — shell commands on `tool.before` / `tool.after` / `agent.start` / `agent.end`: block risky tool calls, feed linter output back to the model, add per-turn context, notify on completion. See [Hooks](#hooks).
 - **Embeddable runtime boundaries** — `headless --json` for one-shot CI/scripting; `serve` for hosting apps (resident process, bidirectional protocol: multi-turn memory, mid-run Q&A, protocol-level cancel).
 
 ## Usage
@@ -140,7 +141,7 @@ Agent files are markdown (`.md`) in `prompts/agents/`. Each becomes a switchable
 - `name:` — override the agent name (defaults to file stem)
 - `exclude_tools:` — list of tool names to hide. Matches by exact name, glob (`mcp__git__*`), or `__`-delimited prefix (`mcp__git` hides `mcp__git__list_repos` but `Write` does NOT hide `TodoWrite`).
 
-**Commands vs Agents:** Commands (`/review`) are one-shot with a hardcoded kickoff and reset after run. Agents (`/agent reviewer`) persist until the next `/agent`, let the user type their own prompt, and stay active after `Ctrl-C`.
+**Commands vs Agents:** Commands (`/review`) are one-shot with a hardcoded kickoff and reset after run. Agents (`/agent reviewer`) persist until the next `/agent`, let the user type their own prompt, and stay active after `Ctrl-C`. The active agent is always shown in the status bar (`[BUILD] @reviewer ...`, `@default` for the built-in).
 
 ## Configuration
 
@@ -193,10 +194,28 @@ All LLM settings live in `~/.config/python-agent-harness/config.json`. Environme
 - **`paths.context_path` / `paths.skill_path`** — locations for context files and skills. Default: project-local `contexts/` and `skills/`.
 - **`mcp.servers`** — MCP server config (requires `[mcp]` extra). Each supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, `enabled`.
 - **`headless` / `serve`** — optional budget limits: `max_rounds` (LLM rounds) and `timeout` (wall-clock seconds). `--max-rounds` / `--timeout` override per call; `<= 0` or `null` disables. Unset = unlimited.
+- **`hooks`** — shell-command hooks; see [Hooks](#hooks).
 - **Precedence** — code defaults < config file < `OPENAI_*` env vars. Sub-agents also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
 - **Custom config** — `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG` env var.
 - **LLM logging** — request/response bodies logged as JSON to `/tmp/python-agent-harness-<date>-<id>.json`. Set `LLM_LOG_DIR` to change. Path printed at startup.
 
+### Hooks
+
+Shell commands run at four points of a run, configured under `hooks` (`config --init` writes inactive examples under `hooks._examples`; `config` lists the active ones):
+
+```json
+"hooks": {
+  "tool.before": [{ "matcher": "Bash", "command": "~/bin/guard.sh", "fail_closed": true }],
+  "tool.after":  [{ "matcher": "Edit|Write", "command": "ruff check -q . >&2 || exit 2" }],
+  "agent.start": [{ "command": "git status --short" }],
+  "agent.end":   [{ "command": "notify-send 'run finished'" }]
+}
+```
+
+- **Behavior** — the event arrives as JSON on stdin. Exit `2` from `tool.before` blocks the call (stderr is the reason); from `tool.after` it appends stderr to the result as feedback. `agent.start` stdout becomes turn context; `agent.end` is notify-only and gets `status` + `answer`; `tool.after` skips results discarded by `Ctrl-C`.
+- **Keys** — `command` (required), `matcher` (regex on the full tool name), `timeout` (default 30 s), `fail_closed` (block if the hook itself fails), `env_passthrough` (secret env vars the hook may see; others are stripped as for Bash).
+- **Safety** — failures are logged, not fed to the model (except a `fail_closed` reason), and can't crash the agent; `Ctrl-C` stops running hooks; output is capped. The payload is model-written: never `eval` it, and never print secrets (hook output reaches the model).
+
 ## Inspired by opencode
 
 Most of [opencode](https://github.com/anomalyco/opencode)'s prompts and core behaviors have been ported. The goal: retain its practical coding-agent workflow while keeping the implementation small and easy to customize.

{python_agent_harness-1.5.6.6 → python_agent_harness-1.5.6.8}/README.md

@@ -38,7 +38,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 ## Features
 
 - **FSM-driven execution** — explicit `WAIT` / `TOOL` / `TRET` / `SUPERVISE` / `DONE` / `ERRS` / `ABRT` states. Completion supervision nudges the model when it stops early; failed tool calls are sanitized. Transient API failures (`429` / `5xx`) retry with exponential backoff. Auth-expired codes (configurable via `AUTH_REFRESH_STATUS_CODES` in `config.py`; defaults to `[401, 502]`) trigger automatic API key re-read from config/env.
-- **Context management** — CJK-aware token estimation, per-model context windows, automatic compaction at 70% usage.
+- **Context management** — CJK-aware token estimation, per-model context windows, automatic compaction at 80% usage.
 - **Image & text attachments** — attach with `@path` (e.g. `@screenshot.png`, `@README.md`): images (PNG/JPEG/GIF/WebP, up to 20 MB) become multimodal `image_url` parts; text files are inlined. Web URLs supported for images.
 - **Coding tools** — `Agent`, `TodoWrite`, `Glob`, `Grep`, `Read`, `Edit` (incl. unified diffs), `Write`, `Bash`, `Skill`, `Question`, `PlanExit`. Read-only tool rounds (`Read`, `Glob`, `Grep`, `Skill`) dispatch concurrently; async tools (`Bash`, `Agent`) can also run concurrently. Results always delivered in emitted order.
 - **Plan / Build modes** — plan mode is read-only except for the per-session plan file.
@@ -47,6 +47,7 @@ Edit `~/.config/python-agent-harness/config.json` and set your `base_url`, `api_
 - **MCP support** — optional via `[mcp]` extra. MCP tools become ordinary agent tools (`mcp__<server>__<tool>`). Supports `stdio`, `streamable-http`, and `sse` transports.
 - **Slash commands** — built-in `/init`, `/review`, `/explain`, etc., plus custom commands from `prompts/commands/*.md`.
 - **Custom agents** — switch the main agent's system prompt at runtime with `/agent`. Agent files live in `prompts/agents/*.md` and support `name:` and `exclude_tools:` frontmatter.
+- **Hooks** — shell commands on `tool.before` / `tool.after` / `agent.start` / `agent.end`: block risky tool calls, feed linter output back to the model, add per-turn context, notify on completion. See [Hooks](#hooks).
 - **Embeddable runtime boundaries** — `headless --json` for one-shot CI/scripting; `serve` for hosting apps (resident process, bidirectional protocol: multi-turn memory, mid-run Q&A, protocol-level cancel).
 
 ## Usage
@@ -106,7 +107,7 @@ Agent files are markdown (`.md`) in `prompts/agents/`. Each becomes a switchable
 - `name:` — override the agent name (defaults to file stem)
 - `exclude_tools:` — list of tool names to hide. Matches by exact name, glob (`mcp__git__*`), or `__`-delimited prefix (`mcp__git` hides `mcp__git__list_repos` but `Write` does NOT hide `TodoWrite`).
 
-**Commands vs Agents:** Commands (`/review`) are one-shot with a hardcoded kickoff and reset after run. Agents (`/agent reviewer`) persist until the next `/agent`, let the user type their own prompt, and stay active after `Ctrl-C`.
+**Commands vs Agents:** Commands (`/review`) are one-shot with a hardcoded kickoff and reset after run. Agents (`/agent reviewer`) persist until the next `/agent`, let the user type their own prompt, and stay active after `Ctrl-C`. The active agent is always shown in the status bar (`[BUILD] @reviewer ...`, `@default` for the built-in).
 
 ## Configuration
 
@@ -159,10 +160,28 @@ All LLM settings live in `~/.config/python-agent-harness/config.json`. Environme
 - **`paths.context_path` / `paths.skill_path`** — locations for context files and skills. Default: project-local `contexts/` and `skills/`.
 - **`mcp.servers`** — MCP server config (requires `[mcp]` extra). Each supports `transport`, `command`, `args`, `env`, `url`, `headers`, `parallel`, `timeout`, `enabled`.
 - **`headless` / `serve`** — optional budget limits: `max_rounds` (LLM rounds) and `timeout` (wall-clock seconds). `--max-rounds` / `--timeout` override per call; `<= 0` or `null` disables. Unset = unlimited.
+- **`hooks`** — shell-command hooks; see [Hooks](#hooks).
 - **Precedence** — code defaults < config file < `OPENAI_*` env vars. Sub-agents also support `OPENAI_SUBAGENT_*` (`_BASE_URL`, `_API_KEY`, `_MODEL`).
 - **Custom config** — `--config PATH` or `PYTHON_AGENT_HARNESS_CONFIG` env var.
 - **LLM logging** — request/response bodies logged as JSON to `/tmp/python-agent-harness-<date>-<id>.json`. Set `LLM_LOG_DIR` to change. Path printed at startup.
 
+### Hooks
+
+Shell commands run at four points of a run, configured under `hooks` (`config --init` writes inactive examples under `hooks._examples`; `config` lists the active ones):
+
+```json
+"hooks": {
+  "tool.before": [{ "matcher": "Bash", "command": "~/bin/guard.sh", "fail_closed": true }],
+  "tool.after":  [{ "matcher": "Edit|Write", "command": "ruff check -q . >&2 || exit 2" }],
+  "agent.start": [{ "command": "git status --short" }],
+  "agent.end":   [{ "command": "notify-send 'run finished'" }]
+}
+```
+
+- **Behavior** — the event arrives as JSON on stdin. Exit `2` from `tool.before` blocks the call (stderr is the reason); from `tool.after` it appends stderr to the result as feedback. `agent.start` stdout becomes turn context; `agent.end` is notify-only and gets `status` + `answer`; `tool.after` skips results discarded by `Ctrl-C`.
+- **Keys** — `command` (required), `matcher` (regex on the full tool name), `timeout` (default 30 s), `fail_closed` (block if the hook itself fails), `env_passthrough` (secret env vars the hook may see; others are stripped as for Bash).
+- **Safety** — failures are logged, not fed to the model (except a `fail_closed` reason), and can't crash the agent; `Ctrl-C` stops running hooks; output is capped. The payload is model-written: never `eval` it, and never print secrets (hook output reaches the model).
+
 ## Inspired by opencode
 
 Most of [opencode](https://github.com/anomalyco/opencode)'s prompts and core behaviors have been ported. The goal: retain its practical coding-agent workflow while keeping the implementation small and easy to customize.

{python_agent_harness-1.5.6.6 → python_agent_harness-1.5.6.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-agent-harness"
-version = "1.5.6.6"
+version = "1.5.6.8"
 description = "A lightweight, hackable mini-OpenCode written in Python."
 authors = [
     {name = "Huming Chen", email = "chenhuming@gmail.com"}

{python_agent_harness-1.5.6.6 → python_agent_harness-1.5.6.8}/python_agent_harness/__init__.py

@@ -7,7 +7,7 @@ from .mcp.config import MCPConfig, MCPServerConfig
 from .mcp.manager import MCPManager
 from .session.session import Session
 
-__version__ = "1.5.6.6"
+__version__ = "1.5.6.8"
 
 __all__ = [
     "Client",

{python_agent_harness-1.5.6.6 → python_agent_harness-1.5.6.8}/python_agent_harness/core/models.py

@@ -35,6 +35,23 @@ class AgentMode(enum.Enum):
     PLAN = "plan"
 
 
+def extract_reasoning(obj: dict[str, Any]) -> str:
+    """Reasoning text from a backend response object, or "".
+
+    Backends disagree on the field name: most (DeepSeek, GLM, ...) use
+    ``reasoning_content``; Qwen uses ``reasoning``.  This is the single
+    place that knows the variants — callers (the LLM client's streaming
+    and non-streaming parsers, token estimation) must not open-code the
+    keys.  Non-string values (some backends send a list of parts) are
+    dropped, not coerced.
+    """
+    for key in ("reasoning_content", "reasoning"):
+        value = obj.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return ""
+
+
 @dataclass
 class TextPart:
     """A plain-text content part in a multimodal message."""

{python_agent_harness-1.5.6.6 → python_agent_harness-1.5.6.8}/python_agent_harness/core/token_estimator.py

@@ -12,6 +12,7 @@ import os
 import re
 
 from ..session import config
+from .models import extract_reasoning
 
 
 def is_cjk_char(c: str) -> bool:
@@ -128,8 +129,9 @@ def payload_text(system: object, messages: list[dict], tools: list[dict]) -> str
                         if isinstance(v, str):
                             buf.append(v)
                             break
-        reasoning = msg.get("reasoning_content")
-        if isinstance(reasoning, str):
+        # currently unreachable: Message.to_api() never emits reasoning (and strips it from content)
+        reasoning = extract_reasoning(msg)
+        if reasoning:
             buf.append(reasoning)
         for tc in msg.get("tool_calls") or []:
             fn = tc.get("function", {}) if isinstance(tc, dict) else {}

{python_agent_harness-1.5.6.6 → python_agent_harness-1.5.6.8}/python_agent_harness/core/tool_runner.py

@@ -97,11 +97,24 @@ class ToolRunner:
             missing = [k for k in required if k not in args]
             if missing:
                 return f"Error: {call.name} is missing required argument(s): {', '.join(missing)}"
+        hooks = getattr(loop.session, "hooks", None)  # test doubles may lack it
+        if hooks is not None:
+            blocked = hooks.before_tool(call.name, args, call.id, not loop.top_level)
+            if isinstance(blocked, str):  # not just "not None": hooks may be replaced
+                return blocked
         return loop.session.execute_tool(call.name, args, call_id=call.id)
 
     def deliver_tool_result(self, p: ToolCall, result: str) -> None:
         """Append one tool result message for call P (parent thread only)."""
         loop = self.loop
+        # tool.after: the result is final here for sync AND async tools,
+        # and delivery is sequential in call order on the loop's thread.
+        # HookRunner never raises (its own boundary): no handling here.
+        hooks = getattr(loop.session, "hooks", None)  # test doubles may lack it
+        if hooks is not None:
+            final = hooks.after_tool(p.name, p.arguments, p.id, not loop.top_level, result)
+            if isinstance(final, str):  # a replaced hooks object may return anything
+                result = final
         p.result = result
         if hasattr(loop.session, "take_diff"):
             p.diff = loop.session.take_diff(p.id)

{python_agent_harness-1.5.6.6 → python_agent_harness-1.5.6.8}/python_agent_harness/entry/cli.py

@@ -45,6 +45,9 @@ def make_session(
     settings = config.load_llm_config(config_path)
     paths = config.load_paths_config(config_path)
     mcp_config = config.load_mcp_config(config_path)
+    # validated before anything is built: an invalid hooks section stops
+    # startup (a configured guard must never be silently dropped)
+    hook_specs = config.load_hooks(config_path)
     model = model or settings["model"]
     # resolve sub-agent overrides against the EFFECTIVE main settings
     # (so a CLI/caller model override is inherited too when the
@@ -139,13 +142,10 @@ def make_session(
         llm_settings=llm_settings,
         config_path=config_path,
     )
+    session.install_hooks(hook_specs)
     if default_agent and default_agent != RESERVED_AGENT_NAME:
         ok, msg = session.switch_agent(default_agent)
-        if ok:
-            # record the applied agent so saved sessions restore it;
-            # switch_agent("default") clears it again
-            session.store.agent = default_agent
-        else:
+        if not ok:
             # A typo'd/missing default_agent must not silently start the
             # session with the built-in prompt — record the config error
             # so the TUI can surface it (see Tui.run).
@@ -319,6 +319,19 @@ def cmd_config(args: argparse.Namespace) -> int:
             )
     else:
         print('mcp: (none configured — add an "mcp" section to the config file)')
+    try:
+        hooks = config.load_hooks(args.path)
+    except ValueError as e:
+        print(f"hooks: INVALID — {e}")
+    else:
+        if hooks:
+            print("hooks:")
+            for h in hooks:
+                matcher = f" [{h.matcher.pattern}]" if h.matcher else ""
+                flags = ", fail_closed" if h.fail_closed else ""
+                print(f"  {h.event}{matcher}: {h.command} (timeout={h.timeout:g}s{flags})")
+        else:
+            print('hooks: (none configured — add a "hooks" section to the config file)')
     print(
         "subagent_llm: (inherits main)"
         if subagent_settings == settings

{python_agent_harness-1.5.6.6 → python_agent_harness-1.5.6.8}/python_agent_harness/entry/controller.py

@@ -23,8 +23,11 @@ from dataclasses import dataclass
 from typing import Any
 
 from ..core.agent import run_agent_loop
-from ..core.models import ImagePart, Message, TextPart
+from ..core.models import ImagePart, Message, TextPart, api_safe
+from ..hooks import RunStatus
 from ..io.attachments import AttachmentError, parse_at_references
+from ..io.text_filter import strip_final_check
+from ..session import config
 from ..session.session import Session
 from .view import View
 
@@ -51,6 +54,45 @@ class RunHandle:
     warnings: list[str]
 
 
+def final_answer_text(session: Any) -> str:
+    """The run's final assistant answer, TUI-filtered.
+
+    Scans the session history backwards for the last assistant message
+    whose text survives the filters (reasoning preamble and the
+    trailing [FINAL CHECK] block).  Models following the
+    task-completion rules often end with a SEPARATE assistant message
+    holding only the [FINAL CHECK] block, so a check-only message
+    strips to empty and must be skipped in favor of the real answer
+    before it.  Empty when no assistant message has visible text
+    (e.g. the run errored out).
+
+    The scan stops at THIS run's prompt -- the newest user message the
+    harness did not inject itself (nudges, plan reminders and mid-run
+    prompts are ``injected``; compaction re-adds the prompts as plain
+    user messages, so the run's own prompt is still the newest one).
+    History persists across runs (``serve``) and restored sessions
+    (``--restore``), so without the boundary a run that was cancelled
+    or died before answering reported the PREVIOUS run's answer as its
+    own -- and defeated serve's "run produced no answer" check.
+    """
+    for msg in reversed(session.last_messages):
+        role = getattr(msg, "role", None)
+        if role == "user" and not getattr(msg, "injected", False):
+            break
+        if role != "assistant":
+            continue
+        text = strip_final_check(msg.text_without_reasoning()).strip()
+        if text:
+            # api_safe: the answer is written to stdout (headless prints it
+            # verbatim; --json and serve JSON-encode it), and a lone
+            # surrogate from a restored non-UTF-8 session raised
+            # UnicodeEncodeError there — headless died before writing the
+            # result line, and serve's _write_line SWALLOWED it (it is a
+            # ValueError), reporting success with an empty stream.
+            return api_safe(text)
+    return ""
+
+
 class Controller:
     """Mediator between a ``Session`` (model) and a ``View``.
 
@@ -367,9 +409,23 @@ class Controller:
         staleness guard; the cancel event no longer blocks the
         adoption).
         """
+        hooks = getattr(self.session, "hooks", None)  # test doubles may lack it
+        answer: str | None = None
+        crashed = False
         try:
+            context = hooks.agent_start(user_msg.text()) if hooks is not None else None
+            if isinstance(context, str) and context:  # hooks may be a replaced object
+                # its own injected message BEFORE the user's: the request
+                # stays the last thing the model reads (where queued
+                # prompts expect it), and title generation / compaction
+                # skip it like other harness-injected messages
+                self.conversation_history.append(
+                    Message(
+                        role="user", content=config.HOOK_CONTEXT_HEADER + context, injected=True
+                    )
+                )
             self.conversation_history.append(user_msg)
-            run_agent_loop(
+            answer = run_agent_loop(
                 self.session,
                 messages=list(self.conversation_history),
                 top_level=True,
@@ -381,9 +437,17 @@ class Controller:
             if seq == self.session.run_generation and self.session.last_messages:
                 self.conversation_history = list(self.session.last_messages)
         except Exception as e:  # noqa: BLE001
+            crashed = True
             if seq == self.session.run_generation:
                 self.session.log(f"agent error: {e}")
         finally:
+            # every run that started gets its end event (a superseded
+            # one too -- the payload carries its own text).  agent_end
+            # never raises and returns at once (its hooks run on their
+            # own thread); answer/status are computed inside its
+            # boundary, so run_finished/restore below always run
+            if hooks is not None:
+                hooks.agent_end(user_msg.text(), lambda: self._end_outcome(seq, answer, crashed))
             if seq == self.session.run_generation:
                 # the run is done: the final assistant message is now
                 # part of the conversation history, so the view can drop
@@ -392,3 +456,46 @@ class Controller:
                 self.session.notify("run_finished")
                 if restore is not None:
                     restore()
+
+    def _end_outcome(
+        self, seq: int, raw: str | None, crashed: bool
+    ) -> tuple[str | None, RunStatus]:
+        """``(answer, status)`` for the agent.end hook."""
+        status = self._run_status(seq, raw, crashed)
+        return self._end_answer(seq, raw, status), status
+
+    def _end_answer(self, seq: int, raw: str | None, status: RunStatus) -> str | None:
+        """The ``answer`` for agent.end: what the user was shown.
+
+        The loop's raw result can carry the reasoning preamble, or be
+        only the [FINAL CHECK] block of a supervised run, so the current
+        run's answer is extracted like headless/serve do.  An ``error``
+        run reports its error text instead; a superseded run's history
+        already belongs to the next run, so only its raw result (with
+        the check block dropped) is available.
+        """
+        if status == "error":
+            return raw
+        if status == "superseded":
+            if raw is None:
+                return None
+            return strip_final_check(raw).strip() or None
+        return final_answer_text(self.session) or None
+
+    def _run_status(self, seq: int, answer: str | None, crashed: bool) -> RunStatus:
+        """How a run ended, for the agent.end hook (see ``hooks.RunStatus``).
+
+        Derived here rather than from the loop's FSM state, which
+        ``run_agent_loop`` does not expose: superseded beats cancelled
+        (a newer run clears the cancel flag); an ``Error: ...`` result
+        is how the loop reports a failed LLM request (and how the TUI
+        recognizes failures).
+        """
+        if seq != self.session.run_generation:
+            return "superseded"
+        cancel_event = getattr(self.session, "cancel_event", None)
+        if cancel_event is not None and cancel_event.is_set():
+            return "cancelled"
+        if crashed or (answer is not None and answer.startswith("Error:")):
+            return "error"
+        return "done"

{python_agent_harness-1.5.6.6 → python_agent_harness-1.5.6.8}/python_agent_harness/entry/headless.py

@@ -23,9 +23,8 @@ import threading
 from typing import Any, TextIO
 
 from ..core.models import api_safe
-from ..io.text_filter import strip_final_check
 from ..session.session import Session
-from .controller import Controller
+from .controller import Controller, final_answer_text  # noqa: F401  (re-exported)
 from .view import FilteredDeltaStream
 
 # Exec-stream protocol version: rides on every ``start`` and ``result``
@@ -156,45 +155,6 @@ def usage_snapshot(session: Any) -> dict[str, Any] | None:
     return usage
 
 
-def final_answer_text(session: Session) -> str:
-    """The run's final assistant answer, TUI-filtered.
-
-    Scans the session history backwards for the last assistant message
-    whose text survives the filters (reasoning preamble and the
-    trailing [FINAL CHECK] block).  Models following the
-    task-completion rules often end with a SEPARATE assistant message
-    holding only the [FINAL CHECK] block, so a check-only message
-    strips to empty and must be skipped in favor of the real answer
-    before it.  Empty when no assistant message has visible text
-    (e.g. the run errored out).
-
-    The scan stops at THIS run's prompt -- the newest user message the
-    harness did not inject itself (nudges, plan reminders and mid-run
-    prompts are ``injected``; compaction re-adds the prompts as plain
-    user messages, so the run's own prompt is still the newest one).
-    History persists across runs (``serve``) and restored sessions
-    (``--restore``), so without the boundary a run that was cancelled
-    or died before answering reported the PREVIOUS run's answer as its
-    own -- and defeated serve's "run produced no answer" check.
-    """
-    for msg in reversed(session.last_messages):
-        role = getattr(msg, "role", None)
-        if role == "user" and not getattr(msg, "injected", False):
-            break
-        if role != "assistant":
-            continue
-        text = strip_final_check(msg.text_without_reasoning()).strip()
-        if text:
-            # api_safe: the answer is written to stdout (headless prints it
-            # verbatim; --json and serve JSON-encode it), and a lone
-            # surrogate from a restored non-UTF-8 session raised
-            # UnicodeEncodeError there — headless died before writing the
-            # result line, and serve's _write_line SWALLOWED it (it is a
-            # ValueError), reporting success with an empty stream.
-            return api_safe(text)
-    return ""
-
-
 def _restorable_handler(previous: Any) -> Any:
     """A handler value ``signal.signal`` will accept back.