delimit-cli 4.7.1 → 4.7.2

package/CHANGELOG.md

@@ -1,6 +1,28 @@
 # Changelog
 
 
+## [4.7.2] - 2026-06-04
+
+### Fixed
+
+- **Tool-usage telemetry now persists.** `record_call` previously only kept an
+  in-memory per-session counter that vanished on restart, so tool utilization
+  was unobservable. It now appends every call to `~/.delimit/tool_usage.jsonl`
+  (crash-safe, append-only), making utilization and dormancy measurable.
+
+### Added
+
+- **`delimit_toolcard_cache action="usage"`** — durable tool-utilization +
+  dormancy report (per-tool call counts, `last_seen`, and registered tools never
+  called).
+- Additive next-step suggestions wiring under-surfaced tools into the governance
+  loop: `lint → impact`, `agent_dispatch → agent_link`, `deploy_verify →
+  seal_verify`, `evidence_collect → seal_verify`, `os_plan → os_gates`.
+
+Purely additive — no tool signature or behavior changed. Published via OIDC
+trusted publishing with provenance.
+
+
 ## [4.7.1] - 2026-06-03
 
 Release-infrastructure update. No functional changes to the package versus 4.7.0.

package/gateway/ai/server.py

@@ -742,6 +742,7 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
     "lint": [
         {"tool": "delimit_explain", "reason": "Get migration guide for breaking changes", "suggested_args": {"template": "migration"}, "is_premium": False},
         {"tool": "delimit_semver", "reason": "Determine the version bump for these changes", "suggested_args": {}, "is_premium": False},
+        {"tool": "delimit_impact", "reason": "Enumerate downstream callers affected by a breaking change before it ships", "suggested_args": {}, "is_premium": True},
     ],
     "diff": [
         {"tool": "delimit_semver", "reason": "Classify the semver bump for these changes", "suggested_args": {}, "is_premium": False},
@@ -766,7 +767,9 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
         {"tool": "delimit_diagnose", "reason": "Check environment and tool status", "suggested_args": {}, "is_premium": False},
     ],
     # --- Tier 2 Platform (Pro) ---
