premanmcp 1.1.13 → 1.1.14

package/bin/eval_templates.js

@@ -163,11 +163,19 @@ 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)
+_turn_state = contextvars.ContextVar("preman_turn_state", default=None)
+# The call running right now, so a tool called from inside it names it as parent.
+# Copied into pool tasks and threads by _track, like the turn itself.
+_current_call = contextvars.ContextVar("preman_current_call", default=None)
+_local = threading.local()
+_patched = []
 _open_turns = {}
 _open_lock = threading.Lock()
 _stray_calls = []
@@ -175,9 +183,30 @@ _installed = []
 _missing = {}
 _pending = {}
 _unsupported = {}
+_traceable = set()
 _install_lock = threading.Lock()
 
 
+def _is_langchain_tool(obj):
+    # Checked only when LangChain is already loaded: importing it here would
+    # load a framework the agent may not use.
+    tools = sys.modules.get("langchain_core.tools")
+    base = getattr(tools, "BaseTool", None)
+    return isinstance(base, type) and isinstance(obj, base)
+
+
+def _langchain_traced():
+    # OpenInference's LangChain plugin, switched on by the run's tracing. It
+    # hooks LangChain's callback manager, so every '@tool' that runs through
+    # LangChain becomes a tool span -- it sees the calls wrapping cannot.
+    plugin = sys.modules.get("openinference.instrumentation.langchain")
+    cls = getattr(plugin, "LangChainInstrumentor", None)
+    try:
+        return bool(cls is not None and cls().is_instrumented_by_opentelemetry)
+    except Exception:
+        return False
+
+
 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
@@ -202,7 +231,7 @@ def _jsonable(value):
     return json.loads(json.dumps(value, ensure_ascii=False, default=str))
 
 
