agentlock 1.1.2__tar.gz → 1.2.0__tar.gz

agentlock-1.2.0/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes to AgentLock will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-03-30
+
+### Added
+
+- **Adaptive prompt hardening** -- When the gate detects suspicious activity (injection attempts, trust degradation, rate limiting), it generates defensive system prompt instructions for the agent framework to inject before the LLM processes the next turn. Session risk scores are monotonic and session-scoped. Three severity levels: warning, elevated, critical.
+- **MODIFY decision type** -- Authorized tool calls can have their outputs transformed before the LLM sees them. Built-in actions: `redact_pii` (strips SSN, email, phone, credit card, API keys from output), `restrict_domain` (blocks external email recipients), `whitelist_path` (restricts file access to allowed directories), `cap_records` (limits output record count). Configured per-tool via `modify_policy`.
+- **DEFER decision type** -- Suspends authorization when context is ambiguous. Triggers: first tool call in session is HIGH/CRITICAL risk with no history, prompt scanner fired and tool call attempted in the same turn, trust degraded below threshold. Defaults to DENY on timeout (60s).
+- **STEP_UP decision type** -- Dynamically requires human approval based on session state. Triggers: hardening severity at elevated or above with HIGH/CRITICAL risk tool, multiple PII-returning tools already called in session, tool denied earlier and user retrying with a different high-risk tool. Pluggable notification via `StepUpNotifier` protocol.
+- **DecisionType enum** -- Five authorization outcomes: `ALLOW`, `DENY`, `DEFER`, `STEP_UP`, `MODIFY`. `AuthResult.decision` field added alongside backward-compatible `AuthResult.allowed`.
+- **Gate enforcement at critical severity** -- When session risk score exceeds the critical threshold (10+) and `enforce_at_critical` is enabled, the gate blocks HIGH/CRITICAL risk tools regardless of role authorization. MEDIUM/LOW tools remain allowed.
+- **Prompt scanner** (`PromptScanner`) -- Pre-LLM analysis of user messages. Detects injection phrases, authority claims, instruction planting, encoding indicators, agent/system impersonation, format forcing, retrieval exploitation, and cross-turn repetition. Runs before the LLM processes the message, enabling hardening directives on the same turn.
+- **Behavioral velocity detector** (`VelocityDetector`) -- Tracks tool call frequency and topic shifts per session. Fires on rapid calls (3+ in 60s), topic escalation (risk jump from low/medium to high/critical), and burst patterns (same tool 3+ in 30s).
+- **Tool combination detector** (`ComboDetector`) -- Detects suspicious tool call sequences within a session. Configurable suspicion map with 13 default suspicious pairs and 5 default suspicious sequences covering data exfiltration, account takeover, and tool chain attack patterns.
+- **Response echo detector** (`EchoDetector`) -- Framework-side signal that checks LLM responses for attack prompt echoing, tool name disclosure, system prompt leakage, credential-format strings, and compliance language in suspicious contexts.
+- **Compound scoring** -- When multiple signal types co-occur, compound rules add bonus weight. `rapid_exfil` (velocity + combo, +2), `probing_attack` (echo + injection, +3).
+- **Signal-aware targeted instructions** -- Hardening directives contain instructions specific to the detected signal types instead of generic severity-level text. Format forcing attacks get format-specific instructions, not irrelevant tool-blocking language.
+- New schema models: `ModifyPolicyConfig`, `TransformationConfig`, `DeferPolicyConfig`, `StepUpPolicyConfig`
+- New exceptions: `DeferredError`, `StepUpRequiredError`, `ModifyAppliedError`
+- 276 new tests (745 total, 0 failures)
+
+### Changed
+
+- Schema version updated from `"1.1"` to `"1.2"`
+- Package version updated to `1.2.0`
+- Phone number redaction pattern expanded to cover 7-digit, US 10-digit, international (+44, +91, +1), and UK local (0-prefixed) formats
+- `AuthorizationGate.__init__()` accepts optional `hardening_config`, `velocity_config`, `combo_config`
+- `AuthorizationGate.execute()` accepts optional `modify_output_fn` for MODIFY output transformation
+- `AuthorizationGate.authorize()` pipeline extended: velocity/combo signals recorded before policy evaluation, DEFER checked before STEP_UP, STEP_UP checked before MODIFY, MODIFY checked before token issuance
+
+### Backward Compatibility
+
+- All v1.0 and v1.1.x `agentlock` permission blocks remain valid
+- `AuthResult.allowed` continues to work unchanged for existing callers
+- New fields (`decision`, `modify_output_fn`, `deferral_id`, `stepup_request_id`) default to neutral values
+- `execute()` works identically without the `modify_output_fn` parameter
+- Hardening, velocity, combo, DEFER, STEP_UP, and MODIFY are all disabled by default when their respective config/policy objects are not provided
+- All 469 original v1.1.2 tests pass without modification
+
+## [1.1.2] - 2026-03-24
+
+### Added
+
+- **Independent filter pipeline** — Decoupled InjectionFilter and PiiFilter into separate classes on PolicyEngine. Each runs independently with no shared logic or state.
+- **InjectionFilter** — Scans tool call parameters for reconnaissance/enumeration, prompt extraction, social engineering, and command injection patterns. Recursively inspects nested dicts and lists.
+- **PiiFilter** — Checks caller's max_output_classification against tool's output_classification using 7-level classification hierarchy. Independent from injection filtering.
+- 44 new tests (test_filter_pipeline.py)
+
+### Changed
+
+- PolicyEngine.evaluate() refactored into three independent stages: base auth, injection filter, PII filter
+- Trust degradation now runs independently of both filters
+- Package version updated to 1.1.2
+
+### Fixed
+
+- Injection pass rate recovered from 88.6% (v1.1.1) to 93.4% by restoring behavioral filters without PII interference
+
+## [1.1.1] - 2026-03-24
+
+### Added
+
+- **Gate-level PII classification check** — max_output_classification parameter on authorize() blocks tool execution before data is retrieved when caller clearance is below tool's output classification
+- 7-level classification hierarchy: PUBLIC, INTERNAL, CONFIDENTIAL, MAY_CONTAIN_PII, CONTAINS_PII, CONTAINS_PHI, CONTAINS_FINANCIAL
+- 16 new tests (test_pii_defense.py)
+
+### Fixed
+
+- PII regression from v1.1: restored input-layer query blocking (100/A) while maintaining output-layer redaction as backup
+
+### Backward Compatibility
+
+- max_output_classification defaults to None. When not provided, check is skipped entirely. No existing callers affected.
+
+## [1.1.0] - 2026-03-20
+
+### Added
+
+- **Context authority model** — `context_policy` block on `AgentLockPermissions` with `source_authorities` mapping context sources (user messages, tool outputs, web content, peer agents, etc.) to authority levels (`authoritative`, `derived`, `untrusted`)
+- **Trust degradation** — `TrustDegradationConfig` with per-session trust that monotonically degrades when untrusted content enters context. Effects: `require_approval`, `elevate_logging`, `restrict_scope`, `deny_writes`. Trust never escalates within a session.
+- **`allow_cascade_to_untrusted`** flag for security-critical deployments that need maximum restriction after contamination
+- **Memory access control** — `memory_policy` block with `allowed_writers`, `allowed_readers`, `prohibited_content`, `retention` limits, and `require_write_confirmation`
+- **Provenance tracking** — `ContextProvenance` dataclass with source, authority, writer identity, timestamp, content hash, and token binding for every context write
+- **`ContextTracker`** — per-session provenance log and trust state management on the authorization gate
+- **`MemoryGate`** — validates memory read/write operations against `MemoryPolicyConfig` with lazy retention enforcement
+- **`notify_context_write()`** on `AuthorizationGate` — framework integrations report context entries to the gate
+- **`authorize_memory_write()` / `authorize_memory_read()`** on `AuthorizationGate`
+- **New enums**: `ContextSource`, `ContextAuthority`, `DegradationEffect`, `MemoryPersistence`, `MemoryWriter`
+- **New denial reasons**: `TRUST_DEGRADED`, `UNATTRIBUTED_CONTEXT`, `CONTEXT_AUTHORITY_VIOLATION`, `MEMORY_WRITE_DENIED`, `MEMORY_READ_DENIED`, `MEMORY_RETENTION_EXCEEDED`, `MEMORY_PROHIBITED_CONTENT`, `MEMORY_CONFIRMATION_REQUIRED`
+- **New audit actions**: `trust_degraded`, `memory_write`, `memory_write_denied`, `memory_read`, `memory_read_denied`, `memory_expired`, `context_rejected`
+- **New audit fields**: `trust_ceiling`, `is_trust_degraded`, `degradation_effects`, `context_provenance_ids`, `memory_operation`, `memory_entry_id`
+- **New exception classes**: `TrustDegradedError`, `UnattributedContextError`, `MemoryWriteDeniedError`, `MemoryReadDeniedError`, `MemoryRetentionExceededError`, `MemoryProhibitedContentError`, `MemoryConfirmationRequiredError`
+- CLI `validate` and `inspect` commands now display v1.1 context and memory policy fields
+- `agentlock init` now generates v1.1 templates
+- 142 new tests (409 total)
+
+### Changed
+
+- Schema version default updated from `"1.0"` to `"1.1"`
+- Package version updated to `1.1.0`
+
+### Backward Compatibility
+
+- All v1.0 `agentlock` blocks remain valid — new fields are optional with secure defaults
+- When `version` is `"1.0"`, the gate skips all v1.1 checks entirely
+- All 267 original tests continue to pass without modification
+
+## [1.0.0] - 2026-03-18
+
+### Added
+
+- Core AgentLock permissions schema (v1.0)
+- `AuthorizationGate`  central enforcement point with deny-by-default semantics
+- `AgentLockPermissions`  Pydantic model for the `agentlock` permissions block
+- `@agentlock` decorator for one-line tool protection
+- Single-use, time-limited, operation-bound execution tokens
+- Session management with expiry and scope tracking
+- Sliding-window per-user, per-tool rate limiting
+- Automatic data redaction engine with built-in PII patterns
+- Policy evaluation engine with 7-step authorization checks
+- Pluggable audit logging with file and in-memory backends
+- CLI tool: `agentlock validate`, `agentlock schema`, `agentlock init`, `agentlock inspect`, `agentlock audit`
+- Framework integrations: LangChain, CrewAI, AutoGen, MCP, FastAPI, Flask
+- JSON Schema for tool definition validation
+- Comprehensive test suite
+- Working examples for all major use cases
+- Full documentation
+- GitHub Actions CI/CD pipeline
+- Apache 2.0 license

