stacktrace-cli 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

stacktrace_cli/cli.py

@@ -24,16 +24,22 @@ from typing import Final
 import click
 from openaca.cli import main as openaca_cli
 
-from . import __version__
 from .analysis import analyse, parse_since
+from .build import version_label
+from .daemon.cli import daemon as daemon_cmd
+from .daemon.cli import findings
 from .detector.cache import VerdictCache, default_directory
+from .detector.history import DriftHistory, default_history_path
 from .detector.render import render_json as render_detections_json
 from .detector.render import render_text as render_detections_text
 from .detector.run import DEFAULT_BUDGET, DEFAULT_SAMPLE_BUDGET
 from .monitor.server import serve
+from .options import analyzer_option, resolve_analyzer
 from .remote.cli import main as remote_cmd
 from .sessions.access import collect_sessions
 from .sessions.render import render_json, render_text
+from .telemetry import emit_error
+from .telemetry.cli import telemetry as telemetry_cmd
 
 PASSTHROUGH: Final = ("scan", "bom", "policy")
 
@@ -87,7 +93,9 @@ def _show_version(ctx: click.Context, param: click.Parameter, value: bool) -> No
     # click's own `version_option` callback opens with the same two guards.
     if not value or ctx.resilient_parsing:
         return
-    click.echo(f"stacktrace {__version__} (openaca {version('openaca')})")
+    # A build from a branch or PR reports its commit as a PEP 440 local label,
+    # `0.4.0+86eef86`; a release install prints the bare version.
+    click.echo(f"stacktrace {version_label()} (openaca {version('openaca')})")
     ctx.exit()
 
 
