Feature: Decision engine (allow/deny/ask)

[ProduktEntdecker]

Overview

Determine whether to allow, deny, or ask user confirmation based on vulnerability scan results.

Depends On

• Feature: OSV API integration for vulnerability checks #3 (OSV API integration)

Acceptance Criteria

• DENY if any CRITICAL or HIGH severity vulnerabilities found
• ASK if MEDIUM severity vulnerabilities found
• ALLOW if no vulnerabilities or only LOW severity
• Include vulnerability details in denial reason
• Suggest fixed version in denial message
• Format output as valid hook JSON response

Decision Matrix

Severity	Decision	Action
CRITICAL	deny	Block with details
HIGH	deny	Block with details
MEDIUM	ask	Prompt user
LOW	allow	Proceed with warning
None	allow	Proceed silently

Output Examples

// Deny
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "🚨 lodash@4.17.0 has 2 HIGH vulnerabilities:\n- CVE-2021-23337: Prototype Pollution\n- CVE-2020-8203: Prototype Pollution\n\n💡 Update to lodash@4.17.21"
  }
}

Priority: P1

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Feature: OSV API integration for vulnerability checks #3
• Test: Unit tests for parser and decision engine #6
• Pivot: CLI hook scaffold replacing MCP server #1
• Docs: Update README for hook installation #5

👤 Suggested Assignees

• ProduktEntdecker

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

Implement a decision engine that evaluates vulnerability scan results and determines whether to allow, deny, or ask for user confirmation when packages are being installed. The engine will be reusable across both the existing MCP tool and a new Claude Code PreToolUse hook implementation. Output must be formatted as a valid Claude Code PreToolUse hook JSON response.

Observations

PatchPilot is a Node.js MCP server that scans npm packages for vulnerabilities using the OSV API. The current implementation provides a check_package tool that queries OSV, maps severity levels (CRITICAL/HIGH/MEDIUM/LOW), and returns formatted text reports. The codebase uses TypeScript with minimal dependencies (@modelcontextprotocol/sdk, zod), has type definitions in src/types/osv.ts, and implements all OSV API logic in src/index.ts with helper functions for severity mapping and vulnerability formatting.

Assumptions

Assumption 1: Hook Entry Point Architecture

Options Considered:

• Replace the MCP server with a hook script entirely
• Add mode detection to switch between MCP tool and hook behavior in the same entry point
• Create a separate hook entry point (src/hook.ts) that shares core decision logic with the existing MCP tool

Chosen Option: 3

Rationale: Separate entry points provide clean separation of concerns, allow both use cases to coexist, and follow the pattern of extending rather than replacing existing functionality. The ticket depends on issue #3 (OSV API integration), which is already implemented as an MCP tool. The decision engine needs to work as a Claude Code hook, not replace the existing MCP functionality.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Extract Decision Logic into Reusable Module

Create a standalone decision engine that can be used by both the MCP tool and the hook. This module encapsulates the severity-based decision matrix and message formatting.

Task 1: Create Decision Engine Module

Create the core decision-making logic as a reusable module

• Create src/decision.ts to house the decision engine logic
• Export a makeDecision() function that accepts an OsvQueryResponse and returns a decision object with fields: decision (allow/deny/ask), severity (highest severity found), reason (formatted explanation), and fixVersion (suggested version if available)
• Implement the decision matrix: CRITICAL/HIGH → deny, MEDIUM → ask, LOW/UNKNOWN/none → allow
• Use existing helper functions (getHighestSeverity(), findFixedVersion()) from types module
• Return structured data rather than pre-formatted strings to allow different output formats

Task 2: Create Message Formatting Utilities

Build helpers for generating user-facing messages in different contexts

• Add message formatting functions to src/decision.ts for deny/ask/allow scenarios
• Format vulnerability lists with CVE IDs, summaries, and severity levels
• Include emoji indicators consistent with existing patterns (🚨 for critical, ⚠️ for high, etc.)
• Generate fix suggestions when fixed versions are available
• Keep functions pure and testable (input: decision object, output: formatted string)

🤖 Prompt for AI agents

Create a reusable decision engine module that evaluates vulnerability scan
results and provides structured decision output.

Create `src/decision.ts` with:
- Export `makeDecision()` function accepting `OsvQueryResponse`, returning
decision object with fields: decision (allow/deny/ask), severity, reason,
fixVersion
- Implement decision matrix: CRITICAL/HIGH → deny, MEDIUM → ask,
LOW/UNKNOWN/none → allow
- Use existing `getHighestSeverity()` and `findFixedVersion()` helpers from
types module
- Add message formatting functions for deny/ask/allow scenarios with
vulnerability lists, CVE IDs, summaries, severity levels
- Include emoji indicators (🚨 critical, ⚠️ high, etc.) and fix suggestions
- Return structured data to support different output formats

Phase 2: Implement Hook Entry Point

Build a new entry point that implements the Claude Code PreToolUse hook specification, reading JSON from stdin and outputting hook-formatted JSON to stdout.

Task 1: Create Hook Entry Point Script

Implement the stdin/stdout hook interface

• Create src/hook.ts as the hook entry point script with Node.js shebang
• Read and parse JSON from stdin to extract tool_name and tool_input fields from the hook event
• Validate that this is a package installation tool (e.g., npm_install, add_dependency) - allow all other tools to proceed
• Extract package name and version from tool_input parameters
• Add error handling for malformed input with appropriate exit codes

