stacktrace-cli 0.2.3__py3-none-any.whl → 0.3.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.2.3"
+__version__ = "0.3.0"

stacktrace_cli/analysis.py

@@ -106,7 +106,7 @@ def analyse(
     project_map: tuple[str, ...] = (),
     root: Path | None = None,
     session_ids: tuple[str, ...] = (),
-    escalate: bool = False,
+    reasoning: bool = False,
     budget: int = DEFAULT_BUDGET,
     sample_budget: int = DEFAULT_SAMPLE_BUDGET,
     cache: VerdictCache | None = None,
@@ -123,7 +123,7 @@ def analyse(
     pass; a one-shot command passes nothing and gets the default.
 
     `session_ids` narrows the window to named sessions. Empty means the whole
-    window, which is what every command passes; monitor's escalate button is
+    window, which is what every command passes; monitor's reasoning button is
     what needs the narrowing, and needs it to be structural.
 
     `since` is the window's spelling — `parse_since` reads it — or the cutoff
@@ -142,7 +142,7 @@ def analyse(
     )
     run = run_detector(
         acquired.view,
-        escalate=escalate,
+        reasoning=reasoning,
         budget=budget,
         sample_budget=sample_budget,
         cache=cache,
@@ -287,11 +287,11 @@ def analyse_progressively(
     exists to prevent.
 
     `cache` is read and never written. A session graded by an earlier
-    `detect --escalate` shows that grade here; this path never commissions one.
+    `detect --reasoning` shows that grade here; this path never commissions one.
 
-    **No `escalate` parameter, deliberately.** Stage 3's budget is per *run*, so
+    **No `reasoning` parameter, deliberately.** Stage 3's budget is per *run*, so
     judging in batches would give each batch its own budget and spend a multiple
-    of what was authorised. A streaming escalation needs a budget shared across
+    of what was authorised. A streaming reasoning run needs a budget shared across
     batches; until it has one, this path does not offer the option rather than
     offering it wrongly.
     """
@@ -358,8 +358,8 @@ def analyse_progressively(
     for index in range(0, len(ordered), step):
         judged = run_detector(
             CorrelatedView(sessions=tuple(ordered[index : index + step])),
-            # Read, never written, and never escalating: a session an earlier
-            # `detect --escalate` graded renders with that grade here, and this
+            # Read, never written, and never requesting: a session an earlier
+            # `detect --reasoning` graded renders with that grade here, and this
             # path commissions nothing (ADR-0026 clause 2).
             cache=cache,
         )
@@ -367,7 +367,7 @@ def analyse_progressively(
             detections=accumulated.detections + judged.detections,
             unknowns=accumulated.unknowns + judged.unknowns,
             sessions=accumulated.sessions + judged.sessions,
-            escalated=accumulated.escalated + judged.escalated,
+            requested=accumulated.requested + judged.requested,
             analysed=accumulated.analysed + judged.analysed,
             cache_hits=accumulated.cache_hits + judged.cache_hits,
             collection_failures=failures,

stacktrace_cli/cli.py

@@ -223,13 +223,14 @@ def sessions(
     help="Show every detection and all of its evidence. Default: the summary alone.",
 )
 @click.option(
-    "--escalate/--no-escalate",
+    "--reasoning",
+    is_flag=True,
     default=False,
-    show_default=True,
-    help="Send flagged sessions to the agent's own CLI for semantic analysis. 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. --escalate turns it on "
+    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 "
@@ -281,7 +282,7 @@ def detect(
     bom_paths: tuple[Path, ...],
     output_format: str,
     detail: bool,
-    escalate: bool,
+    reasoning: bool,
     budget: int,
     sample_budget: int,
     cache: bool,
@@ -299,7 +300,7 @@ def detect(
 
     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:
-    --escalate turns it on, capped by --budget. Sessions that qualified for it
+    --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.
 
@@ -307,10 +308,10 @@ def detect(
     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 --escalate the run is the two
+    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 --escalate:
+    One network call happens before any of them, with or without --reasoning:
     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.
@@ -325,11 +326,11 @@ def detect(
             bom_paths=bom_paths,
             project_map=project_map,
             root=root,
-            escalate=escalate,
+            reasoning=reasoning,
             budget=budget,
             sample_budget=sample_budget,
-            # Not gated on `escalate`. A verdict already paid for is an
-            # answer this run has, and `escalate` governs whether new ones may
+            # 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
             # `run_detector` states at its cache pass. Gating it here made a
             # session read as graded or ungraded depending on a flag that
@@ -368,11 +369,11 @@ def detect(
     "entirely when nothing on disk has changed.",
 )
 @click.option(
-    "--escalate/--no-escalate",
+    "--reasoning",
+    is_flag=True,
     default=False,
-    show_default=True,
-    help="Let the page send one session to the agent's own CLI for semantic "
-    "analysis. Off by default: stage 3 spends your provider quota, and a page "
+    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.",
 )
 @click.option(
@@ -380,7 +381,7 @@ def detect(
     type=click.IntRange(min=1),
     default=DEFAULT_BUDGET,
     show_default=True,
-    help="Escalations this monitor may spend in total, if --escalate is on.",
+    help="Reasoning runs this monitor may spend in total, if --reasoning is on.",
 )
 @click.option(
     "--no-open", is_flag=True, default=False, help="Print the URL, do not open a browser."
@@ -421,7 +422,7 @@ def monitor(
     port: int,
     host: str,
     interval: float,
-    escalate: bool,
+    reasoning: bool,
     budget: int,
     no_open: bool,
     agent_kinds: tuple[str, ...],
@@ -439,7 +440,7 @@ 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. --escalate adds a button
+    that need no model are the only ones that run. --reasoning adds a button
     that spends your provider quota, off unless asked for.
     """
     try:
@@ -447,7 +448,7 @@ def monitor(
             host=host,
             port=port,
             interval=interval,
-            escalate=escalate,
+            reasoning=reasoning,
             budget=budget,
             open_browser=not no_open,
             echo=click.echo,

stacktrace_cli/detector/analyzer.py

@@ -64,7 +64,7 @@ _TIMEOUT = 180
 #: run /login"* and exits 1, on a machine whose CLI is authenticated and working.
 #: That is the same premise `--bare` is avoided for (ADR-0004: the developer's
 #: own CLI, already authenticated), broken through the environment instead of
-#: through a flag. The failure mode is the dangerous kind: every escalation
+#: through a flag. The failure mode is the dangerous kind: every reasoning request
 #: returns `analyzer_error`, the pipeline records `Unknown`, and stage 3 looks
 #: like it ran. `LOGNAME` accompanies it as the same identity on systems that
 #: set that instead.

stacktrace_cli/detector/cache.py

@@ -3,7 +3,7 @@
 Authorized by ADR-0011, which amends ADR-0006's persistence clause. The argument
 is narrow: a reasoning verdict is an **expensive pure function of an immutable,
 ended session**. `stacktrace detect` is a command a person runs repeatedly, each
-escalation costs roughly $0.09 and 9 seconds, and the answer cannot change once
+reasoning request costs roughly $0.09 and 9 seconds, and the answer cannot change once
 the session has stopped growing.
 
 Three properties carry the whole design, and each exists because its absence was
@@ -116,7 +116,7 @@ class CachedVerdict:
 
 @dataclass(frozen=True)
 class CachedOutcome:
-    """One escalation's stored answer: provenance, plus whichever rules fired.
+    """One reasoning request's stored answer: provenance, plus whichever rules fired.
 
     Provenance sits here rather than on each verdict because ADR-0011
     constraint 1 lists it as part of what an entry *carries*, not only what it is
@@ -132,7 +132,7 @@ class CachedOutcome:
 
 def cache_key(
     session: SessionLike,
-    escalation: object,
+    request: object,
     rule_ids: Sequence[str],
     prompt_version: str,
     identity: tuple[str, str],
@@ -143,17 +143,17 @@ def cache_key(
     ADR-0011 constraint 3 states them apart, and neither is a field `serialise()`
     shows the analyzer — so a fingerprint built only from analyzer-visible
     content would let two distinct sessions with byte-identical rendered turns
-    and escalation context share one verdict.
+    and reasoning-request context share one verdict.
 
     **Reasons and spans are hashed in their given order, never sorted.**
     `_why()` joins each collection in order and puts the result straight into
     the prompt, so the same members in a different order are two different
     prompts. Sorting first would merge them.
 
-    **Which rule cited which span, not only the merged set.** `escalation.spans`
-    is a deduplicated union over every escalating reason, so it cannot say
+    **Which rule cited which span, not only the merged set.** `request.spans`
+    is a deduplicated union over every requesting reason, so it cannot say
     whether a span was the injection marker's evidence or the credential rule's
-    — and `serialise_injection()` reads exactly that, from `escalation.stage_one`,
+    — and `serialise_injection()` reads exactly that, from `request.stage_one`,
     to decide which results and arguments the transcript carries. Two builds
     that attribute overlapping spans differently produce the same union and
     wholly different transcripts, so without this a verdict computed from one
@@ -181,12 +181,12 @@ def cache_key(
             {
                 "session_id": session.session_id,
                 "turn_count": session.turn_count,
-                "reasons": list(getattr(escalation, "reasons", ()) or ()),
-                "spans": list(getattr(escalation, "spans", ()) or ()),
-                "stage_one": _cited_per_rule(escalation),
+                "reasons": list(getattr(request, "reasons", ()) or ()),
+                "spans": list(getattr(request, "spans", ()) or ()),
+                "stage_one": _cited_per_rule(request),
                 "coverage": [
-                    getattr(getattr(escalation, "coverage", None), "total", None),
-                    getattr(getattr(escalation, "coverage", None), "resolved", None),
+                    getattr(getattr(request, "coverage", None), "total", None),
+                    getattr(getattr(request, "coverage", None), "resolved", None),
                 ],
                 "prompt_version": prompt_version,
                 "verdict_logic_version": _VERDICT_LOGIC_VERSION,
@@ -201,7 +201,7 @@ def cache_key(
     return digest.hexdigest()
 
 
-def _cited_per_rule(escalation: object) -> list[list[object]]:
+def _cited_per_rule(request: object) -> list[list[object]]:
     """Which stage-one rule cited which spans, in the order they were found.
 
     Descriptors only, and only the two a prompt reads: `serialise_injection()`
@@ -212,13 +212,13 @@ def _cited_per_rule(escalation: object) -> list[list[object]]:
 
     Order is preserved rather than sorted. Nothing downstream reads it — the
     spans become a set — so the worst a preserved order can do is separate two
-    escalations that would have produced one prompt, which costs a miss. The
+    requests that would have produced one prompt, which costs a miss. The
     opposite mistake merges two prompts under one key, and that is the one
     ADR-0011 constraint 5 forbids.
     """
     return [
         [finding.rule_id, [evidence.span for evidence in finding.evidence]]
-        for finding in getattr(escalation, "stage_one", ()) or ()
+        for finding in getattr(request, "stage_one", ()) or ()
     ]
 
 

stacktrace_cli/detector/deterministic.py

@@ -2,7 +2,7 @@
 
 Every rule here is one a responder can verify by looking at the session. That is
 the bar for this stage, and it is why the stage emits directly rather than
-escalating: nothing a slower stage adds changes *this string looks like a
+requesting reasoning: nothing a slower stage adds changes *this string looks like a
 credential and it went to an outbound call*.
 
 Two asymmetries carry most of the precision:

stacktrace_cli/detector/finding.py

@@ -150,7 +150,7 @@ class Evidence:
 class Verdict:
     """What produced a finding, so two machines' answers are comparable.
 
-    Recorded for every stage, not only escalated ones: knowing a finding came
+    Recorded for every stage, not only requested ones: knowing a finding came
     from `priors` rather than `reasoning` is what tells a reader whether a model
     was involved at all.
     """
@@ -340,9 +340,9 @@ class Unknown:
     reason: UnknownReason
     spans: tuple[str, ...] = ()
     detail: str = ""
-    #: For an escalation that qualified for stage 3 but never reached it, the
+    #: For a reasoning request that qualified for stage 3 but never reached it, the
     #: priors that would have been analysed. Kept so a budget-limited or
-    #: `--no-escalate` run still shows *why* the session was of interest.
+    #: run without `--reasoning` still shows *why* the session was of interest.
     reasons: tuple[str, ...] = field(default_factory=tuple)
     #: Reasoning-stage only: whether this unknown was raised **after** the
     #: session was actually sent to the analyzer. `run_detector` counts a

stacktrace_cli/detector/markers.py

@@ -27,7 +27,7 @@ from data to instruction.
 
 Finding the characters is not finding an attack, and the difference is
 measurable. On 621 real sessions this rule fired three times — the only
-evidence-backed escalations in the whole corpus — and all three were one file:
+evidence-backed reasoning requests in the whole corpus — and all three were one file:
 another agent-security tool's own detector, whose source reads
 `_BIDI_OVERRIDE_CHARS = frozenset('\u202d\u202e')`. Security work names the
 alphabet of the attacks it looks for, and so do specifications, test fixtures

stacktrace_cli/detector/priors.py

@@ -14,14 +14,14 @@ bounds it:
 - **An unreadable connection log is the same kind of bound.** Egress over MCP is
   observed from `transport` alone, so a log that never applied is silent in
   exactly the way a local call is — `_missing_mcp_transport` says which it was.
-- **Nothing here escalates.** The routes into stage three are stage-one facts;
+- **Nothing here requests reasoning.** The routes into stage three are stage-one facts;
   an advisory is already settled by the record, and spending inference to
   confirm it would buy nothing.
 
 **Four rules have been removed from this stage over two decisions.** ADR-0013
 withdrew `tool-shadowing`, which needs an `ambiguous` outcome the join has never
-emitted, and `unpinned-invoked`, which could only escalate in combination with
-it; the combination escalation route went with them. ADR-0015 withdrew
+emitted, and `unpinned-invoked`, which could only request reasoning in combination
+with it; the combination route went with them. ADR-0015 withdrew
 `unsanctioned-mcp-tool-use` — and with it the `uninventoried_component` unknown
 that reported the same fact for every other component type — and
 `capability-crossing`, which ADR-0013 had deliberately kept on the argument that
@@ -58,7 +58,7 @@ _VERDICT = Verdict(stage="priors")
 #: not read enough of it either to clear or to fault it.
 _COVERAGE_FLOOR = 0.5
 
-#: Stage-one rules that escalate on their own. Each names a question only
+#: Stage-one rules that request reasoning on their own. Each names a question only
 #: `reasoning` can settle, and each would otherwise be unreachable:
 #:
 #: - a marker asks whether an injected instruction was *acted on*, which nothing
@@ -84,7 +84,7 @@ _SAMPLE_BUCKETS = 7
 
 #: The one reason that names a session chosen without evidence — no prior fired,
 #: so there is nothing a suppression verdict could withdraw. Named here, next to
-#: `Escalation`, because `reasoning` needs it to recognise the case and `run`
+#: `ReasoningRequest`, because `reasoning` needs it to recognise the case and `run`
 #: needs it to build one.
 SAMPLED = "sampled"
 
@@ -116,7 +116,7 @@ def in_sample_bucket(session_id: str, day_of_run: int) -> bool:
 
 
 @dataclass(frozen=True)
-class Escalation:
+class ReasoningRequest:
     """A session worth spending inference on, and what to look at.
 
     Carries no budget: what remains of a run's allowance belongs to the
@@ -124,7 +124,7 @@ class Escalation:
     """
 
     session: SessionRef
-    #: Which priors fired, by name, or the stage-one rule that escalated alone.
+    #: Which priors fired, by name, or the stage-one rule that requested alone.
     reasons: tuple[str, ...]
     #: Where a semantic question is worth asking.
     spans: tuple[str, ...]
@@ -137,12 +137,12 @@ class Escalation:
 
 def run_priors(
     correlated: CorrelatedSession, stage_one: Sequence[Detection]
-) -> tuple[tuple[Detection, ...], tuple[Unknown, ...], Escalation | None]:
+) -> tuple[tuple[Detection, ...], tuple[Unknown, ...], ReasoningRequest | None]:
     """Score one correlated session against its composition.
 
     Three values, not four. A `prior_recorded` bit used to travel alongside,
-    saying an escalating prior had fired without crossing the combination
-    threshold — a state that no longer exists, because neither the escalating
+    saying a requesting prior had fired without crossing the combination
+    threshold — a state that no longer exists, because neither the requesting
     priors nor the threshold do. A field that is now constantly `False` would
     be a worse answer than no field.
     """
@@ -169,7 +169,7 @@ def run_priors(
                     ),
                 ),
             ),
-            _escalation(_solo_reasons(stage_one), ref, stage_one, coverage),
+            _request(_solo_reasons(stage_one), ref, stage_one, coverage),
         )
 
     composition = correlated.composition
@@ -197,28 +197,28 @@ def run_priors(
         else:
             detections.extend(_advisory_reach(ordered, calls, composition, ref, coverage))
 
-    # One route. A stage-one fact this stage cannot settle escalates on its own;
-    # nothing here combines, because nothing here escalates any more.
-    escalation = _escalation(_solo_reasons(stage_one), ref, stage_one, coverage, spans)
-    return tuple(detections), tuple(unknowns), escalation
+    # One route. A stage-one fact this stage cannot settle requests reasoning on
+    # its own; nothing here combines, because nothing here requests it any more.
+    request = _request(_solo_reasons(stage_one), ref, stage_one, coverage, spans)
+    return tuple(detections), tuple(unknowns), request
 
 
 def _solo_reasons(stage_one: Sequence[Detection]) -> list[str]:
-    """The stage-one rules on this session that escalate on their own."""
+    """The stage-one rules on this session that request reasoning on their own."""
     return sorted({finding.rule_id for finding in stage_one} & _SOLO_ROUTES)
 
 
-def _escalation(
+def _request(
     reasons: Sequence[str],
     ref: SessionRef,
     stage_one: Sequence[Detection],
     coverage: Coverage,
     spans: Sequence[str] = (),
-) -> Escalation | None:
-    """One escalation naming every reason that fired, or nothing.
+) -> ReasoningRequest | None:
+    """One reasoning request naming every reason that fired, or nothing.
 
     Spans from the priors that emitted are joined by those of every stage-one
-    finding whose rule escalated, so the analyzer is pointed at both.
+    finding whose rule requested it, so the analyzer is pointed at both.
     """
     if not reasons:
         return None
@@ -230,7 +230,7 @@ def _escalation(
             if finding.rule_id == reason
             for evidence in finding.evidence
         )
-    return Escalation(
+    return ReasoningRequest(
         session=ref,
         reasons=tuple(dict.fromkeys(reasons)),
         spans=tuple(dict.fromkeys(cited)),