Skip to content

Official Codebase of 3DCodeVerse

Python

skills: one library, one delivery policy — and the routed set as a TOOL for backends without a loader

gaoypenga15c3b97a231
diff --git a/harness/codeverse/agents/api_agent.py b/harness/codeverse/agents/api_agent.py
index a7a50a70..8386e62f 100644
--- a/harness/codeverse/agents/api_agent.py
+++ b/harness/codeverse/agents/api_agent.py
@@ -14,6 +14,7 @@ import logging
import time
from typing import Any
+from codeverse.agents.api_skills import SkillTools
from codeverse.agents.api_tools import FileTools, SpatialTools, ToolOutcome
from codeverse.agents.cli_common import Session, begin_session, failed, finish_session
from codeverse.agents.context import compact_messages, message_chars
@@ -28,6 +29,7 @@ from codeverse.contracts.chat import (
ToolSpec,
)
from codeverse.contracts.common import Usage
+from codeverse.skills.delivery import delivery_for
log = logging.getLogger(__name__)
@@ -102,7 +104,15 @@ class _Loop:
if not self.spatial.tools:
s.notes.append("spatial registry is empty; running with file tools only")
self.spatial = None
- self.specs: list[ToolSpec] = self.files.specs() + (self.spatial.specs() if self.spatial else [])
+ # the routed bundles as a TOOL, not as prose: measured, api-agent read 0 of 5 from a
+ # MANDATORY paragraph in AGENTS.md while the CLI backends read 5 of 5 through their own
+ # loaders. It responds to tool specs; the bundles also sit in hidden dirs list_files
+ # skips, so it could not have found them by looking (codeverse/agents/api_skills.py).
+ # a backend WITHOUT a native loader gets the routed set as a tool; the policy lives
+ # in skills/delivery.py so a new backend is one row there, not a branch here
+ self.skills = SkillTools(s.ws) if delivery_for(agent.kind).needs_tool else None
+ self.specs: list[ToolSpec] = (self.files.specs() + (self.skills.specs() if self.skills else [])
+ + (self.spatial.specs() if self.spatial else []))
self.usage = Usage(backend="api-agent", model=agent.model)
self.tool_calls = 0
self.last_write_turn = -1
@@ -206,6 +216,8 @@ class _Loop:
def _dispatch(self, name: str, args: dict[str, Any]) -> ToolOutcome:
if name == "run_build" and self.spatial and BUILD_TOOL in self.spatial.names():
name = BUILD_TOOL
+ if self.skills and (out := self.skills.dispatch(name, args)) is not None:
+ return out
if name in self.files.names():
return self.files.call(name, args)
if self.spatial and name in self.spatial.names():
diff --git a/harness/codeverse/agents/api_skills.py b/harness/codeverse/agents/api_skills.py
new file mode 100644
index 00000000..7e541611
--- /dev/null
+++ b/harness/codeverse/agents/api_skills.py
@@ -0,0 +1,159 @@
+"""``read_skill`` — the routed skill bundles as a TOOL, for the in-process api-agent.
+
+WHY a tool and not prose. Every CLI backend has a native skill loader, and measured on a
+real build task codex, claude-code and agy each read **5 of 5** routed bundles unprompted.
+api-agent read **0 of 5** on the same library, in the same workspace, while making 52
+``read_file`` calls — so it was reading plenty, just never a skill. Two reasons it could
+not, both structural rather than a matter of persuasion:
+
+* the bundles live in ``.agents/skills/`` and ``.claude/skills/``, which are HIDDEN
+ directories, and ``list_files`` deliberately skips hidden paths — the agent cannot
+ discover them by looking;
+* everything else it knew came from tool specs, while the skills were a paragraph in a
+ 2.3 kB system prompt competing with the contract, the rules and the cookbook pointer.
+
+So the index becomes an affordance: the routed names are in the tool's own description,
+where the model reads its options, and opening one is a tool call like any other. The
+AGENTS.md index stays as well — belt and braces, and it is what a native loader reads.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from codeverse.agents.api_tools import ToolOutcome, _schema
+from codeverse.contracts.chat import ToolSpec
+
+#: every discovery root the library writes to; first match wins (the same bytes go to all
+#: of them, so a loaderless backend can read whichever exists)
+from codeverse.skills.delivery import AGENTS_SKILL_ROOT, CLAUDE_SKILL_ROOT
+from codeverse.workspace import Workspace
+
+SKILL_ROOTS = (AGENTS_SKILL_ROOT, CLAUDE_SKILL_ROOT)
+#: a body is capped like read_file's — a skill that cannot fit is a skill to split
+READ_CAP_CHARS = 24_000
+#: how much of each description the tool spec repeats, per skill
+SPEC_SUMMARY_CHARS = 150
+
+__all__ = ["SKILL_ROOTS", "SkillTools"]
+
+
+class SkillTools:
+ """``read_skill`` over the bundles already materialised into ``ws``."""
+
+ def __init__(self, ws: Workspace):
+ self.ws = ws
+ self.listed, self.summaries = self._discover()
+ self.reads: list[str] = [] # names actually opened, in order — the read-rate ground truth
+
+ def _discover(self) -> tuple[list[str], dict[str, str]]:
+ """Read the routed set off the workspace rather than being told it.
+
+ The bundles are already there — materialize.py wrote them for this round — so
+ discovering them here keeps the tool from ever disagreeing with what is on disk,
+ and needs no field threaded through AgentJob and the generation task. The read
+ CONTROL bundle is excluded: it exists to catch a probe that reports a read nobody
+ made, and offering it as a choice would be inviting exactly that.
+ """
+ from codeverse.skills.materialize import CONTROL_NAME
+
+ names: dict[str, str] = {}
+ for root in SKILL_ROOTS:
+ d = Path(self.ws.root) / root
+ if not d.is_dir():
+ continue
+ for bundle in sorted(d.iterdir()):
+ name = bundle.name
+ if name == CONTROL_NAME or name in names or not (bundle / "SKILL.md").is_file():
+ continue
+ names[name] = _description_of(bundle / "SKILL.md")
+ return list(names), names
+
+ # ------------------------------------------------------------------ specs
+ def specs(self) -> list[ToolSpec]:
+ if not self.listed:
+ return []
+ lines = [f" - {n}: {self.summaries.get(n, '')[:SPEC_SUMMARY_CHARS]}".rstrip(": ") for n in self.listed]
+ desc = (
+ "Read one of the skill bundles the harness routed for THIS task — chosen from your "
+ "track, language, plan and the previous round's gate findings. Read every one before "
+ "writing code; they carry the rules this harness's gates actually enforce.\n"
+ + "\n".join(lines)
+ )
+ return [ToolSpec(
+ name="read_skill", description=desc,
+ parameters=_schema({"name": {"type": "string", "description": "skill name, exactly as listed",
+ "enum": list(self.listed)}}, ["name"]),
+ )]
+
+ # ------------------------------------------------------------------ tool
+ def read_skill(self, name: str) -> ToolOutcome:
+ if not isinstance(name, str) or not name.strip():
+ return ToolOutcome("name must be one of: " + ", ".join(self.listed), is_error=True)
+ name = name.strip()
+ if name not in self.listed:
+ return ToolOutcome(f"{name!r} was not routed for this task; available: {', '.join(self.listed)}",
+ is_error=True)
+ body = self._body(name)
+ if body is None:
+ return ToolOutcome(f"skill {name!r} is listed but its SKILL.md is missing from the workspace",
+ is_error=True)
+ self.reads.append(name)
+ return ToolOutcome(body)
+
+ def dispatch(self, name: str, args: dict[str, Any]) -> ToolOutcome | None:
+ """``None`` when this toolbox does not own ``name`` (the caller keeps looking)."""
+ if name != "read_skill":
+ return None
+ return self.read_skill(str(args.get("name", "")))
+
+ # ------------------------------------------------------------------ internals
+ def _body(self, name: str) -> str | None:
+ for root in SKILL_ROOTS:
+ p = Path(self.ws.root) / root / name / "SKILL.md"
+ if p.is_file():
+ text = p.read_text(errors="replace")
+ extra = self._references(p.parent)
+ if extra:
+ text += "\n\n" + extra
+ return text[:READ_CAP_CHARS] + (
+ f"\n... [truncated at {READ_CAP_CHARS} chars]" if len(text) > READ_CAP_CHARS else "")
+ return None
+
+ @staticmethod
+ def _references(bundle: Path) -> str:
+ """The spec puts depth in ``references/``; name them so a body is not a dead end."""
+ ref = bundle / "references"
+ if not ref.is_dir():
+ return ""
+ names = sorted(p.name for p in ref.iterdir() if p.is_file())
+ if not names:
+ return ""
+ rel = os.path.relpath(ref, bundle.parents[2]) if len(bundle.parents) > 2 else str(ref)
+ return "Further reading in this bundle (open with read_file):\n" + "\n".join(
+ f" {rel}/{n}" for n in names)
+
+
+def _description_of(skill_md: Path) -> str:
+ """The frontmatter ``description``, without importing the loader (which validates the
+ whole bundle and would turn one malformed skill into a session with no tool at all)."""
+ try:
+ text = skill_md.read_text(errors="replace")
+ except OSError:
+ return ""
+ if not text.startswith("---"):
+ return ""
+ end = text.find("\n---", 3)
+ front = text[3:end] if end > 0 else ""
+ out, grabbing = [], False
+ for line in front.splitlines():
+ if line.startswith("description:"):
+ out.append(line.split(":", 1)[1].strip())
+ grabbing = True
+ elif grabbing and line[:1] in (" ", "\t"):
+ out.append(line.strip())
+ elif grabbing:
+ break
+ return " ".join(out).strip().strip("'\"")
diff --git a/harness/codeverse/skills/delivery.py b/harness/codeverse/skills/delivery.py
new file mode 100644
index 00000000..a4842a8f
--- /dev/null
+++ b/harness/codeverse/skills/delivery.py
@@ -0,0 +1,81 @@
+"""How one shared skill library reaches each coding agent — the ONE place that differs.
+
+The library itself is agent-agnostic: plain `agentskills.io` bundles under
+``codeverse/skills/<name>/SKILL.md``, routed by ``router.py`` from typed inputs. Nothing
+in it knows what a backend is. What genuinely differs between backends is only
+**delivery**, and only in two bits:
+
+* does the backend have a NATIVE skill loader (it finds and indexes bundles itself), and
+* which discovery root does it read?
+
+Both were read out of the shipped binaries, not assumed: gemini-cli, codex and agy read
+``<ws>/.agents/skills/<name>/SKILL.md``; claude-code 2.1 reads ``<ws>/.claude/skills/…``
+and has no ``.agents`` skill root at all.
+
+Everything else follows from those two bits, so adding a backend is ONE row here — not a
+new module, not a branch in three files. A backend nobody has classified gets the safe
+answer (no native loader), which means it is handed the explicit index *and* the
+``read_skill`` tool: over-delivering costs tokens, under-delivering costs the skill.
+
+WHY the tool exists at all, measured 2026-08-25: on the same library and workspace, the
+three native loaders read **5 of 5** routed bundles unprompted while api-agent read
+**0 of 5** — not from unwillingness (it made 52 ``read_file`` calls that session) but
+because the bundles sit in hidden directories its ``list_files`` skips, and the index was
+prose in a 2.3 kB system prompt rather than an affordance. So a backend without a loader
+gets the routed set as a TOOL. That is a general rule about loaderless backends, not a
+special case for one of them.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+__all__ = ["AGENTS_SKILL_ROOT", "CLAUDE_SKILL_ROOT", "Delivery", "delivery_for", "known_backends"]
+
+#: discovery roots, relative to the workspace root
+AGENTS_SKILL_ROOT = ".agents/skills"
+CLAUDE_SKILL_ROOT = ".claude/skills"
+
+
+@dataclass(frozen=True)
+class Delivery:
+ """What one backend needs in order to see the routed bundles."""
+
+ root: str
+ """Discovery root this backend reads (bundles are written to every known root anyway,
+ so one copy is never the only copy — this is the path we NAME to it)."""
+ native_loader: bool
+ """True when the backend indexes bundles itself. Such a backend must not be handed a
+ second index — it would list the same skills twice — and needs no tool."""
+
+ @property
+ def needs_index(self) -> bool:
+ """An explicit one-line-per-skill index in the agent body file."""
+ return not self.native_loader
+
+ @property
+ def needs_tool(self) -> bool:
+ """``read_skill``: the routed set as an affordance rather than as prose."""
+ return not self.native_loader
+
+
+#: The whole per-backend policy. One row per backend; anything absent is loaderless.
+_BACKENDS: dict[str, Delivery] = {
+ "claude-code": Delivery(root=CLAUDE_SKILL_ROOT, native_loader=True),
+ "codex": Delivery(root=AGENTS_SKILL_ROOT, native_loader=True),
+ "gemini-cli": Delivery(root=AGENTS_SKILL_ROOT, native_loader=True),
+ "agy": Delivery(root=AGENTS_SKILL_ROOT, native_loader=True),
+ "api-agent": Delivery(root=AGENTS_SKILL_ROOT, native_loader=False),
+}
+
+#: the safe answer for a backend nobody has classified yet
+_UNKNOWN = Delivery(root=AGENTS_SKILL_ROOT, native_loader=False)
+
+
+def delivery_for(agent_kind: str) -> Delivery:
+ """The delivery policy for ``agent_kind``; unknown kinds get the loaderless answer."""
+ return _BACKENDS.get((agent_kind or "").split(":", 1)[0], _UNKNOWN)
+
+
+def known_backends() -> tuple[str, ...]:
+ return tuple(_BACKENDS)
diff --git a/harness/codeverse/skills/prompting.py b/harness/codeverse/skills/prompting.py
index e347c4a2..98a55a9f 100644
--- a/harness/codeverse/skills/prompting.py
+++ b/harness/codeverse/skills/prompting.py
@@ -26,15 +26,17 @@ import re
from collections.abc import Sequence
from codeverse.cost.guard import text_tokens
+from codeverse.skills.delivery import (
+ AGENTS_SKILL_ROOT,
+ CLAUDE_SKILL_ROOT,
+ delivery_for,
+ known_backends,
+)
from codeverse.skills.model import Selection, Skill
-#: where a materialised bundle lives, relative to the workspace root (the `.agents` root
-#: is the one gemini-cli, codex and agy all read; claude-code reads its own copy).
-AGENTS_SKILL_ROOT = ".agents/skills"
-CLAUDE_SKILL_ROOT = ".claude/skills"
-
-#: backends whose own loader indexes the bundles; they must NOT be handed a second index
-NATIVE_LOADERS = ("claude-code", "codex", "gemini-cli", "agy")
+#: Per-backend policy lives in ONE place (``skills/delivery.py``); these are re-exported so
+#: existing importers keep working and so nothing here re-derives what a backend needs.
+NATIVE_LOADERS = tuple(k for k in known_backends() if delivery_for(k).native_loader)
#: what a NATIVE loader is told. Its own index lists every skill it can see, including any
#: the user installed globally, so "the ones that match" is the right instruction there.
@@ -69,8 +71,7 @@ def index_summary(description: str, limit: int = INDEX_SUMMARY_CHARS) -> str:
def skill_path(name: str, *, agent_kind: str = "") -> str:
- root = CLAUDE_SKILL_ROOT if agent_kind == "claude-code" else AGENTS_SKILL_ROOT
- return f"{root}/{name}/SKILL.md"
+ return f"{delivery_for(agent_kind).root}/{name}/SKILL.md"
def index_block(skills: Sequence[Skill | Selection], agent_kind: str) -> str:
@@ -82,7 +83,7 @@ def index_block(skills: Sequence[Skill | Selection], agent_kind: str) -> str:
items = [s.skill if isinstance(s, Selection) else s for s in skills]
if not items:
return ""
- if agent_kind in NATIVE_LOADERS:
+ if not delivery_for(agent_kind).needs_index:
return f"{_HEADING}\n\n{MANDATE}\n"
lines = [f"- **{s.name}** — {index_summary(s.description)} "
f"Read `{skill_path(s.name, agent_kind=agent_kind)}` BEFORE writing code."
diff --git a/harness/docs/ARCHITECTURE.md b/harness/docs/ARCHITECTURE.md
index 14b1c7ab..d0b1535e 100644
--- a/harness/docs/ARCHITECTURE.md
+++ b/harness/docs/ARCHITECTURE.md
@@ -90,7 +90,9 @@ codeverse/
measured, ships OFF, see docs/COST.md §21), health.py (preflight probe: is the model
serving? no retries, no backoff), schema_utils.py (strict schema), registry.py
agents/ CodingAgent; gemini_cli.py claude_code.py codex.py antigravity.py api_agent.py
- (+ api_tools.py run_shell policy), materialize.py, cli_common.py (sessions, retry
+ (+ api_tools.py run_shell policy, api_skills.py: the read_skill tool every
+ backend WITHOUT a native loader gets — measured, prose in a system prompt is
+ not an affordance), materialize.py, cli_common.py (sessions, retry
trajectory naming, files_changed attribution), watchdog.py, transcript.py, registry.py
languages/ LanguageRuntime; blender/ (multi-file: layout.py, model.py + parts/*.py) cadquery/
threejs/ (+ templates.py) urdf/ scene_threejs/ glsl_shader/ (wrap.py header+line-map, gl_build.py)
@@ -111,7 +113,9 @@ codeverse/
finding_kind(): the ONE place gate message text is matched), router.py
(track/language/kind/plan/gate-findings -> a capped, ranked, reasoned set),
materialize.py (writes into ws/.agents/skills AND ws/.claude/skills, real
- copies — codex refuses symlinks), prompting.py (per-backend index text),
+ copies — codex refuses symlinks), delivery.py (THE per-backend policy, two
+ bits — native loader? which root? — so a new backend is one row and nothing
+ else re-derives it), prompting.py (per-backend index text),
telemetry.py (the atime read probe: surfaced vs deep), claims.py (numbers
pinned to live constants), config.py (CV3D_SKILLS, default OFF)
cost/ types.py (CallCost/Stage/Role) ledger.py (append-only telemetry/cost.jsonl + price provenance)
diff --git a/harness/docs/SKILLS.md b/harness/docs/SKILLS.md
index 15a3d781..9026c0ca 100644
--- a/harness/docs/SKILLS.md
+++ b/harness/docs/SKILLS.md
@@ -18,6 +18,46 @@ routed bundles in the measured A/B while the three subscription CLIs read all fi
---
+## 0. How the library is managed
+
+**One library, one policy, thin adapters.** The bundles under `codeverse/skills/<name>/`
+are plain [agentskills.io](https://agentskills.io/specification) `SKILL.md` directories and
+know nothing about any backend — anyone can `cp -r codeverse/skills/<name> ~/.claude/skills/`
+and use them without this harness at all. `router.py` picks the set from typed inputs.
+
+Everything that genuinely differs between coding agents is **two bits**, and they live in
+one file, `skills/delivery.py`:
+
+| backend | native loader? | discovery root |
+|---|---|---|
+| `claude-code` | yes | `.claude/skills` |
+| `codex`, `gemini-cli`, `agy` | yes | `.agents/skills` |
+| `api-agent` | no | `.agents/skills` |
+| *anything unclassified* | **no** (safe default) | `.agents/skills` |
+
+Both bits were read out of the shipped binaries, not assumed. Everything else is derived:
+a backend with its own loader must **not** be handed a second index (it would list the same
+skills twice) and needs no tool; a backend without one gets the explicit index **and** the
+`read_skill` tool. Over-delivering costs tokens; under-delivering costs the skill, so an
+unknown backend gets the loaderless treatment.
+
+**Adding a backend is one row in that table.** A test (`tests/skills/test_delivery.py`)
+fails if per-backend knowledge leaks back out into the other modules, and another checks
+that `prompting.py` agrees with the policy rather than re-deriving it.
+
+### Why loaderless backends get a tool
+
+Measured 2026-08-25, same library, same workspace, same task: `codex`, `claude-code` and
+`agy` each read **5 of 5** routed bundles unprompted through their own loaders.
+`api-agent` read **0 of 5** — not from unwillingness (it made **52 `read_file` calls** that
+session, and called `read_cookbook` twice), but because the bundles sit in hidden
+directories its `list_files` deliberately skips, and the index was prose in a 2.3 kB system
+prompt competing with the contract and the rules. Prose is not an affordance. So the
+routed set became a tool, `read_skill`, whose spec carries the names and one-line summaries
+where a model actually reads its options — and which records what was opened, giving the
+read rate ground truth instead of a probe.
+
+
## 1. The model: progressive disclosure, and why it is also the measurement
The spec's three tiers, and what each costs us per turn:
diff --git a/harness/tests/skills/test_delivery.py b/harness/tests/skills/test_delivery.py
new file mode 100644
index 00000000..7b9ae0f1
--- /dev/null
+++ b/harness/tests/skills/test_delivery.py
@@ -0,0 +1,143 @@
+"""One shared library, one place that knows how each backend receives it.
+
+The owner's requirement: every coding agent shares ONE skill set, extending to a new
+backend must be minimal, and the organisation has to hold up. So the whole per-backend
+policy is two bits in `skills/delivery.py` — has a native loader, and which discovery root
+— and every consumer asks it rather than re-deriving. These tests pin that.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from codeverse.skills.delivery import (
+ AGENTS_SKILL_ROOT,
+ CLAUDE_SKILL_ROOT,
+ delivery_for,
+ known_backends,
+)
+
+
+def test_a_native_loader_is_never_handed_a_second_index():
+ """It lists the bundles itself; ours on top would double-index the same skills."""
+ for kind in ("claude-code", "codex", "gemini-cli", "agy"):
+ d = delivery_for(kind)
+ assert d.native_loader and not d.needs_index and not d.needs_tool, kind
+
+
+def test_a_loaderless_backend_gets_both_the_index_and_the_tool():
+ """Measured 2026-08-25: the three native loaders read 5 of 5 routed bundles; api-agent
+ read 0 of 5 from a MANDATORY paragraph while making 52 read_file calls. Prose is not
+ an affordance, so a backend without a loader gets the routed set as a tool."""
+ d = delivery_for("api-agent")
+ assert not d.native_loader and d.needs_index and d.needs_tool
+
+
+def test_an_unclassified_backend_gets_the_safe_answer():
+ """Over-delivering costs tokens; under-delivering costs the skill entirely."""
+ for kind in ("some-future-cli", "", "typo-agent"):
+ d = delivery_for(kind)
+ assert d.needs_index and d.needs_tool, kind
+ assert d.root == AGENTS_SKILL_ROOT
+
+
+def test_a_qualified_kind_resolves_to_its_backend():
+ """`codex:gpt-5.6-sol` is codex; the model suffix must not fall through to unknown."""
+ assert delivery_for("codex:gpt-5.6-sol") == delivery_for("codex")
+ assert delivery_for("api-agent:gemini:gemini-3.7-flash") == delivery_for("api-agent")
+
+
+def test_claude_code_reads_its_own_root_and_nobody_else_does():
+ """Read out of the shipped binaries, not assumed: claude-code 2.1 has no `.agents`
+ skill root at all, and the other three have no `.claude` one."""
+ assert delivery_for("claude-code").root == CLAUDE_SKILL_ROOT
+ for kind in ("codex", "gemini-cli", "agy", "api-agent"):
+ assert delivery_for(kind).root == AGENTS_SKILL_ROOT, kind
+
+
[email protected]("kind", known_backends())
+def test_every_consumer_agrees_with_the_policy(kind):
+ """`prompting` must not re-derive what `delivery` decides — one source, or they drift."""
+ from codeverse.skills.prompting import NATIVE_LOADERS, skill_path
+
+ d = delivery_for(kind)
+ assert (kind in NATIVE_LOADERS) is d.native_loader
+ assert skill_path("cv3d-x", agent_kind=kind) == f"{d.root}/cv3d-x/SKILL.md"
+
+
+def test_adding_a_backend_is_one_row():
+ """The guard behind the claim: if per-backend knowledge spreads back out of
+ delivery.py, this catches it. `prompting` may name the backends it re-exports."""
+ import pathlib
+
+ root = pathlib.Path(__file__).resolve().parents[2] / "codeverse"
+ names = ("claude-code", "gemini-cli", "api-agent")
+ offenders = []
+ for py in (root / "skills").rglob("*.py"):
+ if py.name in ("delivery.py", "prompting.py"):
+ continue
+ text = py.read_text()
+ if any(f'"{n}"' in text or f"'{n}'" in text for n in names):
+ offenders.append(py.name)
+ assert not offenders, f"per-backend knowledge leaked out of delivery.py into {offenders}"
+
+
+# ------------------------------------------------------------------ the read_skill tool
+def _workspace_with_skills(tmp_path, agent_kind="api-agent"):
+ from codeverse.agents.materialize import materialize_workspace
+ from codeverse.skills import attach_skills
+ from codeverse.workspace import Workspace
+
+ ws = Workspace(tmp_path / "ws")
+ ws.create()
+ materialize_workspace(ws, agent_kind=agent_kind, contract_md="(contract)",
+ cookbook_rel=".c3v/cookbook.md", spatial_tools=False, mcp_command=[])
+ attach_skills(ws.root, track="static_object", language="blender", kind="baseline",
+ agent_kind=agent_kind)
+ return ws
+
+
+def test_the_tool_discovers_the_routed_set_off_the_workspace(tmp_path):
+ """Not threaded through AgentJob: the bundles are already on disk for this round, so
+ the tool reads what was actually written and cannot disagree with it."""
+ from codeverse.agents.api_skills import SkillTools
+
+ st = SkillTools(_workspace_with_skills(tmp_path))
+ assert st.listed, "nothing discovered"
+ spec = st.specs()[0]
+ assert spec.name == "read_skill"
+ assert spec.parameters["properties"]["name"]["enum"] == st.listed
+ for name in st.listed:
+ assert name in spec.description, "the model must be able to choose without opening one"
+
+
+def test_the_read_control_is_never_offered(tmp_path):
+ """It exists to catch a probe reporting a read nobody made; offering it would invite
+ exactly that."""
+ from codeverse.agents.api_skills import SkillTools
+ from codeverse.skills.materialize import CONTROL_NAME
+
+ assert CONTROL_NAME not in SkillTools(_workspace_with_skills(tmp_path)).listed
+
+
+def test_reading_records_ground_truth_and_rejects_an_unrouted_name(tmp_path):
+ from codeverse.agents.api_skills import SkillTools
+
+ st = SkillTools(_workspace_with_skills(tmp_path))
+ first = st.listed[0]
+ out = st.read_skill(first)
+ assert not out.is_error and len(out.text) > 200
+ assert st.reads == [first], "the read rate needs ground truth, not a probe"
+ bad = st.read_skill("cv3d-not-routed")
+ assert bad.is_error and "not routed" in bad.text
+ assert st.reads == [first], "a rejected call must not count as a read"
+
+
+def test_a_workspace_with_no_skills_advertises_no_tool(tmp_path):
+ """The feature being off must not leave a tool that always errors."""
+ from codeverse.agents.api_skills import SkillTools
+ from codeverse.workspace import Workspace
+
+ ws = Workspace(tmp_path / "bare")
+ ws.create()
+ assert SkillTools(ws).specs() == []