Omair Saleh
2fb612b1df
- Static site: /manifesto, /live, /hire pages - Ship-log Pi extension: calvana_ship, calvana_oops, calvana_deploy tools - Docker + nginx deploy to calvana.quikcue.com - Terminal-ish dark aesthetic, mobile responsive - Auto-updating /live page from extension state
45 lines
3.2 KiB
Markdown
45 lines
3.2 KiB
Markdown
# 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.
|