stacktrace-cli 0.19.0__py3-none-any.whl → 0.20.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. stacktrace/__init__.py +16 -2
  2. stacktrace/__main__.py +19 -3
  3. stacktrace/cloud/boot.py +160 -21
  4. stacktrace/correlate/observed.py +1 -1
  5. stacktrace/daemon/activity_log.py +2 -1
  6. stacktrace/daemon/costs.py +22 -6
  7. stacktrace/daemon/frame_limits.py +11 -0
  8. stacktrace/daemon/inline_hook.py +65 -6
  9. stacktrace/daemon/paths.py +7 -2
  10. stacktrace/daemon/policy_collect.py +10 -2
  11. stacktrace/daemon/policy_result.py +38 -0
  12. stacktrace/daemon/policy_runtime.py +63 -33
  13. stacktrace/daemon/protocol.py +2 -5
  14. stacktrace/daemon/runtime.py +3 -2
  15. stacktrace/daemon/unreadable.py +101 -0
  16. stacktrace/daemon/usage.py +10 -1
  17. stacktrace/detector/deterministic.py +1870 -178
  18. stacktrace/detector/guard_files.py +115 -0
  19. stacktrace/detector/inline.py +20 -1
  20. stacktrace/detector/rules.py +70 -4
  21. stacktrace/detector/run.py +2 -2
  22. stacktrace/detector/secret_paths.py +206 -0
  23. stacktrace/detector/secret_refs.py +231 -0
  24. stacktrace/detector/wipers.py +494 -0
  25. stacktrace/finding_titles.py +8 -1
  26. stacktrace/hooks/admit.py +102 -0
  27. stacktrace/hooks/claude.py +63 -10
  28. stacktrace/hooks/codex.py +10 -13
  29. stacktrace/hooks/cursor.py +10 -13
  30. stacktrace/hooks/devin.py +10 -13
  31. stacktrace/hooks/session.py +60 -9
  32. stacktrace/monitor/site/app.js +2 -0
  33. stacktrace/policy_display.py +5 -1
  34. stacktrace/remote/cli.py +4 -0
  35. stacktrace/remote/hook_policy.py +8 -12
  36. stacktrace/remote/policy_service.py +27 -0
  37. stacktrace/sessions/outcome.py +19 -0
  38. stacktrace/sessions/toolclass.py +13 -0
  39. {stacktrace_cli-0.19.0.dist-info → stacktrace_cli-0.20.0.dist-info}/METADATA +4 -4
  40. {stacktrace_cli-0.19.0.dist-info → stacktrace_cli-0.20.0.dist-info}/RECORD +42 -33
  41. {stacktrace_cli-0.19.0.dist-info → stacktrace_cli-0.20.0.dist-info}/WHEEL +0 -0
  42. {stacktrace_cli-0.19.0.dist-info → stacktrace_cli-0.20.0.dist-info}/entry_points.txt +0 -0
stacktrace/__init__.py CHANGED
@@ -1,14 +1,28 @@
1
1
  """The `stacktrace` command-line interface — detection and response for AI agents."""
2
2
 
3
3
  import logging as _logging
4
+ from typing import TYPE_CHECKING
4
5
 
5
- __version__ = "0.19.0"
6
+ __version__ = "0.20.0"
6
7
 
7
8
  # Only the daemon attaches a handler (ADR-0048). Without this one, a WARNING
8
9
  # logged in any other process would reach Python's last-resort handler and
9
10
  # print onto the user's terminal.
10
11
  _logging.getLogger(__name__).addHandler(_logging.NullHandler())
11
12
 
12
- from stacktrace.sdk import ObservationClient
13
+ if TYPE_CHECKING:
14
+ from stacktrace.sdk import ObservationClient
15
+
16
+
17
+ def __getattr__(name: str) -> object:
18
+ # Loaded on first use: the SDK imports httpx and pydantic, and every
19
+ # `stacktrace` process imports this package, the per-call hook included
20
+ # (ADR-0194).
21
+ if name == "ObservationClient":
22
+ from stacktrace.sdk import ObservationClient
23
+
24
+ return ObservationClient
25
+ raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
26
+
13
27
 
14
28
  __all__ = ["ObservationClient", "__version__"]
