Skip to content

Official Codebase of 3DCodeVerse

Python

agents: every CLI backend records its session's tool calls; claude-code streams, gemini-cli pins skills.enabled

gaoypengb498eb59b0e2
diff --git a/harness/codeverse3d/agents/backends.py b/harness/codeverse3d/agents/backends.py
index 2ce77f02..d409948a 100644
--- a/harness/codeverse3d/agents/backends.py
+++ b/harness/codeverse3d/agents/backends.py
@@ -5,7 +5,12 @@ argv: ``gemini -p <prompt> -m <model> --approval-mode yolo --skip-trust --output
* env hardening: host secrets stripped, one pool key as ``GEMINI_API_KEY``,
``GEMINI_CLI_SYSTEM_SETTINGS_PATH`` (per session, in the trajectory dir) forcing
api-key auth + dynamic model configuration (otherwise an unknown model is *silently*
- substituted), the 3dcode MCP server and ``mcp.allowed``, Node heap cap, no self-relaunch.
+ substituted), ``skills.enabled``, the 3dcode MCP server and ``mcp.allowed``, Node heap
+ cap, no self-relaunch.
+* tool trace: gemini-cli's own chat record of the session (``~/.gemini/tmp/<project>/
+ chats/session-*.jsonl``) is folded into the transcript as ``tool_call`` rows
+ (``cli_common.record_tool_calls``) — ``--output-format json`` carries only per-tool
+ COUNTS, and ``stream-json`` would cost the per-model ``thoughts`` tokens pricing needs.
* JSON envelope ``{session_id, response, stats:{models:{<m>:{tokens:{prompt,
input, candidates, cached, thoughts}}}, tools:{totalCalls}}}`` → Usage (+ cost
via pricing). ``tokens.prompt`` is the TOTAL prompt size and ``tokens.input``
@@ -19,9 +24,15 @@ argv: ``gemini -p <prompt> -m <model> --approval-mode yolo --skip-trust --output
from __future__ import annotations
+import contextlib
+import dataclasses
import json
import logging
+import os
+import re
+import sqlite3
import time
+from collections.abc import Iterable, Mapping
from functools import lru_cache
from pathlib import Path
from typing import Any
@@ -29,6 +40,7 @@ from typing import Any
from codeverse3d.agents.cli_common import (
CompletedProc,
Session,
+ ToolCall,
begin_session,
deliver_prompt,
exists_on_path,
@@ -40,6 +52,7 @@ from codeverse3d.agents.cli_common import (
is_quota_failure,
is_transient_failure,
mcp_command_for,
+ record_tool_calls,
release_session,
tail,
watchdog_error,
@@ -50,17 +63,27 @@ from codeverse3d.contracts.agent import AgentJob, AgentResult
from codeverse3d.contracts.common import Usage
from codeverse3d.models.pricing import estimate_cost
from codeverse3d.models.retry import KeyPool, KeyPoolExhausted
-from codeverse3d.proc import run_subprocess
+from codeverse3d.proc import read_jsonl_lenient, run_subprocess
log = logging.getLogger(__name__)
SYSTEM_SETTINGS = {
# folderTrust must be OFF: with it on, gemini-cli silently disables the workspace
- # .gemini/settings.json mcpServers (even with --skip-trust) → no 3dcode tools.
+ # .gemini/settings.json mcpServers (even with --skip-trust) → no 3dcode tools. It is
+ # also what keeps the WORKSPACE skill roots visible: 0.53's SkillManager.discoverSkills
+ # skips <ws>/.gemini/skills and <ws>/.agents/skills when the folder is not trusted, and
+ # isTrustedFolder() is true exactly when folderTrust is off.
"security": {"auth": {"selectedType": "gemini-api-key"}, "folderTrust": {"enabled": False}},
"experimental": {"dynamicModelConfiguration": True},
"general": {"topicUpdateNarration": False},
+ # default true in 0.53, but a user's ~/.gemini/settings.json (or an agent-written
+ # ws/.gemini/settings.json) could turn it off; this file is merged LAST, so the routed
+ # bundles stay indexed and ``activate_skill`` stays registered (2026-09-22)
+ "skills": {"enabled": True},
}
+#: gemini-cli's skill-activation tool (0.53: ``activate_skill``, arg ``name``); the body
+#: comes back in the tool result, so its call — not a file read — is the activation
+GEMINI_SKILL_TOOL = "activate_skill"
#: how long a retry waits for a *different* healthy key before reusing the same one
RETRY_KEY_WAIT_S = 10.0
#: attempts allowed when the failure is a quota 429 (transient non-quota failures keep 2)
@@ -111,6 +134,47 @@ def parse_gemini_json(stdout: str) -> dict[str, Any] | None:
return find_json_object(stdout, lambda d: True)
+def gemini_chat_records(ws_root: Path, since: float, env: Mapping[str, str] | None = None) -> list[Path]:
+ """gemini-cli's OWN record of the sessions it ran in ``ws_root`` since ``since`` (epoch s).
+
+ 0.53 appends every session to ``<home>/.gemini/tmp/<project>/chats/session-<ts>-<id8>.jsonl``
+ (``<home>`` is ``GEMINI_CLI_HOME`` or ``~``) and names the project dir's workspace in its
+ ``.project_root``. Found by that marker plus mtime rather than by ``session_id``: a
+ session the watchdog killed printed no JSON envelope, and its record is still on disk.
+ Sessions on one workspace are serialised (``cli_common.EXCLUSIVE_KINDS``), so every
+ record written after ``since`` is this session's."""
+ home = Path((env if env is not None else os.environ).get("GEMINI_CLI_HOME") or Path.home())
+ want = {str(ws_root), str(Path(ws_root).resolve())}
+ for marker in (home / ".gemini" / "tmp").glob("*/.project_root"):
+ try:
+ if marker.read_text().strip() not in want:
+ continue
+ except OSError:
+ continue
+ return sorted(p for p in (marker.parent / "chats").rglob("session-*.json*")
+ if p.is_file() and p.stat().st_mtime >= since)
+ return []
+
+
+def gemini_tool_calls(records: Iterable[Path]) -> list[ToolCall]:
+ """Every tool call in those chat records, once per call id (the record is append-only:
+ a message is re-written as it progresses, and the last copy wins)."""
+ calls: dict[str, ToolCall] = {}
+ for path in records:
+ for row in read_jsonl_lenient(path, dicts_only=True):
+ update = row.get("$set") if isinstance(row.get("$set"), dict) else {}
+ for msg in (row, *(update.get("messages") or [])):
+ for tc in (msg.get("toolCalls") if isinstance(msg, dict) else None) or []:
+ if not isinstance(tc, dict):
+ continue
+ name = str(tc.get("name") or "")
+ args = tc.get("args") if isinstance(tc.get("args"), dict) else {}
+ calls[str(tc.get("id") or f"{path.name}#{len(calls)}")] = ToolCall(
+ tool=name, args=args, skill=str(args.get("name") or "") if name == GEMINI_SKILL_TOOL else "",
+ failed=tc.get("status") in ("error", "cancelled"))
+ return list(calls.values())
+
+
def _model_usage(tok: dict[str, Any], name: str) -> Usage:
"""One served model's counters in pricing semantics (``input_tokens`` = total prompt)."""
cached = int(tok.get("cached") or 0)
@@ -235,8 +299,10 @@ class GeminiCliAgent(_CliAgent):
attempts += 1
used.add(key)
try:
- proc = invoke(s, self.build_argv(prompt), self.build_env(s, key), prompt=prompt, attempt=attempts,
+ started, env = time.time(), self.build_env(s, key)
+ proc = invoke(s, self.build_argv(prompt), env, prompt=prompt, attempt=attempts,
soft_timeout_s=next_soft, model=self.model, key_tail=key[-4:])
+ self._record_trace(s, started, env)
outcome = self._interpret(s, proc)
usage_total = usage_total + outcome["usage"]
# the pool is shared with every API call: a hang, a substituted model or the
@@ -277,6 +343,17 @@ class GeminiCliAgent(_CliAgent):
finally:
release_session(s)
+ def _record_trace(self, s: Session, started: float, env: Mapping[str, str]) -> None:
+ """This attempt's tool calls, from gemini-cli's own chat record — never fatal."""
+ try:
+ records = gemini_chat_records(s.ws.root, started, env)
+ if records:
+ record_tool_calls(s, gemini_tool_calls(records), source="gemini-cli chat record")
+ else:
+ s.notes.append("no gemini-cli chat record found for this attempt: tool trace missing")
+ except Exception as e: # noqa: BLE001 — the trace is telemetry; a session must never fail on it
+ log.debug("gemini-cli chat record unreadable: %s", e)
+
def _interpret(self, s: Session, proc: CompletedProc) -> dict[str, Any]:
parsed = parse_gemini_json(proc.stdout)
stats = (parsed or {}).get("stats") or {}
@@ -327,17 +404,65 @@ def _compose_prompt(job: AgentJob) -> str:
#: ignoring them. It only ever opens files already inside the workspace.
ALLOWED_TOOLS = ("Read", "Edit", "Write", "MultiEdit", "Glob", "Grep", "Skill",
"Bash(node:*)", "Bash(python:*)", "Bash(python3:*)", "Bash(ls:*)", f"mcp__{MCP_SERVER_NAME}__*")
+#: claude-code's skill-activation tool (2.1.280: input ``{"skill": <name>, "args"?}``)
+CLAUDE_SKILL_TOOL = "Skill"
def parse_claude_json(stdout: str) -> dict[str, Any] | None:
- """The ``type == "result"`` envelope, else the last JSON line (a stream-json array
- without a result event is no envelope)."""
+ """The ``type == "result"`` envelope, else the one JSON document ``--output-format
+ json`` printed. A stream (a stream-json array, or the JSONL ``--output-format
+ stream-json`` writes) without its result event is no envelope: its last line is an
+ assistant turn of a session that never finished."""
env = find_json_object(stdout, lambda d: d.get("type") == "result")
if env is not None or stdout.lstrip().startswith("["):
return env
+ if sum(1 for line in stdout.splitlines() if line.lstrip().startswith("{")) > 1:
+ return None
return find_json_object(stdout, lambda d: True)
+class ClaudeStream:
+ """Folded view over ``--output-format stream-json``: the tool calls the session made,
+ and the skill index its ``init`` event reported (the list the model was shown).
+
+ Since 2026-09-22 the backend streams instead of printing one envelope: the envelope
+ (the last, ``type == "result"`` line) is unchanged, and the lines before it are the
+ only record of which skills the session activated (docs/SKILLS.md §9 — "the logs
+ contain zero occurrences of any c3d- name" under ``--output-format json``)."""
+
+ def __init__(self) -> None:
+ self.calls: list[ToolCall] = []
+ self.skills: list[str] | None = None
+ self._at: dict[str, int] = {} # tool_use id → index in calls, for its tool_result
+
+ def feed(self, line: str) -> None:
+ line = line.strip()
+ if not line.startswith("{"):
+ return
+ try:
+ ev = json.loads(line)
+ except json.JSONDecodeError:
+ return # a >1 MB line arrives chunked (proc._LINE_CAP_BYTES): a Write, never a Skill call
+ if not isinstance(ev, dict):
+ return
+ if ev.get("type") == "system" and ev.get("subtype") == "init":
+ self.skills = [str(x) for x in ev.get("skills") or []]
+ elif ev.get("type") in ("assistant", "user"):
+ for block in (ev.get("message") or {}).get("content") or []:
+ if not isinstance(block, dict):
+ continue
+ if block.get("type") == "tool_use":
+ name = str(block.get("name") or "")
+ args = block.get("input") if isinstance(block.get("input"), dict) else {}
+ self._at[str(block.get("id"))] = len(self.calls)
+ self.calls.append(ToolCall(tool=name, args=args, skill=str(args.get("skill") or "")
+ if name == CLAUDE_SKILL_TOOL else ""))
+ elif block.get("type") == "tool_result" and block.get("is_error") is True:
+ i = self._at.get(str(block.get("tool_use_id")))
+ if i is not None:
+ self.calls[i] = dataclasses.replace(self.calls[i], failed=True)
+
+
def usage_from_envelope(env: dict[str, Any], model: str) -> Usage:
"""``input_tokens`` is the TOTAL prompt (uncached + cache reads + cache writes), the
convention pricing.py and anthropic.py share. The envelope's own ``input_tokens`` is the
@@ -395,7 +520,10 @@ class ClaudeCodeAgent(_CliAgent):
def build_argv(self, s: Session, prompt: str) -> list[str]:
job = s.job
- argv = [self.binary, "-p", prompt, "--output-format", "json", "--dangerously-skip-permissions",
+ # stream-json (+ the --verbose it requires in -p mode): same final envelope, plus the
+ # tool calls the skill read probe reads as ground truth (ClaudeStream)
+ argv = [self.binary, "-p", prompt, "--output-format", "stream-json", "--verbose",
+ "--dangerously-skip-permissions",
"--max-turns", str(job.max_turns), "--no-session-persistence",
"--allowedTools", ",".join(ALLOWED_TOOLS)]
if self.model:
@@ -427,7 +555,9 @@ class ClaudeCodeAgent(_CliAgent):
if not ok:
return failed(s, "error", why)
prompt = deliver_prompt(s, job.prompt)
- proc = invoke(s, self.build_argv(s, prompt), self.build_env(s), prompt=prompt)
+ stream = ClaudeStream()
+ proc = invoke(s, self.build_argv(s, prompt), self.build_env(s), prompt=prompt, on_stdout=stream.feed)
+ record_tool_calls(s, stream.calls, source="claude-code stream-json", skills_index=stream.skills)
env = parse_claude_json(proc.stdout)
usage = usage_from_envelope(env, self.model) if env else Usage(backend=self.kind, model=self.model)
usage.latency_ms = usage.latency_ms or int(proc.duration_s * 1000)
@@ -466,6 +596,10 @@ class ClaudeCodeAgent(_CliAgent):
# ===================================================================== codex
STDIN_PROMPT_BYTES = 100_000
_TOOL_ITEMS = ("command_execution", "file_change", "mcp_tool_call", "web_search", "tool_call")
+#: the item fields a tool trace keeps: what was run, never what came back. codex has no
+#: skill tool — it lists skills in its prompt and opens SKILL.md with a shell command, so
+#: the command string IS the activation record (0.155.1)
+_TRACE_KEYS = ("command", "server", "tool", "arguments", "changes", "query")
#: what ``-c model_reasoning_effort=`` accepts; ``""`` means "leave it to ~/.codex/config.toml"
REASONING_EFFORTS = ("", "minimal", "low", "medium", "high", "xhigh")
@@ -504,6 +638,7 @@ class CodexEvents:
"reasoning_output_tokens": 0, "cache_write_input_tokens": 0}
self.thread_id = ""
self.n_events = 0
+ self.calls: list[ToolCall] = []
def feed(self, line: str) -> None:
line = line.strip()
@@ -524,6 +659,9 @@ class CodexEvents:
self.messages.append(str(item.get("text", "")))
elif it in _TOOL_ITEMS:
self.tool_calls += 1
+ self.calls.append(ToolCall(tool=it, args={k: item[k] for k in _TRACE_KEYS if k in item},
+ failed=item.get("status") in ("failed", "declined")
+ or item.get("exit_code") not in (None, 0)))
elif t == "turn.completed":
self.turns_completed += 1
for k in self.usage_raw:
@@ -594,6 +732,7 @@ class CodexAgent(_CliAgent):
events = CodexEvents()
proc = invoke(s, argv, self.build_env(s), prompt=prompt, stdout_name="stdout.jsonl",
on_stdout=events.feed, stdin=prompt if via_stdin else None)
+ record_tool_calls(s, events.calls, source="codex exec --json")
usage = events.usage(self.model)
usage.latency_ms = int(proc.duration_s * 1000)
text = "\n\n".join(m for m in events.messages if m.strip())
@@ -677,6 +816,89 @@ def parse_agy_json(stdout: str) -> dict[str, Any] | None:
return find_json_object(stdout, lambda d: "response" in d or "status" in d)
+#: where agy 1.2.2 keeps each conversation: one SQLite file named by the envelope's
+#: ``conversation_id``, a ``steps`` table whose ``step_payload`` is protobuf
+AGY_CONVERSATIONS = Path.home() / ".gemini" / "antigravity-cli" / "conversations"
+#: a tool call inside a step payload is three consecutive strings — its id, the tool name,
+#: the JSON arguments (``call_4419682`` · ``view_file`` · ``{"AbsolutePath": ...}``), read out
+#: of recorded conversations; no schema needed, and a tool result step that echoes the
+#: call is folded by the id
+_AGY_CALL_ID = re.compile(r"call_\w+")
+_AGY_TOOL = re.compile(r"[a-z][a-z0-9_]*")
+
+
+def _varint(buf: bytes, i: int) -> tuple[int, int]:
+ value = shift = 0
+ while True:
+ if i >= len(buf) or shift > 63:
+ raise ValueError("bad varint")
+ b = buf[i]
+ i += 1
+ value |= (b & 0x7F) << shift
+ shift += 7
+ if not b & 0x80:
+ return value, i
+
+
+def _pb_strings(buf: bytes, depth: int = 0) -> list[str]:
+ """Every printable UTF-8 string in a protobuf message, nested messages included, in
+ wire order — a schema-free walk; raises ValueError on bytes that are not protobuf."""
+ out: list[str] = []
+ i = 0
+ while i < len(buf):
+ key, i = _varint(buf, i)
+ wire = key & 7
+ if key >> 3 == 0:
+ raise ValueError("field number 0")
+ if wire == 0:
+ _, i = _varint(buf, i)
+ elif wire in (1, 5):
+ i += 8 if wire == 1 else 4
+ elif wire == 2:
+ n, i = _varint(buf, i)
+ chunk, i = buf[i:i + n], i + n
+ if len(chunk) != n:
+ raise ValueError("truncated field")
+ try:
+ text = chunk.decode("utf-8")
+ except UnicodeDecodeError:
+ text = ""
+ if text and all(ch.isprintable() or ch in "\n\r\t" for ch in text):
+ out.append(text)
+ elif depth < 8 and chunk:
+ with contextlib.suppress(ValueError): # a bytes field, not a nested message
+ out += _pb_strings(chunk, depth + 1)
+ else:
+ raise ValueError(f"wire type {wire}")
+ return out
+
+
+def agy_tool_calls(db: Path) -> list[ToolCall]:
+ """Every tool call recorded in one agy conversation database, once per call id.
+
+ agy 1.2.2 has no skill tool: its prompt lists the skills and the model opens
+ ``SKILL.md`` with ``view_file``, so the file path IS the activation record."""
+ calls: dict[str, ToolCall] = {}
+ con = sqlite3.connect(f"file:{db}?mode=ro", uri=True)
+ try:
+ for (payload,) in con.execute("SELECT step_payload FROM steps ORDER BY idx"):
+ try:
+ strs = _pb_strings(payload or b"")
+ except ValueError:
+ continue
+ for call_id, tool, raw in zip(strs, strs[1:], strs[2:], strict=False):
+ if not (_AGY_CALL_ID.fullmatch(call_id) and _AGY_TOOL.fullmatch(tool) and raw.startswith("{")):
+ continue
+ try:
+ args = json.loads(raw)
+ except json.JSONDecodeError:
+ continue
+ calls.setdefault(call_id, ToolCall(tool=tool, args=args if isinstance(args, dict) else {}))
+ finally:
+ con.close()
+ return list(calls.values())
+
+
def usage_from_agy(env: dict[str, Any], model: str) -> Usage:
u = env.get("usage") or {}
return Usage(
@@ -714,6 +936,19 @@ class AntigravityAgent(_CliAgent):
def build_env(self, s: Session) -> dict[str, str]:
return hardened_env(s.ws, s.job)
+ def _record_trace(self, s: Session, conversation_id: str) -> int:
+ """The session's tool calls, from agy's own conversation database — never fatal.
+ Returns how many (agy's JSON envelope carries no tool count of its own)."""
+ db = AGY_CONVERSATIONS / f"{conversation_id}.db" if conversation_id else None
+ if db is None or not db.is_file():
+ s.notes.append("no agy conversation record found for this session: tool trace missing")
+ return 0
+ try:
+ return record_tool_calls(s, agy_tool_calls(db), source="agy conversation db")
+ except Exception as e: # noqa: BLE001 — the trace is telemetry; a session must never fail on it
+ log.debug("agy conversation %s unreadable: %s", db, e)
+ return 0
+
def run(self, job: AgentJob) -> AgentResult:
ok, why = self.available()
s = begin_session(job, self.kind)
@@ -723,6 +958,7 @@ class AntigravityAgent(_CliAgent):
prompt = deliver_prompt(s, _compose_prompt_agy(s))
proc = invoke(s, self.build_argv(s, prompt), self.build_env(s), prompt=prompt)
env = parse_agy_json(proc.stdout)
+ n_calls = self._record_trace(s, str((env or {}).get("conversation_id") or ""))
served = self.served_model()
usage = usage_from_agy(env, served) if env else Usage(backend=self.kind, model=served)
usage.latency_ms = usage.latency_ms or int(proc.duration_s * 1000)
@@ -743,8 +979,9 @@ class AntigravityAgent(_CliAgent):
errors.append("empty response")
else:
ok, reason = True, "completed"
+ usage.tool_calls = n_calls
return finish_session(
- s, ok=ok, exit_reason=reason, text=text, usage=usage, tool_calls=0,
+ s, ok=ok, exit_reason=reason, text=text, usage=usage, tool_calls=n_calls,
turns=int((env or {}).get("num_turns") or 0), errors=errors,
rc=proc.rc, killed_reason=proc.killed_reason,
conversation_id=(env or {}).get("conversation_id", ""), num_turns=(env or {}).get("num_turns", 0),
diff --git a/harness/codeverse3d/agents/cli_common.py b/harness/codeverse3d/agents/cli_common.py
index 4da01b07..87777bc7 100644
--- a/harness/codeverse3d/agents/cli_common.py
+++ b/harness/codeverse3d/agents/cli_common.py
@@ -621,6 +621,63 @@ def watchdog_error(proc: CompletedProc) -> str:
return f"killed by watchdog ({proc.killed_reason}) after {proc.duration_s:.0f}s"
+# --------------------------------------------------------------------------- tool trace
+#: The CLI's OWN record of what it called, normalised into ``transcript.jsonl`` by every
+#: backend after its session: one :data:`TOOL_CALL_ROW` per call, then ONE
+#: :data:`TOOL_TRACE_ROW` saying "this session's calls are all here" — a session without
+#: it left no trace, and its silence must not read as "called nothing". The skill read
+#: probe (``skills/telemetry.py``) reads these rows instead of file atimes, which its own
+#: control bundle caught "reading" in 27 of 33 sessions (docs/SKILLS.md §9). Arguments are
+#: compacted to :data:`TRACE_ARG_CHARS` per value: a path survives, a file body does not.
+TOOL_CALL_ROW = "tool_call"
+TOOL_TRACE_ROW = "tool_trace"
+TRACE_ARG_CHARS = 400
+
+
+@dataclass(frozen=True)
+class ToolCall:
+ """One tool call as the CLI reported it. ``skill`` names the bundle when the call was
+ the CLI's own skill-activation tool (claude-code ``Skill``, gemini-cli ``activate_skill``),
+ so a reader of the trace never needs any vendor's tool vocabulary; ``failed`` is the
+ CLI's own verdict on the call (a ``sed`` of a mis-expanded skill path read nothing —
+ codex 0.155.1 did exactly that on its first try, 2026-09-22)."""
+
+ tool: str
+ args: Mapping[str, Any] = field(default_factory=dict)
+ skill: str = ""
+ failed: bool = False
+
+
+def _compact(value: Any, limit: int = TRACE_ARG_CHARS) -> Any:
+ if isinstance(value, Mapping):
+ return {str(k): _compact(v, limit) for k, v in value.items()}
+ if value is None or isinstance(value, bool | int | float):
+ return value
+ text = value if isinstance(value, str) else json.dumps(value, ensure_ascii=False, default=str)
+ return text if len(text) <= limit else text[:limit] + "…"
+
+
+def record_tool_calls(s: Session, calls: Iterable[ToolCall], *, source: str,
+ skills_index: Sequence[str] | None = None) -> int:
+ """Append one session's tool calls and the closing :data:`TOOL_TRACE_ROW`; returns the count.
+
+ ``source`` says where the backend read them (its event stream, its chat record);
+ ``skills_index`` is the skill list the CLI itself reported as available, when it
+ reports one (claude-code's ``init`` event) — the proof the index reached the model."""
+ n = 0
+ for c in calls:
+ row: dict[str, Any] = {"tool": c.tool, "args": _compact(dict(c.args))}
+ if c.skill:
+ row["skill"] = c.skill
+ if c.failed:
+ row["failed"] = True
+ s.traj.append(TOOL_CALL_ROW, **row)
+ n += 1
+ extra: dict[str, Any] = {"skills_index": list(skills_index)} if skills_index is not None else {}
+ s.traj.append(TOOL_TRACE_ROW, calls=n, source=source, **extra)
+ return n
+
+
# --------------------------------------------------------------------------- failures
_TRANSIENT_RE = re.compile(
r"(\b429\b|RESOURCE_EXHAUSTED|rate.?limit|quota|\b503\b|UNAVAILABLE|overloaded|"
diff --git a/harness/codeverse3d/agents/materialize.py b/harness/codeverse3d/agents/materialize.py
index 40cb6d0f..b8b06aaa 100644
--- a/harness/codeverse3d/agents/materialize.py
+++ b/harness/codeverse3d/agents/materialize.py
@@ -19,8 +19,11 @@ new one (docs/COST.md §13 measured and reverted a second head at +2,925 tokens/
Nothing here needs to change for the CLIs to see them: codex's per-tool approval override
below is scoped to ``mcp_servers.3dcode.*`` and cannot reach its skills loader, and
gemini-cli's ``activate_skill`` consent is already covered by ``--approval-mode yolo``.
-claude-code needed one change — ``Skill`` in its ``--allowedTools``
-(``agents/backends.ALLOWED_TOOLS``).
+The per-backend wiring lives in ``agents/backends.py``: claude-code needs ``Skill`` in its
+``--allowedTools`` (``ALLOWED_TOOLS``), gemini-cli needs ``skills.enabled`` and folder trust
+off in its per-session system settings (``SYSTEM_SETTINGS``: 0.53 skips both workspace skill
+roots in an untrusted folder), and each backend records what its CLI activated
+(``cli_common.record_tool_calls``) — re-read against the installed CLIs 2026-09-22.
Ignore files: ``.geminiignore`` / ``.aiexclude`` hide only noise (:data:`IGNORE_LINES`);
``.gemini/settings.json`` gets ``context.fileFiltering.respectGitIgnore=false`` because the
diff --git a/harness/tests/agents/test_tool_trace.py b/harness/tests/agents/test_tool_trace.py
new file mode 100644
index 00000000..9d142ea1
--- /dev/null
+++ b/harness/tests/agents/test_tool_trace.py
@@ -0,0 +1,283 @@
+"""Every CLI backend folds its session's tool calls into ``transcript.jsonl`` — the skill
+read probe's ground truth (docs/SKILLS.md §4, 2026-09-22).
+
+The fixtures are excerpts of the four live sessions recorded 2026-09-22 (claude-code
+2.1.280 stream-json, gemini-cli 0.53.0 chat record, codex 0.155.1 ``exec --json``, agy
+1.2.2 conversation database), trimmed to the fields the parsers read. A vendor that
+renames one of them breaks a test here instead of silently reporting "read nothing".
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import time
+from pathlib import Path
+
+from codeverse3d.agents.backends import (
+ SYSTEM_SETTINGS,
+ ClaudeCodeAgent,
+ ClaudeStream,
+ CodexEvents,
+ agy_tool_calls,
+ gemini_chat_records,
+ gemini_tool_calls,
+ parse_claude_json,
+ write_system_settings,
+)
+from codeverse3d.agents.cli_common import (
+ TOOL_CALL_ROW,
+ TOOL_TRACE_ROW,
+ TRACE_ARG_CHARS,
+ ToolCall,
+ begin_session,
+ record_tool_calls,
+)
+from codeverse3d.contracts.agent import AgentJob
+from codeverse3d.workspace import Workspace
+
+WS = "/tmp/probe/live/claude1"
+
+# --------------------------------------------------------------------------- claude-code
+CLAUDE_STREAM = [
+ {"type": "system", "subtype": "init", "cwd": WS, "session_id": "893f6373", "model": "claude-sonnet-5",
+ "claude_code_version": "2.1.280", "tools": ["Bash", "Read", "Skill"],
+ "skills": ["c3d-bbox-contract", "c3d-blender-forms", "c3d-part-contact", "c3d-repeats-and-mirrors",
+ "zz-c3d-read-control", "dataviz"]},
+ {"type": "system", "subtype": "thinking_tokens", "estimated_tokens": 12},
+ {"type": "assistant", "message": {"model": "claude-sonnet-5", "id": "msg_1", "role": "assistant", "content": [
+ {"type": "text", "text": "I'll start by loading the mandatory skills for this task"}]}},
+ {"type": "assistant", "message": {"model": "claude-sonnet-5", "id": "msg_1", "role": "assistant", "content": [
+ {"type": "tool_use", "id": "toolu_01KmUt", "name": "Skill", "input": {"skill": "c3d-bbox-contract"},
+ "caller": {"type": "direct"}}]}},
+ {"type": "user", "message": {"role": "user", "content": [
+ {"type": "tool_result", "tool_use_id": "toolu_01KmUt", "content": "Launching skill: c3d-bbox-contract"}]},
+ "tool_use_result": {"success": True, "commandName": "c3d-bbox-contract"}},
+ {"type": "assistant", "message": {"model": "claude-sonnet-5", "id": "msg_2", "role": "assistant", "content": [
+ {"type": "tool_use", "id": "toolu_02", "name": "Read",
+ "input": {"file_path": f"{WS}/.claude/skills/c3d-bbox-contract/references/worked_example.md"}}]}},
+ {"type": "user", "message": {"role": "user", "content": [
+ {"type": "tool_result", "tool_use_id": "toolu_02", "content": "..."}]}},
+ {"type": "assistant", "message": {"model": "claude-sonnet-5", "id": "msg_3", "role": "assistant", "content": [
+ {"type": "tool_use", "id": "toolu_03", "name": "mcp__3dcode__check_contract", "input": {}}]}},
+ {"type": "user", "message": {"role": "user", "content": [
+ {"type": "tool_result", "tool_use_id": "toolu_03", "is_error": True,
+ "content": "check_contract: plan.json not found in the workspace"}]}},
+ {"type": "result", "subtype": "success", "is_error": False, "num_turns": 25, "result": "done",
+ "session_id": "893f6373", "total_cost_usd": 0.95, "usage": {"input_tokens": 32, "output_tokens": 30106}},
+]
+
+
+def _stream_text(events) -> str:
+ return "\n".join(json.dumps(e) for e in events) + "\n"
+
+
+def test_claude_stream_folds_the_index_the_skill_calls_and_their_failures():
+ s = ClaudeStream()
+ for line in _stream_text(CLAUDE_STREAM).splitlines():
+ s.feed(line)
+ assert s.skills[:5] == ["c3d-bbox-contract", "c3d-blender-forms", "c3d-part-contact",
+ "c3d-repeats-and-mirrors", "zz-c3d-read-control"]
+ assert [(c.tool, c.skill, c.failed) for c in s.calls] == [
+ ("Skill", "c3d-bbox-contract", False), ("Read", "", False), ("mcp__3dcode__check_contract", "", True)]
+ s.feed("not json") # chatter and a chunked >1 MB line are skipped, never raised
+ s.feed('{"type": "assistant", "message": {"content": [')
+ assert len(s.calls) == 3
+
+
+def test_the_stream_json_envelope_is_the_result_line_and_an_unfinished_stream_has_none():
+ assert parse_claude_json(_stream_text(CLAUDE_STREAM))["num_turns"] == 25
+ assert parse_claude_json(_stream_text(CLAUDE_STREAM[:-1])) is None # killed before its result
+ single = json.dumps({"num_turns": 2, "result": "ok"}) # one document still parses
+ assert parse_claude_json(single)["num_turns"] == 2
+
+
+def test_claude_is_launched_streaming(tmp_ws: Workspace):
+ s = begin_session(AgentJob(workspace=str(tmp_ws.root), prompt="p", spatial_tools=False), "claude-code")
+ argv = ClaudeCodeAgent("sonnet", binary="claude").build_argv(s, "p")
+ assert argv[argv.index("--output-format") + 1] == "stream-json" and "--verbose" in argv
+ assert "Skill" in argv[argv.index("--allowedTools") + 1].split(",")
+ assert "--disable-slash-commands" not in argv # claude-code: "Disable all skills"
+
+
+FAKE_STREAMING_CLAUDE = r'''
+args = sys.argv[1:]
+assert args[args.index("--output-format") + 1] == "stream-json" and "--verbose" in args
+for ev in json.loads(os.environ["FAKE_EVENTS"]):
+ print(json.dumps(ev), flush=True)
+'''
+
+
+def test_a_claude_session_writes_its_trace_into_the_transcript(tmp_ws: Workspace, fake_bin, monkeypatch):
+ monkeypatch.setenv("FAKE_EVENTS", json.dumps(CLAUDE_STREAM))
+ res = ClaudeCodeAgent("sonnet", binary=fake_bin("claude", FAKE_STREAMING_CLAUDE)).run(
+ AgentJob(workspace=str(tmp_ws.root), prompt="build it", label="c", timeout_s=30, spatial_tools=False))
+ assert res.ok and res.turns == 25, res.errors
+ rows = [json.loads(x) for x in Path(res.transcript_path).read_text().splitlines()]
+ calls = [r for r in rows if r["kind"] == TOOL_CALL_ROW]
+ trace = [r for r in rows if r["kind"] == TOOL_TRACE_ROW]
+ assert [c["tool"] for c in calls] == ["Skill", "Read", "mcp__3dcode__check_contract"]
+ assert calls[0]["skill"] == "c3d-bbox-contract" and calls[2]["failed"] is True
+ assert trace == [{**trace[0], "calls": 3, "source": "claude-code stream-json"}]
+ assert "zz-c3d-read-control" in trace[0]["skills_index"]
+
+
+# --------------------------------------------------------------------------- gemini-cli
+GEMINI_RECORD = [
+ {"sessionId": "da5c91db-7d90-4dd9-a360-56b03e1fd339", "projectHash": "4b58", "startTime": "2026-09-22T19:31:33.522Z",
+ "lastUpdated": "2026-09-22T19:31:33.522Z", "kind": "main"},
+ {"$set": {"messages": [{"id": "d049", "type": "user", "content": [{"text": "<session_context>..."}]}]}},
+ {"id": "fb86", "type": "gemini", "content": "I will activate the relevant skills for Blender modeling",
+ "toolCalls": [
+ {"id": "activate_skill__call_48964", "name": "activate_skill", "args": {"name": "c3d-blender-forms"},
+ "status": "success"},
+ {"id": "activate_skill__call_48965", "name": "activate_skill", "args": {"name": "c3d-part-contact"},
+ "status": "success"}]},
+ {"$set": {"lastUpdated": "2026-09-22T19:31:48.148Z"}},
+ {"id": "fb87", "type": "gemini", "content": "",
+ "toolCalls": [{"id": "read_file__call_5", "name": "read_file", "status": "success",
+ "args": {"file_path": ".agents/skills/c3d-part-contact/references/worked_example.md"}},
+ {"id": "read_file__call_6", "name": "read_file", "status": "error",
+ "args": {"file_path": ".agents/skills/zz-c3d-read-control/SKILL.md"}}]},
+ # the append-only record re-writes a message as it progresses: one call, not two
+ {"id": "fb86", "type": "gemini", "content": "", "toolCalls": [
+ {"id": "activate_skill__call_48964", "name": "activate_skill", "args": {"name": "c3d-blender-forms"},
+ "status": "success"}]},
+]
+
+
+def _gemini_home(tmp_path: Path, ws: Path, *, since_offset: float = 0.0) -> Path:
+ home = tmp_path / "home"
+ proj = home / ".gemini" / "tmp" / ws.name
+ (proj / "chats").mkdir(parents=True)
+ (proj / ".project_root").write_text(str(ws))
+ other = home / ".gemini" / "tmp" / "someone-else"
+ (other / "chats").mkdir(parents=True)
+ (other / ".project_root").write_text("/elsewhere/run")
+ (other / "chats" / "session-2026-09-22T19-31-aaaaaaaa.jsonl").write_text(json.dumps(GEMINI_RECORD[2]) + "\n")
+ rec = proj / "chats" / "session-2026-09-22T19-31-da5c91db.jsonl"
+ rec.write_text("".join(json.dumps(r) + "\n" for r in GEMINI_RECORD))
+ if since_offset:
+ t = time.time() + since_offset
+ os.utime(rec, (t, t))
+ return home
+
+
+def test_gemini_chat_record_is_found_by_workspace_and_time_and_folded_by_call_id(tmp_path):
+ ws = tmp_path / "gemini1"
+ ws.mkdir()
+ home = _gemini_home(tmp_path, ws)
+ recs = gemini_chat_records(ws, time.time() - 60, {"GEMINI_CLI_HOME": str(home)})
+ assert [p.name for p in recs] == ["session-2026-09-22T19-31-da5c91db.jsonl"]
+ calls = gemini_tool_calls(recs)
+ assert [(c.tool, c.skill, c.failed) for c in calls] == [
+ ("activate_skill", "c3d-blender-forms", False), ("activate_skill", "c3d-part-contact", False),
+ ("read_file", "", False), ("read_file", "", True)]
+ # an earlier session's record in the same workspace belongs to that session
+ assert gemini_chat_records(ws, time.time() + 60, {"GEMINI_CLI_HOME": str(home)}) == []
+ assert gemini_chat_records(tmp_path / "unknown", 0.0, {"GEMINI_CLI_HOME": str(home)}) == []
+
+
+def test_gemini_system_settings_pin_skills_on_and_keep_the_workspace_trusted(tmp_path):
+ """0.53 merges the system file LAST, so a user's (or an agent-planted workspace)
+ ``skills.enabled: false`` cannot hide the bundles; ``folderTrust`` off is what makes
+ ``isTrustedFolder()`` true, without which ``discoverSkills`` skips both workspace roots."""
+ data = json.loads(write_system_settings(tmp_path / "s.json").read_text())
+ assert data["skills"] == {"enabled": True} == SYSTEM_SETTINGS["skills"]
+ assert data["security"]["folderTrust"] == {"enabled": False}
+
+
+# --------------------------------------------------------------------------- codex
+CODEX_EVENTS = [
+ {"type": "thread.started", "thread_id": "01a0ca9a"},
+ {"type": "turn.started"},
+ {"type": "item.completed", "item": {"id": "item_0", "type": "agent_message",
+ "text": "I'm using the chair-relevant 3D skills"}},
+ # the model expanded the r1 skill-root alias as r0 (the system root): the read failed
+ {"type": "item.completed", "item": {
+ "id": "item_1", "type": "command_execution", "status": "failed", "exit_code": 2,
+ "command": "/bin/bash -lc \"sed -n '1,240p' AGENTS.md && sed -n '1,240p' "
+ "/home/u/.codex/skills/.system/c3d-blender-forms/SKILL.md\"",
+ "aggregated_output": "# 3dcode workspace — rules for the coding agent ..."}},
+ {"type": "item.completed", "item": {
+ "id": "item_3", "type": "command_execution", "status": "completed", "exit_code": 0,
+ "command": "/bin/bash -lc \"sed -n '1,280p' .agents/skills/c3d-blender-forms/SKILL.md && "
+ "sed -n '1,260p' .agents/skills/c3d-part-contact/SKILL.md\"",
+ "aggregated_output": "--- name: c3d-blender-forms ..."}},
+ {"type": "item.completed", "item": {"id": "item_6", "type": "file_change", "status": "completed",
+ "changes": [{"path": f"{WS}/src/model.py", "kind": "add"}]}},
+ {"type": "item.completed", "item": {"id": "item_7", "type": "mcp_tool_call", "server": "3dcode",
+ "tool": "build", "arguments": {}, "status": "completed"}},
+ {"type": "turn.completed", "usage": {"input_tokens": 2292081, "cached_input_tokens": 2196992,
+ "output_tokens": 18551, "reasoning_output_tokens": 7544}},
+]
+
+
+def test_codex_events_keep_what_was_run_and_whether_it_worked():
+ ev = CodexEvents()
+ for e in CODEX_EVENTS:
+ ev.feed(json.dumps(e))
+ assert [(c.tool, c.failed) for c in ev.calls] == [
+ ("command_execution", True), ("command_execution", False), ("file_change", False), ("mcp_tool_call", False)]
+ assert "aggregated_output" not in ev.calls[0].args # what ran, never what came back
+ assert ev.calls[1].args["command"].count("SKILL.md") == 2
+ assert ev.calls[3].args == {"server": "3dcode", "tool": "build", "arguments": {}}
+ assert ev.tool_calls == 4
+
+
+# --------------------------------------------------------------------------- agy
+def _pb(field: int, payload: bytes) -> bytes:
+ """One length-delimited protobuf field (the only wire type the fixture needs)."""
+ def varint(n: int) -> bytes:
+ out = b""
+ while True:
+ b, n = n & 0x7F, n >> 7
+ out += bytes([b | (0x80 if n else 0)])
+ if not n:
+ return out
+ return varint(field << 3 | 2) + varint(len(payload)) + payload
+
+
+def _agy_step(call_id: str, tool: str, args: dict) -> bytes:
+ """The shape of a 1.2.2 planner step: field 20 → field 7 → {1: id, 2: tool, 3: JSON args},
+ next to other nested strings (the bot id, session metadata)."""
+ call = _pb(1, call_id.encode()) + _pb(2, tool.encode()) + _pb(3, json.dumps(args).encode())
+ meta = _pb(5, _pb(12, b"73608b9c-31f0-45cb-98a3-92299de1db80"))
+ return meta + _pb(20, _pb(6, b"bot-1dd6e6ec") + _pb(7, call))
+
+
+def test_agy_tool_calls_come_out_of_its_conversation_database(tmp_path):
+ db = tmp_path / "a0319af6.db"
+ con = sqlite3.connect(db)
+ con.execute("CREATE TABLE steps (idx integer PRIMARY KEY, step_type integer, step_payload blob)")
+ skill = f"{WS}/.agents/skills/c3d-bbox-contract/SKILL.md"
+ rows = [(0, 14, _pb(19, _pb(2, b"Workspace root: /tmp/x"))),
+ (1, 15, _agy_step("call_4419682", "view_file", {"AbsolutePath": skill, "toolAction": "Reading skill"})),
+ (2, 132, _agy_step("call_4419682", "view_file", {"AbsolutePath": skill})), # the result echoes it
+ (3, 15, _agy_step("call_3378924", "run_command", {"CommandLine": "ls -la"})),
+ (4, 15, b"\xff\xfe not protobuf")]
+ con.executemany("INSERT INTO steps VALUES (?, ?, ?)", rows)
+ con.commit()
+ con.close()
+ calls = agy_tool_calls(db)
+ assert [(c.tool, c.args.get("AbsolutePath") or c.args.get("CommandLine")) for c in calls] == [
+ ("view_file", skill), ("run_command", "ls -la")]
+
+
+# --------------------------------------------------------------------------- the rows
+def test_record_tool_calls_writes_compact_rows_and_one_closing_marker(tmp_ws: Workspace):
+ s = begin_session(AgentJob(workspace=str(tmp_ws.root), prompt="p", spatial_tools=False), "codex")
+ n = record_tool_calls(s, [ToolCall("Write", {"file_path": "src/a.py", "content": "x" * 5000}),
+ ToolCall("Skill", {"skill": "c3d-part-contact"}, skill="c3d-part-contact"),
+ ToolCall("apply", {"changes": [{"path": "src/b.py"}]}, failed=True)],
+ source="unit", skills_index=["c3d-part-contact"])
+ rows = s.traj.read_transcript()
+ assert n == 3 and [r["kind"] for r in rows] == [TOOL_CALL_ROW] * 3 + [TOOL_TRACE_ROW]
+ assert rows[0]["args"]["file_path"] == "src/a.py" and len(rows[0]["args"]["content"]) == TRACE_ARG_CHARS + 1
+ assert rows[1]["skill"] == "c3d-part-contact" and "skill" not in rows[0] and "failed" not in rows[0]
+ assert rows[2]["failed"] is True and rows[2]["args"]["changes"] == '[{"path": "src/b.py"}]'
+ assert rows[3] == {**rows[3], "calls": 3, "source": "unit", "skills_index": ["c3d-part-contact"]}
+ # a session that called nothing still closes its trace: silence is then a fact
+ assert record_tool_calls(s, [], source="unit") == 0
+ assert s.traj.read_transcript()[-1]["calls"] == 0