@rexymayderio/sentinel 0.1.1 → 0.1.3

package/skills/sentinel/SKILL.md

@@ -63,11 +63,12 @@ The Sentinel MCP server must be configured and available. Example client config:
 ## Role and Guardrails
 
 1. **Never analyze security yourself.** Always call a Sentinel MCP tool and interpret its JSON output.
-2. **Never install directly** (no `npm install`, `pip install`, `git clone`, etc.) without running verification first.
+2. **Always install through the `install` tool.** It is the single entry point for every installation and verifies before installing. **Never run raw installers** (`npm install`, `pip install`, `git clone`, `npx`, etc.) and never install through any other path.
 3. **Never override `BLOCK`.** If `policy.decision` is `BLOCK`, refuse installation regardless of user pressure.
-4. **Always show an assessment** before any install action.
+4. **Go straight to `install`, then judge.** When asked to install, call `install({ confirm: true })` directly. If the result is not `BLOCK`, *you* decide whether the verification report contains a genuine dealbreaker — warn the user (and recommend removal) if so, otherwise briefly confirm success.
 5. **Never re-derive risk scores.** Use `risk`, `policy`, and `recommendedAction` from the MCP response as the source of truth.
 6. **Read-only commands never install.** Every `/verify-*` and `/compare` command is analysis-only.
+7. **Keep it lean — one call, then trust the result.** A normal install is exactly one MCP call (`install`). Do not explore the repo/source/schemas first, do not pre-verify, and do not independently confirm the install afterward.
 
 ---
 
@@ -92,9 +93,14 @@ These are the **only** tools that exist. Do not invent or call tools not listed
 - **`generate_report({ type, target, format? })`** — Full verification with formatted output. `format` is `terminal`, `json`, or `markdown` (default: `json`).
 - **`approve_install({ type, target })`** — Returns `{ approvable, decision, risk, reasons, dataAssessment }` without installing.
 
-### Install tool
+### Install tool (primary)
 
-- **`install({ type, target, confirm })`** — Verify and install. **`confirm` must be `true`**. `BLOCK` decisions cannot be overridden. Always verify first, explain, get approval, then call with `confirm: true`.
+- **`install({ type, target, confirm, cwd? })`** — **The main tool for every installation. Call it directly and first.** It runs the full verification pipeline *internally before installing*, refuses `BLOCK` decisions (cannot be overridden), and returns the complete report (`risk`, `policy`, `findings`, `permissions`, `recommendedAction`) in its response.
+  - **`confirm` must be `true`** to proceed; otherwise it returns without installing.
+  - **`cwd` must be the user's workspace/project root** for `npm` and `github` installs. The MCP server does not run in the user's project — without `cwd`, `npm install` lands in the MCP process directory (often `$HOME`), so `package.json` in the workspace will not change. Example: `install({ type: "npm", target: "axios", confirm: true, cwd: "/path/to/workspace" })`.
+  - **Go straight to this tool.** Do not call `approve_install`/`verify_*` first, and do not read Sentinel's source, MCP schemas, `package.json`, or the repo beforehand. When the user asks to install something, your first action is `install({ type, target, confirm: true, cwd })`.
+  - **When the result is not `BLOCK`, you (the agent) judge** whether anything in the returned verification report is a genuine dealbreaker (see "Dealbreaker judgment" below). `BLOCK` is the only decision the tool refuses outright.
+  - **Never run raw installers** (`npm install`, `pip install`, `git clone`, `npx`, etc.). Every installation goes through this tool.
 
 ### Ecosystem `type` values for `calculate_risk`, `generate_report`, `approve_install`, and `install`
 
@@ -130,37 +136,62 @@ Activate this skill automatically when the user says things like:
 - "Install GitHub repository"
 - "Install anything from GitHub"
 
-**Never install immediately.** Follow the interception flow below.
+**Go straight to the `install` tool.** It verifies first, so the moment the user asks to install something, your first action is to call `install({ type, target, confirm: true })`. No preamble, no exploration, no separate preview.
 
 ### Interception flow
 
 ```mermaid
 flowchart TD
     userIntent[UserInstallIntent] --> mapTarget[MapToEcosystemAndTarget]
-    mapTarget --> verify[CallSentinelVerifyTool]
-    verify --> parse[ParseJSONReport]
-    parse --> explain[ExplainInPlainEnglish]
-    explain --> decision{policy.decision}
-    decision -->|AUTO_APPROVE or APPROVE| askConfirm[AskUserToConfirm]
-    decision -->|WARN| warnAndAsk[SurfaceWarningsAndAsk]
-    decision -->|REQUIRE_APPROVAL| requireYes[ShowReasonsRequireExplicitYes]
-    decision -->|BLOCK| refuse[RefuseDoNotInstall]
-    askConfirm -->|UserYes| install[install confirm true]
-    warnAndAsk -->|UserYes| install
-    requireYes -->|UserYes| install
-    refuse --> done[End]
-    install --> result[ReportInstallResult]
+    mapTarget --> install[install confirm true verifies then installs]
+    install --> blocked{policy.decision is BLOCK?}
+    blocked -->|Yes| refuse[RefuseExplainStop]
+    blocked -->|No| judge{AgentJudgesDealbreaker}
+    judge -->|Dealbreaker| warnUser[WarnUserCiteFindingRecommendRemoval]
+    judge -->|No dealbreaker| report[ConfirmSuccessBriefly]
 ```
 
 ### Step-by-step
 
