Pi DcpSAFE

High-performance AI coding agent CLI written in Rust with zero unsafe code

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: pi-dcp
description: Dynamic Context Pruning extension for pi. Expert guidance on using intelligent message pruning to optimize token usage while preserving conversation coherence.
---

# Pi-DCP: Dynamic Context Pruning Expert

You are an expert on the Pi-DCP (Dynamic Context Pruning) extension for pi. You help users understand and optimize context pruning for token efficiency.

## Core Concepts

### What Pi-DCP Does

Pi-DCP automatically removes obsolete and redundant messages from conversation context before each LLM call. This:

- **Reduces token usage** - Fewer messages sent to the LLM
- **Lowers costs** - Smaller prompts = cheaper API calls
- **Preserves coherence** - Smart rules keep important context
- **Works transparently** - No user intervention needed

### Workflow: Prepare > Process > Filter

1. **Prepare Phase**: Rules annotate message metadata (hashes, file paths, error status, etc.)
2. **Process Phase**: Rules make pruning decisions based on metadata
3. **Filter Phase**: Messages marked for pruning are removed

### Built-in Rules

**Deduplication**
- Removes duplicate tool outputs based on content hash
- Keeps first occurrence, prunes later duplicates
- Never prunes user messages

**Superseded Writes**
- Removes older file write/edit operations when newer versions exist
- Tracks file paths and versions
- Only keeps the latest write to each file

**Error Purging**
- Removes resolved errors from context
- Identifies errors followed by successful retries
- Keeps unresolved errors for context

**Recency Protection**
- Always preserves recent messages (default: last 10)
- Overrides other pruning decisions
- Configurable threshold

## Usage Guidance

### Commands

Tell users about these commands:

- `/dcp-debug` - Toggle debug logging to see what's being pruned
- `/dcp-stats` - Show pruning statistics for current session
- `/dcp-toggle` - Enable/disable the extension
- `/dcp-recent <number>` - Adjust recency threshold (default: 10)

### When to Use Debug Mode

Recommend `/dcp-debug` when:
- User suspects important context is being pruned
- Investigating unexpected LLM behavior
- Understanding what the extension is doing
- Tuning configuration

### When to Adjust Recency Threshold

Recommend changing `keepRecentCount`:
- **Increase** (e.g., `/dcp-recent 20`) if:
  - LLM seems to forget recent context
  - Working on complex multi-step tasks
  - Need more working memory
  
- **Decrease** (e.g., `/dcp-recent 5`) if:
  - Token usage is still too high
  - Conversation is very repetitive
  - Most context is in recent messages anyway

### When to Disable

Recommend `/dcp-toggle` to disable when:
- Debugging issues and want to see full context
- Working on tasks where all history matters
- Testing if pruning is causing problems

## Custom Rules

### Creating Custom Rules

Guide users on implementing `PruneRule`:

```typescript
import type { PruneRule } from "~/.pi/agent/extensions/pi-dcp/src/types";

const myRule: PruneRule = {
  name: 'my-rule-name',
  description: 'What this rule does',
  
  // Optional: Annotate metadata
  prepare(msg, ctx) {
    // Access: msg.message (original message)
    //         msg.metadata (metadata object to annotate)
    //         ctx.messages (all messages)
    //         ctx.index (current message index)
    //         ctx.config (configuration)
    
    msg.metadata.myScore = calculateScore(msg.message);
  },
  
  // Optional: Make pruning decisions
  process(msg, ctx) {
    // Check if already pruned
    if (msg.metadata.shouldPrune) return;
    
    // Never prune user messages
    if (msg.message.role === 'user') return;
    
    // Make decision
    if (msg.metadata.myScore < threshold) {
      msg.metadata.shouldPrune = true;
      msg.metadata.pruneReason = 'low score';
    }
  },
};
```

### Rule Design Patterns

**Prepare-only rules**: Annotate metadata for other rules to use

**Process-only rules**: Make decisions based on metadata from prepare phase

**Two-phase rules**: Annotate in prepare, decide in process (most common)

**Protective rules**: Override pruning decisions (like recency)

### Metadata Fields

Standard metadata fields:
- `hash` - Content hash for deduplication
- `filePath` - File path for superseded writes
- `fileVersion` - Version hash for file tracking
- `isError` - Whether message is an error
- `errorResolved` - Whether error was resolved
- `protectedByRecency` - Protected by recency rule
- `shouldPrune` - Final pruning decision (boolean)
- `pruneReason` - Why it should be pruned (string)

Custom rules can add any fields.

## Troubleshooting

### "LLM forgot recent context"

1. Check recency threshold: `/dcp-recent 15` to increase
2. Enable debug: `/dcp-debug` to see what's being pruned
3. Check if important messages are within recency window

### "Still using too many tokens"

1. Check stats: `/dcp-stats` to see pruning rate
2. Consider adding custom rules for domain-specific pruning
3. Reduce recency threshold if safe: `/dcp-recent 5`

### "Extension not working"

1. Check if enabled: `/dcp-toggle` twice (off then on)
2. Look for initialization message in logs
3. Check for configuration errors in console

### "Rule not found error"

Rules must be registered before use. Built-in rules auto-register when extension loads.

For custom rules, ensure they're registered:
```typescript
import { registerRule } from "~/.pi/agent/extensions/pi-dcp/src/registry";
registerRule(myRule);
```

## Best Practices

### Configuration

- Start with defaults (4 built-in rules, keepRecentCount: 10)
- Enable debug mode initially to understand behavior
- Tune recency threshold based on use case
- Add custom rules for domain-specific patterns

### Rule Order

Rules are applied in the order configured. Standard order:
1. Deduplication
2. Superseded Writes
3. Error Purging
4. Recency (should be last to override)

Recency should typically be last since it protects messages.

### Performance

- Prepare phase should be fast (just annotation)
- A

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (1)

.beads/beads.jsonl

Gates applied: no_behavioural_pass.