feat(s10_tool): add per-call tool events (v0.23.0) (#29)

Extend the Stage 10 event vocabulary with tool.call_start and
tool.call_complete so host-side log consumers can render per-call
input, outcome, and latency without reaching into pipeline state
or re-parsing the Anthropic response.

Additive: existing tool.execute_start / tool.execute_complete
summary events are preserved byte-for-byte; the new on_event
kwarg on ToolExecutor.execute_all is keyword-only and optional
(default None matches 0.22.1 semantics). Third-party ToolExecutor
implementations continue to work unchanged.

Changes:
- interface.py: ToolExecutor.execute_all gains on_event kwarg;
  export ToolEventCallback type alias.
- executors.py: SequentialExecutor + ParallelExecutor emit
  call_start before dispatch and call_complete after, with
  {tool_use_id, name, input} and {tool_use_id, name, is_error,
  duration_ms} payloads respectively.
- stage.py: ToolStage wires on_event=state.add_event so the new
  events flow through the existing event-listener path.
- 6-test suite validating sequential ordering, parallel pairing
  by tool_use_id, is_error propagation, on_event=None no-op, and
  nesting inside tool.execute_* brackets.

Full suite: 1015 passed, 18 skipped. Ruff + format clean.

Plan ref: Geny/dev_docs/20260420_3/plan/01_immediate_fixes.md PR II.

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: CocoRoF

CHANGELOG.md

@@ -4,6 +4,75 @@ All notable changes to `geny-executor` are recorded here. The format
 follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.23.0] — 2026-04-20
+
+Additive release on top of 0.22.1. Extends the Stage 10 tool event
+vocabulary with per-call events so downstream log consumers can
+render the input, outcome, and latency of individual tool calls.
+Prior to 0.23.0 only summary events (`tool.execute_start` /
+`tool.execute_complete`) were emitted, forcing hosts like Geny to
+either read pipeline-internal state or re-parse the Anthropic
+response — both brittle. The 0.23.0 contract is event-level and
+stable.
+
+No breaking changes. Existing summary events are preserved
+byte-for-byte; consumers that listen only to `tool.execute_*` see
+no behavior change. The new `on_event` kwarg on
+`ToolExecutor.execute_all` is keyword-only and optional — default
+`None` matches 0.22.1 semantics exactly. Third-party executors
+implementing `ToolExecutor` continue to work without modification
+(they simply don't emit the new events, which was their existing
+reality).
+
+### Added
+
+- **`tool.call_start`** event, fired by the default Stage 10
+  executors (`SequentialExecutor`, `ParallelExecutor`) immediately
+  before each individual dispatch. Payload:
+  `{tool_use_id, name, input}` — the full Anthropic-supplied call
+  id, tool name, and input dict. Paired with `tool.call_complete`
+  via `tool_use_id`.
+- **`tool.call_complete`** event, fired immediately after each
+  dispatch. Payload: `{tool_use_id, name, is_error, duration_ms}`.
+  Does not carry the output payload — full results remain on the
+  message bus (state) to keep the event stream bounded.
+- **`on_event` keyword-only kwarg** on
+  `ToolExecutor.execute_all(...)` (interface + both default
+  implementations). Shape: `Callable[[str, dict], None]`. The
+  default `ToolStage` wires it to `state.add_event`, preserving
+  the existing event-listener path (`state._event_listener`).
+- **`ToolEventCallback` type alias** in
+  `geny_executor.stages.s10_tool.interface`, exported alongside
+  `ToolExecutor` / `ToolRouter`.
+
+### Why
+
+Host-side log UIs (e.g., Geny's `tool_detail_formatter`) need the
+per-call input dict to render a call-by-call detail pane. The
+0.22.1 summary events omit this, and the pipeline-internal
+`pending_tool_calls` field is not a stable event contract. This
+release upgrades the contract so hosts can stop reaching into
+pipeline state. See
+`Geny/dev_docs/20260420_3/plan/01_immediate_fixes.md` (PR II) for
+the design rationale and the full event-vocabulary audit.
+
+### Tests
+
+`tests/unit/test_tool_call_events.py` (new, 6 tests):
+
+- Sequential executor emits `call_start` / `call_complete` per call,
+  in order, carrying the correct payload.
+- `is_error=True` propagates into `call_complete`.
+- `on_event=None` (omitted) is a no-op — matches 0.22.1.
+- Parallel executor emits paired `call_start` / `call_complete`
+  events keyed by `tool_use_id`; inter-pair ordering is not
+  asserted (parallelism).
+- `ToolStage` nests per-call events *inside*
+  `tool.execute_start` / `tool.execute_complete`, preserving the
+  outer bracket contract.
+
+Full suite: 1015 passed, 18 skipped.
+
 ## [0.22.1] — 2026-04-20
 
 CI hygiene patch on top of 0.22.0. No runtime behavior change — same

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "geny-executor"
-version = "0.22.1"
+version = "0.23.0"
 description = "Harness-engineered agent pipeline library with 16-stage dual-abstraction architecture, built on the Anthropic API"
 readme = "README.md"
 license = "MIT"

src/geny_executor/__init__.py

@@ -84,7 +84,7 @@
     GenyPresets,
 )
 