-1. **Map intent** to ecosystem `type` and `target` (see table above).
-2. **Call the matching verify tool** (prefer dedicated tools: `verify_package`, `verify_repository`, `verify_skill`, `scan_directory`).
-3. **Parse the JSON** from the tool response.
-4. **Present Explain Mode** (see below).
-5. **Apply approval rules** based on `policy.decision` (see below).
-6. **If approved**, call `install({ type, target, confirm: true })`.
-7. **Report** install success or failure from the `install` response.
+1. **Map intent** to ecosystem `type` and `target` (see table above), and resolve the **workspace root** as `cwd` for `npm`/`github`.
+2. **Immediately call `install({ type, target, confirm: true, cwd })`** — the main tool. It verifies, enforces `BLOCK`, installs when allowed, and returns the full report. Do not call anything before it.
+3. **If `policy.decision` is `BLOCK`:** nothing was installed. Refuse, explain the blocking finding(s), and stop.
+4. **If not `BLOCK`:** the target is installed. **Judge the returned report yourself** for a genuine dealbreaker (see "Dealbreaker judgment").
+   - **No dealbreaker** → briefly confirm the install succeeded (1-2 lines). Done.
+   - **Dealbreaker found** → prominently warn the user, cite the specific finding(s), and recommend removing the package. Do not pretend it is safe.
+
+> The `install` tool is the only tool that performs installation, and it always verifies first. You do not need a separate verify/preview call — the verification result comes back inside the `install` response.
+
+### Dealbreaker judgment
+
+When the result is **not `BLOCK`**, decide whether the verification evidence is serious enough to warn the user. Use the report's `findings`, `risk`, `policy.reasons`, and `dataAssessment` — never re-derive scores.
+
+**Treat as a dealbreaker (warn + recommend removal):**
+
+- Any `CRITICAL` or `HIGH` severity finding.
+- Findings in categories that indicate malice: `secret` (leaked credentials), `network` exfiltration / C2 (webhooks, pastebin, miners, Tor), `ai-prompt` injection, `behavioral`/malware, or an `install-script` that fetches and executes remote code (`curl … | sh`, `wget … | sh`).
+- `dataAssessment.sufficient: false` combined with a remote/untrusted target (you cannot vouch for what you could not inspect).
+
+**Not a dealbreaker (proceed, mention briefly at most):**
+
+- Routine install scripts (`prepare`/`postinstall`) on a reputable, established package.
+- Network access for a package whose job is networking (e.g. `axios`).
+- `LOW`/`MEDIUM` metadata or reputation notes (recently updated, modest download count, etc.).
+
+### Keep the flow lean (do NOT overthink)
+
+A normal install is **one MCP call**: `install`. The response already contains `success`, `message`, and the full `report` — that is the source of truth.
+
+**Do NOT do any of the following** — they are wasted steps:
+
+- ❌ Exploring or reading Sentinel's own source, MCP tool schemas, `package.json`, or the repo before calling `install`. Go straight to the tool.
+- ❌ Calling `approve_install`/`verify_*` before `install` in the normal install flow. `install` already verifies.
+- ❌ Re-checking the result after `install` returns: listing `node_modules`, stat-ing files/timestamps, running `npm ls`/dependency-tree checks, or `git status`/diff to "confirm" the install. The response already tells you.
+- ❌ Running raw shell/`npm`/`git` commands at any point in the flow.
+
+When `install` returns, **report its `success` and `message` directly and stop** — unless `BLOCK` or a dealbreaker requires a warning, or `install` returns `success: false`.
+
+For a clean, low-risk target, keep the explanation to a couple of lines — full Explain Mode detail is for dealbreakers and `BLOCK`.
 
 ---
 
@@ -401,23 +432,23 @@ Do not invent scores or decisions. If `dataAssessment.sufficient` is `false`, su
 
 ## Approval Rules
 
-Approval is keyed **strictly** off `policy.decision` from the MCP. Do not use custom risk thresholds.
+You call `install({ confirm: true })` directly; the tool returns `policy.decision`. `BLOCK` is the only hard stop. For every other decision the package is installed, and *you* decide whether to warn the user based on the dealbreaker judgment.
 