@@ -101,6 +109,52 @@ class SectionedGroup(click.Group):
     right section with no edit to this class.
     """
 
+    def invoke(self, ctx: click.Context) -> object:
+        """Run the command; count an exception on the way out, and only an exception.
+
+        Click's own control flow travels as exceptions too -- `Exit` from a
+        pass-through's exit code, `Abort` on Ctrl-C, `UsageError` on a typo --
+        and a bare one is not an error in this program. Everything else is,
+        and only an allowlisted class name or `other` leaves (ADR-0039). A
+        command that succeeds performs no telemetry work at all.
+
+        A `ClickException` or an `Exit` a command site raised to wrap a real
+        failure (`raise click.ClickException(...) from exc`, or
+        `raise click.exceptions.Exit(exc.exit_code) from exc` where a specific
+        process exit code matters more than Click's own formatting -- both
+        patterns are already in this package) still carries that failure as
+        `__cause__`, and it is the cause's class that is counted -- exempting
+        either outright would make the `error` metric miss every operational
+        failure a command turned into one, whichever wrapper it used. A bare
+        `ClickException` or `Exit` Click or a command raised on its own, with
+        no wrapped cause, is what a typo, an expected precondition or a
+        pass-through's own exit code looks like here, and stays uncounted.
+        `Abort` is exempt outright, cause or not: Ctrl-C is the user's act,
+        never an operational failure to attribute to a cause.
+
+        `UsageError` (and `BadParameter`, its subclass every parameter
+        callback in this package raises) is exempt outright, cause or not:
+        `_day_count` chains `from error` onto its `BadParameter` for a clean
+        traceback, not to flag an operational failure, and ADR-0039 excludes
+        invalid arguments from the `error` metric. This package's own
+        operational wrappers always raise a bare `click.ClickException`, never
+        `UsageError`, to carry a real cause.
+        """
+        try:
+            return super().invoke(ctx)
+        except click.exceptions.Abort:
+            raise
+        except click.UsageError:
+            raise
+        except (click.exceptions.Exit, click.ClickException) as error:
+            cause = error.__cause__
+            if cause is not None:
+                emit_error(cause)
+            raise
+        except Exception as error:
+            emit_error(error)
+            raise
+
     def format_commands(self, ctx: click.Context, formatter: click.HelpFormatter) -> None:
         commands: list[tuple[str, click.Command]] = []
         for name in self.list_commands(ctx):
@@ -135,7 +189,7 @@ class SectionedGroup(click.Group):
     expose_value=False,
     is_eager=True,
     callback=_show_version,
-    help="Show the stacktrace and OpenACA versions and exit.",
+    help="Show the stacktrace and OpenACA versions (and build commit) and exit.",
 )
 def main() -> None:
     """Stacktrace: agent composition analysis, detection and upload."""
@@ -223,36 +277,31 @@ def sessions(
     help="Show every detection and all of its evidence. Default: the summary alone.",
 )
 @click.option(
-    "--reasoning",
-    is_flag=True,
+    "--reasoning/--no-reasoning",
     default=False,
-    help="Analyse flagged sessions with a reasoning model, run through the "
-    "agent's own CLI. Off by default: it is the only stage that sends anything "
-    "session-derived off this machine, and it spends the developer's own "
-    "provider quota, so a run that does neither is the one to reach for first. "
-    "--reasoning turns it on "
-    "and --budget caps a noisy day. Leaving it off does not make the run "
-    "offline: correlation runs first either way and matches advisories by "
-    "sending the package coordinates of the components a session invoked to "
-    "osv.dev. Sessions that qualified are still counted, and named in "
-    "--format json, so the run says what it did not do.",
+    hidden=True,
+    help="Analyse flagged sessions with a reasoning model. Off by default: it "
+    "is the only stage that sends anything session-derived off this machine, "
+    "so a run that does not is the one to reach for first. --reasoning turns "
+    "it on, --analyzer names who answers, and --budget caps a noisy day.",
 )
 @click.option(
     "--budget",
-    type=click.IntRange(min=1),
+    type=click.IntRange(min=0),
     default=DEFAULT_BUDGET,
-    show_default=True,
-    help="How many sessions one run may send for inference.",
+    hidden=True,
+    help="How many sessions one run may send for inference. 0 is every session.",
 )
 @click.option(
     "--sample-budget",
     type=click.IntRange(min=0),
     default=DEFAULT_SAMPLE_BUDGET,
-    show_default=True,
+    hidden=True,
     help="Quiet sessions to analyse per run with no evidence behind them. Off "
     "by default: it is the only route that spends inference with no evidence, "
     "so it is asked for rather than assumed. Shares the --budget cap.",
 )
+@analyzer_option
 @click.option(
     "--cache/--no-cache",
     default=True,
@@ -285,37 +334,38 @@ def detect(
     reasoning: bool,
     budget: int,
     sample_budget: int,
+    analyzer: str,
     cache: bool,
     project_map: tuple[str, ...],
     root: Path | None,
 ) -> None:
     """Find security and reliability findings in what agents did.
 
-    Four kinds of finding, under two families: a credential reaching an
-    outbound call and an injected instruction followed are security; a
-    vulnerable component actually reached is security with a vulnerability
-    behind it; a stalled loop and a hung call are reliability. The two
-    families carry their own severity ladders, because a stalled loop and a
-    leaked credential cannot share one (ADR-0010).
-
-    Two stages need no model or credential, and they are the two that run by
-    default. The third sends flagged sessions to the agent's own CLI:
-    --reasoning turns it on, capped by --budget. Sessions that qualified for it
-    are counted either way, and named in --format json, so a run without it
-    says so rather than reading as a clean one.
-
-    That third stage is the one that sends session content off this machine:
-    the agent's own CLI hands the prompts, arguments and results a rule needs
-    to the provider it is already authenticated against (ADR-0004 -- provider
-    affinity, so a transcript goes back to the vendor that produced it, and
-    there is no fallback to any other). Without --reasoning the run is the two
-    stages that send nothing.
-
-    One network call happens before any of them, with or without --reasoning:
+    Three kinds of finding, under two families: a credential reaching an
+    outbound call and success reported against evidence of failure are
+    security; why the agent stopped, and who can unblock it, is reliability.
+    The two families carry their own severity ladders, because a blocked agent
+    and a leaked credential cannot share one (ADR-0010).
+
+    Both stages read the record on this machine. Neither needs a model, a
+    credential or an account, and on a default run nothing derived from a
+    session -- no prompt, no argument, no result -- is sent anywhere.
+
+    "On a default run" is the whole of the qualification, and it is here rather
+    than left to the flags: `--reasoning --analyzer jev` adds a third stage
+    that sends per-call windows -- a completion claim, one verification command
+    and its output -- to TypeSafe's Jev (ADR-0033). Both flags must be typed,
+    neither has a default, and this output names them when a session is left
+    unjudged, so it is a run a reader can ask for and therefore one this
+    paragraph has to account for.
+
+    One network call is made on every run, and it is not the detector's:
     correlation matches advisories by sending the package coordinates of the