-    "os_plan": [],
+    "os_plan": [
+        {"tool": "delimit_os_gates", "reason": "Check whether the new OS plan passes its governance gates", "suggested_args": {}, "is_premium": True},
+    ],
     "os_status": [],
     "os_gates": [],
     "gov_health": [
@@ -799,6 +802,7 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
     # --- Agent Orchestration (Pro) ---
     "agent_dispatch": [
         {"tool": "delimit_agent_status", "reason": "Check the status of your dispatched task", "suggested_args": {}, "is_premium": True},
+        {"tool": "delimit_agent_link", "reason": "Link this dispatched task to its ledger item for the replay/audit trail (operating-model mandate)", "suggested_args": {}, "is_premium": True},
     ],
     "agent_status": [
         {"tool": "delimit_agent_complete", "reason": "Mark a task as complete when done", "suggested_args": {}, "is_premium": True},
@@ -871,6 +875,10 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
     "deploy_publish": [
         {"tool": "delimit_deploy_verify", "reason": "Verify deployment health after publish", "suggested_args": {}, "is_premium": True},
     ],
+    "deploy_verify": [
+        {"tool": "delimit_evidence_collect", "reason": "Collect a deploy evidence bundle", "suggested_args": {}, "is_premium": True},
+        {"tool": "delimit_seal_verify", "reason": "Verify the signed, replayable attestation produced by the deploy", "suggested_args": {}, "is_premium": False},
+    ],
     "deploy_rollback": [],
     "deploy_status": [],
     "generate_template": [],
@@ -880,9 +888,13 @@ NEXT_STEPS_REGISTRY: Dict[str, List[Dict[str, Any]]] = {
     ],
     "evidence_collect": [
         {"tool": "delimit_evidence_verify", "reason": "Verify evidence bundle integrity", "suggested_args": {}, "is_premium": True},
+        {"tool": "delimit_seal_verify", "reason": "Verify the Seal attestation receipt (Ed25519 + content-pin) for this artifact", "suggested_args": {}, "is_premium": False},
     ],
     "evidence_verify": [],
-    "seal_verify": [],
+    "seal_verify": [
+        {"tool": "delimit_evidence_collect", "reason": "Collect an evidence bundle for the verified attestation", "suggested_args": {}, "is_premium": True},
+        {"tool": "delimit_notify", "reason": "Notify stakeholders that the merge attestation verified", "suggested_args": {}, "is_premium": True},
+    ],
     "security_audit": [
         {"tool": "delimit_security_scan", "reason": "Run deeper security scan on flagged areas", "suggested_args": {}, "is_premium": True},
         {"tool": "delimit_evidence_collect", "reason": "Collect evidence of security findings", "suggested_args": {}, "is_premium": True},
@@ -13235,7 +13247,7 @@ def delimit_loop_config(session_id: Annotated[str, Field(description="Session to
 
 @mcp.tool()
 def delimit_toolcard_cache(
-    action: Annotated[str, Field(description="One of \"status\" (default), \"register\", \"delta\", \"clear\", \"estimate\", \"flush\".")] = "status",
+    action: Annotated[str, Field(description="One of \"status\" (default), \"register\", \"delta\", \"clear\", \"estimate\", \"flush\", \"usage\" (durable tool utilization + dormancy report).")] = "status",
     tool_schemas: Annotated[Optional[str], Field(description="JSON array of tool schema objects (for register/ estimate).")] = None,
     tool_names: Annotated[Optional[str], Field(description="Comma-separated tool names (for delta).")] = None,
 ) -> Dict[str, Any]:
@@ -13255,13 +13267,16 @@ def delimit_toolcard_cache(
 
     Args:
         action: One of "status" (default), "register", "delta",
-            "clear", "estimate", "flush".
+            "clear", "estimate", "flush", "usage". "usage" returns the
+            durable tool-utilization + dormancy report (per-tool call
+            counts, last_seen, and registry tools never called).
         tool_schemas: JSON array of tool schema objects (for register/
             estimate).
         tool_names: Comma-separated tool names (for delta).
 
     Returns:
-        Dict with the action result (stats, delta names, estimate, etc).
+        Dict with the action result (stats, delta names, estimate,
+        usage/dormancy summary, etc).
     """
     from ai.license import require_premium
     gate = require_premium("toolcard_cache")
@@ -13306,8 +13321,26 @@ def delimit_toolcard_cache(
         r = cache.estimate_savings(schemas)
     elif action == "flush":
         r = cache.flush_session()
+    elif action == "usage":
+        # Durable tool utilization / dormancy report. record_call now persists
+        # every call to ~/.delimit/tool_usage.jsonl; usage_summary aggregates
+        # counts + last_seen and, given the registered-tool list, flags tools
+        # never called as `dormant`. Mechanizes the dormant-tool audit.
+        registry = None
+        try:
+            tm = getattr(mcp, "_tool_manager", None)
+            if tm is not None:
+                if hasattr(tm, "list_tools"):
+                    registry = [getattr(t, "name", None) or t.get("name") for t in tm.list_tools()]
+                elif hasattr(tm, "_tools"):
+                    registry = list(tm._tools.keys())
+            if registry:
+                registry = sorted(n for n in registry if n)
+        except Exception:
+            registry = None
+        r = cache.usage_summary(registry=registry)
     else:
-        r = {"error": "unknown_action", "message": f"Unknown action: {action}. Use: status, register, delta, clear, estimate, flush"}
+        r = {"error": "unknown_action", "message": f"Unknown action: {action}. Use: status, register, delta, clear, estimate, flush, usage"}
 
     return _with_next_steps("toolcard_cache", r)
 

package/gateway/ai/toolcard_cache.py

@@ -209,8 +209,71 @@ class ToolcardCache:
         }
 
     def record_call(self, tool_name: str) -> None:
-        """Record that a tool was called in the current session."""
+        """Record that a tool was called: in-memory (session) AND durably.
+
+        The prior implementation only kept an in-memory counter that vanished on
+        process restart, so tool utilization was never observable across sessions
+        (usage.json stayed empty and dormancy was unmeasurable). We now also
+        append to a crash-safe, append-only JSONL event log so utilization is
+        measurable over time. Append is O(1) with no read-modify-write race.
+        Analytics must never break a tool call, so all failures are swallowed.
+        """
         self._session_calls[tool_name] = self._session_calls.get(tool_name, 0) + 1
+        try:
+            usage_log = self._cache_file.parent / "tool_usage.jsonl"
+            usage_log.parent.mkdir(parents=True, exist_ok=True)
+            with open(usage_log, "a") as f:
+                f.write(json.dumps({
+                    "ts": datetime.now(timezone.utc).isoformat(),
+                    "tool": tool_name,
+                }) + "\n")
+        except Exception:
+            pass
+
+    def usage_summary(self, registry: Optional[List[str]] = None) -> Dict[str, Any]:
+        """Aggregate the durable usage log into per-tool counts + dormancy.
+
+        Reads tool_usage.jsonl (written by record_call). When `registry` (the
+        full list of registered tool names) is provided, tools that appear in
+        the registry but never in the log are reported as `dormant`.
+        """
+        usage_log = self._cache_file.parent / "tool_usage.jsonl"
+        counts: Dict[str, int] = {}
+        last_seen: Dict[str, str] = {}
+        total = 0
+        try:
+            with open(usage_log, "r") as f:
+                for line in f:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        rec = json.loads(line)
+                    except Exception:
+                        continue
+                    name = rec.get("tool")
+                    if not name:
+                        continue
+                    counts[name] = counts.get(name, 0) + 1
+                    ts = rec.get("ts")
+                    if ts and (name not in last_seen or ts > last_seen[name]):
+                        last_seen[name] = ts
+                    total += 1
+        except FileNotFoundError:
+            pass
+        result: Dict[str, Any] = {
+            "total_calls": total,
+            "distinct_tools_used": len(counts),
+            "counts": dict(sorted(counts.items(), key=lambda x: x[1], reverse=True)),
+            "last_seen": last_seen,
+            "usage_log": str(usage_log),
+        }
+        if registry is not None:
+            used = set(counts)
+            result["registry_size"] = len(registry)
+            result["dormant"] = sorted(t for t in registry if t not in used)
+            result["dormant_count"] = len(result["dormant"])
+        return result
 
     def get_stats(self) -> Dict[str, Any]:
         """Return cache stats: total tools, cached, cache hit rate, token savings."""

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "delimit-cli",
   "mcpName": "io.github.delimit-ai/delimit-mcp-server",
-  "version": "4.7.1",
+  "version": "4.7.2",
   "description": "Unify Claude Code, Codex, Cursor, and Gemini CLI with persistent context, governance, and multi-model debate.",
   "main": "index.js",
   "files": [