stacktrace/__main__.py CHANGED
@@ -1,12 +1,28 @@
1
1
  """Entry point shared by the ``stacktrace`` command and ``python -m stacktrace``.
2
2
 
3
- The distribution's console script resolves to the Click group in
4
- ``stacktrace.cli`` through this module.
3
+ The distribution's console script resolves to ``main`` here. It answers the
4
+ per-call hook command, ``remote policy hooks admit``, before the command line
5
+ loads (ADR-0194), and hands every other command to the Click group in
6
+ ``stacktrace.cli``.
5
7
  """
6
8
 
7
9
  from __future__ import annotations
8
10
 
9
- from .cli import main
11
+ import os
12
+ import sys
13
+
14
+
15
+ def main() -> None:
16
+ from stacktrace.hooks.admit import fast_kind, run_standalone
17
+
18
+ kind = fast_kind(sys.argv[1:], os.environ)
19
+ if kind is not None:
20
+ run_standalone(kind)
21
+ return
22
+ from stacktrace.cli import main as cli_main
23
+
24
+ cli_main()
25
+
10
26
 
11
27
  __all__ = ["main"]
12
28
 
stacktrace/cloud/boot.py CHANGED
@@ -6,18 +6,28 @@ One worker at a time holds `boot.lock`, from its own `daemon status` check
6
6
  until the daemon it starts answers. So a worker never replaces the client's
7
7
  files while a daemon runs or is starting: a second hook's worker waits, checks
8
8
  again, and finds the daemon up.
