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

stacktrace_cli/detector/reasoning.py

@@ -31,15 +31,15 @@ completion* needs the closing claim and the checks it rests on.
 ## Suppression was removed, not disabled
 
 A fourth question used to ask whether an innocent reading accounted for the
-priors that escalated a session. It was never once asked: measured on 74
-escalation-eligible sessions, every route was either a stage-one *fact* — which
+priors that requested reasoning on a session. It was never once asked: measured on 74
+reasoning-eligible sessions, every route was either a stage-one *fact* — which
 a transcript reader must never be able to talk the pipeline out of — or the
 evidence-free `sampled` route, which carries no prior to withdraw. The two
-escalating priors that could have produced a suppressible reason were withdrawn
+requesting priors that could have produced a suppressible reason were withdrawn
 for being unfireable, and the combination route with them.
 
 Keeping the machinery would have been keeping a capability the pipeline cannot
-reach. `docs/specs/detector.md` records what would bring it back: an escalating
+reach. `docs/specs/detector.md` records what would bring it back: a requesting
 prior that is a *reading* rather than a fact.
 """
 
@@ -52,7 +52,7 @@ from dataclasses import dataclass
 from stacktrace_cli.correlate.observed import VALUE_TAKING_OPTIONS, command_segments
 from stacktrace_cli.detector.analyzer import Analyzer, Answer, Unavailable
 from stacktrace_cli.detector.finding import Detection, Evidence, SessionRef, Unknown, Verdict
-from stacktrace_cli.detector.priors import Escalation
+from stacktrace_cli.detector.priors import ReasoningRequest
 from stacktrace_cli.detector.prompts import PROMPT_VERSION, load
 from stacktrace_cli.detector.verdict import RuleVerdict, parse_verdict
 from stacktrace_cli.sessions.outcome import denied
@@ -251,7 +251,9 @@ _MUST_HAVE_RUN = frozenset(
 )
 
 
-def admissible_spans(rule_id: str, session: SessionLike, escalation: Escalation) -> frozenset[str]:
+def admissible_spans(
+    rule_id: str, session: SessionLike, request: ReasoningRequest
+) -> frozenset[str]:
     """The calls a verdict on `rule_id` may cite.
 
     Read by `run_reasoning` before a verdict is parsed, and by `run.py` before a
@@ -271,7 +273,7 @@ def admissible_spans(rule_id: str, session: SessionLike, escalation: Escalation)
     """
     calls = [call for turn in session.turns for call in turn.tool_calls]
     if rule_id == "stacktrace-injected-instruction-followed":
-        first = _first_cited_call(session, escalation)
+        first = _first_cited_call(session, request)
         if first is not None:
             # Strictly after: the call at `first` is the one whose *result*
             # carried the instruction, and nothing it did preceded its own
@@ -284,7 +286,7 @@ def admissible_spans(rule_id: str, session: SessionLike, escalation: Escalation)
     return frozenset(call.span for call in calls if not denied(call))
 
 
-def _first_cited_call(session: SessionLike, escalation: Escalation) -> int | None:
+def _first_cited_call(session: SessionLike, request: ReasoningRequest) -> int | None:
     """Where in session order the earliest instruction-shaped *result* sits.
 
     `None` where nothing bounds the front of the window: either no cited span