-__version__ = "0.22.1"
+__version__ = "0.23.0"
 
 __all__ = [
     # Core

src/geny_executor/stages/s10_tool/artifact/default/executors.py

@@ -3,10 +3,47 @@
 from __future__ import annotations
 
 import asyncio
-from typing import Any, Dict, List
+import time
+from typing import Any, Dict, List, Optional
 
 from geny_executor.tools.base import ToolContext
-from geny_executor.stages.s10_tool.interface import ToolExecutor, ToolRouter
+from geny_executor.stages.s10_tool.interface import (
+    ToolEventCallback,
+    ToolExecutor,
+    ToolRouter,
+)
+
+
+def _emit_call_start(on_event: Optional[ToolEventCallback], tc: Dict[str, Any]) -> None:
+    if on_event is None:
+        return
+    on_event(
+        "tool.call_start",
+        {
+            "tool_use_id": tc.get("tool_use_id", ""),
+            "name": tc.get("tool_name", ""),
+            "input": tc.get("tool_input", {}),
+        },
+    )
+
+
+def _emit_call_complete(
+    on_event: Optional[ToolEventCallback],
+    tc: Dict[str, Any],
+    result_dict: Dict[str, Any],
+    duration_ms: int,
+) -> None:
+    if on_event is None:
+        return
+    on_event(
+        "tool.call_complete",
+        {
+            "tool_use_id": tc.get("tool_use_id", ""),
+            "name": tc.get("tool_name", ""),
+            "is_error": bool(result_dict.get("is_error")),
+            "duration_ms": duration_ms,
+        },
+    )
 
 
 class SequentialExecutor(ToolExecutor):
@@ -25,15 +62,22 @@ async def execute_all(
         tool_calls: List[Dict[str, Any]],
         router: ToolRouter,
         context: ToolContext,
+        *,
+        on_event: Optional[ToolEventCallback] = None,
     ) -> List[Dict[str, Any]]:
         results = []
         for tc in tool_calls:
+            _emit_call_start(on_event, tc)
+            t0 = time.monotonic()
             result = await router.route(
                 tc["tool_name"],
                 tc.get("tool_input", {}),
                 context,
             )
-            results.append(result.to_api_format(tc["tool_use_id"]))
+            duration_ms = int((time.monotonic() - t0) * 1000)
+            result_dict = result.to_api_format(tc["tool_use_id"])
+            _emit_call_complete(on_event, tc, result_dict, duration_ms)
+            results.append(result_dict)
         return results
 
 
@@ -56,17 +100,24 @@ async def execute_all(
         tool_calls: List[Dict[str, Any]],
         router: ToolRouter,
         context: ToolContext,
+        *,
+        on_event: Optional[ToolEventCallback] = None,
     ) -> List[Dict[str, Any]]:
         semaphore = asyncio.Semaphore(self._max_concurrency)
 
         async def _execute_one(tc: Dict[str, Any]) -> Dict[str, Any]:
             async with semaphore:
+                _emit_call_start(on_event, tc)
+                t0 = time.monotonic()
                 result = await router.route(
                     tc["tool_name"],
                     tc.get("tool_input", {}),
                     context,
                 )
-                return result.to_api_format(tc["tool_use_id"])
+                duration_ms = int((time.monotonic() - t0) * 1000)
+                result_dict = result.to_api_format(tc["tool_use_id"])
+                _emit_call_complete(on_event, tc, result_dict, duration_ms)
+                return result_dict
 
         tasks = [_execute_one(tc) for tc in tool_calls]
         return list(await asyncio.gather(*tasks))

src/geny_executor/stages/s10_tool/artifact/default/stage.py

@@ -120,7 +120,9 @@ async def execute(self, input: Any, state: PipelineState) -> Any:
         if isinstance(router, RegistryRouter):
             router.bind_registry(self._registry)
 
-        results = await self._executor.execute_all(tool_calls, router, ctx)
+        results = await self._executor.execute_all(
+            tool_calls, router, ctx, on_event=state.add_event
+        )
 
         state.add_message("user", results)
         state.tool_results = results

src/geny_executor/stages/s10_tool/interface.py

@@ -3,11 +3,13 @@
 from __future__ import annotations
 
 from abc import abstractmethod
-from typing import Any, Dict, List
+from typing import Any, Callable, Dict, List, Optional
 
 from geny_executor.core.stage import Strategy
 from geny_executor.tools.base import ToolContext, ToolResult
 
+ToolEventCallback = Callable[[str, Dict[str, Any]], None]
+
 
 class ToolExecutor(Strategy):
     """Base interface for tool execution patterns."""
@@ -18,8 +20,24 @@ async def execute_all(
         tool_calls: List[Dict[str, Any]],
         router: ToolRouter,
         context: ToolContext,
+        *,
+        on_event: Optional[ToolEventCallback] = None,
     ) -> List[Dict[str, Any]]:
-        """Execute all pending tool calls. Returns tool_result messages."""
+        """Execute all pending tool calls. Returns tool_result messages.
+
+        ``on_event`` is an optional keyword-only callback invoked with
+        ``(event_type, data)`` for per-call observability events:
+
+        - ``tool.call_start`` — fires *before* each dispatch; carries
+          ``{"tool_use_id", "name", "input"}``.
+        - ``tool.call_complete`` — fires *after* each dispatch; carries
+          ``{"tool_use_id", "name", "is_error", "duration_ms"}``.
+
+        When ``on_event`` is ``None`` (default), no per-call events are
+        emitted and behavior matches pre-0.23.0 semantics. Third-party
+        executors implementing this protocol are not required to emit
+        these events — the kwarg is optional.
+        """
         ...