9
+
10
+ Each failure, and each daemon this worker had to start, is one line in
11
+ `session-start.log` (docs/specs/plugin-installation.md, "Session-start log").
12
+ The SessionStart adapters write their own failures through `write_log` here.
9
13
  """
10
14
 
11
15
  import fcntl
16
+ import json
12
17
  import os
13
18
  import pwd
19
+ import re
14
20
  import shlex
21
+ import stat
15
22
  import subprocess
16
23
  import sys
17
24
  import time
25
+ from contextlib import contextmanager
18
26
  from datetime import datetime, timezone
19
27
 
20
28
  STATE, UPDATE_ENV = "", ""
29
+ #: The session's agent kind, from the scope argument, or `-` when there is none.
30
+ KIND = "-"
21
31
  #: How long an update may take before the installed client runs instead.
22
32
  UPDATE_SECONDS = 120
23
33
  #: How long the lock waits for the daemon this worker started to answer.
@@ -26,6 +36,113 @@ START_SECONDS = 30
26
36
  #: transition lock while it uploads to Fleet, and refuses until it finishes.
27
37
  REGISTER_ATTEMPTS = 10
28
38
 
39
+ LOG_NAME = "session-start.log"
40
+ #: Past this size the log keeps only its last `LOG_LINES` lines.
41
+ LOG_BYTES = 64 * 1024
42
+ LOG_LINES = 500
43
+ #: An agent kind's shape. The kinds themselves are not listed: a new one needs no change here.
44
+ KIND_SHAPE = re.compile(r"[a-z][a-z0-9-]{0,31}")
45
+ STAGES = (
46
+ "input",
47
+ "scope",
48
+ "launch",
49
+ "lock",
50
+ "update",
51
+ "daemon-start",
52
+ "daemon-started",
53
+ "register",
54
+ "bootstrap",
55
+ )
56
+ #: A fixed word or an exception's type name. Never a message, a path or a value.
57
+ DETAIL = re.compile(r"[A-Za-z][A-Za-z0-9_.-]{0,63}")
58
+
59
+
60
+ def log_root():
61
+ """`state_root()` from `stacktrace.private_state`. Setup copies this file to
62
+ run on system Python, where the package need not import."""
63
+ default = os.path.join(os.path.expanduser("~"), ".local", "state", "stacktrace")
64
+ return os.environ.get("STACKTRACE_STATE_DIR", default)
65
+
66
+
67
+ def write_log(path, agent_kind, stage, detail):
68
+ """Append one line to the session-start log and trim it; never raise.
69
+
70
+ The writer accepts only a name-shaped kind, a known stage and a word-shaped detail, so
71
+ a call site that passes anything else writes `-` rather than the text."""
72
+ try:
73
+ if stage not in STAGES:
74
+ return
75
+ kind = (
76
+ agent_kind if isinstance(agent_kind, str) and KIND_SHAPE.fullmatch(agent_kind) else "-"
77
+ )
78
+ detail = detail if isinstance(detail, str) and DETAIL.fullmatch(detail) else "-"
79
+ line = f"{datetime.now(timezone.utc):%Y-%m-%dT%H:%M:%SZ} {kind} cli {stage} {detail}\n" # noqa: UP017 - legacy wrapper uses system Python, including 3.10
80
+ descriptor = os.open(path, os.O_RDWR | os.O_APPEND | os.O_CREAT | os.O_NOFOLLOW, 0o600)
81
+ except Exception: # noqa: BLE001 - logging never fails the session
82
+ return
83
+ try:
84
+ # Bounded wait: a writer holds the lock for one append and trim.
85
+ for _ in range(20):
86
+ try:
87
+ fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
88
+ break
89
+ except BlockingIOError:
90
+ time.sleep(0.01)
91
+ else:
92
+ return
93
+ os.write(descriptor, line.encode("utf-8"))
94
+ size = os.fstat(descriptor).st_size
95
+ if size > LOG_BYTES:
96
+ kept = os.pread(descriptor, size, 0).splitlines(keepends=True)[-LOG_LINES:]
97
+ os.ftruncate(descriptor, 0)
98
+ os.write(descriptor, b"".join(kept))
99
+ except Exception: # noqa: BLE001, S110 - logging never fails the session
100
+ pass
101
+ finally:
102
+ os.close(descriptor)
103
+
104
+
105
+ def _private_directory(path):
106
+ """`ensure_private_directory` from `stacktrace.private_state`, for the same reason."""
107
+ os.makedirs(path, mode=0o700, exist_ok=True)
108
+ metadata = os.lstat(path)
109
+ if not stat.S_ISDIR(metadata.st_mode) or metadata.st_uid != os.getuid():
110
+ raise OSError("state directory is not a user-owned directory")
111
+ if stat.S_IMODE(metadata.st_mode) != 0o700:
112
+ os.chmod(path, 0o700)
113
+
114
+
115
+ def log(stage, detail):
116
+ """One line for this worker's session; never raise."""
117
+ try:
118
+ root = log_root()
119
+ _private_directory(root)
120
+ write_log(os.path.join(root, LOG_NAME), KIND, stage, detail)
121
+ except Exception: # noqa: BLE001, S110 - logging never fails the session
122
+ pass
123
+
124
+
125
+ @contextmanager
126
+ def stage(name):
127
+ """Log a failure inside this block by its type, once, and let it propagate."""
128
+ try:
129
+ yield
130
+ except Exception as error:
131
+ if not getattr(error, "session_start_logged", False):
132
+ setattr(error, "session_start_logged", True) # noqa: B010 - any exception type
133
+ log(name, type(error).__name__)
134
+ raise
135
+
136
+
137
+ def kind_of(arguments):
138
+ """The agent kind the scope argument names, else `-`."""
139
+ try:
140
+ scope = json.loads(arguments[0])
141
+ kind = scope.get("agent_kind") if isinstance(scope, dict) else None
142
+ except Exception: # noqa: BLE001 - registration reports a bad scope
143
+ return "-"
144
+ return kind if isinstance(kind, str) and KIND_SHAPE.fullmatch(kind) else "-"
145
+
29
146
 
30
147
  def note(text):
31
148
  with open(os.path.join(STATE, "update.log"), "a", encoding="utf-8") as log:
@@ -82,21 +199,26 @@ def update():
82
199
  f"not updating: {user} cannot run uv or write the install; "
83
200
  "rebuild the environment to update the client"
84
201
  )
202
+ log("update", "not-permitted")
85
203
  return
86
204
  environment = {**os.environ, **{k: v for k, v in values.items() if k.startswith("UV_")}}
87
- with open(os.path.join(STATE, "update.log"), "a", encoding="utf-8") as log:
205
+ with open(os.path.join(STATE, "update.log"), "a", encoding="utf-8") as output:
88
206
  try:
