traceforge-toolkit 0.1.0__tar.gz → 0.1.1__tar.gz

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: traceforge-toolkit
-Version: 0.1.0
+Version: 0.1.1
 Summary: Framework-agnostic, CPU-only pipeline that forges AI agent traces into classified, risk-scored, governed output
 Project-URL: Homepage, https://github.com/dfinson/traceforge
 Project-URL: Repository, https://github.com/dfinson/traceforge
@@ -44,6 +44,10 @@ Requires-Dist: tree-sitter-powershell>=0.24
 Requires-Dist: tree-sitter>=0.24
 Requires-Dist: tzdata>=2024.1; platform_system == 'Windows'
 Requires-Dist: watchdog>=4.0
+Provides-Extra: claude
+Requires-Dist: claude-agent-sdk>=0.1; extra == 'claude'
+Provides-Extra: copilot
+Requires-Dist: github-copilot-sdk<0.4,>=0.3; extra == 'copilot'
 Provides-Extra: dev
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
@@ -60,7 +64,7 @@ Description-Content-Type: text/markdown
 
 [![Lint](https://github.com/dfinson/traceforge/actions/workflows/ci-lint.yml/badge.svg)](https://github.com/dfinson/traceforge/actions/workflows/ci-lint.yml)
 [![Test](https://github.com/dfinson/traceforge/actions/workflows/ci-test.yml/badge.svg)](https://github.com/dfinson/traceforge/actions/workflows/ci-test.yml)
-[![PyPI](https://img.shields.io/badge/PyPI-coming%20soon-FF9921)](https://pypi.org/project/traceforge/)
+[![PyPI](https://img.shields.io/pypi/v/traceforge-toolkit?color=FF9921&label=PyPI)](https://pypi.org/project/traceforge-toolkit/)
 [![Python](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13-256EF3)](https://github.com/dfinson/traceforge)
 [![License: MIT](https://img.shields.io/badge/license-MIT-7359AE.svg)](LICENSE)
 [![Docs](https://img.shields.io/badge/docs-traceforge-FF9921)](https://dfinson.github.io/traceforge/)
@@ -137,7 +141,12 @@ print(trace.risk_score, trace.suggested_action)   # e.g. 72 escalate
 ```
 
 See the **[Getting Started guide](https://dfinson.github.io/traceforge/docs/getting-started/installation)**
-for the full CLI (`watch`, `replay`, `score`, `gate`, `init`, `detect`, `status`, `config`, `download-model`).
+for the full CLI (`watch`, `replay`, `score`, `gate`, `init`, `detect`, `status`, `config`).
+
+`traceforge init <agent>` injects the blocking preflight gate hook into a supported agent's own
+native config — for Claude Code, a `PreToolUse` hook in `.claude/settings.json` that runs
+`traceforge gate --stdin`. It does not scaffold `~/.traceforge/` (that config bootstrap happens
+automatically on first config access).
 
 ## Features
 
@@ -179,7 +188,7 @@ the test suite, linting with `ruff`, and how to add a new agent framework mappin
 
 ## Status
 
-🚧 **Under active development**: not yet published to PyPI. The pipeline is feature-complete:
+✅ **Released**: available on PyPI as [`traceforge-toolkit`](https://pypi.org/project/traceforge-toolkit/) (`pip install traceforge-toolkit`). The pipeline is feature-complete:
 sources, adapters, enricher, classification, risk scoring, live phase/boundary/title structuring,
 the governance engine, all storage sinks, and the `traceforge` CLI all ship today.
 

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/README.md

@@ -6,7 +6,7 @@
 
 [![Lint](https://github.com/dfinson/traceforge/actions/workflows/ci-lint.yml/badge.svg)](https://github.com/dfinson/traceforge/actions/workflows/ci-lint.yml)
 [![Test](https://github.com/dfinson/traceforge/actions/workflows/ci-test.yml/badge.svg)](https://github.com/dfinson/traceforge/actions/workflows/ci-test.yml)
-[![PyPI](https://img.shields.io/badge/PyPI-coming%20soon-FF9921)](https://pypi.org/project/traceforge/)
+[![PyPI](https://img.shields.io/pypi/v/traceforge-toolkit?color=FF9921&label=PyPI)](https://pypi.org/project/traceforge-toolkit/)
 [![Python](https://img.shields.io/badge/python-3.11%20|%203.12%20|%203.13-256EF3)](https://github.com/dfinson/traceforge)
 [![License: MIT](https://img.shields.io/badge/license-MIT-7359AE.svg)](LICENSE)
 [![Docs](https://img.shields.io/badge/docs-traceforge-FF9921)](https://dfinson.github.io/traceforge/)
@@ -83,7 +83,12 @@ print(trace.risk_score, trace.suggested_action)   # e.g. 72 escalate
 ```
 
 See the **[Getting Started guide](https://dfinson.github.io/traceforge/docs/getting-started/installation)**
-for the full CLI (`watch`, `replay`, `score`, `gate`, `init`, `detect`, `status`, `config`, `download-model`).
+for the full CLI (`watch`, `replay`, `score`, `gate`, `init`, `detect`, `status`, `config`).
+
+`traceforge init <agent>` injects the blocking preflight gate hook into a supported agent's own
+native config — for Claude Code, a `PreToolUse` hook in `.claude/settings.json` that runs
+`traceforge gate --stdin`. It does not scaffold `~/.traceforge/` (that config bootstrap happens
+automatically on first config access).
 
 ## Features
 
@@ -125,7 +130,7 @@ the test suite, linting with `ruff`, and how to add a new agent framework mappin
 
 ## Status
 
-🚧 **Under active development**: not yet published to PyPI. The pipeline is feature-complete:
+✅ **Released**: available on PyPI as [`traceforge-toolkit`](https://pypi.org/project/traceforge-toolkit/) (`pip install traceforge-toolkit`). The pipeline is feature-complete:
 sources, adapters, enricher, classification, risk scoring, live phase/boundary/title structuring,
 the governance engine, all storage sinks, and the `traceforge` CLI all ship today.
 

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "traceforge-toolkit"
-version = "0.1.0"
+version = "0.1.1"
 description = "Framework-agnostic, CPU-only pipeline that forges AI agent traces into classified, risk-scored, governed output"
 readme = "README.md"
 license = "MIT"
@@ -70,6 +70,12 @@ dev = [
 s3 = [
     "boto3>=1.28",
 ]
+copilot = [
+    "github-copilot-sdk>=0.3,<0.4",
+]
+claude = [
+    "claude-agent-sdk>=0.1",
+]
 
 [project.scripts]
 traceforge = "traceforge.cli:main"

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/src/traceforge/__init__.py

@@ -20,14 +20,25 @@ from traceforge.classify import (
 from traceforge.enricher import Enricher
 from traceforge.parsers.aider import AiderPreParser
 from traceforge.pipeline import EventPipeline
+from traceforge.progress import ProgressEmitter
 from traceforge.sinks.base import StorageSink
 from traceforge.sinks.callback import CallbackSink
+from traceforge.telemetry.attribution import (
+    DURATION_MS_ATTR,
+    Anomaly,
+    AttributionRollup,
+    Attributor,
+    build_attributor,
+)
 from traceforge.trace import EventTrace
 from traceforge.types import (
     KNOWN_KINDS,
+    TRACE_NATIVE_DIMENSIONS,
+    CostBreakdown,
     EventKind,
     EventMetadata,
     IngestionMode,
+    ProgressUpdate,
     SessionEvent,
     TelemetrySpan,
     TitleUpdate,
@@ -54,6 +65,8 @@ __all__ = [
     "IngestionMode",
     "KNOWN_KINDS",
     "Phase",
+    "ProgressEmitter",
+    "ProgressUpdate",
     "SessionEvent",
     "StorageSink",
     "TelemetrySpan",
@@ -69,4 +82,12 @@ __all__ = [
     "is_known_kind",
     "load_config",
     "normalize_tool_name",
+    # Attribution (U11)
+    "Anomaly",
+    "AttributionRollup",
+    "Attributor",
+    "CostBreakdown",
+    "DURATION_MS_ATTR",
+    "TRACE_NATIVE_DIMENSIONS",
+    "build_attributor",
 ]

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/src/traceforge/classify/__init__.py

@@ -43,6 +43,7 @@ from traceforge.classify.shell import (
     classify_shell,
 )
 from traceforge.classify.tools import classify_tool, normalize_tool_name
+from traceforge.classify.tool_display import ToolDisplayProvider, ToolDisplayResolver
 from traceforge.classify.workflow import Phase, Visibility
 
 __all__ = [
@@ -87,6 +88,9 @@ __all__ = [
     "McpServerProfile",
     "McpToolOverride",
     "normalize_tool_name",
+    # Tool display
+    "ToolDisplayProvider",
+    "ToolDisplayResolver",
     # Risk scoring
     "Confidence",
     "RiskAssessment",

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/src/traceforge/classify/config.py

@@ -142,6 +142,11 @@ class ClassifyConfig(StrictModel):
     verification_role_actions: dict[str, str] = Field(default_factory=dict)
     transparent_wrappers: list[str] = Field(default_factory=list)
     activity_defaults: dict[str, dict[str, str]] = Field(default_factory=dict)
+    # Canonical tool identity -> human-facing display label. Populates
+    # EventMetadata.tool_display at enrichment. Small generic default set; a
+    # consumer supplies its own vocabulary as an overlay via the config-override /
+    # traceforge.profiles entry-point chain (per-key override wins).
+    tool_display: dict[str, str] = Field(default_factory=dict)
 
     @classmethod
     def from_yaml(cls, path: str | Path) -> ClassifyConfig:
@@ -226,6 +231,7 @@ def _load_builtin_defaults() -> dict[str, Any]:
         "mcp_profiles.yaml",
         "shell_rules.yaml",
         "tool_classifications.yaml",
+        "tool_display.yaml",
     ):
         resource = data_dir / filename
         try:
@@ -387,6 +393,7 @@ class ClassificationEngine:
     __slots__ = (
         "canonical_tools",
         "tool_classifications",
+        "tool_display",
         "verb_inference",
         "effect_overrides",
         "shell_rules",
@@ -414,6 +421,12 @@ class ClassificationEngine:
             k.lower().replace("-", "_"): v for k, v in config.canonical_tools.items()
         }
 
+        # Tool display labels — canonical tool identity -> human-facing label.
+        # Keys normalized like canonical_tools so lookup matches normalize_tool_name.
+        self.tool_display: dict[str, str] = {
+            k.lower().replace("-", "_"): v for k, v in config.tool_display.items()
+        }
+
         # Tool classifications (with phase_map derived)
         self.tool_classifications: dict[str, Classification] = {}
         for name, tc in config.tool_classifications.items():

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/src/traceforge/classify/data/binary_info.yaml

@@ -206,6 +206,7 @@ binary_info:
   invoke-webrequest: { role: retriever.api_client, default_effect: null, network: true }
   nc: { role: retriever.api_client, default_effect: null, network: true }
   ncat: { role: retriever.api_client, default_effect: null, network: true }
+  netcat: { role: retriever.api_client, default_effect: null, network: true }
   nslookup: { role: retriever.api_client, default_effect: read_only, network: true }
   ping: { role: retriever.api_client, default_effect: read_only, network: true }
   socat: { role: retriever.api_client, default_effect: null, network: true }

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/src/traceforge/classify/data/effect_overrides.yaml

@@ -83,6 +83,47 @@ effect_overrides:
         mode: any_present
     default_effect: read_only
 
+  # netcat family / socat: a bare connection transfers data (mutating sink).
+  # Listen mode (-l/-L/--listen/-k) and help/version are read-only. This lets a
+  # read-sensitive-then-network pipe (e.g. `cat secret | nc host port`) aggregate
+  # to a mutating effect and trip the mutating_with_network rule.
+  nc:
+    flag_effects:
+      - flags: ["-l", "-L", "--listen", "-k"]
+        effect: read_only
+        mode: any_present
+      - flags: ["-h", "--help", "-V", "--version"]
+        effect: read_only
+        mode: any_present
+    default_effect: mutating
+
+  ncat:
+    flag_effects:
+      - flags: ["-l", "-L", "--listen", "-k"]
+        effect: read_only
+        mode: any_present
+      - flags: ["-h", "--help", "-V", "--version"]
+        effect: read_only
+        mode: any_present
+    default_effect: mutating
+
+  netcat:
+    flag_effects:
+      - flags: ["-l", "-L", "--listen", "-k"]
+        effect: read_only
+        mode: any_present
+      - flags: ["-h", "--help", "-V", "--version"]
+        effect: read_only
+        mode: any_present
+    default_effect: mutating
+
+  socat:
+    flag_effects:
+      - flags: ["-h", "-hh", "-hhh", "--help", "-V", "--version"]
+        effect: read_only
+        mode: any_present
+    default_effect: mutating
+
   # Git: subcmd determines effect
   git:
     subcmd_effects:

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/src/traceforge/classify/data/recommendation_rules.yaml

@@ -91,6 +91,37 @@ recommendation_rules:
     recommend: warn
     reason: content_integrity_mismatch
 
+  # ── Semantic hazard tags (classify/hazards.py) ──
+  # These escalate dangerous command shapes regardless of numeric risk score.
+
+  # Raw block-device write (dd of=/dev/sda, redirect into /dev/nvme0n1, ...)
+  - id: raw_device_write
+    when:
+      capability: [raw_device_write]
+    recommend: escalate
+    reason: raw_block_device_write
+
+  # Filesystem format / wipe (mkfs*, mke2fs, mkswap, wipefs, destructive parted)
+  - id: filesystem_format
+    when:
+      capability: [filesystem_format]
+    recommend: escalate
+    reason: filesystem_format
+
+  # Persistence-mechanism write (cron, systemd unit, shell rc file)
+  - id: persistence_write
+    when:
+      capability: [persistence_write]
+    recommend: escalate
+    reason: persistence_mechanism_write
+
+  # Fork bomb / resource-exhaustion pattern
+  - id: fork_bomb
+    when:
+      capability: [fork_bomb]
+    recommend: escalate
+    reason: fork_bomb_pattern
+
   # Fallback risk score thresholds
   - id: risk_critical
     when:

traceforge_toolkit-0.1.1/src/traceforge/classify/data/tool_display.yaml

@@ -0,0 +1,30 @@
+# Tool display names — maps a canonical tool identity to a human-facing label.
+#
+# This populates ``EventMetadata.tool_display`` at enrichment time. Keys are the
+# CANONICAL tool identity (the normalized form produced by ``normalize_tool_name``,
+# e.g. every shell-family alias collapses to ``shell``, every read alias to
+# ``view``), NOT the raw per-harness tool name.
+#
+# This is a SMALL, GENERAL default set covering the universal coding-agent tool
+# taxonomy. It is an extension point: supply your own ``tool_display:`` section via
+# the standard config-override chain (``.traceforge/config.yaml``, a
+# ``TRACEFORGE_CONFIG`` file, or a ``traceforge.profiles`` entry point) to add or
+# override labels with your own vocabulary. Per-key overrides win over these
+# defaults; unknown tools resolve to None (the stub stays empty, unchanged).
+
+tool_display:
+  shell: shell
+  view: read file
+  edit: edit file
+  create: create file
+  delete_file: delete file
+  grep: search
+  glob: find files
+  codebase_search: search codebase
+  web_fetch: fetch url
+  web_search: web search
+  web_browse: browse web
+  task: delegate task
+  ask_user: ask user
+  report_intent: report intent
+  think: think

traceforge_toolkit-0.1.1/src/traceforge/classify/hazards.py

@@ -0,0 +1,126 @@
+"""Semantic hazard detection for shell commands.
+
+Adds high-signal *capability* tags for dangerous command shapes that the
+structural classifier (effect × scope) does not by itself gate — raw block-device
+writes, filesystem formats/wipes, persistence-mechanism writes, and fork bombs.
+
+These tags are consumed by the governance recommendation rules
+(``recommendation_rules.yaml``) to escalate the command regardless of its numeric
+risk score. Detection is pure, deterministic regex/binary matching over the raw
+command string and the already-parsed :class:`Classification`, so it introduces no
+nondeterminism and no new scoring weight (the tags are not in
+``risk.yaml: capability_weights``, so the numeric score is unchanged).
+"""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from traceforge.classify.core import Classification
+
+# ── Capability tag names (kept in sync with recommendation_rules.yaml) ──
+RAW_DEVICE_WRITE = "raw_device_write"
+FILESYSTEM_FORMAT = "filesystem_format"
+PERSISTENCE_WRITE = "persistence_write"
+FORK_BOMB = "fork_bomb"
+
+# ── 1. Raw block-device write ───────────────────────────────────────────────
+# dd ... of=/dev/sda, or a redirect (>, >>) into a physical block device.
+# Physical device classes only — /dev/null, /dev/zero, /dev/urandom, /dev/tty
+# are deliberately excluded so benign `> /dev/null` never trips.
+_RAW_DEVICE_WRITE = re.compile(
+    r"(?:\bof=|>>?\s*)/dev/(?:sd|nvme|disk|hd|vd|mmcblk|xvd)\w*",
+    re.IGNORECASE,
+)
+
+# ── 2. Filesystem format / wipe ─────────────────────────────────────────────
+# Unambiguous formatter binaries (mkfs, mkfs.<fs>, mke2fs, mkswap, wipefs) plus
+# destructive partition-table ops on parted/sfdisk/sgdisk. Read-only inspection
+# (`parted -l`, `fdisk -l`, `parted <dev> print`) is NOT matched.
+_FORMAT_BINARIES = frozenset({"mkfs", "mke2fs", "mkswap", "wipefs"})
+_DISK_PARTITION_TOOLS = frozenset({"parted", "sfdisk", "sgdisk"})
+_DISK_DESTRUCTIVE_OP = re.compile(
+    r"(?<!\S)(?:mklabel|mkpart|--zap-all|--zap|-Z|--delete|--new)\b",
+    re.IGNORECASE,
+)
+
+# ── 3. Persistence-mechanism write ──────────────────────────────────────────
+# A write mechanism (redirect, tee, cp/mv/install/ln, or the crontab binary)
+# targeting a known persistence location: cron, systemd units, or shell rc files.
+_PERSIST_PATH = (
+    r"(?:"
+    r"/etc/cron(?:\.[a-z]+|tab|\.d)?"
+    r"|/var/spool/cron"
+    r"|/etc/systemd/|/run/systemd/|/lib/systemd/|/usr/lib/systemd/"
+    r"|/etc/profile(?:\.d)?|/etc/bash\.bashrc|/etc/zsh/|/etc/zprofile|/etc/zshrc"
+    r"|(?:~|\$HOME|/root|/home/[^/\s]+)/"
+    r"\.(?:bashrc|bash_profile|bash_login|profile|zshrc|zprofile|zlogin|zshenv)"
+    r"|(?:~|\$HOME|/root|/home/[^/\s]+)/\.config/(?:systemd|autostart)"
+    r")"
+)
+_PERSIST_REDIRECT = re.compile(r">>?\s*[\"']?" + _PERSIST_PATH)
+_PERSIST_TEE = re.compile(r"\btee\b(?:\s+-{1,2}\S+)*\s+[\"']?" + _PERSIST_PATH)
+_PERSIST_COPY = re.compile(r"\b(?:cp|mv|install|ln)\b[^\n]*?" + _PERSIST_PATH)
+
+# ── 4. Fork bomb ────────────────────────────────────────────────────────────
+# A function that recursively pipes itself into the background, then invokes
+# itself: classic `:(){ :|:& };:` and named variants like `b(){ b|b& };b`.
+_FORK_BOMB = re.compile(
+    r"(?P<n>[\w:.\-]+)\s*\(\)\s*\{(?P<body>[^{}]*)\}\s*;\s*(?P=n)",
+    re.DOTALL,
+)
+
+
+def _is_fork_bomb(command: str) -> bool:
+    for match in _FORK_BOMB.finditer(command):
+        name = match.group("n")
+        body = match.group("body")
+        if "|" in body and "&" in body and body.count(name) >= 2:
+            return True
+    return False
+
+
+def _has_filesystem_format(command: str, binaries: tuple[str, ...]) -> bool:
+    for binary in binaries:
+        if binary in _FORMAT_BINARIES or binary.startswith("mkfs."):
+            return True
+    if any(tool in binaries for tool in _DISK_PARTITION_TOOLS):
+        return bool(_DISK_DESTRUCTIVE_OP.search(command))
+    return False
+
+
+def _has_persistence_write(command: str, binaries: tuple[str, ...]) -> bool:
+    if "crontab" in binaries:
+        return True
+    return bool(
+        _PERSIST_REDIRECT.search(command)
+        or _PERSIST_TEE.search(command)
+        or _PERSIST_COPY.search(command)
+    )
+
+
+def detect_command_hazards(command: str, classification: Classification) -> set[str]:
+    """Return semantic hazard capability tags for a shell command.
+
+    Pure and deterministic: matches the raw command string and the parsed
+    binaries. Tags are score-neutral (no ``capability_weights`` entry) and are
+    used only to drive escalation via the recommendation rules.
+    """
+    hazards: set[str] = set()
+    if not command:
+        return hazards
+
+    binaries = classification.binaries or ()
+
+    if _RAW_DEVICE_WRITE.search(command):
+        hazards.add(RAW_DEVICE_WRITE)
+    if _has_filesystem_format(command, binaries):
+        hazards.add(FILESYSTEM_FORMAT)
+    if _has_persistence_write(command, binaries):
+        hazards.add(PERSISTENCE_WRITE)
+    if _is_fork_bomb(command):
+        hazards.add(FORK_BOMB)
+
+    return hazards

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/src/traceforge/classify/shell.py

@@ -23,6 +23,7 @@ from traceforge.classify.coding import (
     CodingMechanism,
     ShellStructure,
 )
+from traceforge.classify.hazards import detect_command_hazards
 from traceforge.classify.rules import (
     SHELL_DELIVERY,
     SHELL_SETUP,
@@ -476,6 +477,8 @@ def classify_shell(
     cls = build_classification_from_commands(command_results, structure, "bash")
     # Merge wrapper capabilities (e.g., elevated_privilege from sudo)
     extra_caps: set[str] = set(all_wrapper_caps)
+    # Semantic hazard tags (raw-device write, fs format, persistence, fork bomb)
+    extra_caps |= detect_command_hazards(command, cls)
     extra_effect: str | None = None
     # Redirections (>, >>, 2>) indicate filesystem writes
     if ShellStructure.REDIRECTED in structure:

traceforge_toolkit-0.1.1/src/traceforge/classify/tool_display.py

@@ -0,0 +1,113 @@
+"""Tool display resolution — populate ``EventMetadata.tool_display``.
+
+The display string is the human-facing label for a tool call (e.g. ``"read file"``
+for a ``view``-family tool). It is resolved at enrichment time from the canonical
+tool identity via a layered chain:
+
+1. Programmatic :class:`ToolDisplayProvider` objects (consumer-supplied extension
+   point) — first non-empty result wins. Lets a consumer compute a label
+   dynamically (e.g. per MCP server) beyond what a static map can express.
+2. A static display map (canonical tool identity -> label). This is the
+   ``tool_display`` section of :class:`~traceforge.classify.config.ClassifyConfig`:
+   the built-in generic defaults merged under consumer overrides through the same
+   config-override / ``traceforge.profiles`` entry-point chain used for
+   ``tool_classifications`` / ``mcp_profiles`` / ``tool_overrides``. Per-key
+   overrides win over the defaults.
+3. ``None`` — unknown tools degrade gracefully (the stub stays empty, as before).
+
+Ship only GENERAL defaults here; a consumer supplies its own vocabulary as an
+overlay. Nothing consumer-specific belongs in this module or the default data.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Mapping, Sequence
+from typing import Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+def _normalize_key(name: str) -> str:
+    """Normalize a tool key to the canonical lookup form (lower, dashes -> underscores).
+
+    Mirrors the normalization applied to canonical tool names so map keys and the
+    resolved ``canonical`` argument compare equal regardless of casing/dashes.
+    """
+    return name.lower().replace("-", "_")
+
+
+@runtime_checkable
+class ToolDisplayProvider(Protocol):
+    """Extension point: resolve a display label for a tool call.
+
+    Consumers implement this to supply dynamic or domain-specific display logic
+    that a static map cannot express. It is consulted before the static display
+    map, so a provider can override the shipped defaults.
+
+    Return a non-empty label to claim the tool call, or ``None`` (or an empty
+    string) to defer to the next resolver in the chain (static map, then ``None``).
+    """
+
+    def display_for(self, canonical: str, raw: str) -> str | None:
+        """Return a display label for the tool call, or ``None`` to defer.
+
+        Args:
+            canonical: The normalized/canonical tool identity (e.g. ``"view"``).
+            raw: The original tool name as it appeared on the event (e.g.
+                ``"read_file"`` or ``"mcp__server__search"``).
+        """
+        ...
+
+
+class ToolDisplayResolver:
+    """Resolve a tool call to its display label from providers + a static map.
+
+    Immutable after construction. One resolver serves every tool call an
+    :class:`~traceforge.enricher.Enricher` observes.
+    """
+
+    __slots__ = ("_display_map", "_providers")
+
+    def __init__(
+        self,
+        display_map: Mapping[str, str] | None = None,
+        providers: Sequence[ToolDisplayProvider] | None = None,
+    ) -> None:
+        """
+        Args:
+            display_map: Canonical tool identity -> display label. Keys are
+                normalized on ingest, so callers may pass raw-cased keys.
+            providers: Optional programmatic providers, consulted in order before
+                the static map. The first non-empty result wins.
+        """
+        self._display_map: dict[str, str] = {
+            _normalize_key(k): v for k, v in (display_map or {}).items()
+        }
+        self._providers: tuple[ToolDisplayProvider, ...] = tuple(providers or ())
+
+    def resolve(self, *, canonical: str, raw: str) -> str | None:
+        """Resolve the display label for a tool call.
+
+        Args:
+            canonical: The normalized/canonical tool identity.
+            raw: The original tool name as it appeared on the event.
+
+        Returns:
+            The display label, or ``None`` when nothing matches (unknown tools
+            degrade gracefully — the stub stays empty).
+        """
+        for provider in self._providers:
+            try:
+                result = provider.display_for(canonical, raw)
+            except Exception:
+                # A misbehaving consumer provider must never break enrichment;
+                # log and fall through to the next resolver.
+                logger.warning("ToolDisplayProvider %r raised; ignoring", provider, exc_info=True)
+                continue
+            if result:
+                return result
+
+        # Empty label is treated as "no display" so a map entry cannot force an
+        # empty string onto the stub.
+        return self._display_map.get(_normalize_key(canonical)) or None

{traceforge_toolkit-0.1.0 → traceforge_toolkit-0.1.1}/src/traceforge/cli/__init__.py

@@ -14,7 +14,6 @@ from traceforge.cli.replay import replay
 from traceforge.cli.status import status
 from traceforge.cli.gate_cmd import gate
 from traceforge.cli.init_cmd import init
-from traceforge.cli.download_cmd import download_model
 
 
 @click.group()
@@ -39,4 +38,3 @@ main.add_command(config)
 main.add_command(status)
 main.add_command(gate)
 main.add_command(init)
-main.add_command(download_model)

traceforge_toolkit-0.1.1/src/traceforge/cli/gate_cmd.py

@@ -0,0 +1,60 @@
+"""traceforge gate — CLI command for cross-process gating relay."""
+
+from __future__ import annotations
+
+import click
+
+#: CLI / editor agents that expose an injectable, blocking preflight hook. The
+#: injector (``traceforge init``) writes ``gate --stdin --agent <name>`` into each
+#: agent's hook config, and ``--agent`` selects the matching deny-contract dialect
+#: (JSON shape + exit code) — see ``traceforge.gate.client._output_deny``.
+SUPPORTED_AGENTS: tuple[str, ...] = (
+    "claude-code",
+    "copilot-cli",
+    "codex",
+    "gemini",
+    "cline",
+    "cursor",
+    "amazon-q",
+    "opencode",
+    "openhands",
+)
+
+
+@click.command("gate")
+@click.option("--stdin", "from_stdin", is_flag=True, help="Read event JSON from stdin.")
+@click.option(
+    "--agent",
+    "agent",
+    default=None,
+    type=click.Choice(SUPPORTED_AGENTS),
+    help="Translate the verdict into this agent's native hook deny contract "
+    "(shape + exit code). Defaults to the Claude Code dialect.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    default=None,
+    type=click.Choice(["claude-code", "json"]),
+    help='Output format for the verdict (legacy; prefer --agent). "json" emits the raw verdict.',
+)
+def gate(from_stdin: bool, agent: str | None, output_format: str | None) -> None:
+    """Relay a tool call event to the running Pipeline for gating.
+
+    Reads event JSON from stdin, looks up the Pipeline IPC server by session_id,
+    sends the event for scoring, and outputs the verdict in the target agent's
+    native hook dialect.
+
+    Typically invoked by agent hooks (e.g. Claude Code PreToolUse, Copilot CLI
+    preToolUse, Codex PreToolUse). ``--agent`` picks the deny contract; when it is
+    omitted the Claude Code dialect is used (also selectable via ``--format``).
+    """
+    if not from_stdin:
+        raise click.UsageError("--stdin is required (only stdin mode is currently supported)")
+
+    # --agent is the primary selector; --format stays for backward compatibility.
+    dialect = agent or output_format or "claude-code"
+
+    from traceforge.gate.client import gate_from_stdin
+
+    gate_from_stdin(format=dialect)