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.pyindex 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) forcingapi-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 (+ costvia 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 --outputfrom __future__ import annotations+import contextlib+import dataclassesimport jsonimport logging+import os+import re+import sqlite3import time+from collections.abc import Iterable, Mappingfrom functools import lru_cachefrom pathlib import Pathfrom typing import Any@@ -29,6 +40,7 @@ from typing import Anyfrom 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, AgentResultfrom codeverse3d.contracts.common import Usagefrom codeverse3d.models.pricing import estimate_costfrom codeverse3d.models.retry import KeyPool, KeyPoolExhausted-from codeverse3d.proc import run_subprocess+from codeverse3d.proc import read_jsonl_lenient, run_subprocesslog = 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 oneRETRY_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 += 1used.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 Nonereturn 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), theconvention 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):# ===================================================================== codexSTDIN_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 += 1for 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_callsreturn 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.pyindex 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.pyindex 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 overridebelow is scoped to ``mcp_servers.3dcode.*`` and cannot reach its skills loader, andgemini-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 thediff --git a/harness/tests/agents/test_tool_trace.py b/harness/tests/agents/test_tool_trace.pynew file mode 100644index 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