@@ -295,7 +297,7 @@ def _first_cited_call(session: SessionLike, escalation: Escalation) -> int | Non
     function rather than repeating them, so what the analyzer is *sent* and
     what it is allowed to *cite* cannot drift apart.
     """
-    cited = _injection_spans(escalation)
+    cited = _injection_spans(request)
     calls = [call for turn in session.turns for call in turn.tool_calls]
     if cited - {call.span for call in calls}:
         return None
@@ -311,15 +313,15 @@ class ReasoningOutcome:
 
 
 def run_reasoning(
-    escalation: Escalation, session: SessionLike, analyzer: Analyzer
+    request: ReasoningRequest, session: SessionLike, analyzer: Analyzer
 ) -> ReasoningOutcome:
-    """Ask the analyzer about one escalated session."""
-    ref = escalation.session
+    """Ask the analyzer about one requested session."""
+    ref = request.session
     verdict = _verdict_of(analyzer)
     findings: list[Detection] = []
     unknowns: list[Unknown] = []
 
-    for rule_id in applicable_rules(escalation):
+    for rule_id in applicable_rules(request):
         if (
             rule_id == "stacktrace-intent-drift"
             and session.compactions
@@ -341,11 +343,11 @@ def run_reasoning(
                         ),
                     ),
                     ref,
-                    escalation,
+                    request,
                 )
             )
             continue
-        truncated_span = _truncated_evidence(session, rule_id, escalation)
+        truncated_span = _truncated_evidence(session, rule_id, request)
         if truncated_span is not None:
             # The same reason `truncated` is `Unknown` in stage one: a body
             # elided in the middle looks whole at both ends, and reasoning over
@@ -365,7 +367,7 @@ def run_reasoning(
                         ),
                     ),
                     ref,
-                    escalation,
+                    request,
                 )
             )
             continue
@@ -373,7 +375,7 @@ def run_reasoning(
         # tripwire rather than a window: a body elided in the middle looks
         # whole at both ends, so a body that does not fit is `unknown` for
         # *this* question rather than silently shortened for it.
-        transcript = _CONTEXT[rule_id](session, escalation)
+        transcript = _CONTEXT[rule_id](session, request)
         if len(transcript) > CONTEXT_LIMIT:
             unknowns.append(
                 _with(
@@ -387,7 +389,7 @@ def run_reasoning(
                         ),
                     ),
                     ref,
-                    escalation,
+                    request,
                 )
             )
             continue
@@ -396,21 +398,21 @@ def run_reasoning(
         # three report (`_MUST_HAVE_RUN`).
         answer = _ask(
             analyzer,
-            _prompt_for(rule_id, escalation),
+            _prompt_for(rule_id, request),
             transcript,
             rule_id,
-            admissible_spans(rule_id, session, escalation),
+            admissible_spans(rule_id, session, request),
         )
         if isinstance(answer, Unknown):
-            unknowns.append(_with(answer, ref, escalation))
+            unknowns.append(_with(answer, ref, request))
             continue
         if answer.fired:
-            findings.append(_finding(answer, ref, escalation, verdict))
+            findings.append(_finding(answer, ref, request, verdict))
 
     return ReasoningOutcome(findings=tuple(findings), unknowns=tuple(unknowns))
 
 
-def dispatchable(escalation: Escalation, session: SessionLike) -> bool:
+def dispatchable(request: ReasoningRequest, session: SessionLike) -> bool:
     """Whether `run_reasoning` would ask the analyzer at least one question.
 
     A preflight over the same per-rule bodies `run_reasoning` builds: a session
@@ -422,12 +424,11 @@ def dispatchable(escalation: Escalation, session: SessionLike) -> bool:
     never calls the analyzer at all.
     """
     return any(
-        _block_reason(rule_id, escalation, session) is None
-        for rule_id in applicable_rules(escalation)
+        _block_reason(rule_id, request, session) is None for rule_id in applicable_rules(request)
     )
 
 
-def undispatchable_reason(escalation: Escalation, session: SessionLike) -> str:
+def undispatchable_reason(request: ReasoningRequest, session: SessionLike) -> str:
     """Why `dispatchable()` returned False, for the caller to report accurately.
 
     A session can be undispatchable for three distinct reasons — oversized,
@@ -438,8 +439,8 @@ def undispatchable_reason(escalation: Escalation, session: SessionLike) -> str:
     first blocking reason found is the one reported: with none dispatchable,
     every applicable rule is already blocked by one of these three.
     """
-    for rule_id in applicable_rules(escalation):
-        reason = _block_reason(rule_id, escalation, session)
+    for rule_id in applicable_rules(request):
+        reason = _block_reason(rule_id, request, session)
         if reason is not None:
             return reason
     # Only meaningful once `dispatchable()` is False; unreachable otherwise
@@ -447,35 +448,37 @@ def undispatchable_reason(escalation: Escalation, session: SessionLike) -> str:
     return "session_too_large"
 
 
-def _block_reason(rule_id: str, escalation: Escalation, session: SessionLike) -> str | None:
+def _block_reason(rule_id: str, request: ReasoningRequest, session: SessionLike) -> str | None:
     """Why this one rule would not reach the analyzer, or None if it would."""
     if rule_id == "stacktrace-intent-drift" and session.compactions and not session.initial_prompt:
         return "insufficient_context"
-    if _truncated_evidence(session, rule_id, escalation) is not None:
+    if _truncated_evidence(session, rule_id, request) is not None:
         return "truncated"
-    if len(_CONTEXT[rule_id](session, escalation)) > CONTEXT_LIMIT:
+    if len(_CONTEXT[rule_id](session, request)) > CONTEXT_LIMIT:
         return "session_too_large"
     return None
 
 
-def _injection_spans(escalation: Escalation) -> set[str]:
+def _injection_spans(request: ReasoningRequest) -> set[str]:
     """Where stage one actually found instruction-shaped material.
 
