calvana/specs/damage-control.md

Specification: Damage-Control Extension

1. Overview

Damage-Control is a safety and observability extension for the Pi Coding Agent. It enforces security patterns and "Rules of Engagement" by auditing tool calls in real-time. It intercepts potentially dangerous operations and enforces path-based access controls.

2. Core Architecture

• Rule Engine: Loads .pi/damage-control-rules.yaml on session_start. If missing, it defaults to an empty rule set.
• Interception Hook: Uses pi.on("tool_call", handler) to evaluate every tool call before execution.
• Path Resolver: Utility to expand tildes (~) and resolve relative paths against the current working directory (cwd) for accurate matching.

3. Tool Interception Logic

The extension uses isToolCallEventType(toolName, event) for type-safe narrowing of events.

A. Bash Tool (bash)

• Input Field: event.input.command.
• Destructive Patterns: Match bashToolPatterns regex against the raw command string.
• Path Matching: Best-effort heuristic. Match zeroAccessPaths, readOnlyPaths, and noDeletePaths as substrings/regex patterns within the command string.
• Modification Detection: Block any bash command referencing readOnlyPaths patterns to prevent redirects (>), in-place edits (sed -i), or moves/deletes.

B. File Tools (read, write, edit, grep, find, ls)

• Input Field: event.input.path.
• Default Path: For grep, find, and ls, if path is undefined, treat it as ctx.cwd for matching.
• Access Control:
  • Zero Access: Block if path matches any zeroAccessPaths pattern.
  • Grep Glob: Check the glob field of grep (event.input.glob) against zeroAccessPaths.
  • Read Only: Block write or edit calls if path matches readOnlyPaths.
  • No Delete: Block bash calls involving rm or similar on noDeletePaths.

4. Intervention & UI

• Status Indicator: Use ctx.ui.setStatus() to show an indicator of active safety rules (e.g., "🛡️ Damage-Control Active: 142 Rules").
• Violation Feedback: When a violation is blocked or confirmed, update the status temporarily to show the last event (e.g., "⚠️ Last Violation: git reset --hard").
• Blocking: Return { block: true, reason: "Security Policy Violation: [Reason]" }.
• User Confirmation (ask: true):
  • For rules with ask: true, the handler must await ctx.ui.confirm(title, message, { timeout: 30000 }).
  • Return { block: !confirmed, reason: "User denied execution" }.
• Notifications: Use ctx.ui.notify() to alert the user when a rule is triggered.

5. Logging & Persistence

• Every interception (block or confirm) is logged using pi.appendEntry("damage-control-log", { tool, input, rule, action }). This ensures the security audit is part of the permanent session history.

6. Implementation Notes

• Path Resolution: Must match against both raw input (e.g., src/main.ts) and absolute resolved paths. Handle ctx.cwd fallback for optional paths.
• Tilde Expansion: Manually expand ~ to process.env.HOME or os.homedir().
• Graceful Fallback: If YAML parsing fails, notify the user and continue with no active rules rather than crashing the extension.