@tuent/sentinel 0.1.0 → 0.1.2

package/README.md

@@ -1,19 +1,24 @@
 # @tuent/sentinel
 
-Runtime security for Claude Code. Sentinel evaluates a policy on every Claude Code tool call — before it runs — and records each decision to a hash-chained, signed audit trail.
+**Runtime security for Claude Code.** Sentinel checks your policy on every Claude Code tool call — _before_ it runs — and writes every decision to a signed, tamper-evident audit trail. Install it, point it at your project, and Claude Code operates inside guardrails you control.
 
-It is deliberately narrow. This is not a general-purpose "agent security platform"; it is a Claude-Code-native enforcement layer that hooks Claude Code's own tool-call lifecycle.
+Sentinel is purpose-built for Claude Code. Rather than loosely wrapping a general-purpose "agent platform," it hooks Claude Code's own tool-call lifecycle directly — enforcement happens at the exact point where the agent decides to act.
+
+## What you get
+
+- **Enforcement before execution** — every tool call is evaluated against your policy and allowed or denied before it runs, not flagged after the fact.
+- **A signed audit trail** — every decision appended to a hash-chained, Ed25519-signed trail anchored by a signed manifest, verifiable end to end.
+- **Automatic escalation** — repeated violations move the agent normal → restricted → quarantined at thresholds you set, and one command restores it.
+- **Behavioral baseline** — a per-workspace baseline surfaces deviation signals as advisory context.
 
 ## How it works
 
-`init` installs a hook into Claude Code's PreToolUse lifecycle. Each tool call is routed to a local gateway daemon, evaluated against your policy, and allowed or denied before execution. Every decision is appended to a signed, hash-chained audit trail.
+`init` installs a hook into Claude Code's PreToolUse lifecycle. Each tool call is routed to a local gateway daemon, evaluated against your policy, and allowed or denied before execution — then recorded to the signed trail.
 
 ```
 Claude Code tool call → PreToolUse hook → gateway daemon → policy decision → signed audit
 ```
 
-Enforcement is cooperative: it depends on Claude Code invoking the hook. Sentinel is not a sandbox and does not contain a hostile agent that bypasses the hook.
-
 ## Install
 
 ```sh
@@ -21,9 +26,7 @@ npm install @tuent/sentinel
 npx sentinel init claude-code
 ```
 
-`init` writes a `.sentinel.yaml` policy into your project, sets up the gateway hook, and merges a hook entry into `.claude/settings.local.json`. No `tsx` or build step is required — the gateway ships as a runnable daemon.
-
-Requires Node.js ≥ 20. ESM-only.
+`init` writes a `.sentinel.yaml` policy into your project, sets up the gateway hook, and merges a hook entry into `.claude/settings.local.json`. No build step — the gateway ships as a runnable daemon. Requires Node.js ≥ 20 (ESM-only).
 
 ## Policy
 
