stacktrace-cli 0.4.1__py3-none-any.whl → 0.5.0__py3-none-any.whl

stacktrace_cli/__init__.py

@@ -1,3 +1,3 @@
 """The `stacktrace` command-line interface — detection and response for AI agents."""
 
-__version__ = "0.4.1"
+__version__ = "0.5.0"

stacktrace_cli/daemon/cli.py

@@ -9,6 +9,7 @@ import sys
 import click
 
 from .paths import RuntimePaths
+from .presentation import render_finding
 from .store import FindingStore, SessionKey
 
 
@@ -100,7 +101,4 @@ def findings(agent_kind: str, session_id: str, output_format: str) -> None:
         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')}"
-        )
+        click.echo(render_finding(finding))

stacktrace_cli/daemon/presentation.py

@@ -0,0 +1,68 @@
+"""Explain durable findings without reintroducing discarded transcript prose."""
+
+from __future__ import annotations
+
+import json
+
+from stacktrace_cli.detector.blocked import REASON_CODES, reason_for
+
+# Notification prose is selected by rule ID only (ADR-0031). In particular,
+# finding titles, component names and evidence never supply notification text.
+_GUIDANCE = {
+    "stacktrace-credential-egress": (
+        "Credential-shaped material appeared in an outbound tool call",
+        (
+            "Treat the credential as potentially exposed: revoke or rotate it, "
+            "then inspect why the outbound tool received it."
+        ),
+    ),
+    "stacktrace-deceptive-completion": (
+        "A success claim conflicts with verification evidence",
+        "Inspect the cited verification results before relying on the completion claim.",
+    ),
+    "stacktrace-agent-blocked": (
+        "The agent encountered a block while working",
+        "Inspect the recorded block reason before retrying the task.",
+    ),
+}
+
+
+def rule_guidance(rule_id: str) -> tuple[str, str]:
+    return _GUIDANCE.get(
+        rule_id,
+        ("A finding was recorded", "Inspect the retained evidence in the local session."),
+    )
+
+
+def render_finding(finding: dict[str, object]) -> str:
+    """Render the old, title-less ledger as well as newly recorded findings."""
+    rule_id = str(finding.get("rule_id", "unknown-rule"))
+    title, remedy = rule_guidance(rule_id)
+    evidence = finding.get("evidence", [])
+    items = (
+        [item for item in evidence if isinstance(item, dict)] if isinstance(evidence, list) else []
+    )
+    if rule_id == "stacktrace-agent-blocked" and items:
+        code = items[0].get("kind")
+        if isinstance(code, str) and code in REASON_CODES:
+            reason = reason_for(code)
+            title, remedy = reason.title, reason.remedy
+
+    lines = [
+        f"{str(finding.get('severity', 'unknown')).upper()} {rule_id}: {title}",
+        f"  Confidence: {finding.get('confidence', 'unknown')}",
+    ]
+    for item in items:
+        # Quote stored descriptors as data, including escaped terminal controls.
+        kind = json.dumps(item.get("kind"), ensure_ascii=True)
+        detail = json.dumps(item.get("detail"), ensure_ascii=True)
+        span = json.dumps(item.get("span"), ensure_ascii=True)
+        lines.extend((f"  Evidence ({kind}): {detail}", f"    Location: {span}"))
+    if not items:
+        lines.append("  Evidence: no descriptors were retained.")
+    lines.append(f"  Next step: {remedy}")
+    lines.append(
+        "  Tool/component names and raw call content are not retained in this ledger; "
+        "inspect the cited locations in the local session for attribution."
+    )
+    return "\n".join(lines)

stacktrace_cli/daemon/store.py

@@ -17,6 +17,8 @@ from stacktrace_cli.detector.rules import scope_of
 from stacktrace_cli.private_state import ensure_private_directory
 from stacktrace_cli.telemetry import emit_derived
 
+from .presentation import rule_guidance
+
 
 @dataclass(frozen=True)
 class SessionKey:
@@ -266,10 +268,16 @@ class FindingStore:
         identity = f"{session.agent_kind}\0{session.session_id}\0{rule_id}\0{anchor}".encode()
         return f"stn_{hashlib.sha256(identity).hexdigest()[:24]}"
 
+    #: Severities that earn a notification. `Severity` is `low | medium | high`;
+    #: `critical` is carried because the gate has always tested for it, though
+    #: no rule emits it. `low` stays silent.
+    _NOTIFIABLE_SEVERITIES = frozenset({"medium", "high", "critical"})
+
     @staticmethod
     def _eligible(finding: dict[str, object]) -> bool:
         return (
-            finding.get("severity") in {"high", "critical"} and finding.get("confidence") == "high"
+            finding.get("severity") in FindingStore._NOTIFIABLE_SEVERITIES
+            and finding.get("confidence") == "high"
         )
 
     @staticmethod
@@ -302,13 +310,17 @@ class FindingStore:
         severity = finding["severity"]
         assert isinstance(rule_id, str)
         assert isinstance(severity, str)
+        explanation, _ = rule_guidance(rule_id)
         return Notification(
             event_id=event_id,
             session=session,
             rule_id=rule_id,
             severity=severity,
-            title=f"Stacktrace detected a {severity}-severity finding",
-            body=f"{rule_id} in this agent session. Run /stacktrace:findings for details.",
+            title=f"Stacktrace: {explanation}",
+            body=(
+                f"Severity: {severity}. Rule: {rule_id}. "
+                "Run /stacktrace:findings for evidence and next steps."
+            ),
         )
 
     @staticmethod

