@pi-unipi/workflow

Plan mode and permission modes for the Pi coding agent

Package details

extension

Install @pi-unipi/workflow from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@pi-unipi/workflow

Pi manifest JSON

{
  "skills": [],
  "themes": [],
  "prompts": [],
  "extensions": [
    "./index.ts"
  ]
}

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

Workflow controls which tool calls the agent can run without your approval, and gives a read-only plan mode.

@pi-unipi/workflow · part of UniPi

Checks each tool call against a permission mode: ask, auto (default) or full.
In auto mode, sends an unknown bash command to jev for a risk verdict. Jev is the UniPi decision model: one small LLM call that returns a choice and a confidence.
Saves "Always allow" rules for each project. Saved deny rules apply in all modes.
Gives plan mode. In plan mode, the agent can only read files and write one plan file.
Shows the plan in a review screen. You approve it, ask for changes or discard it.

Install UniPi: pi install npm:@pi-unipi/unipi. You can also install this package alone: pi install npm:@pi-unipi/workflow.
Push Alt+M to change the permission mode.
Push Alt+P to start plan mode. Ask the agent for a plan.

Command or key	What it does
`/unipi:permission`	Shows the current mode, the project mode and the default mode.
`/unipi:permission ask\|auto\|full`	Sets the mode for this project.
`Alt+M`	Cycles the mode: `ask`, `auto`, `full`.
`/unipi:plan`	Starts or stops plan mode.
`/unipi:plan on\|off`	Starts or stops plan mode.
`/unipi:plan view`	Shows the plan file.
`/unipi:plan approve`	Opens the plan review screen.
`Alt+P`	Starts or stops plan mode.

Tool	What it does
`plan_submit`	Plan mode only. Opens the plan review screen for the user.

Mode	What runs without a prompt
`ask`	Read-only tools only. All other calls show a prompt.
`auto`	Read-only tools, read-only `bash`, and writes in the project or the temp folder. Jev checks other `bash` commands.
`full`	All calls, also dangerous `bash`. Saved deny rules still block.

The gate checks a tool call in this order:

Saved rules. A deny rule blocks the call. An allow rule runs it.
Read-only tools, such as read, grep, ls, memory_search and bg_status.
write and edit. A path outside the project and the temp folder shows a prompt in ask and auto modes.
bash. Dangerous patterns, such as rm -rf, sudo or git push --force, show a prompt in ask and auto modes. In auto mode, jev must say safe with a confidence of jevConfidence or more. Otherwise, you get a prompt.
Other tools. They run in auto and full modes.

The prompt gives four options: "Allow once", "Always allow", "Deny" and "Deny with note". The agent gets your note in the block reason.

When there is no UI, nothing shows a prompt. The gate blocks dangerous bash and saved deny rules. It runs all other calls.

The plan file is docs/plans/<date>-<session-id>.md in the project.
The agent can write only the plan file. bash must be read-only. Other tools that change state get a block message.
Each turn gets a short reminder message. The system prompt does not change.
"Approve & implement" stops plan mode. It sends the plan as the next user message.
"Keep planning" sends your feedback to the agent.

Namespace permission. Open it with /unipi:settings.

Key	Default	What it does
`mode`	not set	Mode for this project. Project scope only.
`defaultMode`	`auto`	Mode for projects that set no mode. Global scope only.
`jevJudge`	`true`	Lets jev check unknown `bash` commands in `auto` mode.
`jevConfidence`	`0.7`	Minimum confidence for a `safe` verdict.
`rules`	`[]`	Saved allow and deny rules. The hub has a "Clear saved rules" action.
`decisionModel.source`	`inherit`	`inherit` uses the shared `decision-model` settings. `custom` sets a model for this namespace.

Set UNIPI_DEBUG_PERMISSION=1 to write each decision to ~/.unipi/logs/permission.log.