RuleSpoolfor OpenCode 2
RULESPOOL / NOTE 01UPDATED October 15, 2026

First, know which rules you actually have.

A configuration file describes intent. A resolved agent snapshot describes a later stage. RuleSpool needs the latter—or an explicitly partial ordered rule array.

Start with the effective array

Our explorer accepts ordered objects with action, resource and effect. It evaluates the supplied agent array first and a supplied session array after it. It does not load your machine's configuration layers or silently append defaults.

That boundary matters. Pasting one exception from a configuration file into an otherwise empty array can produce a correct explanation of that small array and still differ from your running agent. The built-in example is deliberately labeled synthetic. Use an actual resolved snapshot when investigating a real request.

V2 does not require a wholesale rewrite

The current migration guide says supported V1 configuration is normalized in memory; converting everything to native V2 shape is optional. Plugins and server integrations have separate migration work. RuleSpool is not a full configuration converter and does not claim an old file is broken merely because it uses the old format.

For native requests, the action names matter. V1 bash corresponds to V2 shell; task corresponds to subagent; write and patch operations use edit. We preserve imported strings rather than guessing whether you intended a legacy name or a custom action.

A minimal diagnostic sequence

  1. Record the installed version and the actual action/resource strings from the permission request.
  2. Import one resolved agent array. If session rules or saved approvals are not available, leave those layers unknown.
  3. Add the request as “Copied from a native request”. Select each resource to inspect its matching trail.
  4. Change one rule and compare the same cases against the original and draft snapshots.
  5. Verify the chosen change in your actual runtime before using it for a real task.

Permissions are one part of execution

The explorer does not run a shell scanner, resolve a filesystem path, expand a home directory or invoke policy hooks. A supplied-layer allow is not evidence that a tool ran or that your application worked. The final stamp therefore always keeps actual runtime status separate.

Primary references: V1 migration, native permissions, and the pinned implementation.