89
- subprocess.run(
207
+ result = subprocess.run(
90
208
  [uv, "tool", "upgrade", "stacktrace-cli"],
91
209
  env=environment,
92
210
  stdin=subprocess.DEVNULL,
93
- stdout=log,
211
+ stdout=output,
94
212
  stderr=subprocess.STDOUT,
95
213
  timeout=UPDATE_SECONDS,
96
214
  check=False,
97
215
  )
98
216
  except (OSError, subprocess.SubprocessError) as error:
99
217
  note(f"update stopped: {type(error).__name__}; the installed client runs")
218
+ log("update", type(error).__name__)
219
+ return
220
+ if result.returncode:
221
+ log("update", "nonzero-exit")
100
222
 
101
223
 
102
224
  def configure():
@@ -135,9 +257,11 @@ def configure():
135
257
 
136
258
 
137
259
  def ensure_daemon():
138
- lock = os.open(os.path.join(STATE, "boot.lock"), os.O_CREAT | os.O_RDWR, 0o600)
260
+ with stage("lock"):
261
+ lock = os.open(os.path.join(STATE, "boot.lock"), os.O_CREAT | os.O_RDWR, 0o600)
139
262
  try:
140
- fcntl.flock(lock, fcntl.LOCK_EX)
263
+ with stage("lock"):
264
+ fcntl.flock(lock, fcntl.LOCK_EX)
141
265
  configure()
142
266
  _ensure_daemon()
143
267
  finally:
@@ -153,10 +277,12 @@ def _ensure_daemon():
153
277
  # answer says nothing. Either may be a live client.
154
278
  if answer == "no":
155
279
  if os.environ.get("CLAUDE_CODE_REMOTE") == "true":
156
- update()
280
+ with stage("update"):
281
+ update()
157
282
  else:
158
283
  note(f"not updating: daemon status said {answer or 'nothing'}, not that no daemon runs")
159
- with open(os.path.join(STATE, "daemon.log"), "a", encoding="utf-8") as out:
284
+ daemon_log = os.path.join(STATE, "daemon.log")
285
+ with stage("daemon-start"), open(daemon_log, "a", encoding="utf-8") as out:
160
286
  subprocess.Popen(
161
287
  ["stacktrace", "daemon", "start", "--no-reasoning"],
162
288
  stdin=subprocess.DEVNULL,
@@ -165,33 +291,46 @@ def _ensure_daemon():
165
291
  start_new_session=True,
166
292
  )
167
293
  deadline = time.monotonic() + START_SECONDS
168
- while time.monotonic() < deadline and running() != "yes":
294
+ while time.monotonic() < deadline:
295
+ if running() == "yes":
296
+ log(
297
+ "daemon-started",
298
+ "was-stopped"
299
+ if answer == "no"
300
+ else "was-unresponsive"
301
+ if answer == "unresponsive"
302
+ else "no-status",
303
+ )
304
+ return
169
305
  time.sleep(0.5)
306
+ log("daemon-start", "timeout")
170
307
 
171
308
 
172
309
  def main():
310
+ global KIND
311
+ KIND = kind_of(sys.argv[3:4])
173
312
  os.makedirs(STATE, mode=0o700, exist_ok=True)
174
313
  os.chmod(STATE, 0o700)
175
314
  ensure_daemon()
176
315
  if len(sys.argv) > 3:
177
- import json
178
-
179
- from stacktrace.hooks.session import register
316
+ with stage("register"):
317
+ from stacktrace.hooks.session import register
180
318
 
181
- scope = json.loads(sys.argv[3])
182
- for attempt in range(REGISTER_ATTEMPTS):
183
- try:
184
- register(scope)
185
- return
186
- except Exception: # a busy daemon refuses or times out alike
187
- if attempt == REGISTER_ATTEMPTS - 1:
188
- raise
189
- time.sleep(1)
319
+ scope = json.loads(sys.argv[3])
320
+ for attempt in range(REGISTER_ATTEMPTS):
321
+ try:
322
+ register(scope)
323
+ return
324
+ except Exception: # a busy daemon refuses or times out alike
325
+ if attempt == REGISTER_ATTEMPTS - 1:
326
+ raise
327
+ time.sleep(1)
190
328
 
191
329
 
192
330
  if __name__ == "__main__":
193
331
  STATE, UPDATE_ENV = sys.argv[1], sys.argv[2]
194
332
  try:
195
- main()
333
+ with stage("bootstrap"):
334
+ main()
196
335
  except Exception: # noqa: BLE001 - never expose native payloads or credentials
197
336
  note("session bootstrap failed; inspect daemon status and rerun setup")
@@ -1594,7 +1594,7 @@ def command_segments_with_ops(
1594
1594
  that preceded it (``None`` for the first segment, then ``&&``, ``||``,
1595
1595
  ``;``, ``|`` or ``\\n``).
1596
1596
 
1597
- Only `_resolve_rm_targets` in the deterministic detector needs the operator
1597
+ Only `_resolve_wipes` in the deterministic detector needs the operator
1598
1598
  context — to decide whether an inline ``cd`` reliably changed the directory
1599
1599
  and whether an ``rm`` segment is unconditionally reachable. Every other
1600
1600
  caller uses the plain `command_segments`, which discards the operator.
@@ -6,7 +6,8 @@ else the package's `NullHandler` keeps those lines off the terminal.
6
6
 
7
7
  A line names kinds, counts, class names and event ids. It never carries a
8
8
  finding's title or body, an exception message, or anything from a transcript,
9
- and a peer-supplied session id is written with `%r`.
9
+ and a peer-supplied session id is written with `%r`. The one exception is a
10
+ reader's failure text, written only through `unreadable.describe` (ADR-0191).
10
11
  """
11
12
 
12
13
  from __future__ import annotations
@@ -55,8 +55,10 @@ from stacktrace.cost.rules import (
55
55
  to_detection,
56
56
  )
57
57
  from stacktrace.cost.runs import Run, runs_of
58
+ from stacktrace.daemon.jobs import Backoff
58
59
  from stacktrace.daemon.observer import Collected
59
60
  from stacktrace.daemon.store import FindingStore, Notification, SessionKey
61
+ from stacktrace.daemon.unreadable import OncePerChange, describe
60
62
  from stacktrace.detector.deterministic import run_deterministic
61
63
  from stacktrace.detector.render import detection_json
62
64
  from stacktrace.detector.rules import COST_RULES, RELIABILITY_RULES
@@ -558,6 +560,14 @@ class CostPass:
558
560
  #: warm-up that failed or could not reach every session must retry on
559
561
  #: a later tick rather than being read as its one chance.
560
562
  self._warmed = False
563
+ #: When a warm-up that failed may read again: 15 s on, doubling,
564
+ #: never past an hour (cost-phase-1 §3). A source that stays
565
+ #: unreadable, such as a Devin store newer than its reader, otherwise
566
+ #: had 36 hours re-read on every tick for as long as the daemon ran.
567
+ self._warm_retries = Backoff(ceiling=3600.0, first=15.0)
568
+ self._warm_after: datetime | None = None
569
+ #: The same failures are logged once, and again when they change.
570
+ self._unreadable = OncePerChange()
561
571
  #: The earliest write this pass was handed for each run, main session
562
572
  #: and sub-agents alike, by main session: where a finding's clock may
563
573
  #: start.
@@ -592,7 +602,7 @@ class CostPass:
592
602
  # Every kind's sessions and every member of a run, sub-agents
593
603
  # included: the scanner reads them all (ADR-0107).
594
604
  changed = [session for item in collected for session in item.view.sessions]
595
- if not self._warmed:
605
+ if not self._warmed and (self._warm_after is None or now >= self._warm_after):
596
606
  changed.extend(self._warm(now, {_key(s) for s in changed}))
597
607
  self._written = {}
598
608
  for item in collected:
@@ -719,17 +729,23 @@ class CostPass:
719
729
  """Every session active in the last 36 hours that the scanner did not
720
730
  hand over, read cold after a start: the scanner resumes from its
721
731
  watermark, so a run quiet since then would otherwise be judged short of
722
- its members, whichever of them resumed it (cost-phase-1 §3). Retried on
723
- a later tick when the read raised or could not reach every session, so
724
- a transient failure does not cost a run's members their one chance at
725
- being backfilled."""
732
+ its members, whichever of them resumed it (cost-phase-1 §3). Retried
733
+ 15 s later when the read raised or could not reach every session, the
734
+ wait doubling to an hour, so a transient failure does not cost a run's
735
+ members their one chance at being backfilled, and a source that never
736
+ becomes readable is not read again on every tick."""
726
737
  try:
727
738
  view = self._cold_read(now - _WARM_WINDOW)
728
739
  except Exception as error: # noqa: BLE001 - a failed warm-up is not the pass
729
740
  logger.debug("cost: could not read the last 36 hours: %s", error)
741
+ self._warm_after = now + timedelta(seconds=self._warm_retries.next())
730
742
  return []
731
743
  if view.unavailable:
732
- logger.debug("cost: some sessions could not be read: %s", view.unavailable[0])
744
+ self._warm_after = now + timedelta(seconds=self._warm_retries.next())
745
+ if self._unreadable.due(view.unavailable):
746
+ logger.debug(
747
+ "cost: some sessions could not be read: %s", describe(view.unavailable)
748
+ )
733
749
  return [session for session in view.sessions if _key(session) not in have]
734
750
  self._warmed = True
735
751
  return [session for session in view.sessions if _key(session) not in have]
@@ -0,0 +1,11 @@
1
+ """The wire version and the frame limits that the per-call hook reads.
2
+
3
+ `protocol.py` imports the store, and the store costs the hook about 0.8 s, so
4
+ these three live here and `protocol.py` imports them (ADR-0194).
5
+ """
6
+
7
+ VERSION = 1
8
+ MAX_FRAME_BYTES = 64 * 1024
9
+ #: An `authorize` request that carries a built-in call's input (ADR-0158). Only
10
+ #: that request may be this large; every other incoming frame keeps the usual limit.
11
+ MAX_CALL_FRAME_BYTES = 2 * 1024 * 1024
@@ -44,6 +44,7 @@ from pathlib import Path
44
44
  from typing import TYPE_CHECKING
45
45
 
46
46
  from stacktrace import __version__
47
+ from stacktrace.correlate.observed import declares_remote_transport
47
48
  from stacktrace.daemon.policy_runtime import sub_agent_session
48
49
  from stacktrace.daemon.store import marker_from_json, marker_json
49
50
  from stacktrace.detector.finding import Detection
@@ -68,6 +69,12 @@ if TYPE_CHECKING:
68
69
 
69
70
  logger = logging.getLogger(__name__)
70
71
 
72
+ #: The name a pending MCP call is read under when its hook sent no tool name
73
+ #: (ADR-0195). Its server and transport are set on the read call directly, so
74
+ #: the name only marks it as an MCP call.
75
+ _PENDING_MCP_TOOL = "mcp__stacktrace_pending__call"
76
+ #: The keys every pending call carries.
77
+ _CALL_KEYS = frozenset({"tool_use_id", "cwd", "tool_input"})
71
78
  #: Claude Code's session ids are UUIDs. Anything else is refused rather than
72
79
  #: kept, because the id names the finding's session and a `:` would forge one.
73
80
  _SESSION_ID = re.compile(r"[A-Za-z0-9-]{1,128}")
@@ -92,6 +99,12 @@ class PendingCall:
92
99
  tool_use_id: str
93
100
  cwd: str
94
101
  tool_input: Mapping[str, object]
102
+ #: For an MCP call, the server Claude Code named, if any (ADR-0202), and
103
+ #: the remote transport its configuration names, if any (ADR-0195). The
104
+ #: transport is declared, never observed, so it is never written into the
105
+ #: call (ADR-0134).
106
+ mcp_server: str | None = None
107
+ declared_transport: str | None = None
95
108
 
96
109
 
97
110
  def pending_call(action: Mapping[str, object]) -> PendingCall:
@@ -108,7 +121,10 @@ def pending_call(action: Mapping[str, object]) -> PendingCall:
108
121
  # costs only attribution, where refusing the call would cost the block.
109
122
  if not isinstance(agent_id, str) or not _AGENT_ID.fullmatch(agent_id):
110
123
  agent_id = None
111
- if not isinstance(call, dict) or set(call) != {"tool_use_id", "cwd", "tool_input"}: # pyright: ignore[reportUnknownArgumentType]
124
+ mcp = action.get("action_kind") == "mcp_tool"
125
+ # An MCP call may name its tool (ADR-0202); a hook from ADR-0195 does not.
126
+ allowed = _CALL_KEYS | ({"tool_name"} if mcp else set())
127
+ if not isinstance(call, dict) or not _CALL_KEYS <= set(call) <= allowed: # pyright: ignore[reportUnknownArgumentType]
112
128
  raise ValueError("invalid_call")
113
129
  tool_use_id, cwd, tool_input = call["tool_use_id"], call["cwd"], call["tool_input"]
114
130
  if not isinstance(tool_use_id, str) or not _TOOL_USE_ID.fullmatch(tool_use_id):
@@ -117,7 +133,31 @@ def pending_call(action: Mapping[str, object]) -> PendingCall:
117
133
  raise ValueError("invalid_call")
118
134
  if not isinstance(tool_input, dict):
119
135
  raise ValueError("invalid_call") # noqa: TRY004 - one refusal type, read by its caller
120
- if (
136
+ server, transport = None, None
137
+ if mcp:
138
+ # Judged whatever the server (ADR-0202). A transport is passed only
139
+ # for a server configured as remote, and adds egress (ADR-0195).
140
+ given = action.get("transport")
141
+ if given is not None and (
142
+ not isinstance(given, str) or not declares_remote_transport(given)
143
+ ):
144
+ raise ValueError("uninspected_tool")
145
+ transport = given
146
+ named = call.get("tool_name", _PENDING_MCP_TOOL) # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
147
+ if (
148
+ not isinstance(named, str)
149
+ or not named.startswith("mcp__")
150
+ or len(named) > 4096
151
+ or "\x00" in named
152
+ ):
153
+ raise ValueError("invalid_call")
154
+ if not isinstance(agent_kind, str) or not isinstance(tool, str):
155
+ raise ValueError("uninspected_tool")
156
+ # The selector names the server when Claude Code named one; with an
157
+ # empty source it is the tool's name, and the tool's name says it.
158
+ server = tool if action.get("source") else None
159
+ tool = named
160
+ elif (
121
161
  not isinstance(agent_kind, str)
122
162
  or not isinstance(tool, str)
123
163
  or not inspected(agent_kind, tool)
@@ -132,6 +172,8 @@ def pending_call(action: Mapping[str, object]) -> PendingCall:
132
172
  tool_use_id=tool_use_id,
133
173
  cwd=cwd,
134
174
  tool_input={str(k): v for k, v in tool_input.items()}, # pyright: ignore[reportUnknownVariableType]
175
+ mcp_server=server,
176
+ declared_transport=transport,
135
177
  )
136
178
 
137
179
 
@@ -270,14 +312,27 @@ def judge(call: PendingCall, rules: frozenset[str]) -> tuple[Detection, ...]:
270
312
  replace(
271
313
  t,
272
314
  tool_calls=tuple(
273
- replace(c, span=span, working_directory=call.cwd) if c.span in pending else c
315
+ (
316
+ replace(c, span=span, working_directory=call.cwd)
317
+ if call.mcp_server is None
318
+ else replace(
319
+ c, span=span, working_directory=call.cwd, mcp_server=call.mcp_server
320
+ )
321
+ )
322
+ if c.span in pending
323
+ else c
274
324
  for c in t.tool_calls
275
325
  ),
276
326
  )
277
327
  for t in turn.session.turns
278
328
  ),
279
329
  )
280
- return judge_pending(session, frozenset({span}) if pending else frozenset(), rules)
330
+ return judge_pending(
331
+ session,
332
+ frozenset({span}) if pending else frozenset(),
333
+ rules,
334
+ declared_transport=call.declared_transport,
335
+ )
281
336
 
282
337
 
283
338
  def inspect_call(action: dict[str, object], rules: frozenset[str]) -> tuple[Detection, ...]:
@@ -410,6 +465,8 @@ def _write_spool(path: Path, markers: Sequence[Marker]) -> None:
410
465
 
411
466
  def block_marker(
412
467
  keep: Callable[[Marker], None],
468
+ *,
469
+ clock: Callable[[], datetime] = lambda: datetime.now(UTC),
413
470
  ) -> Callable[[dict[str, object], Detection, DetectionEntry, int], None]:
414
471
  """Keep the marker of a detection block of a tool call or a prompt. Write
415
472
  no finding (ADR-0178).
@@ -448,7 +505,7 @@ def block_marker(
448
505
  outcome="blocked",
449
506
  where="hook",
450
507
  rules_version=__version__,
451
- blocked_at=datetime.now(UTC),
508
+ blocked_at=clock(),
452
509
  )
453
510
  )
454
511
 
@@ -457,6 +514,8 @@ def block_marker(
457
514
 
458
515
  def component_denial_recorder(
459
516
  keep: Callable[[Marker], object],
517
+ *,
518
+ clock: Callable[[], datetime] = lambda: datetime.now(UTC),
460
519
  ) -> Callable[[dict[str, object], str, PolicyEntry | None, int, Entry | None], None]:
461
520
  """Keep a component deny's marker. Write no finding (ADR-0184).
462
521
 
@@ -526,7 +585,7 @@ def component_denial_recorder(
526
585
  gate_evidence=gate_evidence(
527
586
  rule_id, resolved.evidence if resolved is not None else ()
528
587
  ),
529
- blocked_at=datetime.now(UTC),
588
+ blocked_at=clock(),
530
589
  )
531
590
  )