Task 2: Integrate Decision Engine with Hook Output

Connect the decision engine to hook JSON output format

• Call queryOsv() (from src/index.ts) with extracted package parameters
• Pass OSV response to decision engine's makeDecision() function
• Map decision result to hook JSON format with hookSpecificOutput containing hookEventName: "PreToolUse", permissionDecision (deny/ask/approve), and permissionDecisionReason
• Write JSON to stdout using console.log(JSON.stringify(...))
• Exit with code 0 for all cases (let JSON response control the decision rather than exit codes)

Task 3: Add Hook Configuration

Update project configuration to support hook execution

• Update package.json to add a bin field pointing to compiled hook script in dist/hook.js
• Add build configuration in tsconfig.json to ensure hook script is compiled with executable permissions
• Create example hook configuration in README showing how to register the hook with Claude Code
• Consider adding an npm script (e.g., npm run hook) for manual testing with sample JSON input

🤖 Prompt for AI agents

Build Claude Code PreToolUse hook entry point that reads JSON from stdin and
outputs hook-formatted JSON to stdout.

Create `src/hook.ts` with:
- Add Node.js shebang
- Read and parse JSON from stdin, extract tool_name and tool_input
- Validate package installation tools (npm_install, add_dependency), allow
others to proceed
- Extract package name and version from tool_input
- Call `queryOsv()` with package parameters
- Pass response to `makeDecision()` from decision engine
- Map decision to hook JSON with hookSpecificOutput containing hookEventName:
"PreToolUse", permissionDecision (deny/ask/approve), permissionDecisionReason
- Write JSON to stdout, exit with code 0
- Add error handling for malformed input

Update configuration:
- Add `bin` field in package.json pointing to dist/hook.js
- Configure tsconfig.json for executable compilation
- Add README example for hook registration with Claude Code
- Add npm script for manual testing

Phase 3: Refactor MCP Tool to Use Decision Engine (Optional Enhancement)

Optionally update the existing MCP tool to leverage the shared decision logic for consistency.

Update MCP Tool Response Format

Align MCP tool output with decision engine structure

• Modify the check_package tool handler in src/index.ts to call the decision engine
• Keep the existing detailed vulnerability report format but add a clear decision section at the top
• Prepend decision result (✅ SAFE TO INSTALL / ⚠️ REVIEW REQUIRED / 🚨 NOT RECOMMENDED) to the response
• Maintain backward compatibility by adding to the response rather than replacing existing format
• Consider making this change optional if the current format is preferred for the MCP tool use case

🤖 Prompt for AI agents

Optionally enhance the existing MCP tool to use the shared decision engine for
consistent output.

Update `src/index.ts`:
- Modify `check_package` tool handler to call decision engine's `makeDecision()`
- Prepend decision result to response (✅ SAFE TO INSTALL / ⚠️ REVIEW REQUIRED /
🚨 NOT RECOMMENDED)
- Keep existing detailed vulnerability report format for backward compatibility
- Add decision section at the top without replacing existing format

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Create a reusable decision engine module that evaluates vulnerability scan
results and provides structured decision output.

Create `src/decision.ts` with:
- Export `makeDecision()` function accepting `OsvQueryResponse`, returning
decision object with fields: decision (allow/deny/ask), severity, reason,
fixVersion
- Implement decision matrix: CRITICAL/HIGH → deny, MEDIUM → ask,
LOW/UNKNOWN/none → allow
- Use existing `getHighestSeverity()` and `findFixedVersion()` helpers from
types module
- Add message formatting functions for deny/ask/allow scenarios with
vulnerability lists, CVE IDs, summaries, severity levels
- Include emoji indicators (🚨 critical, ⚠️ high, etc.) and fix suggestions
- Return structured data to support different output formats
===============================================================================

Task: 2

Build Claude Code PreToolUse hook entry point that reads JSON from stdin and
outputs hook-formatted JSON to stdout.

Create `src/hook.ts` with:
- Add Node.js shebang
- Read and parse JSON from stdin, extract tool_name and tool_input
- Validate package installation tools (npm_install, add_dependency), allow
others to proceed
- Extract package name and version from tool_input
- Call `queryOsv()` with package parameters
- Pass response to `makeDecision()` from decision engine
- Map decision to hook JSON with hookSpecificOutput containing hookEventName:
"PreToolUse", permissionDecision (deny/ask/approve), permissionDecisionReason
- Write JSON to stdout, exit with code 0
- Add error handling for malformed input

Update configuration:
- Add `bin` field in package.json pointing to dist/hook.js
- Configure tsconfig.json for executable compilation
- Add README example for hook registration with Claude Code
- Add npm script for manual testing
===============================================================================

Task: 3

Optionally enhance the existing MCP tool to use the shared decision engine for
consistent output.

Update `src/index.ts`:
- Modify `check_package` tool handler to call decision engine's `makeDecision()`
- Prepend decision result to response (✅ SAFE TO INSTALL / ⚠️ REVIEW REQUIRED /
🚨 NOT RECOMMENDED)
- Keep existing detailed vulnerability report format for backward compatibility
- Add decision section at the top without replacing existing format

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!