@@ -60,36 +63,33 @@ enforcement:
   quarantineAfter: 5 # quarantine after this many
 ```
 
+`forbid.targets` is a hard deny — a match blocks the action. `allow.targets` is **advisory for file and tool actions**: a read or write outside it is _logged_ as a `scope_violation` but still runs, because Sentinel governs the agent's own tool calls rather than sandboxing the filesystem. The exception is `networkHosts` — a `network_request` to a host not on the list is **denied** by default. That host allowlist governs **tool-level network requests** (WebFetch/WebSearch); it does not contain network access made from _inside_ a Bash command (`curl`, `wget`, etc.) — Bash commands are checked for forbidden file paths, not egress destinations.
+
+Tool names Sentinel doesn't recognize — for example, tools added in a Claude Code release newer than your Sentinel build — are **allowed and logged** by default (`enforcement.unknownTools: warn`; every unknown call is recorded as an `unknown_tool` audit finding). Set `enforcement.unknownTools: deny` to block them instead, with `enforcement.allowUnknownTools: [<names>]` as the per-name escape hatch for legitimate new tools.
+
 As policy violations accumulate, the agent escalates through modes: normal → restricted → quarantined (at the `restrictAfter` / `quarantineAfter` thresholds). Release a restricted or quarantined agent through the API (`sentinel.release(...)`), which records the change as a signed entry in the audit trail. Editing the mode state file by hand changes the live state without recording it — leaving the trail and the actual state out of sync.
 
 ## Audit trail
 
-Every decision is appended to a hash-chained trail and signed with Ed25519, anchored by a signed manifest. A verify check validates the hash chain and the entry signatures; the signed manifest anchors the chain.
+Every decision is appended to a hash-chained trail and signed with Ed25519, anchored by a signed manifest. Run `sentinel --verify-audit` to validate the chain and every entry signature.
 
-Scope and limits — please read:
+## Behavioral analytics
 
-- The trail is designed for a single writer (the gateway daemon). There is no inter-process write lock. Running concurrent writer processes against one trail can fork the chain, so a verify-audit failure can indicate benign concurrency rather than tampering.
-- Signature determinism currently relies on V8's JSON key ordering. Verifying on another engine (Bun, Deno) is not yet supported and may report false invalids.
-- The trail is stored in plaintext. It is tamper-evident, not tamper-proof: a compromised same-host process can alter it, and the signed manifest is designed to detect that, not prevent it.
+Sentinel maintains a per-workspace behavioral baseline and surfaces session-level deviation signals as advisory context. These are observational and do not block tool calls; the richer signals require a matured workspace baseline.
 
-## Behavioral analytics
+## If a tool call is unexpectedly blocked
 
-Sentinel maintains a per-workspace behavioral baseline and surfaces session-level, advisory deviation signals. These are observational; they do not block tool calls. Activity-absence can surface once a baseline exists; temporal, access-pattern, and the remaining deviation signals require a matured workspace baseline. None fire on a fresh install.
+Sentinel matches forbidden targets conservatively, which can occasionally deny a benign command that only _references_ a sensitive filename — for example, searching your code with `grep` for `.env`. Plain mentions under safe commands (`echo`, comments) pass through. If a false positive restricts or quarantines the agent, restore it in one step:
 
-## What Sentinel does not do
+```sh
+sentinel release
+```
 
-- It does not defend against prompt injection of the agent itself.
-- In log-adapter mode it does not block in real time (it observes, with latency).
-- It does not prevent log tampering by a compromised same-host process.
-- It does not detect encrypted or obfuscated exfiltration.
-- It does not defend against multi-agent coordinated activity.
-- It does not resolve symlinks in target paths.
-- Workspace identity is a non-cryptographic 32-bit hash. It distinguishes local workspaces; it is not collision-resistant.
+This records the change in the audit trail. Don't edit the mode state file by hand — that desyncs the trail from the live state.
 
-## Notes
+## Security model
 
-- Target and content matching is conservative and can produce false positives — for example, a literal token such as `process.env` can match a `.env` forbid pattern. Tune your policy accordingly.
-- On a cold start, the first tool call of a fresh session waits up to ~5 seconds for the daemon to warm up. If it is not ready, Sentinel applies its tiered fallback: high-sensitivity tools are denied, lower-sensitivity tools are allowed through.
+Sentinel's enforcement is **cooperative** — it works by intercepting Claude Code's tool-call hook — and the audit trail is **tamper-evident**, not tamper-proof. Today Sentinel runs on the same host as the agent; running it off-host is the hardened posture on the roadmap. For the full threat model — what Sentinel defends against, what's out of scope by design, and current limitations — see [SECURITY_MODEL.md](./SECURITY_MODEL.md).
 
 ## License
 

package/SECURITY_MODEL.md

@@ -0,0 +1,281 @@
+# Sentinel Security Model
+
+Sentinel's enforcement is **cooperative, not a sandbox**: it governs the agent's own tool calls at the hook layer — it does not intercept syscalls, contain the filesystem, or firewall the network. The audit trail is **tamper-evident, not tamper-proof**. Sentinel currently runs on the same host as the agent; the off-host posture described under "Trust Model" is the hardened, recommended direction. Read every claim below with those three frames in mind.
+
+## What Sentinel Protects Against
+
+### Pre-Execution Enforcement
+
+When using `wrap()` or `wrapTool()`, Sentinel validates every action before the agent executes it. HIGH and CRITICAL severity actions are blocked -- the agent's execution function never runs. The dangerous file is never read, the unauthorized API is never called, the forbidden command is never executed.
+
+This is the strongest integration mode. The agent code passes its intended action and an execute function to Sentinel. If the action violates the role definition or targets a high-sensitivity resource, Sentinel returns `{ blocked: true }` and the execute function is never invoked. LOW and MEDIUM findings are informational -- the action still executes, and the finding is returned alongside the result for logging. (One exception in the blocking direction: a MEDIUM out-of-scope `network_request` is denied by default -- see "Unauthorized Target Access" below.)
+
+### Role Violations
+
+Agents are bound to a defined set of allowed actions. If an agent with `allowedActions: ["file_read", "file_write"]` attempts a `command_exec` or `database_query`, Sentinel produces a **HIGH** `role_violation` finding immediately.
+
+### Unauthorized Target Access
+
+Targets are checked against glob patterns in two layers:
+
+1. **Forbidden patterns** (checked first) -- any match produces a **HIGH** `unauthorized_target`
+2. **Allowed patterns** (checked second) -- access outside allowed scope produces a **MEDIUM** `scope_violation`
+
+A `scope_violation` is **advisory by default, not a block**: an out-of-scope `file_read`, `file_write`, or `tool_invocation` is **logged and still runs** (`DEFAULT_MEDIUM_DISPOSITION` leaves these actions at `allow`). The exception is `network_request` -- an out-of-scope or unlisted host is **denied** by default. So the allowlist _enforces_ egress **for `network_request` actions** (the WebFetch/WebSearch tool surface) but only _annotates_ out-of-scope file and tool activity: forbidden-pattern hits (HIGH) always block; allowed-scope misses (MEDIUM) do not, except for network. The host allowlist does **not** govern network access made from inside a Bash command — see "Bash-Mediated Network Egress" under the limitations below. Sentinel governs the agent's own tool calls; it is not a filesystem sandbox.
+
+Pattern matching uses `**` (any path) and `*` (single segment). Examples:
+
+- `**/.env` matches `.env` at any depth
+- `**/.ssh/**` matches anything inside any `.ssh` directory
+- `src/**` matches all files under `src/`
+
+### Behavioral Anomalies
+
+After a baseline is computed from historical sessions, the DeviationDetector checks every new session for:
+
+- **Volume spikes** -- event count exceeds 3x the baseline average
+- **Unusual targets** -- more than 50% of accessed files are outside the agent's typical target set
+- **Weight anomaly** -- session engagement exceeds baseline normal range + 0.3 threshold
+- **Category shifts** -- activity type represents less than 5% of baseline behavior
+- **Activity drops** -- session event count drops 75%+ below baseline average (possible log suppression)
+- **Activity gaps** -- agent silence exceeds 2-3x the longest observed gap in the baseline period
+- **Convergence escalation** -- when 3+ MEDIUM findings occur in one session, the first is escalated to HIGH
+
+### High-Sensitivity Target Access
+
+The TargetSensitivityScorer assigns risk scores (0.0-1.0) to every target based on built-in pattern rules. Scores are multiplied by action type (writes are 1.3x, command execution is 1.5x). When the effective score reaches 0.9+, findings are escalated to **CRITICAL**.
+
+Built-in sensitivity categories:
+
+- **Credentials** (1.0): `.ssh/`, `.env`, `.aws/`, `secrets/`, `id_rsa*`, `.pem`, `shadow`
+- **System** (0.7-0.9): `/etc/`, `passwd`
+- **PII** (0.8-0.85): `users/`, `customers/`, `payments/`
+- **Database** (0.75-0.8): `database/`, `.sqlite`, `.db`
+- **Config** (0.5-0.75): `config/`, `config/production*`
+- **Source** (0.1-0.45): `src/`, `tests/`, `docs/`, `.git/`
+- **Default** (0.15): anything not matching a specific rule
+
+Custom rules can be injected via the `TargetSensitivityScorer` constructor, overriding built-in patterns.
+
+### Temporal Anomalies
+
+Agents can have an `expectedSchedule` with allowed days and hours (UTC). Activity outside the schedule produces a **MEDIUM** `temporal_anomaly`. The DeviationDetector independently checks against the baseline's typical active hours and days.
+
+### Path Traversal Attempts
+
+All target paths are normalized with `path.normalize()` before pattern matching. This resolves `../` and `./` sequences, preventing bypass attempts like:
+
+- `src/../.env` is normalized to `.env` before checking against `**/.env`
+- `project/subdir/../../.ssh/id_rsa` is normalized to `.ssh/id_rsa`
+
+### Self-Protection: Policy and Hook-Wiring Files
+
+The agent's own tool-writes to the live policy file (`.sentinel.yaml`) and to Claude Code's hook-wiring settings files (`.claude/settings.json` and `.claude/settings.local.json`, project- and user-level) are **denied by default**. Without this, an agent could rewrite its own policy or remove the hook entries that route its tool calls through the gateway with an ordinary file write. The corresponding forbid patterns ship in the defaults and the starter policy; the read carve-out is appended **code-side at ceiling-role construction** and is deliberately not authorable from the workspace yaml (workspace-authored exceptions are dropped by the ceiling merge, so a policy file can never widen its own protection away).
+
+**Defaults are a floor, not a fallback.** The built-in forbidden patterns are unioned into every role at role construction, regardless of what the policy file supplies. A policy file can extend the built-in list but cannot remove entries from it — omitting a built-in pattern from a yaml's `forbid.targets` does not disable it. This is deliberate: a stale policy file (written before newer built-in protections existed) or a hostile one cannot weaken built-in protection by superseding the list. Legitimately relaxing a built-in pattern goes through the operator-ceiling policy's `exceptions` mechanism, which is an explicit, auditable act — never through omission.
+
+Honest boundaries of this protection:
+
+- **Reads are allowed via the Read tool only.** Bash-mediated reads that name these files (`cat`, `grep`, redirection sources) are denied — the gateway's bash layers have no exception plumbing. The agent inspects its policy and hook wiring with the Read tool.
+- **Plain bash writes to the policy/settings files are denied, but encoding-obfuscated bash writes are not decoded for these patterns.** Their basenames are deliberately excluded from the content-scan list to avoid false positives on source files that mention them. This is an accepted limitation.
+- **Operators edit these files directly.** Agent tool-writes are denied by design; a human editing `.sentinel.yaml` or the settings files in an editor or separate shell is outside the agent tool-call surface and unaffected.
+- **`~/.claude.json` is not part of Claude Code's honored-hooks surface** (it holds legacy global state, not hook configuration) and is therefore not on the forbid list.
+- **Managed settings and launch-flag settings files are admin surface**, controlled outside the agent's tool-call path, and out of tool-write scope for this protection.
+
+### Unknown Tool Names
+
+Tool names outside Sentinel's recognized native set (and not MCP-shaped — `mcp__*` names have their own arg-scanning translation path) cannot be evaluated by name-aware policy checks. The gateway's disposition for them is the `enforcement.unknownTools` knob in the operator launch policy:
+
+- **`warn` (shipped default):** the call is allowed and a persisted, observational `unknown_tool` finding is written to the audit trail — no unknown tool passes unlogged. This is the default because the recognized set is inventoried from live sessions and cannot be proven complete against capability-gated or newer Claude Code tools; deny-by-default on an unverifiable list risks breaking legitimate cc features. The default is intended to flip to deny once warn-mode telemetry reconciles the inventory against live traffic.
+- **`deny` (hardened opt-in):** the call is blocked with a HIGH `unknown_tool` finding. The deny message names the blocked tool and the escape hatch: `enforcement.allowUnknownTools` (a list of names to translate as known) plus a daemon restart — so a newly shipped cc tool can be unbricked with a one-line policy edit, without waiting on a Sentinel release.
+
+`unknown_tool` findings are deliberately **not escalation-eligible**: the dominant real-world cause is a recognized set gone stale after a Claude Code update, not agent misbehavior, and counting them would turn every cc update into a restriction ratchet.
+
+**Gateway-down behavior is deliberately stricter:** the fail-closed hook hard-blocks unknown names regardless of the knob, because the hook cannot persist findings while the daemon is down — a warn-equivalent there would be allow-_unlogged_, which is exactly the gap this protection closes. `allowUnknownTools` names are baked into the hook at init so the operator escape hatch survives gateway-down; re-run init after editing the list.
+
+---
+
+## What Sentinel Does NOT Protect Against
+
+### Prompt Injection
+
+Sentinel monitors agent **actions**, not agent **prompts**. It cannot detect or prevent prompt injection attacks directly. However, if a prompt injection causes an agent to perform a forbidden action (e.g., reading `.env`), that action **will** be caught by role validation.
+
+### Real-Time Blocking in Log Adapter Mode
+
+When using the LogAdapter (file-tailing mode), events are detected after they occur with a polling delay (default ~2 seconds). This mode is observation-only -- it cannot block actions.
+
+For real-time pre-execution enforcement, use one of:
+
+- **`sentinel.wrap()` / `sentinel.wrapTool()`** (recommended) -- synchronous enforcement, actions blocked before execution
+- **`sentinel.check()`** -- manual pre-execution gate in your agent orchestrator
+- **WebhookReceiver** in synchronous mode (agent sends event before executing)
+
+### Log Tampering by Compromised Agents
+
+If an AI agent and Sentinel run on the same host and the agent has write access to the filesystem, a compromised agent could theoretically modify its own log files or audit trail. **Mitigation:** Run Sentinel on a separate host and ingest events via the webhook adapter.
+
+### Bash-Mediated Network Egress
+
+The `networkHosts` allowlist is enforced for `network_request` actions — the WebFetch/WebSearch tool surface. It does **not** contain network access initiated from inside a Bash command: `curl`, `wget`, a script that opens a socket, or a package manager's network activity all run under `command_exec`, where Sentinel's bash layers check the command for **forbidden file paths and basenames**, not egress destinations. There is no comprehensive network containment; treat the host allowlist as a control on the agent's tool-level fetches, not a firewall.
+
+### Encrypted or Obfuscated Data Exfiltration
+
+Sentinel sees which targets an agent accesses and what actions it performs. It does not inspect the content of data being read or transmitted. An agent reading a sensitive file and encoding its contents into an innocuous-looking API call would be partially detected (the file read is logged) but the exfiltration channel may not be flagged.
+
+### Self-Hosting Development Boundary
+
+In a repository that contains Sentinel's own source code, the agent can still edit the enforcement code itself (and the running daemon picks the change up on its next restart). The policy/hook-wiring write-deny does not — and cannot — close that vector; it is inherent to developing Sentinel with the agent it monitors. Treat enforcement-source changes in such a repo as requiring the same human review as any security-sensitive code.
+
+### Multi-Agent Coordinated Attacks
+
+Each agent is monitored independently by default. The `CorrelationDetector` provides basic cross-agent pattern detection (e.g., read-then-exfiltrate chains), but sophisticated coordinated attacks where each agent stays within its own role may evade detection.
+
+### Symlink and Hardlink Resolution Limits
+
+When Sentinel runs on the same host as the agent (the Claude Code gateway integration), validation does resolve links before matching: targets are passed through `realpath` (so a symlink named `src/safe-link` pointing at `/etc/shadow` is checked as `/etc/shadow` and hits the `/etc/**` forbid), and a forbidden-inode comparison catches **hardlinks** to forbidden files that pattern matching cannot see. The honest limits:
+
+- **Off-host modes resolve nothing.** The WebhookReceiver / LogAdapter paths operate on path strings without filesystem access to the agent host — there, link-based bypasses are not detected.
+- **Time-of-check vs time-of-use.** A link can be re-pointed between Sentinel's pre-execution check and the tool actually running. This window is inherent to the cooperative model.
+- **Resolution requires the path to exist** at check time; a dangling link that is created after the check is not re-evaluated.
+
+### Concurrent Audit-Trail Writers (No Inter-Process Lock)
+
+The audit trail is designed for a **single writer** -- the gateway daemon. There is no inter-process write lock. Running concurrent writer processes against one trail can fork the hash chain, so a `verify-audit` failure can indicate benign concurrency rather than tampering.
+
+### Cross-Engine Signature Verification
+
+Ed25519 signature determinism currently relies on **V8's JSON key ordering** when serializing the signed payload. Verifying on another JavaScript engine (Bun, Deno) is not supported and may report false invalids.
+
+### Workspace Identity Collisions
+
+Workspace identity is a **32-bit FNV-1a hash** of the workspace root. It is non-cryptographic and not collision-resistant; it distinguishes local workspaces but is not a security boundary.
+
+### Conservative Matching / False Positives
+
+Target matching is deliberately conservative: a command that only _references_ a forbidden filename — for instance, a `grep` whose pattern or path is `.env` — can be denied even though it never opens the file. Because each denial counts toward the escalation ladder, a run of such false positives can move the agent to `restricted` or `quarantined`. Plain mentions under safe verbs (`echo`, `printf`) and in comments are not flagged. When a false positive does restrict or quarantine the agent, recover with `sentinel release`, which records the change in the audit trail. Tune policies to widen the allow set where this proves noisy.
+
+### Cold-Start Window
+
+On a cold start, the first tool call of a fresh session waits up to **~5 seconds** for the gateway daemon to warm up. If the daemon is not ready, the hook applies its **tiered fallback** rather than failing closed uniformly: high-sensitivity tools (e.g. `Bash`, `Write`, `Edit`, `WebFetch`) are **denied**, while lower-sensitivity tools (e.g. `Read`, `Glob`, `Grep`, `WebSearch`) are **allowed** through. MCP tools default to the high (deny) tier; **unrecognized tool names are always high-tier** — floored, not configurable down (allowing them unlogged while the gateway is down would reopen the unknown-tool gap), with the operator's `allowUnknownTools` names (baked into the hook at init) as the only pass-through.
+
+---
+
+## Trust Model
+
+### Recommended Production Deployment
+
+```
++------------------+          HTTPS/webhook          +-------------------+
+|   AI Agent Host  |  -----------------------------> |  Sentinel Host    |
+|                  |     POST /api/sentinel/events   |                   |
+|  Agent runtime   |                                 |  WebhookReceiver  |
+|  sends events    |                                 |  RoleValidator    |
+|  before/after    |                                 |  AuditTrail       |
+|  each action     |                                 |  AlertManager     |
++------------------+                                 +-------------------+
+```
+
+- Sentinel runs on a separate host the agent cannot access
+- Events are pushed via authenticated webhook (API key in Authorization header)
+- Audit trail is on the Sentinel host, inaccessible to the agent
+- Alerts dispatch to external systems (Slack webhook, PagerDuty, etc.)
+
+The off-host posture above is the **hardened, recommended direction**. Note that the **Claude Code gateway integration currently runs same-host** — the gateway daemon, policy file, and audit trail live on the machine the agent runs on, with the self-protection forbids (policy/hook-wiring write-denies, state-dir forbid) as the same-host mitigations. Moving the cc gateway's enforcement core off-host is the roadmap re-architecture; until then, treat same-host deployment with the honesty the "Log Tampering" section above implies.
+
+### Development Deployment
+
+```
++----------------------------------------------+
+|               Same Host                      |
+|                                              |
+|  Agent runtime  --->  activity.log           |
+|                          |                   |
+|                    LogAdapter (polls)         |
+|                          |                   |
+|                    SentinelRunner             |
+|                    AuditTrail                 |
++----------------------------------------------+
+```
+
+- Sentinel watches the agent's log file via LogAdapter
+- Simpler setup but agent could tamper with its own logs
+- Suitable for development and testing
+
+### Audit Trail Integrity
+
+- Append-only: entries are only written, never modified or deleted programmatically
+- Per-agent: each agent has its own `audit.log` file
+- Rotation: files rotate at 10 MB, keeping 3 archives (audit.log.1, .2, .3)
+- All entries include timestamps and are queryable by time range and severity
+
+### Data Storage
+
+- All data is local to the Sentinel host filesystem
+- No cloud services, no external databases, no network dependencies
+- Storage location is configurable via `agentsDir` constructor parameter
+- Default: `~/.dahlia/agents/`
+
+---
+
+## Severity Levels
+
+| Severity     | Meaning                        | Triggers Alert?        | Response                                                                                                                              |
+| ------------ | ------------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| **LOW**      | Notable but expected variation | No (unless configured) | Log for review. Weight anomalies, off-day activity.                                                                                   |
+| **MEDIUM**   | Warrants monitoring            | Configurable           | Single deviation signal. Volume spike, unusual targets, category shift, off-hours. Escalates to HIGH when 3+ converge in one session. |
+| **HIGH**     | Requires investigation         | Yes                    | Role violation, forbidden target access, escalated convergence.                                                                       |
+| **CRITICAL** | Immediate response required    | Yes                    | Target sensitivity effective score >= 0.9. Credential access, system file writes.                                                     |
+
+### Escalation Rules
+
+- MEDIUM findings escalate to HIGH when 3+ MEDIUM findings occur in a single session (convergence escalation)
+- HIGH findings are escalated to CRITICAL by the TargetSensitivityScorer when the effective score (sensitivity x action multiplier) reaches 0.9+
+
+---
+
+## Detection Capabilities
+
+| Threat                                        | Detection Method                             | Component                  | Expected Severity                                                 |
+| --------------------------------------------- | -------------------------------------------- | -------------------------- | ----------------------------------------------------------------- |
+| SSH key access (`~/.ssh/id_rsa`)              | Target sensitivity (1.0)                     | RoleValidator + Scorer     | CRITICAL                                                          |
+| `.env` file read                              | Target sensitivity (1.0)                     | RoleValidator + Scorer     | CRITICAL                                                          |
+| AWS credential access (`~/.aws/credentials`)  | Target sensitivity (1.0)                     | RoleValidator + Scorer     | CRITICAL                                                          |
+| Kubernetes config access (`~/.kube/config`)   | Target sensitivity (0.95)                    | RoleValidator + Scorer     | CRITICAL                                                          |
+| Write to `~/.ssh/authorized_keys` (backdoor)  | Target sensitivity (1.0 x 1.3 write)         | RoleValidator + Scorer     | CRITICAL                                                          |
+| `/etc/passwd` read                            | Target sensitivity (0.9) + forbidden pattern | RoleValidator + Scorer     | CRITICAL                                                          |
+| System config write (`/etc/nginx/nginx.conf`) | Target sensitivity (0.7 x 1.3 write = 0.91)  | RoleValidator + Scorer     | CRITICAL                                                          |
+| Payment data access (`payments/`)             | Target sensitivity (0.85)                    | DeviationDetector + Scorer | HIGH                                                              |
+| Database query by file-only agent             | Action not in allowedActions                 | RoleValidator              | HIGH                                                              |
+| Shell command by code-writer agent            | Action not in allowedActions                 | RoleValidator              | HIGH                                                              |
+| 3x baseline event volume                      | Event count exceeds threshold                | DeviationDetector          | MEDIUM (escalates to HIGH with other signals)                     |
+| >50% novel target files in session            | Target set comparison                        | DeviationDetector          | MEDIUM                                                            |
+| Activity outside expected hours               | Schedule check (UTC)                         | RoleValidator              | MEDIUM                                                            |
+| Weekend activity when weekday-only            | Schedule check (UTC)                         | RoleValidator              | MEDIUM                                                            |
+| Path traversal (`src/../.env`)                | Path normalization + pattern match           | RoleValidator              | HIGH/CRITICAL (depends on target)                                 |
+| Category shift (rare action type)             | Baseline action distribution                 | DeviationDetector          | MEDIUM                                                            |
+| Access outside allowed scope                  | Allowed target pattern miss                  | RoleValidator              | MEDIUM — advisory (logged, not blocked); `network_request` denied |
+| Multiple converging anomalies (3+)            | Finding count in session                     | DeviationDetector          | MEDIUM escalated to HIGH                                          |
+| Activity drop (75%+ fewer events)             | Event count vs baseline average              | DeviationDetector          | MEDIUM (HIGH at 90%+ drop)                                        |
+| Extended agent silence (2-3x max gap)         | Time since last event vs baseline gaps       | DeviationDetector          | LOW (MEDIUM at 3x+)                                               |
+
+---
+
+## Finding Types
+
+| Type                  | Source                           | Description                                                                                                   |
+| --------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `role_violation`      | RoleValidator                    | Agent performed an action not in its `allowedActions` list                                                    |
+| `unauthorized_target` | RoleValidator, DeviationDetector | Agent accessed a target matching `forbiddenTargetPatterns` or scoring high on sensitivity                     |
+| `scope_violation`     | RoleValidator                    | Agent accessed a target outside its `allowedTargetPatterns`                                                   |
+| `temporal_anomaly`    | RoleValidator, DeviationDetector | Activity outside expected schedule or baseline typical hours/days                                             |
+| `volume_spike`        | DeviationDetector                | Session event count exceeds baseline average by 3x+                                                           |
+| `access_pattern`      | DeviationDetector                | Unusual target distribution, weight anomaly, or category shift                                                |
+| `behavioral_absence`  | DeviationDetector                | Significant activity drop (75%+ below baseline) or extended silence (2-3x max gap)                            |
+| `intent_drift`        | Similarity engine (active task)  | Action poorly aligned with the declared active task — informational, never blocks                             |
+| `bash_analysis`       | Gateway L3                       | Dangerous construct / unparseable command without forbidden indicators — informational                        |
+| `hook_block`          | HookEngine                       | A registered pre-execution hook vetoed the action                                                             |
+| `workspace_mismatch`  | Gateway routing                  | Request with no/unresolvable workspace — fail-closed routing refusal; not escalation-eligible                 |
+| `agent_restricted`    | Enforcement ladder               | Action denied because the agent is in restricted mode                                                         |
+| `agent_quarantined`   | Enforcement ladder               | Action denied because the agent is quarantined                                                                |
+| `unknown_tool`        | Gateway unknown-tool consumer    | Tool name outside the recognized set — logged-allow by default (`warn`), deny opt-in; not escalation-eligible |

package/dist/Sentinel-XMSJE4DZ.js

@@ -0,0 +1,10 @@
+import {
+  Sentinel
+} from "./chunk-GRN5P3H2.js";
+import "./chunk-QIYQWOLO.js";
+import "./chunk-WLIDSTS4.js";
+import "./chunk-NUXSUSYY.js";
+export {
+  Sentinel
+};
+//# sourceMappingURL=Sentinel-XMSJE4DZ.js.map

package/dist/{Sentinel-B_sv8Kiy.d.ts → Sentinel-xFCyXH45.d.ts}

@@ -259,8 +259,13 @@ interface SecurityFinding {
      * routing error, not that agent's misbehavior. Same non-eligible posture as
      * `bash_analysis`. Escalation-ineligibility is a consequence of what the type
      * means, not a knob — see Sentinel.ESCALATION_ELIGIBLE_TYPES.
+     *
+     * `unknown_tool` (Sprint 26 Gate-A Item D / F-8) is likewise non-eligible:
+     * its dominant real-world cause is a recognized-tool set gone stale after a
+     * Claude Code update, not agent misbehavior — counting it would turn every
+     * cc update into a restriction ratchet.
      */