{agentlock-1.1.2 → agentlock-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentlock
-Version: 1.1.2
+Version: 1.2.0
 Summary: Authorization framework for AI agent tool calls. Your AI agent needs a login screen — AgentLock is that login screen.
 Project-URL: Homepage, https://agentlock.dev
 Project-URL: Documentation, https://agentlock.dev/docs
@@ -301,7 +301,7 @@ agentlock audit --tool send_email   # Query audit logs
 
 ## What AgentLock Prevents
 
-Based on empirical research: **187 multi-turn adversarial attack tests** across 35 categories, tested against 6 frontier AI models.
+Based on empirical research: multi-turn adversarial attack testing across 35 categories, tested against multiple frontier AI models.
 
 | Attack Category | Prevention |
 |----------------|-----------|
@@ -375,6 +375,55 @@ gate.register_tool("assistant", AgentLockPermissions(
 
 Every write to context generates a `ContextProvenance` record with source, authority, writer identity, timestamp, and content hash. Audit records now include `trust_ceiling`, `context_provenance_ids`, and `memory_operation` fields.
 
+## v1.2: Adaptive Hardening & New Decision Types
+
+AgentLock v1.2 adds four capabilities that close the gap between authorization and runtime defense.
+
+### Adaptive Prompt Hardening
+
+When the gate detects suspicious activity, it generates defensive instructions for the agent's system prompt. A pre-LLM prompt scanner analyzes user messages before the model processes them, enabling hardening on the first turn of an attack. Four signal detectors (velocity, tool combination, response echo, prompt scan) feed into a monotonic session risk score.
+
+### Five Decision Types
+
+v1.0/v1.1 supported ALLOW and DENY. v1.2 adds three more:
+
+| Decision | When | Effect |
+|----------|------|--------|
+| **ALLOW** | Call is authorized | Token issued, tool executes normally |
+| **DENY** | Call is not authorized | No token, structured denial returned |
+| **MODIFY** | Call is authorized but output must be transformed | Token issued, PII redacted from output before LLM sees it |
+| **DEFER** | Context is ambiguous, gate cannot decide | Action suspended, resolves via human review or timeout |
+| **STEP_UP** | Session state indicates elevated risk | Action paused, human approval required |
+
+### MODIFY: Output Transformation
+
+```python
+gate.register_tool("query_database", AgentLockPermissions(
+    risk_level="high",
+    requires_auth=True,
+    allowed_roles=["admin", "support"],
+    modify_policy=ModifyPolicyConfig(
+        enabled=True,
+        transformations=[
+            TransformationConfig(field="output", action="redact_pii"),
+            TransformationConfig(
+                field="to", action="restrict_domain",
+                config={"allowed_domains": ["company.com"]},
+            ),
+        ],
+    ),
+))
+
+result = gate.authorize("query_database", user_id="alice", role="admin")
+# result.decision == DecisionType.MODIFY
+# result.modify_output_fn strips PII from tool output before the LLM sees it
+output = gate.execute("query_database", db_func, token=result.token,
+                      modify_output_fn=result.modify_output_fn)
+# output: {'name': 'Jane Doe', 'email': '[REDACTED:email]', 'ssn': '[REDACTED:ssn]'}
+```
+
+The tool still executes. The admin still gets the answer. But PII never enters the LLM context where it can be weaponized by injection attacks.
+
 ## Standards Alignment
 
 | Standard | Coverage |
@@ -391,8 +440,8 @@ Every write to context generates a `ContextProvenance` record with source, autho
 | Version | Focus |
 |---------|-------|
 | **v1.0** | Core schema, tool permissions, enforcement architecture |
-| **v1.1** | Memory/context permissions, trust degradation, provenance tracking ✅ |
-| **v1.2** | Multi-agent permissions, cross-agent identity delegation |
+| **v1.1** | Memory/context permissions, trust degradation, provenance tracking |
+| **v1.2** | Adaptive hardening, MODIFY/DEFER/STEP_UP decisions, multi-signal detection (745 tests) |
 | **v1.3** | Output destination control, data flow policies |
 | **v2.0** | Execution scope, behavioral policy, anomaly detection, compliance templates |
 

{agentlock-1.1.2 → agentlock-1.2.0}/README.md

@@ -242,7 +242,7 @@ agentlock audit --tool send_email   # Query audit logs
 
 ## What AgentLock Prevents
 
-Based on empirical research: **187 multi-turn adversarial attack tests** across 35 categories, tested against 6 frontier AI models.
+Based on empirical research: multi-turn adversarial attack testing across 35 categories, tested against multiple frontier AI models.
 
 | Attack Category | Prevention |
 |----------------|-----------|
@@ -316,6 +316,55 @@ gate.register_tool("assistant", AgentLockPermissions(
 
 Every write to context generates a `ContextProvenance` record with source, authority, writer identity, timestamp, and content hash. Audit records now include `trust_ceiling`, `context_provenance_ids`, and `memory_operation` fields.
 
+## v1.2: Adaptive Hardening & New Decision Types
+
+AgentLock v1.2 adds four capabilities that close the gap between authorization and runtime defense.
+
+### Adaptive Prompt Hardening
+
+When the gate detects suspicious activity, it generates defensive instructions for the agent's system prompt. A pre-LLM prompt scanner analyzes user messages before the model processes them, enabling hardening on the first turn of an attack. Four signal detectors (velocity, tool combination, response echo, prompt scan) feed into a monotonic session risk score.
+
+### Five Decision Types
+
+v1.0/v1.1 supported ALLOW and DENY. v1.2 adds three more:
+
+| Decision | When | Effect |
+|----------|------|--------|
+| **ALLOW** | Call is authorized | Token issued, tool executes normally |
+| **DENY** | Call is not authorized | No token, structured denial returned |
+| **MODIFY** | Call is authorized but output must be transformed | Token issued, PII redacted from output before LLM sees it |
+| **DEFER** | Context is ambiguous, gate cannot decide | Action suspended, resolves via human review or timeout |
+| **STEP_UP** | Session state indicates elevated risk | Action paused, human approval required |
+
+### MODIFY: Output Transformation
+
+```python
+gate.register_tool("query_database", AgentLockPermissions(
+    risk_level="high",
+    requires_auth=True,
+    allowed_roles=["admin", "support"],
+    modify_policy=ModifyPolicyConfig(
+        enabled=True,
+        transformations=[
+            TransformationConfig(field="output", action="redact_pii"),
+            TransformationConfig(
+                field="to", action="restrict_domain",
+                config={"allowed_domains": ["company.com"]},
+            ),
+        ],
+    ),
+))
+
+result = gate.authorize("query_database", user_id="alice", role="admin")
+# result.decision == DecisionType.MODIFY
+# result.modify_output_fn strips PII from tool output before the LLM sees it
+output = gate.execute("query_database", db_func, token=result.token,
+                      modify_output_fn=result.modify_output_fn)
+# output: {'name': 'Jane Doe', 'email': '[REDACTED:email]', 'ssn': '[REDACTED:ssn]'}
+```
+
+The tool still executes. The admin still gets the answer. But PII never enters the LLM context where it can be weaponized by injection attacks.
+
 ## Standards Alignment
 
 | Standard | Coverage |
@@ -332,8 +381,8 @@ Every write to context generates a `ContextProvenance` record with source, autho
 | Version | Focus |
 |---------|-------|
 | **v1.0** | Core schema, tool permissions, enforcement architecture |
-| **v1.1** | Memory/context permissions, trust degradation, provenance tracking ✅ |
-| **v1.2** | Multi-agent permissions, cross-agent identity delegation |
+| **v1.1** | Memory/context permissions, trust degradation, provenance tracking |
+| **v1.2** | Adaptive hardening, MODIFY/DEFER/STEP_UP decisions, multi-signal detection (745 tests) |
 | **v1.3** | Output destination control, data flow policies |
 | **v2.0** | Execution scope, behavioral policy, anomaly detection, compliance templates |
 

{agentlock-1.1.2 → agentlock-1.2.0}/agentlock/__init__.py

@@ -34,13 +34,16 @@ Copyright 2026 David Grice
 SPDX-License-Identifier: Apache-2.0
 """
 
-__version__ = "1.1.2"
+__version__ = "1.2.0"
 
 from agentlock.audit import AuditLogger, AuditRecord, FileAuditBackend, InMemoryAuditBackend
 from agentlock.context import ContextProvenance, ContextState, ContextTracker
 from agentlock.decorators import agentlock
 from agentlock.exceptions import (
     AgentLockError,
+    DeferredError,
+    ModifyAppliedError,
+    StepUpRequiredError,
     ApprovalRequiredError,
     AuthenticationRequiredError,
     ConfigurationError,
@@ -62,7 +65,26 @@ from agentlock.exceptions import (
     TrustDegradedError,
     UnattributedContextError,
 )
+from agentlock.defer import DeferralManager, DeferralRecord
 from agentlock.gate import AuthorizationGate, AuthResult
+from agentlock.stepup import StepUpManager, StepUpNotifier, StepUpRequest
+from agentlock.modify import ModifyEngine, ModifyResult
+from agentlock.hardening import (
+    HardeningConfig,
+    HardeningDirective,
+    HardeningEngine,
+    HardeningSignal,
+)
+from agentlock.signals import (
+    ComboDetector,
+    ComboSignal,
+    EchoDetector,
+    EchoSignal,
+    PromptScanConfig,
+    PromptScanner,
+    VelocityDetector,
+    VelocitySignal,
+)
 from agentlock.memory_gate import InMemoryMemoryStore, MemoryDecision, MemoryEntry, MemoryGate
 from agentlock.policy import (
     InjectionFilter,
@@ -76,6 +98,10 @@ from agentlock.redaction import RedactionEngine, RedactionResult
 from agentlock.schema import (
     SCHEMA_VERSION,
     AgentLockPermissions,
+    DeferPolicyConfig,
+    ModifyPolicyConfig,
+    StepUpPolicyConfig,
+    TransformationConfig,
     AuditConfig,
     ContextPolicyConfig,
     DataPolicyConfig,
@@ -94,6 +120,7 @@ from agentlock.session import Session, SessionStore
 from agentlock.token import ExecutionToken, TokenStore
 from agentlock.types import (
     ApprovalChannel,
+    DecisionType,
     ApprovalThreshold,
     AuditLogLevel,
     AuthMethod,
@@ -125,6 +152,10 @@ __all__ = [
     "SessionConfig",
     "AuditConfig",
     "HumanApprovalConfig",
+    "DeferPolicyConfig",
+    "ModifyPolicyConfig",
+    "StepUpPolicyConfig",
+    "TransformationConfig",
     "SCHEMA_VERSION",
     # v1.1 schema components
     "ContextPolicyConfig",
@@ -164,7 +195,18 @@ __all__ = [
     # Redaction
     "RedactionEngine",
     "RedactionResult",
+    # DEFER (v1.2)
+    "DeferralManager",
+    "DeferralRecord",
+    # STEP_UP (v1.2)
+    "StepUpManager",
+    "StepUpRequest",
+    "StepUpNotifier",
+    # MODIFY (v1.2)
+    "ModifyEngine",
+    "ModifyResult",
     # Enums
+    "DecisionType",
     "RiskLevel",
     "AuthMethod",
     "DataClassification",
@@ -181,8 +223,23 @@ __all__ = [
     "MemoryWriter",
     "DenialReason",
     "TokenStatus",
+    # Hardening
+    "HardeningEngine",
+    "HardeningDirective",
+    "HardeningSignal",
+    "HardeningConfig",
+    # Signals
+    "VelocityDetector",
+    "VelocitySignal",
+    "ComboDetector",
+    "ComboSignal",
+    "EchoDetector",
+    "EchoSignal",
+    "PromptScanner",
+    "PromptScanConfig",
     # Exceptions
     "AgentLockError",
+    "ModifyAppliedError",
     "DeniedError",
     "AuthenticationRequiredError",
     "InsufficientRoleError",

agentlock-1.2.0/agentlock/defer.py

@@ -0,0 +1,211 @@
+"""DEFER decision type — suspend authorization pending resolution.
+
+When the gate cannot confidently allow or deny a tool call, DEFER
+suspends execution.  The deferral times out to DENY by default.
+
+Triggers:
+
+1. ``first_call_high_risk``: The session's very first tool call is
+   HIGH or CRITICAL risk with zero prior history.
+2. ``scan_plus_tool``: The prompt scanner fired a signal on the
+   current turn AND the LLM is attempting a tool call.
+3. ``trust_below_threshold``: Session trust has degraded below
+   DERIVED ceiling and the tool is HIGH risk.
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+__all__ = ["DeferralManager", "DeferralRecord"]
+
+
+def _generate_deferral_id() -> str:
+    return f"defer_{secrets.token_hex(8)}"
+
+
+@dataclass
+class DeferralRecord:
+    """A suspended authorization decision."""
+
+    deferral_id: str = field(default_factory=_generate_deferral_id)
+    tool_name: str = ""
+    user_id: str = ""
+    role: str = ""
+    reason: str = ""
+    trigger: str = ""
+    created_at: float = field(default_factory=time.time)
+    timeout_seconds: int = 60
+    resolution: str | None = None  # "approved", "denied", "timeout"
+    resolved_at: float | None = None
+    resolved_by: str | None = None
+    parameters: dict[str, Any] | None = None
+
+    @property
+    def is_resolved(self) -> bool:
+        return self.resolution is not None
+
+    @property
+    def is_expired(self) -> bool:
+        if self.is_resolved:
+            return False
+        return time.time() > (self.created_at + self.timeout_seconds)
+
+
+class DeferralManager:
+    """Tracks deferred decisions and their resolution.
+
+    The manager evaluates trigger conditions and creates deferral
+    records.  Resolution is handled externally (human review, additional
+    context, or timeout).
+    """
+
+    def __init__(self) -> None:
+        self._deferrals: dict[str, DeferralRecord] = {}
+        self._session_call_counts: dict[str, int] = {}
+
+    def check_first_call_high_risk(
+        self,
+        session_id: str,
+        tool_name: str,
+        risk_level: str,
+    ) -> DeferralRecord | None:
+        """Trigger: first tool call in session is HIGH/CRITICAL risk.
+
+        Returns a DeferralRecord if triggered, None otherwise.
+        """
+        count = self._session_call_counts.get(session_id, 0)
+        if count > 0:
+            return None
+        if risk_level not in ("high", "critical"):
+            return None
+
+        record = DeferralRecord(
+            tool_name=tool_name,
+            reason=(
+                f"First tool call in session is {risk_level} risk. "
+                f"Deferring for additional context."
+            ),
+            trigger="first_call_high_risk",
+        )
+        self._deferrals[record.deferral_id] = record
+        return record
+
+    def check_scan_plus_tool(
+        self,
+        session_id: str,
+        tool_name: str,
+        scan_signals_this_turn: list[Any],
+    ) -> DeferralRecord | None:
+        """Trigger: prompt scanner fired AND tool call attempted.
+
+        Returns a DeferralRecord if triggered, None otherwise.
+        """
+        if not scan_signals_this_turn:
+            return None
+
+        signal_types = [
+            s.signal_type if hasattr(s, "signal_type") else str(s)
+            for s in scan_signals_this_turn
+        ]
+        record = DeferralRecord(
+            tool_name=tool_name,
+            reason=(
+                f"Prompt scan detected suspicious input "
+                f"({', '.join(signal_types)}) and tool call attempted. "
+                f"Deferring pending review."
+            ),
+            trigger="scan_plus_tool",
+        )
+        self._deferrals[record.deferral_id] = record
+        return record
+
+    def check_trust_below_threshold(
+        self,
+        session_id: str,
+        tool_name: str,
+        risk_level: str,
+        trust_ceiling: str,
+    ) -> DeferralRecord | None:
+        """Trigger: trust degraded below DERIVED and tool is HIGH risk.
+
+        Returns a DeferralRecord if triggered, None otherwise.
+        """
+        if risk_level not in ("high", "critical"):
+            return None
+        if trust_ceiling not in ("untrusted",):
+            return None
+
+        record = DeferralRecord(
+            tool_name=tool_name,
+            reason=(
+                f"Session trust at '{trust_ceiling}' — too low for "
+                f"{risk_level} risk tool '{tool_name}'. "
+                f"Deferring pending human review."
+            ),
+            trigger="trust_below_threshold",
+        )
+        self._deferrals[record.deferral_id] = record
+        return record
+
+    def record_call(self, session_id: str) -> None:
+        """Record that a tool call was attempted in the session."""
+        self._session_call_counts[session_id] = (
+            self._session_call_counts.get(session_id, 0) + 1
+        )
+
+    def get_call_count(self, session_id: str) -> int:
+        """Get the number of tool calls recorded for a session."""
+        return self._session_call_counts.get(session_id, 0)
+
+    def resolve(
+        self,
+        deferral_id: str,
+        resolution: str,
+        resolved_by: str = "",
+    ) -> DeferralRecord | None:
+        """Resolve a deferred decision.
+
+        Args:
+            deferral_id: The deferral to resolve.
+            resolution: "approved", "denied", or "timeout".
+            resolved_by: Who resolved (user_id or "timeout").
+
+        Returns:
+            The resolved DeferralRecord, or None if not found.
+        """
+        record = self._deferrals.get(deferral_id)
+        if record is None:
+            return None
+        record.resolution = resolution
+        record.resolved_at = time.time()
+        record.resolved_by = resolved_by
+        return record
+
+    def check_timeouts(self, timeout_action: str = "deny") -> list[DeferralRecord]:
+        """Check for expired deferrals and resolve them.
+
+        Returns list of newly timed-out records.
+        """
+        timed_out: list[DeferralRecord] = []
+        for record in self._deferrals.values():
+            if not record.is_resolved and record.is_expired:
+                record.resolution = timeout_action
+                record.resolved_at = time.time()
+                record.resolved_by = "timeout"
+                timed_out.append(record)
+        return timed_out
+
+    def get(self, deferral_id: str) -> DeferralRecord | None:
+        """Get a deferral record by ID."""
+        return self._deferrals.get(deferral_id)
+
+    def reset_session(self, session_id: str) -> None:
+        """Clear call count tracking for a session."""
+        self._session_call_counts.pop(session_id, None)
+
+    def __len__(self) -> int:
+        return len(self._deferrals)