stdtel 0.2.3__py3-none-any.whl

stdtel/exporter.py

@@ -0,0 +1,113 @@
+"""OTel span emission for std.skill.invocation. Metadata only — never content."""
+from __future__ import annotations
+
+import os
+import time
+from typing import Iterable
+
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter, SimpleSpanProcessor
+
+SPAN_NAME = "std.skill.invocation"
+SESSION_SPAN_NAME = "std.session.cost"
+DEFAULT_ENDPOINT = "http://localhost:4318"
+DEFAULT_TIMEOUT_S = 2
+# Widened when the hook began seeing every tool, not just Skill: tool_input and
+# tool_response carry file contents, commands and diffs, none of which may leave
+# the machine. Counts only.
+FORBIDDEN_PREFIXES = ("gen_ai.input", "gen_ai.output", "gen_ai.prompt", "gen_ai.completion",
+                      "tool.input", "tool.output", "tool.arguments", "tool.result",
+                      "tool_input", "tool_response", "std.tool.input", "std.tool.output")
+
+
+def build_provider(resource_attrs: dict, exporter: SpanExporter | None = None) -> TracerProvider:
+    base = {"service.name": os.environ.get("OTEL_SERVICE_NAME", "stdtel"),
+            "std.harness": resource_attrs.get("std.harness", "claude-code")}
+    base.update({k: v for k, v in resource_attrs.items() if v is not None})
+    provider = TracerProvider(resource=Resource.create(base))
+    if exporter is None:
+        provider.add_span_processor(BatchSpanProcessor(_otlp_exporter()))
+    else:
+        provider.add_span_processor(SimpleSpanProcessor(exporter))
+    return provider
+
+
+def _endpoint() -> str:
+    """Full traces endpoint URL.
+
+    Claude Code strips `OTEL_*` from every subprocess it spawns, so a hook can
+    never see OTEL_EXPORTER_OTLP_ENDPOINT no matter where it is set — it would
+    silently fall back to localhost. STDTEL_OTLP_ENDPOINT survives the scrub and
+    wins; the OTEL_* names stay as a fallback for direct CLI/CI use, where
+    nothing scrubs them.
+    """
+    base = (os.environ.get("STDTEL_OTLP_ENDPOINT")
+            or os.environ.get("OTEL_EXPORTER_OTLP_TRACES_ENDPOINT")
+            or os.environ.get("OTEL_EXPORTER_OTLP_ENDPOINT")
+            or DEFAULT_ENDPOINT).rstrip("/")
+    return base if base.endswith("/v1/traces") else f"{base}/v1/traces"
+
+
+def _timeout() -> int:
+    try:
+        return max(1, int(os.environ.get("STDTEL_OTLP_TIMEOUT", DEFAULT_TIMEOUT_S)))
+    except ValueError:
+        return DEFAULT_TIMEOUT_S
+
+
+def _otlp_exporter():
+    """OTLP/HTTP exporter that fails fast.
+
+    The timeout must be set on the *exporter*: force_flush(timeout_millis=...)
+    is ignored (open-telemetry/opentelemetry-python#4043), and the env var that
+    would otherwise bound it (OTEL_EXPORTER_OTLP_TIMEOUT) is scrubbed before the
+    hook ever runs. Unbounded, a dead collector stalls the Stop hook for ~7s of
+    retry backoff on every turn.
+    """
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+    return OTLPSpanExporter(endpoint=_endpoint(), timeout=_timeout())
+
+
+def scrub(attrs: dict) -> dict:
+    """Defence in depth: refuse to emit content attributes even if handed to us."""
+    return {k: v for k, v in attrs.items()
+            if not k.startswith(FORBIDDEN_PREFIXES) and isinstance(v, (str, int, float, bool))}
+
+
+def emit_session_cost(provider: TracerProvider, attrs: dict, session_id: str,
+                      started_at: float, ended_at: float) -> int:
+    """One span per Stop carrying the session's whole token cost.
+
+    Deliberately overlaps std.skill.invocation: that span attributes a slice of
+    these tokens to a skill. The two must never be summed — session cost is the
+    total, invocation tail is a share of it.
+    """
+    tracer = provider.get_tracer("stdtel", "0.1.0")
+    a = scrub(dict(attrs))
+    a["session.id"] = session_id
+    span = tracer.start_span(SESSION_SPAN_NAME, attributes=a, start_time=int(started_at * 1e9))
+    span.end(end_time=int(ended_at * 1e9))
+    return 1
+
+
+def emit_invocations(provider: TracerProvider, invocations: Iterable[dict], session_id: str) -> int:
+    """Each invocation dict: started_at, ended_at, attributes(dict), error(bool)."""
+    tracer = provider.get_tracer("stdtel", "0.1.0")
+    n = 0
+    for inv in invocations:
+        start_ns = int(inv["started_at"] * 1e9)
+        end_ns = int((inv.get("ended_at") or time.time()) * 1e9)
+        attrs = scrub(inv.get("attributes", {}))
+        attrs["session.id"] = session_id
+        attrs["gen_ai.operation.name"] = "execute_tool"
+        attrs["gen_ai.tool.name"] = "Skill"
+        span = tracer.start_span(SPAN_NAME, attributes=attrs, start_time=start_ns)
+        if inv.get("error"):
+            span.set_status(trace.StatusCode.ERROR)
+        span.end(end_time=end_ns)
+        n += 1
+    provider.force_flush()
+    return n