-    type: "scope_violation" | "temporal_anomaly" | "access_pattern" | "volume_spike" | "unauthorized_target" | "role_violation" | "behavioral_absence" | "agent_quarantined" | "agent_restricted" | "intent_drift" | "hook_block" | "bash_analysis" | "workspace_mismatch";
+    type: "scope_violation" | "temporal_anomaly" | "access_pattern" | "volume_spike" | "unauthorized_target" | "role_violation" | "behavioral_absence" | "agent_quarantined" | "agent_restricted" | "intent_drift" | "hook_block" | "bash_analysis" | "workspace_mismatch" | "unknown_tool";
     agentId: string;
     agentName: string;
     description: string;
@@ -278,6 +283,22 @@ interface SecurityFinding {
         args: string[];
     };
     softSignal?: boolean;
+    /**
+     * True when the forbidden token was a confident command-string MENTION (a
+     * proper substring of an argv token, no L1 path-glob hit, no ambiguity) rather
+     * than a forbidden-file access. Excluded from getEffectiveBlockCount. Absent /
+     * false = counted (today's behavior). Strict-safe: a real file open resolves to
+     * an L1 path hit, so it can never be mentionOnly.
+     */
+    mentionOnly?: boolean;
+    /**
+     * Distinct-target dedup key for getEffectiveBlockCount — the COMMAND identity
+     * (event.primaryTarget). Distinct real accesses, including same-basename-family
+     * files (`cat .env` vs `cat .env.local`), get distinct keys and count
+     * separately; a true repeat of the same command dedups to one. Absent = the
+     * finding is its own distinct entry (never merged).
+     */
+    dedupKey?: string;
 }
 /** Computed behavioral baseline for an agent over a time window. */
 /**
@@ -1778,6 +1799,15 @@ declare class Sentinel {
      * Sprint 16 Prompt 3 — replaces in-memory blockCounts Map to survive
      * gateway restarts. Same pattern as Sprint 11 sessionCount Shape D fix.
      */
