pi-heed

# pi-heed

**Your agent understood your instruction. pi-heed makes sure it still remembers.**

Runtime constraints for the [pi](https://pi.dev) coding agent: every side-effecting tool call is checked against what you said, before it runs.

[](https://pi.dev)
[](https://docs.typesafe.ai)
[](#development)
[](LICENSE)

</div>

---

You say *"review only, don't touch anything"*. Forty tool calls and one context compaction later, the agent reaches for `write`. pi-heed stops it, with your own words as the reason:

```
[pi-heed] User constraint c1 "Review only. Don't modify any files.". Pending call: bash: echo reviewed >> notes.txt.
It would change files or external state. Do not apply it; describe the intended change instead, or ask the user to lift the constraint.
```

And when you *did* change your mind (*"I've changed my mind for notes.txt only"*), it lets that one file through and keeps everything else locked.

## Conversational policy, not a keyword list

What you say over a session is a policy that changes: *"don't touch src — but src/auth is fine — except secrets.ts"*, *"this once you can edit package.json"*, *"this round you can install deps"*, *"never mind, revoke that"*. pi-heed keeps it as structured state:

```ts
{ id, sourceQuote, effect, action, resource, scope, exceptions, status, provenance }
//      DENY | ALLOW | REQUIRE_CONFIRMATION | REQUIRE_BEFORE
//                     modify | install_deps | git_push | git_commit | custom
//                               "*" | "tests" | path/dir
//                                         session | goal | run | once
//                                                             active | superseded | expired
```

| You say | What happens |
|---|---|
| *"不要改测试"* | ADD `DENY modify tests` |
| *"现在测试可以改了"* | LIFT: the deny