-    `escalation.spans` is every solo-escalating reason's evidence merged into
-    one set, so a session that escalated on both `stacktrace-credential-egress`
+    `request.spans` is every solo-requesting reason's evidence merged into
+    one set, so a session that requested on both `stacktrace-credential-egress`
     and `stacktrace-injection-marker` carries the credential call's span there
     too. Filtering `stage_one` to the marker's own rule keeps that unrelated
     span out of what `injected-instruction-followed` treats as cited.
     """
     return {
         evidence.span
-        for finding in escalation.stage_one
+        for finding in request.stage_one
         if finding.rule_id == "stacktrace-injection-marker"
         for evidence in finding.evidence
     }
 
 
-def _truncated_evidence(session: SessionLike, rule_id: str, escalation: Escalation) -> str | None:
+def _truncated_evidence(
+    session: SessionLike, rule_id: str, request: ReasoningRequest
+) -> str | None:
     """The span of a truncated call this rule would otherwise read as whole.
 
     Truncation loses evidence in the middle: the retained fragment looks
@@ -486,7 +489,7 @@ def _truncated_evidence(session: SessionLike, rule_id: str, escalation: Escalati
     and `deceptive-completion`'s verification output.
     """
     if rule_id == "stacktrace-injected-instruction-followed":
-        cited = _injection_spans(escalation)
+        cited = _injection_spans(request)
         for turn in session.turns:
             for call in turn.tool_calls:
                 if call.span in cited and call.truncated:
@@ -499,14 +502,14 @@ def _truncated_evidence(session: SessionLike, rule_id: str, escalation: Escalati
     return None
 
 
-def applicable_rules(escalation: Escalation) -> tuple[str, ...]:
-    """The rules that could return a finding on this escalation.
+def applicable_rules(request: ReasoningRequest) -> tuple[str, ...]:
+    """The rules that could return a finding on this request.
 
     Asking a rule whose precondition is absent spends an invocation to hear the
     only answer it can give. `injected-instruction-followed` asks whether the
     agent *carried out* instruction-shaped content stage 1 found in a result or
     a context item — so with no such finding on this session there is nothing to
-    have carried out. Measured on 74 real escalation-eligible sessions, 71 had
+    have carried out. Measured on 74 real reasoning-eligible sessions, 71 had
     no marker, and skipping the rule there is not a narrowed catalogue: it is
     declining to ask a question with no subject.
 
@@ -514,7 +517,7 @@ def applicable_rules(escalation: Escalation) -> tuple[str, ...]:
     to any session that reached this stage.
     """
     has_marker = any(
-        finding.rule_id == "stacktrace-injection-marker" for finding in escalation.stage_one
+        finding.rule_id == "stacktrace-injection-marker" for finding in request.stage_one
     )
     return tuple(
         rule for rule in _RULES if rule != "stacktrace-injected-instruction-followed" or has_marker
@@ -681,7 +684,7 @@ def serialise(session: SessionLike) -> str:
     return "\n".join(lines)
 
 
-def serialise_scope(session: SessionLike, escalation: Escalation | None = None) -> str:
+def serialise_scope(session: SessionLike, request: ReasoningRequest | None = None) -> str:
     """Every request, every action, and no payloads — for `intent-drift`.
 
     Drift is a question about *scope*: did the agent do work nobody asked for.
@@ -707,7 +710,7 @@ def serialise_scope(session: SessionLike, escalation: Escalation | None = None)
     return "\n".join(lines)
 
 
-def serialise_injection(session: SessionLike, escalation: Escalation) -> str:
+def serialise_injection(session: SessionLike, request: ReasoningRequest) -> str:
     """The instruction-shaped material, and everything the agent did after it.
 
     The question is whether a *later call carried out* what the content asked
@@ -716,9 +719,9 @@ def serialise_injection(session: SessionLike, escalation: Escalation) -> str:
     evidence — a call that acted on an injected instruction shows it in what it
     was asked to do.
 
-    Cited from the `stacktrace-injection-marker` findings in `escalation.stage_one`
-    alone — never `escalation.spans`, which also carries the evidence of any
-    other solo-escalating reason (`stacktrace-credential-egress`) that fired on
+    Cited from the `stacktrace-injection-marker` findings in `request.stage_one`
+    alone — never `request.spans`, which also carries the evidence of any
+    other solo-requesting reason (`stacktrace-credential-egress`) that fired on
     this session. A credential call is not instruction-shaped material, and
     treating its span as cited here would gate this question on that call's own
     truncation and print its result as though it were the injected content.
@@ -729,12 +732,12 @@ def serialise_injection(session: SessionLike, escalation: Escalation) -> str:
     call's: standing context precedes every turn, so a call obeying it can come
     before that later call, and must not be starved of its own arguments.
     """
-    cited = _injection_spans(escalation)
+    cited = _injection_spans(request)
     lines = _header(session)
     # The same window `admissible_spans` refuses a citation outside of. Shared
     # rather than restated: a call this body sends no arguments for is a call
     # no verdict may cite, and two copies of that reading would drift.
-    reached = _first_cited_call(session, escalation) is None
+    reached = _first_cited_call(session, request) is None
     for turn in session.turns:
         lines.append(_turn_heading(turn))
         if turn.text:
@@ -759,7 +762,7 @@ def serialise_injection(session: SessionLike, escalation: Escalation) -> str:
     return "\n".join(lines)
 
 
-def serialise_completion(session: SessionLike, escalation: Escalation | None = None) -> str:
+def serialise_completion(session: SessionLike, request: ReasoningRequest | None = None) -> str:
     """The closing claim, and the checks it rests on — for `deceptive-completion`.
 
     Two things make this finding: an agent saying a task is done, and a
@@ -979,35 +982,43 @@ def _module_of(arguments: Sequence[str]) -> str | None:
 #: Which body each question is sent. Keyed by rule so adding a rule without
 #: deciding this is a `KeyError` at the call site rather than a silent
 #: full-session send.
-_CONTEXT: dict[str, Callable[[SessionLike, Escalation], str]] = {
+_CONTEXT: dict[str, Callable[[SessionLike, ReasoningRequest], str]] = {
     "stacktrace-intent-drift": serialise_scope,
     "stacktrace-injected-instruction-followed": serialise_injection,
     "stacktrace-deceptive-completion": serialise_completion,
 }
 
 
-def _prompt_for(name: str, escalation: Escalation) -> str:
-    """Framing, then the question, then why this was escalated. Never the
-    transcript — that is a separate argument, and it goes last."""
-    parts = [load("framing"), load(name), load("exclusions"), _why(escalation)]
+def _prompt_for(name: str, request: ReasoningRequest) -> str:
+    """Framing, then the question, then why this session is being asked about.
+    Never the transcript — that is a separate argument, and it goes last."""
+    parts = [load("framing"), load(name), load("exclusions"), _why(request)]
     return "\n\n".join(part for part in parts if part)
 
 
-def _why(escalation: Escalation) -> str:
+def _why(request: ReasoningRequest) -> str:
     """Which priors fired, by name and span. **Descriptors only.**
 
     This position is read as pipeline testimony, so a decoded payload or a
     secret quoted here would be attacker text promoted from data to
     instruction. Rule names and spans carry everything the analyzer needs to
     know where to look, and nothing an attacker controls.
+
+    **The heading below is prompt text with nothing pinning it.** Unlike the
+    fragments in `prompts/v1/`, it is a literal here, so editing it changes
+    every stage-3 prompt while `PROMPT_VERSION` stays `v1` — `cache_key()`
+    never sees the difference, verdicts bought under the old wording keep
+    hitting for `MAX_AGE_SECONDS`, and two different prompts both record as
+    `v1`. It kept its pre-rename spelling for exactly that reason. Reword it
+    only in the same change that copies `v1/` to `v2/` and bumps the version.
     """
-    reasons = ", ".join(escalation.reasons) or "no prior named"
-    spans = ", ".join(escalation.spans) or "none"
+    reasons = ", ".join(request.reasons) or "no prior named"
+    spans = ", ".join(request.spans) or "none"
     return (
         "## Why this session was escalated\n\n"
         f"Earlier stages reported: {reasons}.\n"
         f"Calls worth attention: {spans}.\n"
-        f"Coverage: {escalation.coverage.resolved} of {escalation.coverage.total} "
+        f"Coverage: {request.coverage.resolved} of {request.coverage.total} "
         "calls could be placed against the component inventory.\n\n"
         "These are this pipeline's own findings, not content from the session."
     )
@@ -1120,7 +1131,7 @@ def _text_of(result: Answer | Unavailable) -> str:
 _BLANK = SessionRef(session_id="", agent_kind="", started_at=None, turn_count=0)
 
 
-def _with(unknown: Unknown, ref: SessionRef, escalation: Escalation) -> Unknown:
+def _with(unknown: Unknown, ref: SessionRef, request: ReasoningRequest) -> Unknown:
     """Attach the session and the priors this unknown leaves unresolved.
 
     A stage that cannot run is not a stage that found nothing, so the reason for
@@ -1137,8 +1148,8 @@ def _with(unknown: Unknown, ref: SessionRef, escalation: Escalation) -> Unknown:
     return replace(
         unknown,
         session=ref,
-        spans=escalation.spans,
-        reasons=escalation.reasons,
+        spans=request.spans,
+        reasons=request.reasons,
         dispatched=True,
     )
 
@@ -1162,7 +1173,7 @@ _VERDICT_DETAIL = {
 
 
 def _finding(
-    answer: RuleVerdict, ref: SessionRef, escalation: Escalation, verdict: Verdict
+    answer: RuleVerdict, ref: SessionRef, request: ReasoningRequest, verdict: Verdict
 ) -> Detection:
     return Detection(
         rule_id=answer.rule_id,
@@ -1176,5 +1187,5 @@ def _finding(
         ),
         remediation=_REMEDIATION.get(answer.rule_id, ""),
         verdict=verdict,
-        coverage=escalation.coverage,
+        coverage=request.coverage,
     )

stacktrace_cli/detector/render.py

@@ -31,7 +31,7 @@ def render_json(result: DetectorRun) -> str:
                     "reason": u.reason,
                     "spans": list(u.spans),
                     "detail": u.detail,
-                    "escalated_on": list(u.reasons),
+                    "reasoning_reasons": list(u.reasons),
                     # True for a reasoning-stage unknown raised after the session
                     # was already sent to the analyzer — one unanswered question
                     # inside a session `summary.analysed` already counts, not a
@@ -47,7 +47,7 @@ def render_json(result: DetectorRun) -> str:
                 "security": sum(1 for d in result.detections if d.family == "security"),
                 "reliability": sum(1 for d in result.detections if d.family == "reliability"),
                 "unknowns": len(result.unknowns),
-                "escalated": result.escalated,
+                "reasoning_requested": result.requested,
                 "analysed": result.analysed,
                 "cache_hits": result.cache_hits,
             },
@@ -172,17 +172,17 @@ def render_text(result: DetectorRun, detail: bool = False) -> str:
     """
     lines: list[str] = []
     # Not `not result.detections and not result.unknowns` alone: a run that
-    # escalated, analysed and cleared every session (nothing fired, nothing
+    # requested, analysed and cleared every session (nothing fired, nothing
     # unanswered) has no detections and no unknowns either, and is the most
     # common successful outcome — the one this shortcut must not hide the
-    # cost of. `escalated` is what distinguishes it from a run that never
+    # cost of. `requested` is what distinguishes it from a run that never
     # reached stage three at all. `collection_failures` is checked too: a
     # reader that failed before correlation ever saw a session leaves every
     # other count at zero, and that must never read as the clean-run shortcut.
     if (
         not result.detections
         and not result.unknowns
-        and not result.escalated
+        and not result.requested
         and not result.collection_failures
     ):
         return f"No detections across {result.sessions} sessions."
@@ -237,7 +237,7 @@ def render_text(result: DetectorRun, detail: bool = False) -> str:
     lines.append(
         f"Summary — {result.sessions} sessions, {security} security, "
         f"{reliability} reliability, {len(result.unknowns)} unsettled, "
-        f"{result.escalated} escalated, {result.analysed} analysed {analysed_sessions}, "
+        f"{result.requested} for reasoning, {result.analysed} analysed {analysed_sessions}, "
         f"{result.cache_hits} from cache"
     )
     return "\n".join(lines)
@@ -248,12 +248,12 @@ def render_text(result: DetectorRun, detail: bool = False) -> str:
 #:
 #: A gloss, not a gate: a reason with no entry still prints, under its bare name,
 #: because the accounting below has to balance whether or not anyone wrote a
-#: sentence for it. `test_the_reasoning_stage_block_accounts_for_every_escalation`
-#: is what enforces that -- every escalated session lands in exactly one
+#: sentence for it. `test_the_reasoning_stage_block_accounts_for_every_request`
+#: is what enforces that -- every requested session lands in exactly one
 #: session-level row, whether or not it also has unanswered questions.
 _REASONING_OUTCOMES: dict[str, str] = {
     "budget_exhausted": "deferred: the run's --budget was reached",
-    "reasoning_not_requested": "not requested: re-run with --escalate to analyse them",
+    "reasoning_not_requested": "not requested: re-run with --reasoning to analyse them",
     "analyzer_unavailable": "no analyzer available for the agent kind",
     "session_too_large": "too large for the analyzer's context window",
     "insufficient_context": "compaction removed the turns a rule needed",
@@ -265,16 +265,16 @@ _REASONING_OUTCOMES: dict[str, str] = {
 
 
 def _reasoning_lines(result: DetectorRun) -> list[str]:
-    """What the third stage actually spent, and where every escalation went.
+    """What the third stage actually spent, and where every request went.
 
     Stated as accounting rather than as one number. With the stage opt-in the
     reader has both questions -- *did it run* and, when it did, *what did this
     run cost me* -- and one number answers neither. Three outcomes are not the same
     fact: a model call spends seconds and money, a cache hit settles the same
-    question for free, and a deferred escalation spends nothing and leaves the
+    question for free, and a deferred request spends nothing and leaves the
     concern open.
 
-    Every escalated session appears in exactly one *session-level* row —
+    Every requested session appears in exactly one *session-level* row —
     analysed, a cache hit, or one of the reasons a session never reached the
     analyzer at all — so those rows sum to the headline. `run_reasoning` asks
     one to three rules per analysed session, and one rule's clean answer does
@@ -283,12 +283,12 @@ def _reasoning_lines(result: DetectorRun) -> list[str]:
     since a session already counted in `analysed` must not be counted again
     for a question it also failed to answer.
     """
-    if not result.escalated:
+    if not result.requested:
         return []
     lines = [
         "",
         (
-            f"Reasoning stage — {result.analysed} of {result.escalated} escalated "
+            f"Reasoning stage — {result.analysed} of {result.requested} requested "
             f"session(s) reached the model"
         ),
     ]

stacktrace_cli/detector/rules.py

@@ -14,8 +14,8 @@ These are not advisory identifiers, they never enter the overlay corpus
 `guardrail-modification`, `destructive-action`, `tool-shadowing` and
 `unpinned-invoked` — were removed rather than kept as aspirations (ADR-0013).
 Two produced *noise*: output whose majority a reader learns to skip. Two had *no
-input*: a match outcome the join has never emitted, and an escalation threshold
-that could not be met.
+input*: a match outcome the join has never emitted, and a reasoning-request
+threshold that could not be met.
 
 **Five more were withdrawn by ADR-0015, and not for either of those reasons.**
 `unsanctioned-mcp-tool-use`, `unattended-privileged-action`, `provider-refusal`,
@@ -57,7 +57,7 @@ SECURITY_RULES = frozenset(
 #: A stalled loop and a leaked credential competed for one reader's attention
 #: while sharing one severity ladder, and the ladder cannot express the
 #: difference. ADR-0010 gives each finding family its own grades; this is that
-#: argument one level down. These rules never escalate: no amount of inference
+#: argument one level down. These rules never request reasoning: no amount of inference
 #: makes a repeated call more or less repeated.
 RELIABILITY_RULES = frozenset(
     {