+    /**
+     * Shared escalation-eligibility predicate (Sprint 26 F-5). Single source of
+     * truth for "this finding counts toward the block ladder", extracted from the
+     * formerly-inline copies in getEffectiveBlockCount and maybeEscalate — behavior
+     * of both is identical to before the extraction. Accepts either a
+     * SecurityFinding-shaped object ({type}) or an audit entry ({findingType},
+     * mapped by the caller).
+     */
+    private static isEscalationEligible;
     private getEffectiveBlockCount;
     private maybeEscalate;
 }

package/dist/chunk-B5QKJHSV.js

@@ -0,0 +1,32 @@
+// src/workspaceIdentity.ts
+var AGENT_PREFIX = "claude-code";
+function fnv1a32Hex(s) {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+function lastSegment(path) {
+  const parts = path.split("/").filter(Boolean);
+  return parts.length > 0 ? parts[parts.length - 1] : "";
+}
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "");
+}
+function normalizeRoot(root) {
+  if (root === "" || root === "/") return root;
+  return root.replace(/\/+$/, "") || "/";
+}
+function deriveAgentId(workspaceRoot) {
+  const root = normalizeRoot(workspaceRoot);
+  const slug = slugify(lastSegment(root)) || "root";
+  const hash = fnv1a32Hex(root);
+  return `${AGENT_PREFIX}@${slug}-${hash}`;
+}
+
+export {
+  deriveAgentId
+};
+//# sourceMappingURL=chunk-B5QKJHSV.js.map