Pi Decision Router

Route Pi questions and confirmations to a child Pi agent, then keep an audit trail.

What this is

pi-decision-router removes routine human-choice UI from unattended Pi runs. It registers one conflict-free canonical decision tool, adapts common question-tool shapes through Pi UI/event hooks, asks a tool-disabled child Pi for the decision, and falls back to the recommended option when the child is unavailable.

This is intentionally generic. It does not depend on gstack and does not modify gstack itself.

Features

• Adapts question, questionnaire, ask_question, ask_user_question, and AskUserQuestion when their host exposes supported Pi UI/event hooks.
• Auto-answers ctx.ui.select(), ctx.ui.confirm(), and ctx.ui.input() when the active Pi context can be patched.
• Uses a child pi --print --no-tools process with strict JSON output.
• Persists JSONL decisions outside the vault for auditability.
• Never gives the child agent tools, extensions, skills, project context, or a session.
• Uses recommended/default/positive options first, then the first option as a deterministic fallback.
• Shows an ON/OFF status-bar toggle; run /decision-router-toggle and press Enter to switch it.
• After a turn ends, warns and forces compaction at 95% context usage; 100% is treated as an emergency threshold.
• Resumes an interrupted tool-driven task with a hidden follow-up after compaction, then lets Pi produce the final response.

Install

pi install npm:pi-decision-router

For local development:

pi -e C:/path/to/pi-decision-router/extensions/index.ts

Configuration

The package is enabled by default for unattended operation.

| Variable | Default | Purpose | |---|---:|---| | PI_DECISION_ROUTER_ENABLED | 1 | Set 0 to disable routing. | | PI_DECISION_ROUTER_CHILD | 1 | Set 0 to skip the child and use fallback decisions. | | PI_DECISION_ROUTER_AUTO_COMPACTION | 1 | Set 0 to disable the router's post-turn compaction trigger. | | PI_DECISION_ROUTER_COMPACTION_THRESHOLD_PERCENT | 95 | Context percentage that triggers compaction after a turn. | | PI_DECISION_ROUTER_COMPACTION_EMERGENCY_PERCENT | 100 | Emergency percentage; bypasses the one-compaction-per-cycle guard. | | PI_DECISION_ROUTER_TIMEOUT_MS | 45000 | Child decision timeout. | | PI_DECISION_ROUTER_MODEL | current model | Child Pi model pattern or ID. | | PI_DECISION_ROUTER_PROVIDER | current provider | Child Pi provider. | | PI_DECISION_ROUTER_PI_BIN | auto | Explicit Pi executable path. | | PI_DECISION_ROUTER_AUDIT_LOG | ~/.pi/agent/pi-decision-router/audit.jsonl | JSONL audit path. |

Useful commands:

/decision-router-status
/decision-router-log
/decision-router-toggle

The toggle switches Router Mode — routing and auto compaction together — and remembers the choice per project directory in ~/.pi/agent/pi-decision-router/state.json, so new sessions in the same directory restore it. An explicit PI_DECISION_ROUTER_ENABLED=0 (or PI_DECISION_ROUTER_AUTO_COMPACTION) still wins over the persisted state when Pi should start with a deterministic configuration.

Automatic compaction

Automatic compaction is enabled by default. At the end of a Pi turn, when ctx.getContextUsage() reports at least 95%, the extension shows a warning, starts compaction, and shows completion. At 100% it uses the emergency path, so the next completed turn is always eligible even if the previous high-context turn already armed a compaction cycle.

When the compacted turn contained tool calls or tool results, the extension queues a hidden followUp message after compaction. Pi then continues the interrupted work and produces the final response. A normal final assistant turn does not receive a duplicate response. Pi's native threshold compaction remains active too; the router adds an explicit post-turn 95%/100% trigger and does not change Pi's global compaction settings.

Runtime boundary

Pi's public extension API can intercept registered tool calls and patch the ctx.ui object supplied to active extension contexts. Multiple packages may already own the same question-tool name, so this package deliberately does not register duplicate aliases; it uses UI/event adapters instead. It cannot reliably replace an arbitrary third-party process, a browser dialog, or a UI call made before this extension is loaded. Unsupported question tools are left untouched instead of being silently blocked. When the toggle is OFF, supported UI adapters delegate back to Pi's native UI and the canonical decision tool is removed from Pi's active tool list.

Security

This package intentionally auto-approves routine decisions, including destructive confirmation dialogs, when configured for unattended use. The child agent runs without tools, but it still receives the question and a bounded recent-conversation excerpt. Review the package before installing it and protect the audit log.

See docs/usage.md for the decision contract and failure modes.

Development

npm install
npm run ci

Run the local extension in Pi:

pi -e .

Release

The package uses npm Trusted Publishing through GitHub Actions. No NPM_TOKEN is required.

npm version patch
git push

See docs/release.md.

Links

• npm: https://www.npmjs.com/package/pi-decision-router
• GitHub: https://github.com/eiei114/pi-decision-router
• Issues: https://github.com/eiei114/pi-decision-router/issues

License

MIT