-    components a session invoked to osv.dev. Coordinates only -- never a
-    prompt, an argument or a result.
+    components a session invoked to osv.dev. Coordinates only, so this is not
+    an offline run, and without stage three it is the only thing that leaves
+    this machine.
     """
+    analyzer = resolve_analyzer(analyzer, reasoning)
     try:
         # One call, because the order it runs in is `analysis.py`'s to know:
         # `monitor` and `sync detect` read the same pipeline and must not be
@@ -329,6 +379,7 @@ def detect(
             reasoning=reasoning,
             budget=budget,
             sample_budget=sample_budget,
+            analyzer=analyzer,
             # Not gated on `reasoning`. A verdict already paid for is an
             # answer this run has, and `reasoning` governs whether new ones may
             # be commissioned, not whether old ones may be read -- the rule
@@ -336,9 +387,17 @@ def detect(
             # session read as graded or ungraded depending on a flag that
             # spent nothing either way.
             cache=VerdictCache(default_directory()) if cache else None,
+            # One point per session per reasoning run, so the monitor's drift
+            # line grows with each run made here (ADR-0033).
+            history=DriftHistory(default_history_path()),
         )
     except ValueError as error:
-        raise click.ClickException(str(error)) from error
+        # No `from error`: this is argument validation (a bad --project-map,
+        # an unrecognised analyzer), which ADR-0039 excludes from the `error`
+        # metric the same way UsageError already is. Chaining it would let
+        # the dispatcher count it by cause and, on a fresh machine, create an
+        # installation identity for an invocation that never ran anything.
+        raise click.ClickException(str(error))
     result = analysis.run
     output = (
         render_detections_json(result)
@@ -369,20 +428,30 @@ def detect(
     "entirely when nothing on disk has changed.",
 )
 @click.option(
-    "--reasoning",
-    is_flag=True,
+    "--reasoning/--no-reasoning",
     default=False,
-    help="Let the page analyse one session with a reasoning model, run through "
-    "the agent's own CLI. Off by default: stage 3 spends your provider quota, and a page "
-    "left open is the wrong place for that to be implicit. Capped by --budget.",
+    hidden=True,
+    help="Let the page judge sessions with a reasoning model. Off by default: "
+    "stage 3 is the only one that sends anything off this machine, and a page "
+    "left open is the wrong place for that to be implicit. --analyzer names "
+    "who answers; --budget caps a pass.",
 )
 @click.option(
     "--budget",
-    type=click.IntRange(min=1),
-    default=DEFAULT_BUDGET,
-    show_default=True,
-    help="Reasoning runs this monitor may spend in total, if --reasoning is on.",
+    type=click.IntRange(min=0),
+    default=0,
+    hidden=True,
+    help=(
+        "Sessions the first pass may send for inference, if --reasoning is on. "
+        "The default 0 is every session: a page that answered some of them and "
+        "left the rest silently unjudged would be a partial account presented "
+        "as a whole one. Only the first pass commissions anything — later ticks "
+        "read the cache and the drift history — so this is what the page costs "
+        "in total, not what it costs every few seconds. After that, a session "
+        "is judged on request, and this is that request's budget too."
+    ),
 )
+@analyzer_option
 @click.option(
     "--no-open", is_flag=True, default=False, help="Print the URL, do not open a browser."
 )
@@ -424,6 +493,7 @@ def monitor(
     interval: float,
     reasoning: bool,
     budget: int,
+    analyzer: str,
     no_open: bool,
     agent_kinds: tuple[str, ...],
     since: str,
@@ -440,9 +510,9 @@ def monitor(
 
     Loopback only, and free to leave open: a pass is skipped when nothing has
     changed, advisory lookups are asked once per component, and the two stages
-    that need no model are the only ones that run. --reasoning adds a button
-    that spends your provider quota, off unless asked for.
+    that need no model are the only ones that run.
     """