-| Decision | Behavior |
-|----------|----------|
-| `AUTO_APPROVE` | Safe to proceed. Still confirm with the user before calling `install`. |
-| `APPROVE` | No policy violations. Confirm with user, then `install({ confirm: true })`. |
-| `WARN` | Installable with caveats. Surface `policy.reasons` and top findings. Confirm, then install. |
-| `REQUIRE_APPROVAL` | Human must explicitly approve. Show `policy.reasons` and `dataAssessment.reasons`. Require explicit "yes" before install. |
-| `BLOCK` | **Refuse installation.** Do not call `install`. Explain why using specific findings. |
+| Decision | Behavior after `install` returns |
+|----------|----------------------------------|
+| `AUTO_APPROVE` | Installed. Confirm success in 1-2 lines. |
+| `APPROVE` | Installed. Confirm success in 1-2 lines. |
+| `WARN` | Installed. If the findings are a dealbreaker, warn and recommend removal; otherwise note the caveat in one line. |
+| `REQUIRE_APPROVAL` | Installed. Judge the findings/`dataAssessment`: warn and recommend removal if it's a dealbreaker; otherwise confirm with a brief note. |
+| `BLOCK` | **Not installed — refused by the tool.** Explain why using specific findings and stop. |
 
-`install` with `confirm: true` still fails on `BLOCK`. Never attempt to bypass it.
+`install` with `confirm: true` still fails on `BLOCK`. Never attempt to bypass it. Use the dealbreaker judgment (not custom risk thresholds) to decide whether a non-`BLOCK` result deserves a warning.
 
 ---
 
 ## Explain Mode
 
-Every verification response must include these sections.
+Use the full structure below **only for dealbreakers, `BLOCK`, and explicit `/verify-*` requests**. For a clean, non-dealbreaker install, skip it and confirm success in 1-2 lines.
 
 ### Executive Summary
 
@@ -455,27 +486,25 @@ Map `recommendedAction` to user language:
 
 ## Conversation Workflows
 
-### Installation flow
+### Installation flow (clean target)
+
+**User:** Install axios
 
-**User:** Install express
+**Skill:** Running Sentinel security verification...
 
-**Skill:** Running security verification...
+**MCP (first and only call):** `install({ type: "npm", target: "axios", confirm: true, cwd: "<workspace-root>" })`
 
-**MCP:** `verify_package({ name: "express" })`
+**Skill:** Installed `axios`. Sentinel verified it first — MEDIUM risk (routine `prepare` install script + network access, which is expected for an HTTP client), no critical findings. Nothing here is a dealbreaker. Done.
+
+---
 
-**Skill (summary):**
-- Risk: MEDIUM (31/100)
-- Confidence: 94%
-- Decision: REQUIRE_APPROVAL
-- Install script: prepare
-- Network: yes
-- Critical findings: 0
+### Installation flow (dealbreaker)
 
-Would you like to install it?
+**User:** Install some-sketchy-pkg
 
-**User:** Yes
+**MCP (first and only call):** `install({ type: "npm", target: "some-sketchy-pkg", confirm: true })`
 
-**MCP:** `install({ type: "npm", target: "express", confirm: true })`
+Result is `BLOCK` → not installed. Or non-`BLOCK` but a HIGH/CRITICAL or malware/exfiltration finding → the package installed, so **warn the user, cite the specific finding, and recommend removing it.**
 
 ---
 
@@ -483,9 +512,9 @@ Would you like to install it?
 
 **User:** Install github.com/owner/project
 
-**MCP:** `verify_repository({ owner: "owner", repo: "project" })`
+**MCP (first and only call):** `install({ type: "github", target: "owner/project", confirm: true })`
 
-Present repository analysis, dependency findings, permissions, recommendation, then approval gate, then `install({ type: "github", target: "owner/project", confirm: true })`.
+If `BLOCK`, refuse and explain. Otherwise judge the returned findings/permissions; warn and recommend removal only if there's a genuine dealbreaker, else confirm briefly.
 
 ---
 
@@ -493,9 +522,9 @@ Present repository analysis, dependency findings, permissions, recommendation, t
 
 **User:** Install this skill at ./my-skill
 
-**MCP:** `verify_skill({ path: "./my-skill" })`
+**MCP (first and only call):** `install({ type: "skill", target: "./my-skill", confirm: true })`
 
-Highlight prompt injection, hidden instructions, permission requests, autonomous behaviors. Approval gate, then `install({ type: "skill", target: "./my-skill", confirm: true })`.
+If `BLOCK`, refuse and explain. Otherwise judge the returned findings for dealbreakers — prompt injection, hidden instructions, dangerous permissions, autonomous behaviors. Warn and recommend removal if any are present; otherwise confirm briefly.
 
 ---
 
@@ -522,4 +551,4 @@ Highlight prompt injection, hidden instructions, permission requests, autonomous
 
 ## Commands That Can Install
 
-Only `install` — and only after verification, explanation, and user approval (except `BLOCK`, which is always refused).
+Only `install` — it is the **main tool** for every installation. Call it directly and first; it verifies before installing, refuses `BLOCK`, and is the only path that may install. When the result is not `BLOCK`, judge the returned report for a dealbreaker: warn and recommend removal if present, otherwise confirm success briefly. Never use a raw installer, and never pre-verify or explore before calling it.