premanmcp 1.1.12 → 1.1.13

package/bin/eval.js

@@ -1988,13 +1988,16 @@ async function runWithToken(
     // import path, so the harness reads this and inserts it before handing off.
     process.env.PREMAN_EVAL_SYS_PATH = target.sysPath;
   }
-  // Opt-in for now (docs/EVAL_AGENT_TRACING.md). Kept only for an agent that
-  // runs inside the harness's Python process; a node bridge or a subprocess
-  // is invisible to in-process tracing, and tracing it would only replace the
-  // adapter's reported tool calls with nothing.
-  if (process.env.PREMAN_EVAL_TRACE === "1" && !tracesInProcess(target)) {
-    say(`tracing is not available for this agent (${target.language || "?"} / ${target.shape || "?"}); running untraced`);
-    process.env.PREMAN_EVAL_TRACE = "0";
+  // On unless PREMAN_EVAL_TRACE=0 (docs/EVAL_AGENT_TRACING.md). Kept only for an
+  // agent that runs inside the harness's Python process; a node bridge or a
+  // subprocess is invisible to in-process tracing, and tracing it would only
+  // replace the adapter's reported tool calls with nothing.
+  const traceAsked = process.env.PREMAN_EVAL_TRACE;
+  if (traceAsked !== "0") {
+    process.env.PREMAN_EVAL_TRACE = tracesInProcess(target) ? "1" : "0";
+    if (traceAsked === "1" && !tracesInProcess(target)) {
+      say(`tracing is not available for this agent (${target.language || "?"} / ${target.shape || "?"}); running untraced`);
+    }
   }
 
   if (adapter.translated) {

package/bin/eval_entry.js

@@ -52,7 +52,10 @@ export const ENTRY_FILE = `${ENTRY_MODULE}.py`;
 export const BRIDGE_FILE = "agent_bridge.mjs";
 
 const SEARCH_TIMEOUT_MS = 120_000;
-const PROBE_TIMEOUT_MS = 60_000;
+// One real turn, after importing the customer's agent. GPUScraper alone takes
+// 37s to import from /mnt/c (2,227 modules), so 60s failed on the import plus
+// one model call. PREMAN_PROBE_TIMEOUT_S overrides for slower repos.
+const PROBE_TIMEOUT_MS = (Number(process.env.PREMAN_PROBE_TIMEOUT_S) || 180) * 1000;
 const MAX_TREE_PATHS = 4_000;
 const MAX_TREE_BYTES = 120_000;
 const MAX_SHORTLIST = 12;
@@ -392,7 +395,11 @@ export async function validateShim(file, { projectPath, log }) {
     cwd: projectPath,
   });
   if (ran.error?.code === "ETIMEDOUT") {
-    return { ok: false, why: "it did not answer within 60 seconds" };
+    return {
+      ok: false,
+      why: `it did not answer within ${PROBE_TIMEOUT_MS / 1000} seconds (importing the agent ` +
+        `counts; set PREMAN_PROBE_TIMEOUT_S to allow longer)`,
+    };
   }
   const line = String(ran.stdout || "")
     .split("\n")

package/bin/eval_harness.py

@@ -304,6 +304,36 @@ def _is_adapter_payload(value) -> bool:
     return isinstance(value, dict) and isinstance(value.get("response"), str)
 
 
+def _turn_raw(ref, raw_result):
+    """The turn's raw record, plus the wrapper's capture outcome when it sent one.
+
+    Carried on ``raw`` because assert-ai stores it verbatim and owns every other
+    field of the artifact; the backend reads it back per turn
+    (docs/superpowers/specs/2026-09-30-tool-call-capture-design.md §7.2).
+    """
+    raw = {"callable": ref}
+    capture = raw_result.get("tool_capture")
+    if isinstance(capture, dict):
+        raw["tool_capture"] = _session._sanitize_endpoint_value(capture)
+    return raw
+
+
+def _attach_capture(result, payload):
+    """Carry the wrapper's tool_capture onto a traced turn.
+
+    A traced turn's stored record is rebuilt by assert-ai from spans
+    (trace_events / trace_metadata / span_validation), so the record
+    ``_turn_raw`` writes on the untraced path never reaches it.
+    """
+    capture = payload.get("tool_capture") if isinstance(payload, dict) else None
+    if not isinstance(capture, dict):
+        return
+    for message in reversed(result.interaction_messages):
+        if message.get("role") == "assistant" and isinstance(message.get("raw"), dict):
+            message["raw"]["tool_capture"] = _session._sanitize_endpoint_value(capture)
+            return
+
+
 async def _callable_run_turn(self, messages: list[Message]) -> TurnResult:
     user_text = ""
     for msg in reversed(messages):
@@ -380,7 +410,7 @@ async def _callable_run_turn(self, messages: list[Message]) -> TurnResult:
     response = _session._normalize_connector_response({
         "text": _session._sanitize_response_text(raw_result["response"]),
         "events": _session._sanitize_endpoint_value(raw_result.get("events")),
-        "raw": {"callable": self._callable_ref},
+        "raw": _turn_raw(self._callable_ref, raw_result),
     })
     interaction_messages = _session._serialize_connector_interaction_messages(
         user_text=user_text,
@@ -484,6 +514,7 @@ if os.environ.get("PREMAN_EVAL_TRACE") == "1":
             raise classified from exc
 
         payload, self._preman_payload = self._preman_payload, None
+        _attach_capture(result, payload)
         if payload is None or any(m.get("role") == "tool" for m in result.interaction_messages):
             return result  # nothing reported, or the spans already carry the tools
 

package/bin/eval_target.js

@@ -160,7 +160,15 @@ export async function discoverTarget(args, { log = () => {}, allowSearch = true
   const saved = savedEntry(projectPath);
   if (saved) {
     const verified = verifyEntry(saved);
-    if (verified) return verified;
+    if (verified) {
+      if (CAPTURE_SHAPES.has(verified.shape) && !verified.capturesTools) {
+        log(
+          "this agent's wrapper was approved before PreMan recorded tool calls; " +
+            "run `preman eval target` again to record them"
+        );
+      }
+      return verified;
+    }
     log(
       `The approved entry point ${saved.file} has changed since it was approved, ` +
         `so it is being re-checked rather than trusted.`
@@ -199,6 +207,9 @@ export async function discoverTarget(args, { log = () => {}, allowSearch = true
   return searchForEntry({ projectPath, args, log });
 }
 
+/** Shapes the tool-capture wrapper applies to (PY_CAPTURE in eval_templates.js). */
+const CAPTURE_SHAPES = new Set(["py_history", "py_plain", "py_class", "other"]);
+
 /**
  * The approved shim, if it is still the file that was approved.
  *
@@ -215,6 +226,13 @@ export function verifyEntry(saved) {
   const digest = createHash("sha256").update(source).digest("hex");
   if (saved.sha256 && digest !== saved.sha256) return null;
 
+  // True for a wrapper the CLI generated with tool capture wired in (every
+  // shape but `node_bridge`, `cli_subprocess` and `langgraph` defines this at
+  // module scope -- see PY_CAPTURE in eval_templates.js). A wrapper approved
+  // before that change has no such line and keeps matching its digest, so this
+  // is read from the file rather than the approval record.
+  const capturesTools = /^_TOOLS = /m.test(source);
+
   // Every file the approval produced, not only the wrapper.
   //
   // A `node_bridge` target is two files: the Python wrapper and the `.mjs` it
@@ -246,6 +264,7 @@ export function verifyEntry(saved) {
     sysPath,
     sha256: digest,
     files: extra,
+    capturesTools,
     shape: saved.shape || "",
     language: saved.language,
     framework: saved.framework,

package/bin/eval_templates.js

@@ -32,6 +32,7 @@ export const SHAPES = new Set([
 export const FREEFORM = "other";
 
 const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const TOOL_SYMBOL = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/;
 
 /** Python literal for a JS string. JSON is a subset of Python for these. */
 function lit(value) {
@@ -43,6 +44,37 @@ function litList(values) {
   return `[${(values || []).map((v) => lit(v)).join(", ")}]`;
 }
 
+/**
+ * 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.
+ */
+function toolsLiteral(tools) {
+  const list = Array.isArray(tools) ? tools : [];
+  const pairs = list.map((tool) => {
+    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.
+    if (
+      !file.endsWith(".py")
+      || file.startsWith("/")
+      || file.split("/").includes("..")
+      || [...file].some((ch) => ch.charCodeAt(0) < 0x20)
+    ) {
+      throw new TemplateError(`tool file ${JSON.stringify(file)} is not a repository .py path`);
+    }
+    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(", ")}]`;
+}
+
 // ── The parts every wrapper shares ──────────────────────────────────────
 
 const HEADER = `# Generated by \`preman eval target\`. Do not edit by hand.
@@ -111,6 +143,312 @@ def preman_selfcheck() -> str:
     return _SYMBOL
 `;
 
+/**
+ * Tool capture for the Python shapes (docs/superpowers/specs/2026-09-30-tool-call-capture-design.md §4).
+ *
+ * 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.
+ */
+const PY_CAPTURE = String.raw`
+import contextvars
+import functools
+import inspect
+import json
+import threading
+import time
+
+_TOOLS = %%TOOLS%%
+_turn_calls = contextvars.ContextVar("preman_turn_calls", default=None)
+_open_turns = {}
+_open_lock = threading.Lock()
+_stray_calls = []
+_installed = []
+_missing = {}
+_pending = {}
+_unsupported = {}
+_install_lock = threading.Lock()
+
+
+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.
+    if (_REPO / file).resolve() == _SRC.resolve():
+        return _agent()
+    wanted = (_REPO / file).resolve()
+    for mod in list(sys.modules.values()):
+        where = getattr(mod, "__file__", None)
+        if where:
+            try:
+                if Path(where).resolve() == wanted:
+                    return mod
+            except (OSError, ValueError):
+                continue
+    return None
+
+
+def _jsonable(value):
+    return json.loads(json.dumps(value, ensure_ascii=False, default=str))
+
+
+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.
+    """
+    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,
+        }
+    except Exception:
+        with _open_lock:
+            _stray_calls.append(time.monotonic())
+        return
+
+    calls = _turn_calls.get()
+    if calls is None:
+        with _open_lock:
+            _stray_calls.append(time.monotonic())
+    else:
+        calls.append(event)
+
+
+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__
+    try:
+        return "error: %s: %s" % (name, exc)
+    except Exception:
+        pass
+    try:
+        return "error: %s: %r" % (name, exc)
+    except Exception:
+        return "error: %s" % name
+
+
+def _recording(name, original):
+    if inspect.iscoroutinefunction(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 _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.
+    with _install_lock:
+        _agent()
+        for file, symbol in _TOOLS:
+            key = "%s:%s" % (file, symbol)
+            if key in _installed:
+                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)
+                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]
+
+
+def _begin_turn():
+    calls = []
+    token = _turn_calls.set(calls)
+    marker = object()
+    with _open_lock:
+        _open_turns[id(marker)] = time.monotonic()
+    return token, marker, calls
+
+
+def _end_turn(token, marker, calls):
+    _turn_calls.reset(token)
+    now = time.monotonic()
+    with _open_lock:
+        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.
+    with _install_lock:
+        installed = list(_installed)
+        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"
+    elif not_watched:
+        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"
+    else:
+        state, reason = "recorded", ""
+    return {
+        "state": state,
+        "source": "wrapped",
+        "watched": _tool_names(installed),
+        "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 _missing:
+        raise RuntimeError(
+            "tool functions named by discovery were not found: "
+            + "; ".join("%s (%s)" % (k, v) for k, v in sorted(_missing.items()))
+            + ". Re-run 'preman eval target'."
+        )
+    return _SYMBOL
+`;
+
 /**
  * The reply, normalised.
  *
@@ -162,13 +500,41 @@ def _text(value):
         if isinstance(found, str) and found.strip():
             return found
     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. */
+const PY_CHAT_REPORTED = String.raw`
+
+def chat(message: str, history: list | None = None) -> dict:
+    reply, events, capture = _turn(message, history or [])
+    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`
+
+def chat(message: str, history: list | None = None) -> dict:
+    _install()
+    token, marker, calls = _begin_turn()
+    try:
+        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,
+    }
+`;
+
 // ── One `_turn` per shape ───────────────────────────────────────────────
 
 const TURNS = {
@@ -420,9 +786,11 @@ for await (const line of createInterface({ input: process.stdin })) {
  * and shows up in process listings.
  */
 const CLI_SUBPROCESS = String.raw`
+import json
 import os
 import shutil
 import subprocess
+import tempfile
 from pathlib import Path
 
 _REPO = Path(__file__).resolve().parent.parent
@@ -530,20 +898,64 @@ def _prompt(message, history):
     return "\n\n".join(lines)
 
 
+def _not_visible(reason):
+    return {"state": "not_visible", "source": "events_file", "watched": [], "missing": [], "reason": reason}
+
+
+def _read_events(path):
+    """The tool calls the agent wrote to PREMAN_TOOL_EVENTS_FILE, one JSON line each.
+
+    The agent creates the file even when it calls nothing, so a missing file
+    means "this agent does not report", never "it called no tools".
+    """
+    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 = []
+    with open(path, encoding="utf-8") as handle:
+        for line in handle:
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                item = json.loads(line)
+            except ValueError:
+                return events, _not_visible("PREMAN_TOOL_EVENTS_FILE held a line that is not JSON")
+            if not isinstance(item, dict) or not item.get("tool_name"):
+                return events, _not_visible("a line in PREMAN_TOOL_EVENTS_FILE has no tool_name")
+            args = item.get("tool_args")
+            content = item.get("content", "")
+            events.append({
+                "role": "tool_result",
+                "tool_name": str(item["tool_name"]),
+                "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": ""}
+
+
 def _turn(message, history):
     argv = [_binary()] + list(_ARGV[1:])
-    done = subprocess.run(
-        argv,
-        input=_prompt(message, history),
-        capture_output=True,
-        text=True,
-        cwd=str(_REPO),
-        timeout=_TIMEOUT,
-    )
-    if done.returncode != 0:
-        tail = (done.stderr or "").strip()[-600:]
-        raise RuntimeError("%s exited %s: %s" % (_ARGV[0], done.returncode, tail))
-    return done.stdout.strip(), []
+    # One file 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")
+    try:
+        done = subprocess.run(
+            argv,
+            input=_prompt(message, history),
+            capture_output=True,
+            text=True,
+            cwd=str(_REPO),
+            timeout=_TIMEOUT,
+            env=dict(os.environ, PREMAN_TOOL_EVENTS_FILE=events_path),
+        )
+        if done.returncode != 0:
+            tail = (done.stderr or "").strip()[-600:]
+            raise RuntimeError("%s exited %s: %s" % (_ARGV[0], done.returncode, tail))
+        events, capture = _read_events(events_path)
+    finally:
+        shutil.rmtree(folder, ignore_errors=True)
+    return done.stdout.strip(), events, capture
 `;
 
 // ── Assembly ────────────────────────────────────────────────────────────
@@ -596,7 +1008,7 @@ export function buildWrapper(found, { tree = [] } = {}) {
 
   if (shape === "cli_subprocess") {
     return {
-      shim: header + CLI_SUBPROCESS.replace("%%COMMAND%%", litList(command)) + PY_NORMALISE,
+      shim: header + CLI_SUBPROCESS.replace("%%COMMAND%%", litList(command)) + PY_NORMALISE + PY_CHAT_REPORTED,
       bridge: "",
     };
   }
@@ -615,7 +1027,8 @@ export function buildWrapper(found, { tree = [] } = {}) {
       + NODE_BRIDGE
           .replace("%%NODE_RUNTIME%%", lit(runtime))
           .replace("%%ENTRY_SYMBOL%%", lit(symbol))
-      + PY_NORMALISE;
+      + PY_NORMALISE
+      + PY_CHAT;
     const bridge = NODE_SIDE
       .replace(/%%NODE_ENTRY%%/g, lit("../" + nodeEntry))
       .replace(/%%ENTRY_SYMBOL%%/g, lit(symbol));
@@ -631,12 +1044,20 @@ export function buildWrapper(found, { tree = [] } = {}) {
     turn = turn.replace("%%METHOD%%", lit(method));
   }
 
-  const shim = header
-    + PY_LOADER
-        .replace("%%ENTRY_FILE%%", lit(entryFile))
-        .replace("%%ENTRY_SYMBOL%%", lit(symbol))
-    + turn
-    + PY_NORMALISE;
+  const loader = PY_LOADER
+    .replace("%%ENTRY_FILE%%", lit(entryFile))
+    .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()`.
+  if (shape === "langgraph") {
+    return { shim: header + loader + turn + PY_NORMALISE + PY_CHAT, 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;
   return { shim, bridge: "" };
 }
 
@@ -660,6 +1081,9 @@ export function buildFreeform(found, { tree = [], turnSource = "" } = {}) {
   }
   const body = String(turnSource || "").trimEnd();
   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 header = HEADER
     .replace("%%SHAPE%%", "other")
@@ -676,9 +1100,11 @@ export function buildFreeform(found, { tree = [], turnSource = "" } = {}) {
     + PY_LOADER
         .replace("%%ENTRY_FILE%%", lit(entryFile))
         .replace("%%ENTRY_SYMBOL%%", lit(symbol))
+    + PY_CAPTURE.replace("%%TOOLS%%", tools)
     + "\n\ndef _turn(message, history):\n"
     + `    ${symbol} = _target()\n`
     + body + "\n"
-    + PY_NORMALISE;
+    + PY_NORMALISE
+    + PY_CHAT_CAPTURING;
   return { shim, bridge: "" };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "premanmcp",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "description": "PreMan CLI and stdio proxy for PreMan's hosted MCP server",
   "type": "module",
   "bin": {