+    analyzer = resolve_analyzer(analyzer, reasoning)
     try:
         code = serve(
             host=host,
@@ -450,6 +520,7 @@ def monitor(
             interval=interval,
             reasoning=reasoning,
             budget=budget,
+            analyzer=analyzer,
             open_browser=not no_open,
             echo=click.echo,
             agent_kinds=agent_kinds,
@@ -458,7 +529,15 @@ def monitor(
             project_map=project_map,
             root=root,
         )
-    except (OSError, ValueError) as error:
+    except ValueError as error:
+        # No `from error`: a non-loopback --host is argument validation,
+        # excluded from the `error` metric the same way UsageError already is
+        # (see the matching comment in `detect`). Unlike the OSError below --
+        # a port already in use, a real runtime condition -- the host itself
+        # is not something running the command again with the same argument
+        # would ever make succeed.
+        raise click.ClickException(str(error))
+    except OSError as error:
         raise click.ClickException(str(error)) from error
     if code:
         raise click.exceptions.Exit(code)
@@ -477,3 +556,6 @@ main.add_command(remote_cmd, "remote")
 main.add_command(sessions)
 main.add_command(detect)
 main.add_command(monitor)
+main.add_command(daemon_cmd, "daemon")
+main.add_command(findings)
+main.add_command(telemetry_cmd, "telemetry")

stacktrace_cli/correlate/acquire.py

@@ -397,6 +397,28 @@ def _identity_of(component: dict[str, Any]) -> str | None:
     return None
 
 
+def identity_versions(
+    documents: Sequence[dict[str, Any]], identities: AbstractSet[str]
+) -> dict[str, str | None]:
+    """Each wanted identity's own declared version, the first time it is found.
+
+    The identity this codebase assigns does not encode a version — that is
+    what lets one scan answer for a component across every composition it
+    appears in — so a cache keyed on identity alone cannot tell an upgrade
+    from no change at all. Pairing identity with this lets a long-lived
+    lookup cache do that.
+    """
+    versions: dict[str, str | None] = {}
+    for document in documents:
+        for component in document.get("components") or []:
+            identity = _identity_of(component)
+            if identity is None or identity not in identities or identity in versions:
+                continue
+            version = component.get("version")
+            versions[identity] = version if isinstance(version, str) else None
+    return versions
+
+
 def _identity_by_ref(document: dict[str, Any]) -> dict[str, str]:
     return {
         str(component["bom-ref"]): identity
@@ -419,8 +441,7 @@ def _scan(
     **A response whose shape is not the one we read is `None`, never `{}`.** The
     two are different answers: `{}` says the scan ran and matched nothing, and
     `_attach_advisories` records `advisories_checked=True` on the strength of
-    it, which suppresses both the vulnerability findings and the
-    `advisories_unchecked` warning that would have said we never looked. Every
+    it, which is what a reader of the composition takes for *we looked*. Every
     field this function reads is therefore checked against the shape
     `Advisory` declares — `findings` a list, `fixed_in`, `source`, `severity`
     and `title` a string or absent — so version skew or a corrupted response

stacktrace_cli/correlate/orchestrate.py

@@ -40,7 +40,13 @@ from dataclasses import dataclass, replace
 from pathlib import Path
 from typing import Any
 
-from stacktrace_cli.correlate.acquire import Built, advisories_for, build_bom, load_bom
+from stacktrace_cli.correlate.acquire import (
+    Built,
+    advisories_for,
+    build_bom,
+    identity_versions,
+    load_bom,
+)
 from stacktrace_cli.correlate.composition import Advisory, Composition
 from stacktrace_cli.correlate.join import is_builtin, is_builtin_subagent, join_key
 from stacktrace_cli.correlate.project_map import ProjectMapping, remap
@@ -94,7 +100,7 @@ def _build(kind: str, project: Path | None) -> Built | None:
 _SCAN_WORKERS = 8
 
 
-def _build_all(
+def build_compositions(
     work: Sequence[tuple[str, Path | None]],
     build: Callable[[str, Path | None], Built | None] = _build,
 ) -> dict[tuple[str, str | None], Built]:
@@ -132,6 +138,9 @@ def _key(project: Path | None) -> str | None:
     return str(project) if project is not None else None
 
 
+BuildAll = Callable[[Sequence[tuple[str, Path | None]]], dict[tuple[str, str | None], Built]]
+
+
 def _invoked_identities(correlated: object) -> set[str]:
     """Every component identity a session actually reached.
 
@@ -140,9 +149,10 @@ def _invoked_identities(correlated: object) -> set[str]:
     rather than unasked. Advisories for both is the honest answer.
 
     A rejected call never reached the component it resolved to — the same fact
-    `priors.py`'s `_advisory_reach` already acts on for findings. Without the same exclusion here, a denied call's coordinates would
-    still be sent to osv.dev: an unnecessary disclosure and scan cost for a
-    component nothing actually ran.
+    `sessions/outcome.py` states for every rule that claims a call reached
+    something. Without the same exclusion here, a denied call's coordinates
+    would still be sent to osv.dev: an unnecessary disclosure and scan cost
+    for a component nothing actually ran.
     """
     identities: set[str] = set()
     for session in correlated.sessions:  # type: ignore[attr-defined]
@@ -167,6 +177,54 @@ AdvisoryLookup = Callable[
 AttachAdvisories = Callable[[CorrelatedView, "Sequence[Built]"], CorrelatedView]
 
 
+class CachingAdvisoryLookup:
+    """`advisories_for`, asked once per identity for the life of the process.
+
+    `None` from the underlying lookup means *not checked at all*, which must
+    stay distinguishable from *checked and found nothing* — an unchecked
+    composition must never read as a clean one. So a `None` answer is not
+    cached: the next tick asks again rather than remembering an absence of
+    knowledge as knowledge.
+
+    Shared by `monitor`'s watcher and the daemon's session observer: both are
+    long-lived processes asking the same question repeatedly, and a second
+    copy of this memo would be a second chance to get the `None`-means-unasked
+    distinction wrong.
+    """
+
+    def __init__(self, lookup: Callable[..., Any] = advisories_for) -> None:
+        self._lookup = lookup
+        self._known: dict[tuple[str, str | None], tuple[Any, ...]] = {}
+        self._asked: set[tuple[str, str | None]] = set()
+
+    def __call__(
+        self, documents: Sequence[dict[str, Any]], identities: AbstractSet[str]
+    ) -> dict[str, tuple[Any, ...]] | None:
+        wanted = set(identities or ())
+        # Keyed by (identity, version) rather than identity alone: the identity
+        # this codebase assigns does not encode a version, so an upgrade or
+        # downgrade of an already-asked component must still be asked about.
+        versions = identity_versions(documents, wanted)
+        keys = {identity: (identity, versions.get(identity)) for identity in wanted}
+        unasked = {identity for identity in wanted if keys[identity] not in self._asked}
+        if unasked:
+            matched = self._lookup(documents, unasked)
+            if matched is None:
+                # Never checked. Do not record these as asked, and do not
+                # answer for the ones we do know: a partial answer here would
+                # be indistinguishable from a complete one downstream.
+                return None
+            self._asked |= {keys[identity] for identity in unasked}
+            self._known.update(
+                {keys[identity]: advisories for identity, advisories in matched.items()}
+            )
+        return {
+            identity: self._known[keys[identity]]
+            for identity in wanted
+            if keys[identity] in self._known
+        }
+
+
 def advisory_attacher(lookup: AdvisoryLookup = advisories_for) -> AttachAdvisories:
     """`_attach_advisories`, with the network call substitutable.
 
@@ -307,7 +365,7 @@ def _mapped_compositions(
     mappings: tuple[ProjectMapping, ...],
     build_all: Callable[
         [Sequence[tuple[str, Path | None]]], dict[tuple[str, str | None], Built]
-    ] = _build_all,
+    ] = build_compositions,
 ) -> dict[tuple[str, str], Built]:
     """Compositions for projects the user has said moved, built where they say.
 
@@ -399,8 +457,14 @@ def acquire_correlated_view(
     The four hooks exist for tests and for nothing else; production passes none
     of them and gets the module-level implementations.
     """
-    build_all = build_all or _build_all
-    mapped = mapped or _mapped_compositions
+    build_all = build_all or build_compositions
+    if mapped is None:
+        mapped = lambda correlated, supplied, mappings: _mapped_compositions(
+            correlated,
+            supplied,
+            mappings,
+            build_all=build_all,
+        )
     projects_worth_scanning = projects_worth_scanning or _projects_worth_scanning
     attach_advisories = attach_advisories or _attach_advisories
 
@@ -423,7 +487,7 @@ def acquire_correlated_view(
         for kind in sorted({s.agent_kind for s in sessions.sessions if s.agent_kind})
         if kind not in supplied_kinds
     ]
-    # Guarded, because `_build_all` opens a thread pool: asking it for nothing
+    # Guarded, because `build_compositions` opens a thread pool: asking it for nothing
     # is a pool created and torn down to return an empty dict.
     for (kind, _), built in (build_all(user_scope) if user_scope else {}).items():
         builts.append(built)

stacktrace_cli/correlate/render.py

@@ -22,6 +22,7 @@ from stacktrace_cli.correlate.composition import Advisory, Component, Compositio
 from stacktrace_cli.correlate.join import Resolution
 from stacktrace_cli.correlate.observed import CAPABILITY_NAMES, observe
 from stacktrace_cli.correlate.record import CorrelatedSession, CorrelatedView
+from stacktrace_cli.sessions.index import calls_by_span
 from stacktrace_cli.sessions.outcome import denied
 from stacktrace_cli.sessions.protocols import ToolCallLike
 from stacktrace_cli.sessions.render import session_document
@@ -47,7 +48,9 @@ def render_text(view: CorrelatedView, include_content: bool = False, detail: boo
 
 
 def _calls_by_span(correlated: CorrelatedSession) -> dict[str, ToolCallLike]:
-    return {call.span: call for turn in correlated.session.turns for call in turn.tool_calls}
+    # One definition, in `sessions`, because the detector needs the same walk to
+    # date a finding and must not import a renderer to get it.
+    return calls_by_span(correlated.session)
 
 
 #: How an observation was established, in the order a reader should weigh it.
@@ -421,8 +424,7 @@ def _session_lines(correlated: CorrelatedSession, include_content: bool) -> list
 
     if include_content:
         # The durable request and the standing context — the only place a
-        # context-item evidence span (`stacktrace-injection-marker`'s
-        # context-item route) can be looked up. Both wait for
+        # context-item evidence span can be looked up. Both wait for
         # `--include-content` exactly as a turn's text and a call's arguments
         # do; the JSON path already carries them via `session_document()`.
         if session.initial_prompt:
@@ -589,8 +591,8 @@ def _composition_document(composition: Composition) -> dict[str, object]:
         "component_count": len(composition.components),
         # Advisory matching, both halves. Without `advisories_checked` an empty
         # map reads identically whether nothing was found or nothing was looked
-        # for, and `stacktrace-advisory-reach` — the whole vulnerability
-        # category — had no input at this seam at all.
+        # for, and a reader of the composition cannot tell a clean scan from a
+        # scan that never ran.
         "advisories_checked": composition.advisories_checked,
         "advisories": {
             bom_ref: [_advisory_document(advisory) for advisory in advisories]

stacktrace_cli/daemon/__init__.py

@@ -0,0 +1 @@
+"""Host-level session observation and finding delivery."""

stacktrace_cli/daemon/cli.py

@@ -0,0 +1,106 @@
+"""CLI surfaces for daemon lifecycle, subscriptions, and local findings."""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+import click
+
+from .paths import RuntimePaths
+from .store import FindingStore, SessionKey
+
+
+@click.group()
+def daemon() -> None:
+    """Manage automatic session detection."""
+
+
+@daemon.command("run", hidden=True)
+def run_command() -> None:
+    _, _, run_daemon = _runtime()
+    run_daemon(RuntimePaths.from_environment())
+
+
+@daemon.command()
+def status() -> None:
+    """Show whether the local Stacktrace daemon is running."""
+    daemon_is_running, _, _ = _runtime()
+    paths = RuntimePaths.from_environment()
+    if not daemon_is_running(paths.socket):
+        raise click.ClickException("Stacktrace daemon is not running")
+    click.echo("Stacktrace daemon is running.")
+
+
+@daemon.command()
+@click.option(
+    "--agent-kind",
+    required=True,
+    help="Agent kind that owns the native session.",
+)
+@click.option(
+    "--session-id",
+    envvar="CLAUDE_CODE_SESSION_ID",
+    required=True,
+    help="Native agent session ID. Defaults to CLAUDE_CODE_SESSION_ID.",
+)
+def subscribe(agent_kind: str, session_id: str) -> None:
+    """Relay notifications for exactly one native agent session."""
+    try:
+        _, follow_notifications, _ = _runtime()
+        follow_notifications(
+            RuntimePaths.from_environment(),
+            SessionKey(agent_kind, session_id),
+            stdout=sys.stdout,
+            stderr=sys.stderr,
+        )
+    except RuntimeError as error:
+        raise click.ClickException(str(error)) from error
+
+
+def _runtime():
+    if os.name != "posix":
+        raise click.ClickException(
+            "automatic session monitoring is currently available on macOS and Linux"
+        )
+    from .runtime import daemon_is_running, follow_notifications, run_daemon
+
+    return daemon_is_running, follow_notifications, run_daemon
+
+
+@click.command()
+@click.option(
+    "--agent-kind",
+    required=True,
+    help="Agent kind that owns the native session.",
+)
+@click.option(
+    "--session",
+    "session_id",
+    envvar="CLAUDE_CODE_SESSION_ID",
+    required=True,
+    help="Native session ID. Defaults to CLAUDE_CODE_SESSION_ID.",
+)
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["text", "json"]),
+    default="text",
+    show_default=True,
+)
+def findings(agent_kind: str, session_id: str, output_format: str) -> None:
+    """Show Stacktrace findings for one native agent session."""
+    paths = RuntimePaths.from_environment()
+    stored = FindingStore(paths.state).findings(SessionKey(agent_kind, session_id))
+    if output_format == "json":
+        click.echo(json.dumps({"findings": stored}, indent=2))
+        return
+    if not stored:
+        click.echo("No Stacktrace findings for this session.")
+        return
+    for finding in stored:
+        click.echo(
+            f"{str(finding.get('severity', 'unknown')).upper()} "
+            f"{finding.get('rule_id', 'unknown-rule')}: {finding.get('title', 'Finding')}"
+        )