@tuent/sentinel 0.1.1 → 0.1.2

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,31 @@ 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`
 
+### 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 +115,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 +157,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 +181,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 +236,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-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-WPTJBRX5.js → chunk-FWIISAZZ.js}

@@ -6,8 +6,12 @@ import {
   discoverPolicy
 } from "./chunk-FMZWHT4M.js";
 import {
+  FORBIDDEN_BASENAMES
+} from "./chunk-QIYQWOLO.js";
+import {
+  loadPolicy,
   loadPolicyFromString
-} from "./chunk-2FFMYSVC.js";
+} from "./chunk-WLIDSTS4.js";
 
 // src/setup/initClaudeCode.ts
 import { access, writeFile as writeFile2, mkdir as mkdir2 } from "fs/promises";
@@ -17,12 +21,16 @@ import { createServer } from "http";
 import { fileURLToPath } from "url";
 
 // src/gateway/hookScriptSource.ts
+var SCORER_CRITICAL_EXTRAS = ["shadow", "passwd"];
+var HOOK_SENSITIVE_BASENAMES = [
+  .../* @__PURE__ */ new Set([...FORBIDDEN_BASENAMES, ...SCORER_CRITICAL_EXTRAS])
+];
 var HOOK_SCRIPT_SOURCE = `#!/usr/bin/env node
 // Sentinel cc hook bridge \u2014 generated by sentinel init claude-code
 // Do not edit manually; regenerate with: sentinel init claude-code --force
 
 import { readFileSync, appendFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { join, resolve, sep } from "node:path";
 import { spawn } from "node:child_process";
 
 const GATEWAY_ENTRY_POINT = "__GATEWAY_ENTRY_POINT__";
@@ -74,6 +82,17 @@ function logFallback(entry) {
   try { appendFileSync(FALLBACK_LOG, line + "\\n"); } catch { /* best effort */ }
 }
 
+// Sprint 26 Fix-2 Part 1 \u2014 hardcoded fail-closed FLOOR. tiers.json may ADD
+// high-tier tools but can never DOWNGRADE a floor tool to low (defeats the
+// two-step tier-config rewrite). Checked BEFORE the editable tiers below.
+const FLOOR_HIGH = ["Bash", "Write", "Edit", "WebFetch", "NotebookEdit", "Task", "Skill"];
+
+// Item D \u2014 operator allowUnknownTools escape hatch, baked at init from the
+// launch policy so it survives gateway-down (the daemon allows these names
+// unconditionally at the name level, so allowing them here keeps down \u2287 up).
+// The marker default is [] \u2014 an un-substituted script stays strictest.
+const ALLOW_UNKNOWN_TOOLS = /* __ALLOW_UNKNOWN_TOOLS__ */ [];
+
 // Tier config uses flat format: { high, low, mcpDefault, unknownDefault } (plan v3.1 spec'd nested but simplified during 5a)
 function loadTiers() {
   try {
@@ -90,10 +109,52 @@ function loadTiers() {
 }
 
 function isHighSensitivity(toolName, tiers) {
+  if (FLOOR_HIGH.includes(toolName)) return true; // floor: tiers may add high, never downgrade
   if (tiers.high && tiers.high.includes(toolName)) return true;
   if (tiers.low && tiers.low.includes(toolName)) return false;
   if (toolName.startsWith("mcp__")) return tiers.mcpDefault === "high";
-  return tiers.unknownDefault === "high";
+  // Item D \u2014 operator-allowlisted names pass: gateway-up they are translated
+  // as known and allowed at the name level, so the escape hatch must survive
+  // gateway-down too.
+  if (ALLOW_UNKNOWN_TOOLS.includes(toolName)) return false;
+  // Item D floor: all other unknown names are always high-tier gateway-down.
+  // Deliberately stricter than gateway-up's warn default: the hook cannot
+  // persist findings while the daemon is down, so a warn-equivalent here
+  // would be allow-UNLOGGED \u2014 the exact F-8 hole. Hard-deny keeps down \u2287 up
+  // in both knob modes (same fail-closed stance as Fix-2's read handling),
+  // and a tiers.json edit (unknownDefault: "low") cannot reopen it. Named
+  // tools can still be tiered low explicitly via tiers.low above.
+  return true;
+}
+
+// Sprint 26 Fix-2 Part 2 \u2014 gateway-down safe-read exception.
+// INVARIANT: on gateway-down a read is NEVER more permissive than gateway-up.
+// Low-tier file reads (Read/Glob/Grep) fail CLOSED by default; only a
+// structurally-provably-safe target is allowed. The guard is GENERATED from the
+// canonical FORBIDDEN_BASENAMES (\u222A scorer extras), so it can't drift open.
+const SENSITIVE_BASENAMES = ${JSON.stringify(HOOK_SENSITIVE_BASENAMES)};
+const READ_TOOL_PATH_KEYS = { Read: "file_path", Glob: "pattern", Grep: "path" };
+
+function isProvablySafeRead(toolName, toolInput, payloadCwd) {
+  const key = READ_TOOL_PATH_KEYS[toolName];
+  if (!key) return false; // not a path-bearing read tool \u2014 not provably safe
+  const raw = toolInput && toolInput[key];
+  if (typeof raw !== "string" || raw.length === 0) return false; // no target \u2192 not provable
+  if (raw[0] === "/" || raw[0] === "~") return false; // absolute / home \u2192 fail closed
+  const cwd = typeof payloadCwd === "string" && payloadCwd ? payloadCwd : process.cwd();
+  const cwdNorm = resolve(cwd);
+  const norm = resolve(cwd, raw);
+  // Must resolve strictly within cwd (rejects any .. escape).
+  if (norm !== cwdNorm && !norm.startsWith(cwdNorm + sep)) return false;
+  const segments = norm.slice(cwdNorm.length).split(sep).filter(Boolean);
+  for (const seg of segments) {
+    const low = seg.toLowerCase();
+    if (low[0] === ".") return false; // dotfile / dot-dir
+    for (const s of SENSITIVE_BASENAMES) {
+      if (low.includes(s.toLowerCase())) return false; // conservative sensitive-token match
+    }
+  }
+  return true;
 }
 
 // ---------------------------------------------------------------------------
@@ -111,15 +172,29 @@ if (mode === "pre") {
     const result = JSON.parse(resp.body);
     process.stdout.write(JSON.stringify(result), () => process.exit(0));
   } catch {
-    // Gateway unreachable \u2014 tiered fail-closed
+    // Gateway unreachable \u2014 tiered fail-closed (Sprint 26 Fix-2).
     const tiers = loadTiers();
+    const restore = "Restart your Claude Code session to relaunch the gateway; see ~/.dahlia/gateway-fallback.log.";
     if (isHighSensitivity(toolName, tiers)) {
       logFallback({ event: "fail-closed-block", tool: toolName, tier: "high" });
       process.stderr.write(
-        \`Sentinel gateway unreachable; high-sensitivity tool "\${toolName}" blocked per fail-closed policy\`,
+        \`Sentinel gateway unreachable; high-sensitivity tool "\${toolName}" blocked per fail-closed policy. \${restore}\`,
+        () => process.exit(2),
+      );
+    } else if (
+      READ_TOOL_PATH_KEYS[toolName] &&
+      !isProvablySafeRead(toolName, payload.tool_input || {}, payload.cwd)
+    ) {
+      // Low-tier read whose target is not provably safe \u2192 fail CLOSED. The hook
+      // carries no policy, so it cannot evaluate the forbid surface; a read it
+      // can't prove safe is treated as if the gateway would deny it.
+      logFallback({ event: "fail-closed-block", tool: toolName, tier: "low", reason: "read-not-provably-safe" });
+      process.stderr.write(
+        \`Sentinel gateway unreachable; read by "\${toolName}" blocked (fail-closed: target not provably safe). \${restore}\`,
         () => process.exit(2),
       );
     } else {
+      // Provably-safe read, or a non-read low-tier tool (e.g. WebSearch) \u2192 allow.
       logFallback({ event: "fail-closed-allow", tool: toolName, tier: "low" });
       process.stdout.write(JSON.stringify({
         hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "allow" },
@@ -322,6 +397,11 @@ agent:
 policy:
   allow:
     actions: [file_read, file_write, tool_invocation, network_request, command_exec]
+    # allow.targets is ADVISORY for file_read / file_write / tool_invocation: an
+    # access outside this list is logged as a MEDIUM scope_violation but still
+    # runs \u2014 Sentinel governs the agent's own tool calls, it is not a filesystem
+    # sandbox. forbid.targets below is the hard deny. network_request is the
+    # exception: unlisted hosts are DENIED by default (see the networkHosts note).
     targets:
       - "src/**"
       - "test/**"
@@ -378,6 +458,28 @@ policy:
       - "**/*.pem"
       - "**/*.key"
       - "/etc/**"
+      # Sprint 26 FIX 1 (A) \u2014 common credential stores. DRIFT: keep in sync with
+      # DEFAULT_FORBIDDEN_PATTERNS in defaults.ts (unification tracked separately).
+      - "**/.netrc"
+      - "**/.npmrc"
+      - "**/.git-credentials"
+      - "**/.pgpass"
+      - "**/.zsh_history"
+      - "**/.config/gh/**"
+      - "**/.docker/config.json"
+      - "**/.gnupg/**"
+      - "**/.config/gcloud/**"
+      - "**/.kube/**"
+      - "**/Library/Keychains/**"
+      # Sprint 26 FIX 1 (B) \u2014 Sentinel's own state dir (current path only).
+      - "**/.dahlia/**"
+      # Sprint 26 FIX 3 \u2014 this policy file and cc's hook-wiring settings files.
+      # Agent tool-writes are denied; reads stay allowed via a code-side ceiling
+      # exception (not authorable here \u2014 workspace-authored exceptions are
+      # dropped by the ceiling merge, by design). DRIFT: keep in sync with
+      # DEFAULT_FORBIDDEN_PATTERNS in defaults.ts.
+      - "**/.sentinel.yaml"
+      - "**/.claude/settings*.json"
 enforcement:
   restrictAfter: 3
   quarantineAfter: 5
@@ -418,7 +520,16 @@ async function runInitClaudeCode(options) {
   );
   const hookPath = join(dahliaDir, "cc-hook.mjs");
   const gatewayEntryPoint = resolveGatewayEntryPoint();
-  const hookContent = HOOK_SCRIPT_SOURCE.replace(/__GATEWAY_ENTRY_POINT__/g, gatewayEntryPoint);
+  let allowUnknownTools = [];
+  try {
+    const effectivePolicy = await loadPolicy(policyPath);
+    allowUnknownTools = effectivePolicy.enforcement?.allowUnknownTools ?? [];
+  } catch {
+  }
+  const hookContent = HOOK_SCRIPT_SOURCE.replace(
+    /__GATEWAY_ENTRY_POINT__/g,
+    gatewayEntryPoint
+  ).replace("/* __ALLOW_UNKNOWN_TOOLS__ */ []", JSON.stringify(allowUnknownTools));
   if (hookContent.includes("__GATEWAY_ENTRY_POINT__")) {
     throw new Error("Failed to substitute all __GATEWAY_ENTRY_POINT__ placeholders");
   }
@@ -536,4 +647,4 @@ export {
   runInitClaudeCode,
   runSessionStart
 };
-//# sourceMappingURL=chunk-WPTJBRX5.js.map
+//# sourceMappingURL=chunk-FWIISAZZ.js.map