{stacktrace_cli-0.4.1.dist-info → stacktrace_cli-0.5.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stacktrace-cli
-Version: 0.4.1
+Version: 0.5.0
 Summary: CLI for Stacktrace — Detection and Response platform for AI Agents.
 Project-URL: Homepage, https://stacktrace.ai
 Author-email: "Stacktrace AI, Inc" <founders@stacktrace.ai>
@@ -51,7 +51,7 @@ Requires Python 3.11 or newer.
 
 ```console
 $ stacktrace --version
-stacktrace 0.4.1 (openaca 0.7.0)
+stacktrace 0.5.0 (openaca 0.7.0)
 ```
 
 ## Quick start

{stacktrace_cli-0.4.1.dist-info → stacktrace_cli-0.5.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-stacktrace_cli/__init__.py,sha256=bXjoLHPSd6YwfHKM4Sfm35_n4QAJu53np9qMAKHK4cQ,111
+stacktrace_cli/__init__.py,sha256=zHZ09_BkTtuYNvOWuyPl2wfwi89SQMreN3vwkdmlloU,111
 stacktrace_cli/__main__.py,sha256=F_tqj3PRzeBtY-uvBs923H8oc-s9bebhIh6UnAUwNYc,448
 stacktrace_cli/analysis.py,sha256=cNsFO0Awr2gxzQWfEC1befhQ-6XOZDcv0VMmR5QYFug,23766
 stacktrace_cli/build.py,sha256=lXMXBMoQtXC5qVMAWBsJavcVfXPmJiAZgV3cRBqUvyk,4846
@@ -15,16 +15,17 @@ stacktrace_cli/correlate/project_map.py,sha256=R37SktEsBzVPufQZmQeYWm9PoO0YGg98Y
 stacktrace_cli/correlate/record.py,sha256=ggpEJaQNyuUqjNcE2FuskivTgNhIBmqnxWncpigRT50,12057
 stacktrace_cli/correlate/render.py,sha256=hJZhZcqE4bKAeXIegddY7uViCyp7NAPTQl1cj9YfM68,35387
 stacktrace_cli/daemon/__init__.py,sha256=YP0eKpNcRl1GzKO1GXh9gOoigViU2duV-PEOw0lLLwQ,59
-stacktrace_cli/daemon/cli.py,sha256=KY6q0YZxoIktDgCn9a3qroSxmVMtkyTzzticGk1MMuQ,3034
+stacktrace_cli/daemon/cli.py,sha256=vDUF93touwMFKEH1lEv8J5cHCermBGu8hCmqJJqyJ58,2932
 stacktrace_cli/daemon/client.py,sha256=DRiyuhlPn4S4XFzzegCBZJmhkcMjL6N8xu1ETDPZq6c,4751
 stacktrace_cli/daemon/composition.py,sha256=3SiDqtfKpW5lhpN3H9SYVGQzhSotRvrt-o_3kd41D54,4286
 stacktrace_cli/daemon/observer.py,sha256=uc8AriC4xPvSENg4bdWSI7vtF1vjA4GmcWANZZvcziQ,6761
 stacktrace_cli/daemon/paths.py,sha256=fDmGavMvSQg_UbJTmamwmOUBwTm18NUeI_Lo2JFMtGI,1380
+stacktrace_cli/daemon/presentation.py,sha256=LPm9ibm4Kw42RtB3H4PNT3iJgHUyWn-rlhgvymmlHrk,2751
 stacktrace_cli/daemon/protocol.py,sha256=s6VGko72dWOW0V2iDq0WTpYQmWV2l4Q-97bU_NR5Xo4,762
 stacktrace_cli/daemon/runtime.py,sha256=cJusGYyWKo-4hp1bKYgDPCgvBFKHptX6DEv2GqeNcXg,8115
 stacktrace_cli/daemon/server.py,sha256=pMNoJ8BOTNAhyJigM_WHwDOczjJtyN_YYaNUs5M6qic,5986
 stacktrace_cli/daemon/service.py,sha256=ULUWfS0hvjQ2j9Lk0u_tofpFbfLDMUcXrPYOircSld0,6128
-stacktrace_cli/daemon/store.py,sha256=FnpmkPP1uhWrsQ6BGNTmu4QSvYFbJvMkz_Rqd61LCq0,14346
+stacktrace_cli/daemon/store.py,sha256=uS3QcLUN48RiVje3lnvHEs_zrtpRYg7ly1VQph8cr9M,14788
 stacktrace_cli/detector/__init__.py,sha256=uUwte-wGAjsXDlTgYClDtYtmZSj3-X52U_bRHIZzICw,69
 stacktrace_cli/detector/analyzer.py,sha256=HGBJmXI8_9Z8iDink1YXTMMuIoyUYWOSVc0qeNzWR00,8437
 stacktrace_cli/detector/blocked.py,sha256=Bd88-ADzTlWV-Bd5JH7DPRrlJHxh6KwoAe2tlDd-drA,24377
@@ -84,7 +85,7 @@ stacktrace_cli/telemetry/cli.py,sha256=YgNFWxa24BFuq20uW7VdNRBaSJO7fKsvmMQYR8yo9
 stacktrace_cli/telemetry/events.py,sha256=VF_My0Nu9wLT9qk2FQfMgPjJob9uVbDtIHjBJ4ju5pw,10690
 stacktrace_cli/telemetry/posthog.py,sha256=8Bu5AwhVUcvV-4pqTdybWUfOGqPR-7W7apmSjkX3_94,4705
 stacktrace_cli/telemetry/state.py,sha256=-7UmK8bBFj3Zh3bzX0kJwxn7-CvreMar_0x1NiZghkE,7242
-stacktrace_cli-0.4.1.dist-info/METADATA,sha256=KQUHzPqcvqETFW66LsToGUc77HL08B33wjt-P9ypvZ0,7763
-stacktrace_cli-0.4.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-stacktrace_cli-0.4.1.dist-info/entry_points.txt,sha256=OYDmb2CtEjd8TV78zxiGB1XVrLrC6vvayAPXa79_tJ0,60
-stacktrace_cli-0.4.1.dist-info/RECORD,,
+stacktrace_cli-0.5.0.dist-info/METADATA,sha256=YO4ib9vOki1qJ2mTuUkhjYv15tORfuIGX3whJy9R0YY,7763
+stacktrace_cli-0.5.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+stacktrace_cli-0.5.0.dist-info/entry_points.txt,sha256=OYDmb2CtEjd8TV78zxiGB1XVrLrC6vvayAPXa79_tJ0,60
+stacktrace_cli-0.5.0.dist-info/RECORD,,