@tuent/sentinel 0.1.1 → 0.1.3

package/README.md

@@ -63,6 +63,10 @@ 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
@@ -85,7 +89,7 @@ This records the change in the audit trail. Don't edit the mode state file by ha
 
 ## Security model
 
-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. For the full threat model — what Sentinel defends against, what's out of scope by design, and current v0.1.0 limitations — see [SECURITY_MODEL.md](./SECURITY_MODEL.md).
+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

@@ -1,12 +1,14 @@
 # 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.
+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
 
@@ -19,6 +21,8 @@ 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
@@ -64,6 +68,40 @@ All target paths are normalized with `path.normalize()` before pattern matching.
 - `src/../.env` is normalized to `.env` before checking against `**/.env`
 - `project/subdir/../../.ssh/id_rsa` is normalized to `.ssh/id_rsa`
 
+Conversely, `command_exec` targets (whole shell command strings) are **never glob-matched as if they were a path**. They are screened by a scanner: the command is tokenized, path-shaped tokens are resolved and matched against the forbidden patterns, and every argv token's basename is matched against each pattern's basename component with **component-boundary** semantics (the basename must match as a whole, not as a substring). So `process.env` and similarly-shaped code constructs are not treated as file access (the basename `process.env` is not the basename `.env`), while a real operand like `payroll.csv` against a `payroll.csv` forbid pattern is denied — in any command position, not only at the end. This screen is the single source of truth for command screening on **both** the gateway and the embedded-SDK (`wrap()`/`check()`) paths; the gateway additionally keeps its inline L1/L2 scan as defense-in-depth. Correspondingly, `command_exec` is **exempt from the allowed-target allowlist** (and session `SCOPE:` narrowing): those are path globs, and a command string is not a path, so matching it there only produced false `scope_violation`s — which the sensitivity scorer could escalate to a hard block when the command merely named a credential token (e.g. `process.env`). Whether an agent may run commands at all is governed by `allowedActions`; whether a given command is forbidden is the command screen above.
+
+Two residuals of letting operators forbid bare basenames in commands (both pre-existing, narrower than the prior whole-string glob, and operator-self-inflicted):
+
+- **R1 — generic-word custom basenames.** A custom forbid pattern whose basename is a common word (e.g. a pattern ending in `build`) will also match a command that uses that word as a non-file argument (e.g. `npm run build`). This is intrinsic to forbidding a bare common word; prefer specific basenames for custom command-forbid patterns. The same property holds for path-target matching.
+- **R2 — positional-safety scope.** The echo-class positional-safety suppression (`isPositionallySafeMention`) is scoped to the built-in basename list, not to operator-custom patterns, so a custom basename mentioned in an otherwise-safe position (e.g. as an `echo` argument) is still denied.
+
+SDK-path residual: obfuscated/encoded command operands are de-obfuscated only on the gateway path (the translator's resolver pipeline); a direct `wrap()`/`check()` caller gets tokenized + basename + substring screening but not the decode layer.
+
+### 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
@@ -86,17 +124,29 @@ For real-time pre-execution enforcement, use one of:
 
 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 Resolution
+### Symlink and Hardlink Resolution Limits
 
-RoleValidator operates on path strings, not the filesystem. A symlink named `src/safe-link` pointing to `/etc/shadow` would pass the `src/**` allowed pattern check. Sentinel cannot resolve symlinks without filesystem access on the target host.
+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)
 
@@ -116,7 +166,7 @@ Target matching is deliberately conservative: a command that only _references_ a
 
 ### 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 and unknown tools default to the high (deny) tier.
+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.
 
 ---
 
@@ -140,6 +190,8 @@ On a cold start, the first tool call of a fresh session waits up to **~5 seconds
 - 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
 
 ```
@@ -193,39 +245,46 @@ On a cold start, the first tool call of a fresh session waits up to **~5 seconds
 
 ## 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                                        |
-| 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+)                           |
+| 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)        |
+| 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-5CQ6HKXS.js

@@ -0,0 +1,10 @@
+import {
+  Sentinel
+} from "./chunk-SSDIBY52.js";
+import "./chunk-JTR2E7RD.js";
+import "./chunk-WLIDSTS4.js";
+import "./chunk-NUXSUSYY.js";
+export {
+  Sentinel
+};
+//# sourceMappingURL=Sentinel-5CQ6HKXS.js.map

package/dist/{Sentinel-B_sv8Kiy.d.ts → Sentinel-BVoMEF3F.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,37 @@ 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;
+    /**
+     * Sprint 26B F-5a (corroboration-by-distinct-target). Identity of the RESOLVED
+     * forbidden target the deny fired on: the L1-resolved path when one exists,
+     * else a basename-family fallback (`l2:<sorted basenames>`) for L2-only hits
+     * that never produced a resolved path (unparseable / construct ambiguity).
+     * When present, getEffectiveBlockCount keys distinct-counting on it INSTEAD of
+     * dedupKey, so repeated denials against the same forbidden target — e.g. many
+     * differently-shaped commands all naming one token during self-hosted
+     * development — contribute ONE count toward the escalation ladder, while
+     * distinct forbidden targets still accumulate (a real multi-file sweep
+     * escalates as before). Additive and conditional (soft-signal discipline):
+     * absent on pre-F-5a entries, which keep counting by dedupKey / keyless
+     * exactly as before. NEVER changes the per-command deny disposition.
+     */
+    targetKey?: string;
 }
 /** Computed behavioral baseline for an agent over a time window. */
 /**
@@ -1778,6 +1814,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;
 }