532
591
 
@@ -3,7 +3,6 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import os
6
- import tempfile
7
6
  from collections.abc import Mapping
8
7
  from dataclasses import dataclass
9
8
  from pathlib import Path
@@ -29,7 +28,13 @@ class RuntimePaths:
29
28
  environ = os.environ if environment is None else environment
30
29
  state_root = private_state_root(environ)
31
30
  user_key = str(os.getuid()) if hasattr(os, "getuid") else str(os.getpid())
32
- runtime_root = Path("/tmp") if os.name == "posix" else Path(tempfile.gettempdir())
31
+ if os.name == "posix":
32
+ runtime_root = Path("/tmp")
33
+ else:
34
+ # Imported here: the per-call hook reads these paths (ADR-0194).
35
+ import tempfile
36
+
37
+ runtime_root = Path(tempfile.gettempdir())
33
38
  short_runtime = runtime_root / f"stacktrace-{user_key}"
34
39
  return cls(
35
40
  socket=Path(environ.get("STACKTRACE_DAEMON_SOCKET", short_runtime / "daemon-v1.sock")),
@@ -143,6 +143,12 @@ def evaluate_bundle(
143
143
  if blocked
144
144
  else {}
145
145
  )
146
+ if component_type == "mcp_server":
147
+ # The egress rules judge a call's input only for a server whose
148
+ # configuration names a remote transport (ADR-0195).
149
+ transport = ref.extra.get("transport")
150
+ if isinstance(transport, str) and 0 < len(transport) <= 64:
151
+ found["transport"] = transport
146
152
  if scope.agent_kind == "codex":
147
153
  entries.extend(
148
154
  (Entry("mcp_tool", namespace, "codex", blocked, rule, detail, **found), 0)
@@ -327,7 +333,7 @@ def collect_bounded(document: dict[str, object], scope: Scope) -> Collected:
327
333
  for row in rows:
328
334
  if (
329
335
  not isinstance(row, list)
330
- or len(row) != 9
336
+ or len(row) != 10
331
337
  or not all(isinstance(v, str) and len(v) <= 4096 for v in row[:3])
332
338
  or not isinstance(row[3], bool)
333
339
  or not (row[4:6] == [None, None] or valid_rule_detail(row[4], row[5]))
@@ -335,9 +341,10 @@ def collect_bounded(document: dict[str, object], scope: Scope) -> Collected:
335
341
  or not isinstance(row[8], list)
336
342
  or len(row[8]) > 256
337
343
  or not all(isinstance(v, str) and len(v) <= 4096 for v in row[8])
344
+ or not (row[9] is None or (isinstance(row[9], str) and 0 < len(row[9]) <= 64))
338
345
  ):
339
346
  raise ValueError("policy_evidence_invalid")
340
- entries.append(Entry(*row[:8], evidence=tuple(row[8])))
347
+ entries.append(Entry(*row[:8], evidence=tuple(row[8]), transport=row[9]))
341
348
  paths = bundle["watch_paths"]
342
349
  if (
343
350
  not isinstance(paths, list)
@@ -493,6 +500,7 @@ def main() -> int:
493
500
  e.version,
494
501
  e.identity,
495
502
  list(e.evidence),
503
+ e.transport,
496
504
  ]
497
505
  for e in entries
498
506
  ],