-def _record(name, original, args, kwargs, result):
+def _record(name, original, args, kwargs, result, shape=None):
     """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
@@ -239,14 +268,54 @@ def _record(name, original, args, kwargs, result):
     except Exception:
         with _open_lock:
             _stray_calls.append(time.monotonic())
+        turn = _turn_state.get()
+        if shape is not None and turn is not None:
+            shape["ended"] = round(time.monotonic() - turn["started"], 3)  # finished, but no event
         return
 
     calls = _turn_calls.get()
-    if calls is None:
+    turn = _turn_state.get()
+    if calls is None or (turn is not None and turn["closed"]):
+        # No turn, or its turn already returned: appending would add it to a
+        # list nobody reads any more.
         with _open_lock:
             _stray_calls.append(time.monotonic())
     else:
         calls.append(event)
+        if shape is not None:
+            shape["event"] = event  # replaced by its position when the turn ends
+            shape["ended"] = round(time.monotonic() - turn["started"], 3)
+
+
+def _start_call(name):
+    """The trace entry for a call starting now, and the token to reset
+    _current_call with; (None, None) outside a turn."""
+    turn = _turn_state.get()
+    if turn is None or turn["closed"]:
+        return None, None
+    with _open_lock:
+        turn["count"] += 1
+        cid = "c%d" % turn["count"]
+        # Filed at the start, so a call still running when the turn ends is
+        # listed (ended null) and its children's parent still resolves.
+        shape = {
+            "id": cid,
+            "tool": name,
+            "parent": _current_call.get(),
+            "started": round(time.monotonic() - turn["started"], 3),
+            "thread": threading.current_thread().name,
+        }
+        turn["trace"].append(shape)
+    return shape, _current_call.set(cid)
+
+
+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 _error_text(exc):
@@ -267,22 +336,30 @@ def _recording(name, original):
     if inspect.iscoroutinefunction(original):
         @functools.wraps(original)
         async def recorded(*args, **kwargs):
+            shape, token = _start_call(name)
             try:
                 result = await original(*args, **kwargs)
             except BaseException as exc:
-                _record(name, original, args, kwargs, _error_text(exc))
+                _record(name, original, args, kwargs, _error_text(exc), shape)
                 raise
-            _record(name, original, args, kwargs, result)
+            finally:
+                if token is not None:
+                    _current_call.reset(token)
+            _record(name, original, args, kwargs, result, shape)
             return result
     else:
         @functools.wraps(original)
         def recorded(*args, **kwargs):
+            shape, token = _start_call(name)
             try:
                 result = original(*args, **kwargs)
             except BaseException as exc:
-                _record(name, original, args, kwargs, _error_text(exc))
+                _record(name, original, args, kwargs, _error_text(exc), shape)
                 raise
-            _record(name, original, args, kwargs, result)
+            finally:
+                if token is not None:
+                    _current_call.reset(token)
+            _record(name, original, args, kwargs, result, shape)
             return result
     recorded.__preman_original__ = original
     return recorded
@@ -312,6 +389,96 @@ def _replace_everywhere(original, recorded):
             continue
 
 
+def _track(fn):
+    # fn, set to run in a copy of the caller's context -- so a tool it calls
+    # files under the caller's turn -- and counted against that turn until it
+    # finishes, so a turn that ends with it still running is not called complete.
+    ctx = contextvars.copy_context()
+    turn = _turn_state.get()
+    if turn is not None:
+        with _open_lock:
+            turn["pending"] += 1
+    done = []
+
+    def finish():
+        if turn is not None and not done:
+            done.append(True)
+            with _open_lock:
+                turn["pending"] -= 1
+
+    def run(*args, **kwargs):
+        try:
+            return ctx.run(fn, *args, **kwargs)
+        finally:
+            finish()
+
+    run.__preman_finish__ = finish
+    return run
+
+
+def _patch_threads():
+    # A new thread starts with empty context variables, so a tool run on a
+    # pool or a Thread saw no turn and was counted as a stray call. Patched on
+    # the classes, so pools the agent created at import are covered too.
+    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):
+        # Every task, not only those in a turn: a worker thread is reused, and a
+        # task must never run in a context an earlier task's turn left behind.
+        run = _track(fn)
+        before = getattr(_local, "in_submit", False)
+        _local.in_submit = True  # the pool's own worker threads are not the agent's
+        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):
+        if _turn_calls.get() is None or getattr(_local, "in_submit", False):
+            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 flagging(original):
+        # Work sent to another process runs where no tool is wrapped.
+        @functools.wraps(original)
+        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
@@ -323,6 +490,9 @@ def _install():
     # _turn() always sees the same, already-wrapped module -- concurrent first
     # calls included.
     with _install_lock:
+        if not _patched:
+            _patch_threads()
+            _patched.append(True)
         _agent()
         for file, symbol in _TOOLS:
             key = "%s:%s" % (file, symbol)
@@ -367,6 +537,8 @@ def _install():
                 # 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__
+                if _is_langchain_tool(owner):
+                    _traceable.add(key)
                 continue
             elif getattr(owner, "__preman_original__", None) is None:
                 _replace_everywhere(owner, _recording(owner_name, owner))
@@ -381,7 +553,9 @@ def _tool_names(installed):
 
 def _begin_turn():
     calls = []
-    token = _turn_calls.set(calls)
+    turn = {"pending": 0, "process": False, "closed": False,
+            "started": time.monotonic(), "count": 0, "trace": []}
+    token = (_turn_calls.set(calls), _turn_state.set(turn), turn)
     marker = object()
     with _open_lock:
         _open_turns[id(marker)] = time.monotonic()
@@ -389,9 +563,21 @@ def _begin_turn():
 
 
 def _end_turn(token, marker, calls):
-    _turn_calls.reset(token)
+    calls_token, state_token, turn = token
+    _turn_calls.reset(calls_token)
+    _turn_state.reset(state_token)
+    # A thread this turn started may finish a moment after the reply: wait a
+    # little for it rather than call the turn not visible. Bounded, because a
+    # worker the agent keeps running would otherwise hang the case.
+    began = time.monotonic()
+    deadline = began + _thread_wait()
+    while turn["pending"] and time.monotonic() < deadline:
+        time.sleep(0.01)
+    waited = time.monotonic() - began
     now = time.monotonic()
     with _open_lock:
+        turn["closed"] = True
+        still_running = turn["pending"]
         started = _open_turns.pop(id(marker))
         stray = any(started <= t <= now for t in _stray_calls)
         oldest = min(_open_turns.values(), default=now)
@@ -407,6 +593,11 @@ def _end_turn(token, marker, calls):
         unseen.update(_unsupported)
         not_watched = dict(_missing)
         not_watched.update(unseen)
+        traceable = set(_traceable)
+    # A LangChain tool object can't be wrapped, but when the LangChain plugin
+    # is on, every call to it is a tool span, so it is still seen. Only when
+    # every unwatched tool is one: any other unwatched tool could run unseen.
+    traced = bool(not_watched) and set(not_watched) <= traceable and _langchain_traced()
     # "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.
@@ -414,21 +605,42 @@ def _end_turn(token, marker, calls):
         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"
-    elif not_watched:
+    elif not_watched and not traced:
         state, reason = "not_visible", "not watched: " + "; ".join(
             "%s (%s)" % (k, v) for k, v in sorted(not_watched.items())
         )
     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", ""
-    return {
+    capture = {
         "state": state,
-        "source": "wrapped",
-        "watched": _tool_names(installed),
+        "source": "traced" if traced else "wrapped",
+        "watched": _tool_names(installed) + (_tool_names(sorted(not_watched)) if traced else []),
         "missing": missing,
         "reason": reason,
     }
+    if not traced:
+        # A traced turn's LangChain calls come from spans; the harness builds its trace.
+        with _open_lock:
+            started = list(turn["trace"])
+        calls_out = []
+        for call in sorted(started, key=lambda c: int(c["id"][1:])):
+            call = dict(call)
+            call.setdefault("ended", None)  # still running when the turn ended
+            calls_out.append(call)
+        capture["trace"] = {
+            "links": "full",
+            "known": ["parent", "started", "ended", "thread"],
+            "unknown": {"step": "function wrapping sees tool calls, not the model replies that asked for them"},
+            "waited": round(waited, 3),
+            "calls": calls_out,
+        }
+    return capture
 
 
 def preman_selfcheck() -> str:
@@ -502,15 +714,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:
@@ -528,11 +733,15 @@ def chat(message: str, history: list | None = None) -> dict:
         reply, events = _turn(message, history or [])
     finally:
         capture = _end_turn(token, marker, calls)
-    return {
-        "response": _text(reply),
-        "events": list(events or []) + calls,
-        "tool_capture": capture,
-    }
+    events = list(events or []) + calls
+    trace = capture.get("trace")
+    if trace:
+        # Each call's event, as its position among this turn's tool results.
+        tools = [e for e in events if isinstance(e, dict) and e.get("role") == "tool_result"]
+        where = {id(e): i for i, e in enumerate(tools)}
+        for call in trace["calls"]:
+            call["event"] = where.get(id(call.pop("event", None)))
+    return {"response": _text(reply), "events": events, "tool_capture": capture}
 `;
 
 // ── One `_turn` per shape ───────────────────────────────────────────────
@@ -601,6 +810,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 +837,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 +953,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 +984,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 +1012,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 +1045,7 @@ def _bridge():
             stderr=open(_STDERR, "w"),
             text=True,
             bufsize=1,
+            env=env,
         )
     return _proc
 
@@ -725,18 +1060,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 +1160,7 @@ import json
 import os
 import shutil
 import subprocess
+import sys
 import tempfile
 from pathlib import Path
 
@@ -910,7 +1281,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 +1301,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 +1371,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 +1450,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 +1469,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,9 +1492,10 @@ 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