stdtel/hooks/cli.py

@@ -0,0 +1,318 @@
+"""Single entrypoint for Claude Code hooks: `stdtel-hook <event>`.
+
+Reads the hook JSON payload from stdin. Events: session-start, pre-tool-use,
+post-tool-use, stop. Always exits 0 so a telemetry failure never blocks the
+developer (design §7: memory is best-effort, telemetry likewise).
+
+Every stdtel import is deliberately function-local. PreToolUse and PostToolUse
+fire on *every* Skill call and are pure latency in the developer's loop, so they
+must not pay for OpenTelemetry (~19ms) or PyYAML when they never touch them.
+Only `stop` needs the exporter; only the catalogue lookup needs the parser.
+Module scope stays stdlib-only.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+
+def _payload() -> dict:
+    try:
+        return json.load(sys.stdin)
+    except Exception:
+        return {}
+
+
+def skills_roots() -> list[Path]:
+    """Directories to scan for SKILL.md, in precedence order.
+
+    STDTEL_SKILLS_ROOT may name several roots separated by os.pathsep; a relative
+    one is resolved against CLAUDE_PROJECT_DIR (the project the hook fired in),
+    not the process cwd, so `skills` in a project settings file keeps working.
+    The user-level catalogue is always searched last, which is what makes hooks
+    registered once in ~/.claude/settings.json useful from every project.
+    """
+    base = Path(os.environ.get("CLAUDE_PROJECT_DIR") or Path.cwd())
+    roots = []
+    for raw in os.environ.get("STDTEL_SKILLS_ROOT", "").split(os.pathsep):
+        if raw.strip():
+            root = Path(raw).expanduser()
+            roots.append(root if root.is_absolute() else base / root)
+    roots.append(Path.home() / ".claude" / "skills")
+    out, seen = [], set()
+    for root in roots:
+        try:
+            resolved = root.resolve()
+        except OSError:
+            continue
+        if resolved not in seen and resolved.is_dir():
+            seen.add(resolved)
+            out.append(root)
+    return out
+
+
+def _catalogue():
+    """Merged catalogue across roots; earlier roots win on name collisions."""
+    from stdtel.manifest import load_catalogue          # pulls in PyYAML
+
+    cat: dict = {}
+    for root in skills_roots():
+        try:
+            found = load_catalogue(root, strict=False)
+        except Exception:
+            continue
+        for name, manifest in found.items():
+            cat.setdefault(name, manifest)
+    return cat
+
+
+def _skill_from_payload(p: dict) -> tuple[str, str]:
+    """(skill name as invoked, trigger).
+
+    Field name verified against 120 real Skill invocations across 114 transcripts
+    in ~/.claude/projects: the input carries `skill` every time (never `name`,
+    never `skill_name` — that is the OTel event surface, a different payload).
+    `args` also appears and is deliberately not captured: it can hold content.
+
+    Trigger is provisional here. The transcript carries the tool_use `caller`
+    block, which is ground truth, so Stop upgrades this value; a name is never
+    slash-prefixed in the observed data, so nothing sets "explicit" in practice.
+    """
+    inp = p.get("tool_input") or p.get("toolArgs") or {}
+    name = str(inp.get("skill") or inp.get("name") or "")
+    caller = p.get("caller")
+    if name.startswith("/"):
+        trigger = "explicit"
+    elif isinstance(caller, dict) and caller.get("type"):
+        trigger = str(caller["type"])
+    else:
+        trigger = "unknown"
+    return name.lstrip("/"), trigger
+
+
+def _resolve(name: str, cat: dict):
+    """(manifest | None, catalogue name) for a skill as invoked.
+
+    Plugin-provided skills arrive namespaced — `epic-loop:epic-loop`,
+    `anthropic-skills:skill-creator` — which is 71% of real invocations, and is
+    what every skill looks like once distributed as a plugin. The catalogue is
+    keyed on the bare front-matter `name`, so match the full string first, then
+    the segment after the last ":".
+    """
+    if name in cat:
+        return cat[name], name
+    bare = name.rsplit(":", 1)[-1]
+    if bare in cat:
+        return cat[bare], bare
+    return None, bare
+
+
+def session_start(p: dict) -> None:
+    from stdtel.enrich import resource_attributes
+    from stdtel.state import SessionState
+
+    st = SessionState.load(p.get("session_id", "unknown"))
+    st.resource = resource_attributes(Path(p.get("cwd", ".")), payload=p)
+    st.started_at = st.started_at or time.time()
+    st.save()
+
+
+def pre_tool_use(p: dict) -> None:
+    if p.get("tool_name") != "Skill":
+        return
+    from stdtel.state import SessionState
+
+    st = SessionState.load(p.get("session_id", "unknown"))
+    name, trigger = _skill_from_payload(p)
+    # Version is resolved from the catalogue at Stop, which loads it anyway to
+    # attach the rest of the manifest attributes. Reading it here too would put
+    # a PyYAML parse of every SKILL.md on the hot path for a value Stop discards.
+    st.open_window(name, "unversioned", trigger, p.get("tool_use_id"),
+                   prompt_id=str(p.get("prompt_id") or ""),
+                   permission_mode=str(p.get("permission_mode") or ""))
+    st.save()
+
+
+def post_tool_use(p: dict, error: bool = False) -> None:
+    """Fires for every tool, not just Skill.
+
+    Tool-call failure rate is a first-class metric and a leading indicator of a
+    skill instructing the model to do something the environment cannot do. The
+    non-Skill path stays at the interpreter floor: state only, no catalogue, no
+    exporter, and counts only — tool_input and tool_response never leave here.
+    """
+    from stdtel.state import SessionState
+
+    tool = str(p.get("tool_name") or p.get("toolName") or "")
+    st = SessionState.load(p.get("session_id", "unknown"))
+    st.record_tool(tool, failed=error)
+    if tool != "Skill":
+        st.save()
+        return
+    w = st.close_window(p.get("tool_use_id"), error=error)
+    if w is not None and p.get("duration_ms"):
+        w.duration_ms = int(p["duration_ms"])      # the harness times the tool call itself
+    st.save()
+
+
+def stop(p: dict, exporter=None) -> int:
+    from stdtel.exporter import build_provider, emit_invocations, emit_session_cost
+    from stdtel.state import SessionState
+    from stdtel.transcript import attribute, read_slice
+
+    sid = p.get("session_id", "unknown")
+    st = SessionState.load(sid)
+    transcript = Path(p.get("transcript_path", ""))
+    sl = read_slice(transcript, st.transcript_offset)
+    st.transcript_offset = sl.new_offset
+    attributions = {a.skill: a for a in attribute(sl)}
+    loads = {l.skill: l for l in sl.skill_loads}
+    cat = _catalogue()
+    # any window still open at Stop is closed now (turn ended)
+    for w in st.open_windows():
+        st.close_window(w.tool_use_id)
+    invocations = []
+    for w in st.drain_closed():
+        manifest, resolved = _resolve(w.skill, cat)
+        if manifest is not None and not manifest.telemetry_emit:
+            # `telemetry.emit: false` in SKILL.md. Parsed and validated since the
+            # first commit, and until now read by nothing — an advertised control
+            # that did nothing. The session total still counts these tokens; what
+            # is suppressed is attributing them to this skill by name.
+            continue
+        load = loads.get(w.skill)
+        attrs = {
+            "std.skill.name": resolved,
+            "std.skill.invoked_as": w.skill,
+            "std.skill.version": w.version,
+            # the transcript's caller block is ground truth; the hook payload may not carry it
+            "std.skill.trigger": (load.caller if load and load.caller else w.trigger),
+            "std.skill.load_tokens": load.load_tokens if load else 0,
+        }
+        if ":" in w.skill:
+            attrs["std.skill.plugin"] = w.skill.rsplit(":", 1)[0]
+        if w.prompt_id:
+            # join key to Claude Code's native claude_code.* telemetry
+            attrs["std.prompt.id"] = w.prompt_id
+        if w.permission_mode:
+            attrs["std.harness.permission_mode"] = w.permission_mode
+        if w.duration_ms:
+            attrs["std.skill.duration_ms"] = w.duration_ms
+        if manifest:
+            attrs.update(manifest.as_attributes())
+        a = attributions.get(w.skill)
+        if a:
+            attrs["std.skill.tail_tokens"] = a.tail.total
+            attrs["std.skill.tail_tokens_first_only"] = a.tail_first_only.total
+            attrs["std.skill.llm_requests"] = a.request_count
+            attrs["gen_ai.request.model"] = a.models[0] if a.models else "unknown"
+            attrs.update(a.tail.as_attributes())
+        invocations.append({"started_at": w.started_at, "ended_at": w.ended_at,
+                            "attributes": attrs, "error": w.error})
+    # The session's whole cost, emitted whether or not a skill was ever loaded.
+    # Without this a session that used no skill produces no telemetry at all, and
+    # cost-per-PR has no denominator (CLAUDE.md: unattributed sessions are kept
+    # for cost analysis, excluded from outcome analysis).
+    totals = sl.totals()
+    tool_calls, tool_failures = st.tool_totals()
+    session_attrs = {}
+    if sl.requests or tool_calls:
+        session_attrs = {
+            "std.session.llm_requests": len(sl.requests),
+            "gen_ai.request.model": (sl.models() or ["unknown"])[0],
+            "std.session.tool_calls": tool_calls,
+            "std.session.tool_failures": tool_failures,
+            **totals.as_attributes(),
+        }
+        # per-tool counts as std.session.tool.<name>.{calls,failures}
+        for name, (calls, failures) in sorted(st.tool_calls.items()):
+            session_attrs[f"std.session.tool.{name}.calls"] = calls
+            if failures:
+                session_attrs[f"std.session.tool.{name}.failures"] = failures
+        st.tool_calls = {}          # drained with the windows
+    st.save()
+    if not invocations and not session_attrs:
+        return 0
+    # ADR-008: when spooling, the hook writes to disk and opens no socket at all.
+    # stdtel-export drains it. A hook that never talks to the network cannot stall
+    # on one, which is what "never block the developer" was reaching for.
+    if exporter is None and _spooling():
+        from stdtel.exporter import SESSION_SPAN_NAME, SPAN_NAME
+        from stdtel.spool import append
+        rows = [{"name": SPAN_NAME, "session_id": sid, "resource": st.resource,
+                 "started_at": i["started_at"], "ended_at": i["ended_at"],
+                 "attributes": i["attributes"], "error": i.get("error", False)}
+                for i in invocations]
+        if session_attrs:
+            rows.append({"name": SESSION_SPAN_NAME, "session_id": sid, "resource": st.resource,
+                         "started_at": (st.started_at or time.time()), "ended_at": time.time(),
+                         "attributes": session_attrs})
+        st.last_export_ok = True          # spooled successfully; export is someone else's job
+        st.save()
+        return append(rows)
+
+    provider = build_provider(st.resource, exporter=exporter)
+    try:
+        emitted = emit_invocations(provider, invocations, sid) if invocations else 0
+        st.last_export_ok = True
+    except Exception:
+        st.last_export_ok = False
+        st.save()
+        raise
+    if session_attrs:
+        # Session start comes from state, not the transcript: transcript timestamps
+        # can be absent or unparseable, and a start near the epoch turns the span's
+        # duration into "seconds since 1970" rather than the session's length.
+        now = time.time()
+        started = st.started_at or min((i["started_at"] for i in invocations), default=now)
+        emitted += emit_session_cost(provider, session_attrs, sid, started, now)
+    st.save()
+    return emitted
+
+
+def _spooling() -> bool:
+    """Write spans to disk rather than exporting inline (ADR-008)."""
+    return os.environ.get("STDTEL_SPOOL", "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def disabled() -> bool:
+    """True when the developer has switched telemetry off.
+
+    Checked before the payload is even read: an opt-out that still parses your
+    transcript is not an opt-out.
+    """
+    return os.environ.get("STDTEL_DISABLED", "").strip().lower() in ("1", "true", "yes", "on")
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    event = argv[0] if argv else ""
+    if disabled():
+        return 0
+    p = _payload()
+    try:
+        if event == "session-start":
+            session_start(p)
+        elif event == "pre-tool-use":
+            pre_tool_use(p)
+        elif event == "post-tool-use":
+            post_tool_use(p)
+        elif event == "post-tool-use-failure":
+            post_tool_use(p, error=True)
+        elif event == "stop":
+            stop(p)
+        else:
+            # still exit 0: an unknown event must never block the developer
+            print(f"stdtel-hook: unknown event {event!r}; expected one of "
+                  f"session-start, pre-tool-use, post-tool-use, "
+                  f"post-tool-use-failure, stop", file=sys.stderr)
+    except Exception as e:   # never block the developer
+        print(f"stdtel: {e}", file=sys.stderr)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

stdtel/install.py

@@ -0,0 +1,173 @@
+"""Render hook configuration bound to *this* installation's absolute path.
+
+Hook processes get a non-login `sh -c` and inherit whatever PATH launched the
+harness, so a bare `stdtel-hook` is not resolvable when a version manager (mise,
+asdf, pyenv) or an activated venv is what put it on PATH. Every comparable tool
+solves this the same way — pre-commit bakes `sys.executable` into the generated
+git hook at install time — so we resolve the absolute path here and write it in.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shlex
+import shutil
+import sys
+from pathlib import Path
+
+HOOK_NAME = "stdtel-hook"
+# What the *shipped plugin* manifests invoke. A distributed manifest cannot know
+# the install path, and a bare name does not resolve in a hook's `sh -c` — that
+# failed with "command not found" on every tool call (issue #13). bin/stdtel-hook
+# resolves the real CLI at run time and exits 0 silently when it is absent.
+PLUGIN_LAUNCHER = "${CLAUDE_PLUGIN_ROOT}/bin/stdtel-hook"
+
+# (stdtel event, Claude Code event, tool matcher, Copilot event)
+# PreToolUse stays matched to Skill: it only opens skill windows, and firing it on
+# every tool would be pure latency. PostToolUse is unmatched because tool-call
+# failure rate needs every tool, and the non-Skill path is a counter increment.
+EVENTS = (
+    ("session-start",         "SessionStart",       None,    "sessionStart"),
+    ("pre-tool-use",          "PreToolUse",         "Skill", "preToolUse"),
+    ("post-tool-use",         "PostToolUse",        None,    "postToolUse"),
+    ("post-tool-use-failure", "PostToolUseFailure", None,    "postToolUseFailure"),
+    ("stop",                  "Stop",               None,    "agentStop"),
+)
+
+
+class InstallError(RuntimeError):
+    pass
+
+
+def hook_binary() -> Path:
+    """Absolute path to the stdtel-hook belonging to this installation.
+
+    Prefer the console script beside the running interpreter — for `uv tool
+    install` and pipx that is the tool's own bin directory — and only then fall
+    back to PATH, which may resolve to a different install.
+    """
+    # NOT .resolve(): in a venv sys.executable is a symlink to the base
+    # interpreter, and resolving it lands in the base install's bin/, not the
+    # venv's — where the console script we want does not exist.
+    sibling = Path(sys.executable).parent / HOOK_NAME
+    if sibling.is_file():
+        return sibling
+    found = shutil.which(HOOK_NAME)
+    if found:
+        return Path(found).resolve()
+    raise InstallError(
+        f"{HOOK_NAME} not found beside {sys.executable} or on PATH; "
+        f"install with `uv tool install stdtel` (or `pipx install stdtel`) first")
+
+
+def _entry(binary: Path, event: str, exec_form: bool, env: dict | None, timeout: int | None) -> dict:
+    """One hook entry.
+
+    Shell form (default) is a single quoted absolute path — the shape Claude Code
+    has always accepted. Exec form skips `sh -c` and saves ~3ms per call, but is
+    opt-in because we have not executed it against a live harness.
+    """
+    if exec_form:
+        entry: dict = {"type": "command", "command": str(binary), "args": [event]}
+    else:
+        entry = {"type": "command", "command": f"{shlex.quote(str(binary))} {event}"}
+    if timeout is not None:
+        entry["timeout"] = timeout
+    if env:
+        entry["env"] = dict(env)
+    return entry
+
+
+def claude_hooks(binary: "Path | str", exec_form: bool = False) -> dict:
+    hooks: dict = {}
+    for event, cc_event, matcher, _ in EVENTS:
+        group: dict = {"hooks": [_entry(binary, event, exec_form, None, None)]}
+        if matcher:
+            group["matcher"] = matcher
+        hooks[cc_event] = [group]
+    return {"hooks": hooks}
+
+
+def copilot_hooks(binary: "Path | str", harness: str = "copilot-vscode",
+                  exec_form: bool = False) -> dict:
+    """Copilot hook config.
+
+    STDTEL_HARNESS is set per hook on purpose. Copilot also reads
+    `~/.claude/settings.json`, and its snake_case dialect is indistinguishable
+    from Claude Code's in the payload, so this env block is the only thing that
+    keeps Copilot activity from being recorded as claude-code.
+    """
+    hooks: dict = {}
+    for event, _, matcher, cop_event in EVENTS:
+        entry = _entry(binary, event, exec_form, {"STDTEL_HARNESS": harness}, None)
+        group: dict = {"hooks": [entry]}
+        if matcher:
+            group["matcher"] = matcher
+        hooks[cop_event] = [group]
+    return {"version": 1, "disableAllHooks": False, "hooks": hooks}
+
+
+def merge_settings(target: Path, block: dict) -> dict:
+    """Merge hooks/env into an existing settings file without clobbering it."""
+    current = {}
+    if target.is_file():
+        try:
+            current = json.loads(target.read_text() or "{}")
+        except json.JSONDecodeError as e:
+            raise InstallError(f"{target} is not valid JSON: {e}") from e
+    for key, value in block.items():
+        if isinstance(value, dict):
+            current.setdefault(key, {}).update(value)
+        else:
+            current[key] = value
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(current, indent=2) + "\n")
+    return current
+
+
+def _dump(obj: dict) -> str:
+    return json.dumps(obj, indent=2)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="stdtel-install", description=__doc__.splitlines()[0])
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_hooks = sub.add_parser("hooks", help="print hook config for a harness")
+    p_hooks.add_argument("--harness", default="claude-code",
+                         choices=["claude-code", "copilot-vscode", "copilot-cli"])
+    p_hooks.add_argument("--exec-form", action="store_true",
+                         help="use command+args instead of a shell string (unverified upstream)")
+
+    p_set = sub.add_parser("settings", help="merge hooks into a Claude Code settings.json")
+    p_set.add_argument("--path", type=Path, default=Path.home() / ".claude" / "settings.json")
+    p_set.add_argument("--exec-form", action="store_true")
+    p_set.add_argument("--dry-run", action="store_true")
+
+    p_where = sub.add_parser("where", help="print the resolved absolute hook path")
+    args = parser.parse_args(sys.argv[1:] if argv is None else argv)
+
+    try:
+        binary = hook_binary()
+    except InstallError as e:
+        print(f"stdtel-install: {e}", file=sys.stderr)
+        return 1
+
+    if args.cmd == "where":
+        print(binary)
+    elif args.cmd == "hooks":
+        block = (claude_hooks(binary, args.exec_form) if args.harness == "claude-code"
+                 else copilot_hooks(binary, args.harness, args.exec_form))
+        print(_dump(block))
+    elif args.cmd == "settings":
+        block = claude_hooks(binary, args.exec_form)
+        if args.dry_run:
+            print(_dump(block))
+        else:
+            merge_settings(args.path, block)
+            print(f"wrote {len(block['hooks'])} hook events to {args.path} -> {binary}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())