premanmcp 1.1.13 → 1.1.15

package/bin/eval_templates.js

@@ -44,21 +44,23 @@ function litList(values) {
   return `[${(values || []).map((v) => lit(v)).join(", ")}]`;
 }
 
+const TOOL_NAME = /^[A-Za-z0-9_-]{1,64}$/;
+/** Frameworks whose tracing plugin records their own tools (decorate_tools.py COVERED). */
+const COVERING_FRAMEWORKS = new Set(["langchain"]);
+
 /**
- * Python literal for the named tools. Every value came from a model, so each is
- * checked here; the backend filtered the same rules, and this is the second
- * gate the templates promise ("every value the model supplied is checked").
- * Membership in the repository is not checked here -- the caller passes only
- * the entry file as `tree` -- and a file that is never loaded stays "pending",
- * which every turn reports as not visible, naming it.
+ * Python literals for the tools the wrapper watches: those carrying
+ * @preman_tool, and those a framework's tracing plugin records instead. Every
+ * value came from a model or from decorate_tools.py, so each is checked before
+ * it is quoted into the template.
  */
-function toolsLiteral(tools) {
-  const list = Array.isArray(tools) ? tools : [];
-  const pairs = list.map((tool) => {
+function decoratedLiterals(tools) {
+  const decorated = [];
+  const covered = [];
+  for (const tool of Array.isArray(tools) ? tools : []) {
     const file = String(tool?.file || "");
     const symbol = String(tool?.symbol || "");
-    // The same rules as the backend's `_tools` (flowtest/services/agent_entry_search.py),
-    // plus no control characters. `lit()` quotes everything else safely.
+    const toolName = String(tool?.tool_name || "");
     if (
       !file.endsWith(".py")
       || file.startsWith("/")
@@ -70,9 +72,20 @@ function toolsLiteral(tools) {
     if (!TOOL_SYMBOL.test(symbol)) {
       throw new TemplateError(`tool symbol ${JSON.stringify(symbol)} is not a name or Class.method`);
     }
-    return `(${lit(file)}, ${lit(symbol)})`;
-  });
-  return `[${pairs.join(", ")}]`;
+    if (!TOOL_NAME.test(toolName)) {
+      throw new TemplateError(`tool name ${JSON.stringify(toolName)} is not a name a model can call`);
+    }
+    const by = String(tool?.covered_by || "");
+    if (by) {
+      if (!COVERING_FRAMEWORKS.has(by)) {
+        throw new TemplateError(`no tracing plugin records ${JSON.stringify(by)} tools`);
+      }
+      covered.push(`(${lit(file)}, ${lit(symbol)}, ${lit(toolName)}, ${lit(by)})`);
+    } else {
+      decorated.push(`(${lit(file)}, ${lit(symbol)}, ${lit(toolName)})`);
+    }
+  }
+  return { decorated: `[${decorated.join(", ")}]`, covered: `[${covered.join(", ")}]` };
 }
 
 // ── The parts every wrapper shares ──────────────────────────────────────
@@ -144,46 +157,90 @@ def preman_selfcheck() -> str:
 `;
 
 /**
- * Tool capture for the Python shapes (docs/superpowers/specs/2026-09-30-tool-call-capture-design.md §4).
+ * Tool capture for the Python shapes (docs/superpowers/specs/2026-10-04-tool-decorators-design.md §6).
  *
- * Each named tool function is replaced, once, by a recording version -- in its
- * own module, in every loaded module holding the same object (`from x import
- * f`), in module-level dicts and lists holding it, and on the class for a
- * method. Replacing once rather than per turn is what keeps concurrent cases
- * from racing each other's swaps.
- *
- * A turn's calls go into a context variable set in `chat()`. assert-ai runs a
- * synchronous `chat` through `asyncio.to_thread`, which copies the context, so
- * concurrent cases stay separate without a lock. A call made in a thread the
- * agent starts itself sees no turn; it is not guessed onto one -- every turn
- * open at that moment is reported not visible instead.
+ * The tools record themselves: @preman_tool in the agent's own code creates a
+ * TOOL span per call, which the harness collects. This file only checks that
+ * every named tool still carries its decorator, and decides whether a turn's
+ * count can be trusted: a tool run in another process, in a thread still
+ * running when the reply comes back, or outside any turn would be missed or
+ * filed under the wrong turn, so such a turn is "not visible", never "recorded".
  */
-const PY_CAPTURE = String.raw`
+const PY_DECORATED = String.raw`
+import asyncio
+import concurrent.futures
 import contextvars
 import functools
 import inspect
-import json
+import math
+import os
 import threading
 import time
 
-_TOOLS = %%TOOLS%%
-_turn_calls = contextvars.ContextVar("preman_turn_calls", default=None)
+# (file, symbol, tool name) for each tool carrying @preman_tool, and
+# (file, symbol, tool name, framework) for each tool a framework's tracing
+# plugin records instead.
+_DECORATED = %%DECORATED%%
+_COVERED = %%COVERED%%
+# Set when the customer declined the decorators: every turn says why.
+_NOT_RECORDED = %%NOT_RECORDED%%
+
+_FRAMEWORK_PLUGINS = {
+    "langchain": ("openinference.instrumentation.langchain", "LangChainInstrumentor"),
+}
+
+_turn_state = contextvars.ContextVar("preman_turn_state", default=None)
+_local = threading.local()
+_patched = []
 _open_turns = {}
 _open_lock = threading.Lock()
 _stray_calls = []
-_installed = []
+_watched = []
+_watched_keys = []
 _missing = {}
 _pending = {}
-_unsupported = {}
+
+# An async entry point returns a coroutine. It runs on this one loop, kept for
+# the whole run because an agent object can hold clients tied to the loop that
+# created them, on its own thread so concurrent cases can all wait on it.
+# Started here, before any turn, so the thread rules never count it as the
+# agent's work outliving a turn.
+_async_loop = asyncio.new_event_loop()
+threading.Thread(target=_async_loop.run_forever, name="preman-async-entry", daemon=True).start()
+
+
+def _settle(value):
+    if not inspect.isawaitable(value):
+        return value
+    # The turn state is a context variable; the task gets a copy so the tools
+    # it calls are counted in this turn.
+    context = contextvars.copy_context()
+    done = concurrent.futures.Future()
+
+    async def awaited():
+        return await value
+
+    def finished(task):
+        if task.cancelled():
+            done.cancel()
+        elif task.exception() is not None:
+            done.set_exception(task.exception())
+        else:
+            done.set_result(task.result())
+
+    def start():
+        _async_loop.create_task(awaited(), context=context).add_done_callback(finished)
+
+    _async_loop.call_soon_threadsafe(start)
+    return done.result()
 _install_lock = threading.Lock()
+_HIDDEN = "a module named preman in this project hides PreMan's recorder"
 
 
 def _tool_module(file):
     # Only a module that is already loaded, found by the file it came from.
     # Importing it here under a name guessed from its path would run the
-    # customer's module-level code a second time, as a second copy the agent
-    # never calls -- the copy that got wrapped would then see no calls at all.
-    # A file that is not loaded yet is left pending and retried next turn.
+    # customer's module-level code a second time.
     if (_REPO / file).resolve() == _SRC.resolve():
         return _agent()
     wanted = (_REPO / file).resolve()
@@ -198,251 +255,289 @@ def _tool_module(file):
     return None
 
 
-def _jsonable(value):
-    return json.loads(json.dumps(value, ensure_ascii=False, default=str))
+def _resolve(mod, symbol):
+    owner_name, _, method = symbol.partition(".")
+    owner = getattr(mod, owner_name, None)
+    if owner is None or not method:
+        return owner
+    raw = inspect.getattr_static(owner, method, None)
+    if isinstance(raw, property):
+        raw = raw.fget
+    return getattr(raw, "__func__", raw)  # staticmethod / classmethod
 
 
-def _record(name, original, args, kwargs, result):
-    """Build and file the event. Must never raise into the caller ('recorded()',
-    which is standing in for the agent's own call) -- capture failing is not
-    allowed to change what the agent sees. 'default=str' covers values json
-    does not know how to serialise, but not dict keys (a tuple key) or a
-    container that contains itself, both of which raise out of 'json.dumps'
-    regardless. Each of those falls back to 'repr()'; if even that raises, the
-    call is simply not recorded rather than recorded wrong or crashing the turn.
-    """
+def _listed(preman, file, tool_name):
+    # None: no @preman_tool("tool_name") ran in that file. False: one ran above
+    # an object-returning decorator.
+    wanted = str((_REPO / file).resolve())
+    found = [placed for where, name, placed in preman.decorated() if where == wanted and name == tool_name]
+    return all(found) if found else None
+
+
+def _observer(event, name, detail):
+    # Called by preman.tool around each recorded call, in the caller's context.
+    turn = _turn_state.get()
+    with _open_lock:
+        if turn is None or turn["closed"]:
+            _stray_calls.append(time.monotonic())
+            return
+        if event == "start":
+            turn["open"] += 1
+        elif event == "end":
+            turn["open"] -= 1
+        elif event == "broken":
+            turn["broken"].append("%s (%s)" % (name, detail))
+
+
+def _framework_traced(framework):
+    module_name, cls_name = _FRAMEWORK_PLUGINS.get(framework, ("", ""))
+    cls = getattr(sys.modules.get(module_name), cls_name, None)
     try:
-        try:
-            bound = inspect.signature(original).bind(*args, **kwargs).arguments
-            tool_args = {k: v for k, v in bound.items() if k not in ("self", "cls")}
-        except Exception:
-            tool_args = {"args": list(args), "kwargs": dict(kwargs)}
-        if isinstance(result, str):
-            content = result
-        elif inspect.isgenerator(result):
-            content = "<generator>"
-        else:
-            try:
-                content = json.dumps(result, ensure_ascii=False, default=str)
-            except Exception:
-                content = repr(result)
-        try:
-            args_out = _jsonable(tool_args)
-        except Exception:
-            args_out = {str(k): repr(v) for k, v in tool_args.items()}
-        event = {
-            "role": "tool_result",
-            "tool_name": name,
-            "tool_args": args_out,
-            "content": content,
-        }
+        return bool(cls is not None and cls().is_instrumented_by_opentelemetry)
     except Exception:
-        with _open_lock:
-            _stray_calls.append(time.monotonic())
-        return
+        return False
+
 
-    calls = _turn_calls.get()
-    if calls is None:
+def _thread_wait():
+    # How long a turn waits for threads it started that are still running.
+    try:
+        value = float(os.environ.get("PREMAN_THREAD_WAIT", "1"))
+    except ValueError:
+        return 1.0
+    return max(0.0, value) if math.isfinite(value) else 1.0  # "inf" would hang the case
+
+
+def _track(fn):
+    # (carried over from the earlier wrapper) fn, set to run in a copy of the caller's
+    # context -- so a tool it calls files under the caller's turn, and its span
+    # under the caller's span -- and counted against that turn until it finishes.
+    ctx = contextvars.copy_context()
+    turn = _turn_state.get()
+    if turn is not None:
         with _open_lock:
-            _stray_calls.append(time.monotonic())
-    else:
-        calls.append(event)
+            turn["pending"] += 1
+    done = []
 
+    def finish():
+        if turn is not None and not done:
+            done.append(True)
+            with _open_lock:
+                turn["pending"] -= 1
 
-def _error_text(exc):
-    # str(exc) runs the agent's own __str__, which may itself raise; a new
-    # error here would replace the tool's exception before it is re-raised.
-    name = type(exc).__name__
+    def run(*args, **kwargs):
+        try:
+            return ctx.run(fn, *args, **kwargs)
+        finally:
+            finish()
+
+    run.__preman_finish__ = finish
+    return run
+
+
+def _repo_code(thread):
+    # NEW (hooks design §7.1): a thread whose code lives in a library
+    # (braintrust's log publisher, LangSmith, Sentry, an OTel exporter) is not
+    # the agent's work, and many run for the life of the process. Unknown code
+    # counts as the agent's. site-packages is checked because a .venv often
+    # lives inside the repository.
+    fn = getattr(thread, "_target", None) or type(thread).run
+    fn = getattr(fn, "func", fn)        # functools.partial
+    fn = getattr(fn, "__func__", fn)    # bound method
     try:
-        return "error: %s: %s" % (name, exc)
+        fn = inspect.unwrap(fn)         # @preman_tool's closure lives outside the repo
     except Exception:
         pass
-    try:
-        return "error: %s: %r" % (name, exc)
-    except Exception:
-        return "error: %s" % name
-
+    code = getattr(fn, "__code__", None)
+    if code is None:
+        return True
+    path = Path(code.co_filename).resolve()
+    if "site-packages" in path.parts or "dist-packages" in path.parts:
+        return False
+    return _REPO in path.parents
+
+
+def _patch_threads():
+    # (carried over from the earlier wrapper except where marked)
+    import concurrent.futures
+    import multiprocessing.pool
+    import multiprocessing.process
+
+    pool_submit = concurrent.futures.ThreadPoolExecutor.submit
+
+    @functools.wraps(pool_submit)
+    def submit(self, fn, /, *args, **kwargs):
+        run = _track(fn)
+        before = getattr(_local, "in_submit", False)
+        _local.in_submit = True
+        try:
+            return pool_submit(self, run, *args, **kwargs)
+        except BaseException:
+            run.__preman_finish__()
+            raise
+        finally:
+            _local.in_submit = before
+
+    thread_start = threading.Thread.start
+
+    @functools.wraps(thread_start)
+    def start(self):
+        # CHANGED: _turn_state instead of the removed _turn_calls, and library
+        # threads are left alone.
+        if (_turn_state.get() is None or getattr(_local, "in_submit", False)
+                or not _repo_code(self)):
+            return thread_start(self)
+        original = self.run
+        self.run = _track(original)
+        try:
+            return thread_start(self)
+        except BaseException:
+            self.run.__preman_finish__()
+            self.run = original
+            raise
 
-def _recording(name, original):
-    if inspect.iscoroutinefunction(original):
+    def flagging(original):
         @functools.wraps(original)
-        async def recorded(*args, **kwargs):
-            try:
-                result = await original(*args, **kwargs)
-            except BaseException as exc:
-                _record(name, original, args, kwargs, _error_text(exc))
-                raise
-            _record(name, original, args, kwargs, result)
-            return result
-    else:
-        @functools.wraps(original)
-        def recorded(*args, **kwargs):
-            try:
-                result = original(*args, **kwargs)
-            except BaseException as exc:
-                _record(name, original, args, kwargs, _error_text(exc))
-                raise
-            _record(name, original, args, kwargs, result)
-            return result
-    recorded.__preman_original__ = original
-    return recorded
-
-
-def _replace_everywhere(original, recorded):
-    for mod in list(sys.modules.values()):
-        try:
-            space = getattr(mod, "__dict__", None)
-            if not isinstance(space, dict):
-                continue
-            for key, value in list(space.items()):
-                if value is original:
-                    space[key] = recorded
-                elif isinstance(value, dict):
-                    for inner, item in list(value.items()):
-                        if item is original:
-                            value[inner] = recorded
-                elif isinstance(value, list):
-                    for index, item in enumerate(value):
-                        if item is original:
-                            value[index] = recorded
-        except Exception:
-            # One odd entry in sys.modules (a proxy whose __dict__ or .items()
-            # raises) must not fail the whole install and take every other
-            # tool down with it.
-            continue
+        def sent(self, *args, **kwargs):
+            turn = _turn_state.get()
+            if turn is not None and not isinstance(self, multiprocessing.pool.ThreadPool):
+                turn["process"] = True
+            return original(self, *args, **kwargs)
+        return sent
+
+    concurrent.futures.ThreadPoolExecutor.submit = submit
+    threading.Thread.start = start
+    for owner, name in (
+        (concurrent.futures.ProcessPoolExecutor, "submit"),
+        (multiprocessing.pool.Pool, "apply_async"),
+        (multiprocessing.pool.Pool, "_map_async"),
+        (multiprocessing.pool.Pool, "imap"),
+        (multiprocessing.pool.Pool, "imap_unordered"),
+        (multiprocessing.process.BaseProcess, "start"),
+    ):
+        setattr(owner, name, flagging(getattr(owner, name)))
 
 
 def _install():
-    # Serialized, and the agent loaded first, unconditionally, inside the
-    # lock -- PY_LOADER's own _agent() has no lock of its own, so two threads
-    # reaching it at once can each exec_module a distinct module object, and
-    # whichever one _turn() ends up calling is not reliably the one whose
-    # functions got wrapped below. Taking the lock here and loading the agent
-    # before touching _TOOLS means every chat() (every chat() calls _install()
-    # first) either does that one load-and-wrap or blocks until it is done, so
-    # _turn() always sees the same, already-wrapped module -- concurrent first
-    # calls included.
+    # Serialized, and the agent loaded first inside the lock, for the reason
+    # the earlier wrapper gave: concurrent first calls must all see one loaded module.
     with _install_lock:
+        if not _patched:
+            _patch_threads()
+            _patched.append(True)
         _agent()
-        for file, symbol in _TOOLS:
+        try:
+            import preman
+        except ImportError:
+            preman = None
+        # The customer's own preman.py at the top of the repo is found first.
+        hidden = preman is not None and not hasattr(preman, "_observer")
+        if preman is not None and not hidden:
+            preman._observer = _observer
+        for file, symbol, tool_name in _DECORATED:
             key = "%s:%s" % (file, symbol)
-            if key in _installed:
+            if key in _watched_keys:
                 continue
             mod = _tool_module(file)
             if mod is None:
                 _pending[key] = "module not loaded yet"
                 continue
             _pending.pop(key, None)
-            owner_name, _, method = symbol.partition(".")
-            owner = getattr(mod, owner_name, None)
-            if owner is None:
-                _missing[key] = "%s not defined" % owner_name
-                continue
-            if method:
-                if not inspect.isclass(owner):
-                    # owner_name names an instance ('support = Support()'),
-                    # not the class -- setattr on it would shadow the method
-                    # with a plain function on one object, and calling it would
-                    # raise a missing-argument TypeError the agent never had.
-                    _missing[key] = "%s.%s is not a method on a class" % (owner_name, method)
-                    continue
-                raw = inspect.getattr_static(owner, method, None)
-                if raw is None:
-                    _missing[key] = "%s has no %s" % (owner_name, method)
-                    continue
-                if isinstance(raw, (staticmethod, classmethod)):
-                    wrapped = type(raw)(_recording(method, raw.__func__))
-                elif inspect.isfunction(raw):
-                    wrapped = _recording(method, raw)
+            fn = _resolve(mod, symbol)
+            if fn is None:
+                _missing[key] = "not defined"
+            elif preman is None:
+                _missing[key] = "PreMan's recorder (preman) could not be imported in this run"
+            elif hidden:
+                _missing[key] = _HIDDEN
+            else:
+                placed = _listed(preman, file, tool_name)
+                if placed is None:
+                    _missing[key] = 'has no @preman_tool("%s")' % tool_name
+                elif not placed:
+                    _missing[key] = ('@preman_tool("%s") is above a decorator that returns an object, '
+                                     'so calls skip it; move it directly beneath that decorator' % tool_name)
                 else:
-                    # A property or other descriptor: replacing it with a
-                    # plain function would change what the attribute even is.
-                    _missing[key] = "%s.%s is not a method on a class" % (owner_name, method)
-                    continue
-                setattr(owner, method, wrapped)
-            elif not inspect.isfunction(owner):
-                # A framework tool object (LangChain/crewAI '@tool', OpenAI
-                # Agents '@function_tool'), a callable instance or a class:
-                # swapping it for a plain function would remove the attributes
-                # and type the agent relies on. Left exactly as it is.
-                _missing.pop(key, None)
-                _unsupported[key] = "not a plain function (%s)" % type(owner).__name__
-                continue
-            elif getattr(owner, "__preman_original__", None) is None:
-                _replace_everywhere(owner, _recording(owner_name, owner))
-            _missing.pop(key, None)
-            _unsupported.pop(key, None)
-            _installed.append(key)
-
-
-def _tool_names(installed):
-    return [key.split(":", 1)[1].split(".")[-1] for key in installed]
+                    _missing.pop(key, None)
+                    _watched_keys.append(key)
+                    _watched.append(tool_name)
 
 
 def _begin_turn():
-    calls = []
-    token = _turn_calls.set(calls)
+    turn = {"pending": 0, "process": False, "closed": False, "open": 0,
+            "broken": [], "started": time.monotonic()}
+    token = (_turn_state.set(turn), turn)
     marker = object()
     with _open_lock:
         _open_turns[id(marker)] = time.monotonic()
-    return token, marker, calls
+    return token, marker
 
 
-def _end_turn(token, marker, calls):
-    _turn_calls.reset(token)
+def _end_turn(token, marker):
+    state_token, turn = token
+    _turn_state.reset(state_token)
+    deadline = time.monotonic() + _thread_wait()
+    while turn["pending"] and time.monotonic() < deadline:
+        time.sleep(0.01)
     now = time.monotonic()
     with _open_lock:
+        turn["closed"] = True
+        still_running = turn["pending"] or turn["open"]
         started = _open_turns.pop(id(marker))
         stray = any(started <= t <= now for t in _stray_calls)
         oldest = min(_open_turns.values(), default=now)
         _stray_calls[:] = [t for t in _stray_calls if t >= oldest]
-    # A snapshot under the same lock _install() mutates them under, so a turn
-    # that lands between two of _install()'s steps on another thread cannot
-    # read a torn "some tools installed, matching missing entry not popped yet"
-    # state.
+        broken = list(turn["broken"])
     with _install_lock:
-        installed = list(_installed)
+        watched = list(_watched)
         missing = sorted(_missing)
-        unseen = dict(_pending)
-        unseen.update(_unsupported)
         not_watched = dict(_missing)
-        not_watched.update(unseen)
-    # "recorded" only when every named tool is installed: a tool that is not
-    # watched could have run without being seen, so a zero would not be a
-    # confirmed zero.
-    if not _TOOLS:
-        state, reason = "not_visible", "discovery named no tool functions"
-    elif not installed and not unseen:
-        state, reason = "not_visible", "no named tool function could be found"
+        not_watched.update(_pending)
+    frameworks = sorted({fw for _, _, _, fw in _COVERED})
+    untraced = [fw for fw in frameworks if not _framework_traced(fw)]
+    if _NOT_RECORDED:
+        state, reason = "not_visible", _NOT_RECORDED
+    elif not _DECORATED and not _COVERED:
+        state, reason = "not_visible", "PreMan found no tool functions in this agent"
+    elif os.environ.get("PREMAN_EVAL_TRACE") != "1":
+        state, reason = "not_visible", "tracing is switched off for this run, and @preman_tool records through it"
+    elif _DECORATED and not os.environ.get("PREMAN_EVAL_RUN"):
+        state, reason = "not_visible", "PREMAN_EVAL_RUN is not set, so @preman_tool records nothing"
     elif not_watched:
         state, reason = "not_visible", "not watched: " + "; ".join(
             "%s (%s)" % (k, v) for k, v in sorted(not_watched.items())
         )
+    elif untraced:
+        state, reason = "not_visible", "%s tools are recorded by its tracing plugin, which is not switched on in this run" % ", ".join(untraced)
+    elif broken:
+        state, reason = "not_visible", "PreMan's recorder could not record: " + "; ".join(broken)
     elif stray:
         state, reason = "not_visible", "a tool ran outside any turn, in a thread the agent started"
+    elif turn["process"]:
+        state, reason = "not_visible", "work was sent to another process, where tools are not watched"
+    elif still_running:
+        state, reason = "not_visible", "a thread started in this turn was still running when the reply came back"
     else:
         state, reason = "recorded", ""
+    covered_names = [name for _, _, name, fw in _COVERED if fw not in untraced]
     return {
         "state": state,
-        "source": "wrapped",
-        "watched": _tool_names(installed),
+        "source": "decorated",
+        "watched": watched + covered_names,
         "missing": missing,
         "reason": reason,
     }
 
 
 def preman_selfcheck() -> str:
-    # _install() first: it takes _install_lock and loads the agent itself
-    # before touching _TOOLS. Calling _target() first would load the agent
-    # outside that lock, racing a concurrent call's locked load.
     _install()
     _target()
-    # Only a missing tool fails: a pending one (its module is not loaded yet)
-    # or an unsupported one (not a plain function) is reported per turn as
-    # "not visible" instead, and the agent still runs.
+    if _HIDDEN in _missing.values():
+        raise RuntimeError(
+            _HIDDEN + ". Rename that module so PreMan can record the agent's tool calls."
+        )
     if _missing:
         raise RuntimeError(
-            "tool functions named by discovery were not found: "
+            "tool functions PreMan watches are gone or no longer carry @preman_tool: "
             + "; ".join("%s (%s)" % (k, v) for k, v in sorted(_missing.items()))
             + ". Re-run 'preman eval target'."
         )
@@ -502,15 +597,8 @@ def _text(value):
     return "" if value is None else str(value)
 `;
 
-/** `chat()` for the shapes that do not capture tool calls. */
-const PY_CHAT = String.raw`
-
-def chat(message: str, history: list | None = None) -> dict:
-    reply, events = _turn(message, history or [])
-    return {"response": _text(reply), "events": list(events or [])}
-`;
-
-/** `chat()` for `cli_subprocess`: the agent reports its own calls through a file. */
+/** `chat()` for shapes whose `_turn` returns (reply, events, tool_capture): cli_subprocess,
+ * node_bridge and langgraph. */
 const PY_CHAT_REPORTED = String.raw`
 
 def chat(message: str, history: list | None = None) -> dict:
@@ -518,21 +606,19 @@ def chat(message: str, history: list | None = None) -> dict:
     return {"response": _text(reply), "events": list(events or []), "tool_capture": capture}
 `;
 
-/** `chat()` for the Python shapes: the turn runs inside a capture window. */
-const PY_CHAT_CAPTURING = String.raw`
+/** `chat()` for the Python shapes: the turn runs inside a capture window. The
+ * calls themselves arrive as spans; this adds no events of its own. */
+const PY_CHAT_DECORATED = String.raw`
 
 def chat(message: str, history: list | None = None) -> dict:
     _install()
-    token, marker, calls = _begin_turn()
+    token, marker = _begin_turn()
     try:
         reply, events = _turn(message, history or [])
+        reply = _settle(reply)
     finally:
-        capture = _end_turn(token, marker, calls)
-    return {
-        "response": _text(reply),
-        "events": list(events or []) + calls,
-        "tool_capture": capture,
-    }
+        capture = _end_turn(token, marker)
+    return {"response": _text(reply), "events": list(events or []), "tool_capture": capture}
 `;
 
 // ── One `_turn` per shape ───────────────────────────────────────────────
@@ -601,6 +687,8 @@ def _turn(message, history):
 # \`m.type\`, which a dict does not have -- measured: passing dicts broke a
 # fixture whose reference wrapper passed objects. The fallback below carries
 # both shapes at once so a node written either way works.
+import json
+
 try:
     from langchain_core.messages import AIMessage, HumanMessage
 
@@ -626,12 +714,109 @@ def _turn(message, history):
         messages.append(_msg(role, (item or {}).get("content", "")))
     messages.append(_msg("user", message))
     state = _target().invoke({"messages": messages})
-    return state, []
+    events, capture = _graph_calls(state)
+    return state, events, capture
+
+
+def _field(item, name):
+    return item.get(name) if isinstance(item, dict) else getattr(item, name, None)
+
+
+def _graph_calls(state):
+    # A call is a tool request (AIMessage.tool_calls) paired with its result
+    # (ToolMessage, same tool_call_id). A request with no result is not counted:
+    # nothing shows it ran. The input holds only text messages, so every pair
+    # found here happened in this turn. Paired in one pass in message order, so
+    # an id the provider reuses later in the turn still pairs each result with
+    # the request just before it.
+    messages = _field(state, "messages")
+    if not isinstance(messages, list):
+        reason = "the graph returned no messages list, so its tool calls cannot be read"
+        return [], {"state": "not_visible", "source": "langgraph", "watched": [], "missing": [], "reason": reason,
+                    "trace": {"links": "order_only", "reason": reason, "known": [], "unknown": {}, "calls": []}}
+    pending = {}  # id -> (request, trace entry) still waiting for its result
+    events, trace = [], []
+    step = 0
+    unpaired_request = unpaired_result = shared_id = False
+    for m in messages:
+        asked = _field(m, "tool_calls") or []
+        if asked:
+            step += 1  # one model message asking for tools is one step
+        for call in asked:
+            if not (isinstance(call, dict) and call.get("id")):
+                unpaired_request = True  # no id: nothing can pair it with a result
+            elif call["id"] in pending:
+                shared_id = True  # two waiting requests, one id: results can't be told apart
+            else:
+                entry = {"id": "c%d" % (len(trace) + 1), "tool": str(call.get("name") or ""), "step": step, "event": None}
+                trace.append(entry)
+                pending[call["id"]] = (call, entry)
+        if _field(m, "type") != "tool" and _field(m, "role") != "tool":
+            continue
+        found = pending.pop(_field(m, "tool_call_id"), None)
+        if found is None:
+            unpaired_result = True
+            continue
+        call, entry = found
+        entry["event"] = len(events)
+        content = _field(m, "content")
+        if not isinstance(content, str):
+            content = json.dumps(content, ensure_ascii=False, default=str)
+        args = call.get("args")
+        events.append({
+            "role": "tool_result",
+            "tool_name": str(call.get("name") or _field(m, "name") or ""),
+            "tool_args": json.loads(json.dumps(args if isinstance(args, dict) else {}, ensure_ascii=False, default=str)),
+            "content": content,
+        })
+    # Only answered calls ran; ids and steps renumbered so neither has gaps.
+    answered = [e for e in trace if e["event"] is not None]
+    steps = {}
+    for n, entry in enumerate(answered, 1):
+        entry["id"] = "c%d" % n
+        entry["step"] = steps.setdefault(entry["step"], len(steps) + 1)
+    shape = {"links": "full", "known": ["step"],
+             "unknown": {"parent": "the graph's messages do not show a tool calling another tool"},
+             "calls": answered}
+
+    def outcome(state, reason=""):
+        return events, {"state": state, "source": "langgraph", "watched": [], "missing": [],
+                        "reason": reason, "trace": shape}
+
+    if shared_id:
+        return outcome("not_visible", "the graph asked for two tools under one id at once, so their results cannot be told apart")
+    # Either half on its own means a tool may have run without being counted.
+    if unpaired_request or pending:
+        return outcome("not_visible", "the graph asked for a tool whose result is not in its messages")
+    if unpaired_result:
+        return outcome("not_visible", "a tool result in the graph's messages matches no request")
+    return outcome("recorded")
 `,
 };
 
 // ── Shapes that are not a Python import at all ──────────────────────────
 
+/** Loads the CLI's recording proxy (bin/tool_proxy.py), or None. Spec §6.0.2. */
+const PY_PROXY = String.raw`
+
+def _tool_proxy():
+    # Shipped with the CLI rather than written into this file, so a proxy fix
+    # reaches every repository without re-approving it. PREMAN_CLI_BIN is set by
+    # every CLI launch; added here because "python -c" and PYTHONSAFEPATH both
+    # leave the CLI's folder off sys.path.
+    folder = os.environ.get("PREMAN_CLI_BIN")
+    if folder and folder not in sys.path:
+        sys.path.insert(0, folder)
+    try:
+        import tool_proxy
+        # Started here so a proxy that imports but cannot start (bind error, bad
+        # PREMAN_AGENT_TIMEOUT) is "no proxy" and the agent still runs.
+        tool_proxy.shared()
+    except Exception:
+        return None
+    return tool_proxy
+`;
+
 /**
  * A JS/TS agent, over one long-lived node process.
  *
@@ -645,8 +830,10 @@ def _turn(message, history):
  */
 const NODE_BRIDGE = String.raw`
 import json
+import os
 import shutil
 import subprocess
+import sys
 import threading
 
 _REPO = Path(__file__).resolve().parent.parent
@@ -674,6 +861,8 @@ def _why() -> str:
         return ""
     if not text:
         return ""
+    if _channel:
+        text = text.replace(_channel, "<proxy>")
     for line in text.splitlines():
         stripped = line.strip()
         if "Error" in stripped and len(stripped) > 12:
@@ -700,9 +889,31 @@ def _runtime() -> str:
     )
 
 
+_proxy = None
+_channel = None
+
+
+def _proxy_off() -> bool:
+    # PREMAN_TOOL_PROXY=0 runs the agent against its own model address, unproxied.
+    return os.environ.get("PREMAN_TOOL_PROXY") == "0"
+
+
+def _proxy_channel():
+    global _proxy, _channel
+    if _channel is None and not _proxy_off():
+        module = _tool_proxy()
+        if module is not None:
+            _proxy = module
+            _channel = module.shared().channel()
+    return _channel
+
+
 def _bridge():
     global _proc
     if _proc is None or _proc.poll() is not None:
+        env = dict(os.environ)
+        if _proxy_channel():
+            env.update(_proxy.shared().env(_channel))
         _proc = subprocess.Popen(
             [_runtime(), str(_BRIDGE)],
             cwd=str(_REPO),
@@ -711,6 +922,7 @@ def _bridge():
             stderr=open(_STDERR, "w"),
             text=True,
             bufsize=1,
+            env=env,
         )
     return _proc
 
@@ -725,18 +937,53 @@ def preman_selfcheck() -> str:
     return %%ENTRY_SYMBOL%%
 
 
+def _is_tool(event):
+    return str((event or {}).get("role") or "").startswith("tool") or bool((event or {}).get("tool_name"))
+
+
 def _turn(message, history):
     with _lock:
         proc = _bridge()
-        proc.stdin.write(json.dumps({"message": message, "history": history}) + "\n")
-        proc.stdin.flush()
-        line = proc.stdout.readline()
+        if _channel:
+            _proxy.shared().begin(_channel)
+        try:
+            proc.stdin.write(json.dumps({"message": message, "history": history}) + "\n")
+            proc.stdin.flush()
+            line = proc.stdout.readline()
+        finally:
+            proxied = _proxy.shared().end(_channel) if _channel else None
         if not line:
             raise RuntimeError("the node bridge closed without answering%s" % _why())
         parsed = json.loads(line)
         if parsed.get("error"):
-            raise RuntimeError(str(parsed["error"]))
-        return parsed.get("response", ""), parsed.get("events", [])
+            message_text = str(parsed["error"])
+            raise RuntimeError(message_text.replace(_channel, "<proxy>") if _channel else message_text)
+        # A role-less event naming a tool is a tool result: given the role so it
+        # counts, displays, and is replaced by the proxy's account like one.
+        own = [
+            dict(e, role="tool_result") if isinstance(e, dict) and not e.get("role") and e.get("tool_name") else e
+            for e in parsed.get("events") or []
+        ]
+        # Returned events are the agent's own claim; an empty list cannot be told
+        # apart from an agent that does not report, so it is not a confirmed zero.
+        # Only tool events are a report: a reply with assistant messages alone
+        # says nothing about tools.
+        reports_tools = any(_is_tool(e) for e in own)
+        reported = (own, {"state": "recorded", "source": "agent", "watched": [], "missing": [], "reason": "", "proxy_version": None}) if reports_tools else None
+        if proxied is None:
+            why = "was switched off for this agent" if _proxy_off() else "could not be loaded"
+            capture = reported[1] if reported else {
+                "state": "not_visible", "source": "agent", "watched": [], "missing": [], "proxy_version": None,
+                "reason": "PreMan's tool proxy %s, and the agent did not report its tool calls" % why,
+            }
+            return parsed.get("response", ""), own, capture
+        events, capture = _proxy.choose(proxied, reported)
+        if capture.get("source") == "proxy":
+            # The proxy's account replaces only the agent's tool events; anything
+            # else it returned (its own messages, notes) is kept, in front.
+            kept = [e for e in own if not _is_tool(e)]
+            events = kept + list(events)
+        return parsed.get("response", ""), events, capture
 `;
 
 /** The node side. Also CLI-owned, for the same reason. */
@@ -790,6 +1037,7 @@ import json
 import os
 import shutil
 import subprocess
+import sys
 import tempfile
 from pathlib import Path
 
@@ -910,7 +1158,7 @@ def _read_events(path):
     """
     if not os.path.exists(path):
         return [], _not_visible("the agent did not create PREMAN_TOOL_EVENTS_FILE, so its tool calls are not reported")
-    events = []
+    events, lines = [], []
     with open(path, encoding="utf-8") as handle:
         for line in handle:
             line = line.strip()
@@ -930,15 +1178,68 @@ def _read_events(path):
                 "tool_args": args if isinstance(args, dict) else {},
                 "content": content if isinstance(content, str) else json.dumps(content, ensure_ascii=False, default=str),
             })
-    return events, {"state": "recorded", "source": "events_file", "watched": [], "missing": [], "reason": ""}
+            lines.append(item)
+    return events, {"state": "recorded", "source": "events_file", "watched": [], "missing": [], "reason": "",
+                    "trace": _file_trace(lines)}
+
+
+def _file_trace(lines):
+    """The agent's own links: 'step' and 'parent' only when every line gives them.
+    A link that cannot be checked makes the turn order-only; it is never guessed."""
+    def plain(reason):
+        return {"links": "order_only", "reason": reason, "known": [], "unknown": {},
+                "calls": [{"id": "c%d" % (i + 1), "tool": str(item["tool_name"]), "event": i}
+                          for i, item in enumerate(lines)]}
+    known = [f for f in ("step", "parent") if lines and all(f in item for item in lines)]
+    if not known:
+        return plain("the agent's events file gives no step or parent")
+    ids = [str(item.get("id") or "") for item in lines]
+    if "parent" in known:
+        if not all(ids) or len(set(ids)) != len(ids):
+            return plain("the agent's events file gives parents but not a unique id on every line")
+        for i, item in enumerate(lines):
+            if item["parent"] is not None and str(item["parent"]) not in ids[:i]:
+                return plain("the agent's events file has a parent that names no earlier call")
+    if "step" in known and not all(isinstance(item["step"], int) and not isinstance(item["step"], bool) and item["step"] >= 1 for item in lines):
+        return plain("the agent's events file has a step that is not a whole number from 1")
+    rename = {cid: "c%d" % (i + 1) for i, cid in enumerate(ids)}
+    calls = []
+    for i, item in enumerate(lines):
+        call = {"id": "c%d" % (i + 1), "tool": str(item["tool_name"]), "event": i}
+        if "step" in known:
+            call["step"] = item["step"]
+        if "parent" in known:
+            call["parent"] = None if item["parent"] is None else rename[str(item["parent"])]
+        calls.append(call)
+    return {"links": "full", "known": known,
+            "unknown": {f: "the agent's events file does not give it" for f in ("step", "parent") if f not in known},
+            "calls": calls}
+
+
+#: Commands that run the agent on another machine or in a container, where
+#: 127.0.0.1 is not this machine and the proxy cannot be reached.
+_REMOTE_LAUNCHERS = ("docker", "podman", "ssh", "kubectl")
+
+
+def _proxy_off() -> bool:
+    return os.environ.get("PREMAN_TOOL_PROXY") == "0" or os.path.basename(_ARGV[0]) in _REMOTE_LAUNCHERS
 
 
 def _turn(message, history):
     argv = [_binary()] + list(_ARGV[1:])
-    # One file per turn: each turn is its own process, so nothing can be filed
-    # under the wrong turn.
+    # One file and one proxy channel per turn: each turn is its own process, so
+    # nothing can be filed under the wrong turn.
     folder = tempfile.mkdtemp(prefix="preman-tools-")
     events_path = os.path.join(folder, "tool_events.jsonl")
+    env = dict(os.environ, PREMAN_TOOL_EVENTS_FILE=events_path)
+    switched_off = _proxy_off()
+    proxy_mod = None if switched_off else _tool_proxy()
+    proxy = proxy_mod.shared() if proxy_mod else None
+    channel = proxy.channel() if proxy else None
+    if channel:
+        env.update(proxy.env(channel))
+        proxy.begin(channel)
+    proxied = None
     try:
         done = subprocess.run(
             argv,
@@ -947,15 +1248,33 @@ def _turn(message, history):
             text=True,
             cwd=str(_REPO),
             timeout=_TIMEOUT,
-            env=dict(os.environ, PREMAN_TOOL_EVENTS_FILE=events_path),
+            env=env,
         )
+        if channel:
+            proxied = proxy.end(channel)
         if done.returncode != 0:
-            tail = (done.stderr or "").strip()[-600:]
+            tail = (done.stderr or "").strip()
+            if channel:
+                tail = tail.replace(channel, "<proxy>")
+            tail = tail[-600:]
             raise RuntimeError("%s exited %s: %s" % (_ARGV[0], done.returncode, tail))
-        events, capture = _read_events(events_path)
+        reported = _read_events(events_path)
     finally:
+        if channel:
+            proxy.drop(channel)
         shutil.rmtree(folder, ignore_errors=True)
-    return done.stdout.strip(), events, capture
+    if proxied is None:
+        events, capture = reported
+        capture = dict(capture, proxy_version=None)
+        if capture["state"] != "recorded":
+            why = "was switched off for this agent" if switched_off else "could not be loaded"
+            capture["reason"] = "PreMan's tool proxy %s; %s" % (why, capture["reason"])
+    else:
+        events, capture = proxy_mod.choose(proxied, reported)
+    reply = done.stdout.strip()
+    if channel:
+        reply = reply.replace(channel, "<proxy>")
+    return reply, events, capture
 `;
 
 // ── Assembly ────────────────────────────────────────────────────────────
@@ -1008,7 +1327,7 @@ export function buildWrapper(found, { tree = [] } = {}) {
 
   if (shape === "cli_subprocess") {
     return {
-      shim: header + CLI_SUBPROCESS.replace("%%COMMAND%%", litList(command)) + PY_NORMALISE + PY_CHAT_REPORTED,
+      shim: header + CLI_SUBPROCESS.replace("%%COMMAND%%", litList(command)) + PY_PROXY + PY_NORMALISE + PY_CHAT_REPORTED,
       bridge: "",
     };
   }
@@ -1027,8 +1346,9 @@ export function buildWrapper(found, { tree = [] } = {}) {
       + NODE_BRIDGE
           .replace("%%NODE_RUNTIME%%", lit(runtime))
           .replace("%%ENTRY_SYMBOL%%", lit(symbol))
+      + PY_PROXY
       + PY_NORMALISE
-      + PY_CHAT;
+      + PY_CHAT_REPORTED;
     const bridge = NODE_SIDE
       .replace(/%%NODE_ENTRY%%/g, lit("../" + nodeEntry))
       .replace(/%%ENTRY_SYMBOL%%/g, lit(symbol));
@@ -1049,18 +1369,31 @@ export function buildWrapper(found, { tree = [] } = {}) {
     .replace("%%ENTRY_SYMBOL%%", lit(symbol));
 
   // langgraph reads tool calls out of the graph's own messages (§5.1 of the
-  // design), not by wrapping functions, so it keeps the plain `chat()`.
+  // design), not by wrapping functions, so its `_turn` returns the capture and
+  // it uses `chat()` from PY_CHAT_REPORTED.
   if (shape === "langgraph") {
-    return { shim: header + loader + turn + PY_NORMALISE + PY_CHAT, bridge: "" };
+    return { shim: header + loader + turn + PY_NORMALISE + PY_CHAT_REPORTED, bridge: "" };
   }
   // Checked only for the shapes that use it, so a tool path this shape never
   // reads cannot fail the build. Every value is checked before it is quoted
   // into the template, so a tool value a model invented cannot interpolate.
-  const tools = toolsLiteral(found?.tools);
-  const shim = header + loader + PY_CAPTURE.replace("%%TOOLS%%", tools) + turn + PY_NORMALISE + PY_CHAT_CAPTURING;
+  const shim = header + loader + decoratedCapture(found) + turn + PY_NORMALISE + PY_CHAT_DECORATED;
   return { shim, bridge: "" };
 }
 
+/** PY_DECORATED with this answer's tools filled in. */
+function decoratedCapture(found) {
+  const { decorated, covered } = decoratedLiterals(found?.tools);
+  const notRecorded = String(found?.tools_not_recorded || "");
+  if ([...notRecorded].some((ch) => ch.charCodeAt(0) < 0x20)) {
+    throw new TemplateError("tools_not_recorded holds a control character");
+  }
+  return PY_DECORATED
+    .replace("%%DECORATED%%", decorated)
+    .replace("%%COVERED%%", covered)
+    .replace("%%NOT_RECORDED%%", lit(notRecorded));
+}
+
 /**
  * The `other` shape: the CLI still owns everything except one function body.
  *
@@ -1083,7 +1416,7 @@ export function buildFreeform(found, { tree = [], turnSource = "" } = {}) {
   if (!body.trim()) throw new TemplateError("no conversion body was returned");
   // Computed before any text is built, so a tool value a model invented does
   // not get the chance to interpolate into a template.
-  const tools = toolsLiteral(found?.tools);
+  const capture = decoratedCapture(found);
 
   const header = HEADER
     .replace("%%SHAPE%%", "other")
@@ -1100,11 +1433,11 @@ export function buildFreeform(found, { tree = [], turnSource = "" } = {}) {
     + PY_LOADER
         .replace("%%ENTRY_FILE%%", lit(entryFile))
         .replace("%%ENTRY_SYMBOL%%", lit(symbol))
-    + PY_CAPTURE.replace("%%TOOLS%%", tools)
+    + capture
     + "\n\ndef _turn(message, history):\n"
     + `    ${symbol} = _target()\n`
     + body + "\n"
     + PY_NORMALISE
-    + PY_CHAT_CAPTURING;
+    + PY_CHAT_DECORATED;
   return { shim, bridge: "" };
 }