@leo-alvarenga/pi-agent-manager

A pi-coding-agent extension providing persona-based agent switching and OpenCode-style permission guards.

Each agent combines a system prompt persona with a permission ruleset that resolves tool executions into three actions:

• deny: Physically disables tools via pi.setActiveTools() so the model never sees them.
• ask: Pauses execution and prompts for interactive user confirmation (once, always, or reject).
• allow: Permits immediate tool execution without confirmation.

---

How It Works

1. Tool Stripping: On startup or agent switch, the extension evaluates the active agent's ruleset. Tools matched with deny rules are filtered out entirely via pi.setActiveTools()
2. Prompt Injection: The active agent's system prompt (and optional XML permission envelope) is prepended to the system prompt before each conversation turn
3. Interactive Gate: When a tool configured with ask is invoked, the user is prompted to allow or deny the call. Allowing then asks whether to remember the decision ("always") for the rest of the session, which appends a runtime rule to the session state.

---

Built-In Agents

Agent	Description	Default Ruleset Summary
planner 󱞁	Analysis and inspection profile; cannot modify files or execute shell commands.	read, grep, glob, list, websearch, webfetch, task, todo, and all context-mode tools except ctx_execute / ctx_execute_file / ctx_batch_execute allowed; edit, bash, and context-mode exec tools denied.
builder 󱁤	Execution-oriented profile; unrestricted file changes and commands, but web tools are unavailable.	All tools allowed except websearch and webfetch (denied); destructive commands (rm, sudo, chmod, chown) trigger ask.

---

Installation

Install via the pi package manager:

pi install npm:@leo-alvarenga/pi-agent-manager

After installation, restart pi or execute /reload within the TUI.

---

Commands & Keybindings

TUI Commands

Command	Description
/agents	Opens the interactive agent selection picker
/agents <name>	Switches directly to the specified agent (supports tab-completion)
/agents_help	Shows agent list, permissions, keybindings, and usage
/agent_guard [on / off]	Toggles XML permission-envelope system prompt injection (toggles if omitted)

Note: Selected agents persist across sessions and are restored upon restarting

Custom Keybindings

Configure shortcuts in ~/.pi/agent/keybindings.json:

{
  "piAgentManager.next": "shift+tab",
  "piAgentManager.previous": "ctrl+shift+alt+p",
  "piAgentManager.picker": "ctrl+shift+alt+a"
}

Run /reload after updating keybindings.

---

Permission Engine

The permission engine evaluates { permission, pattern } pairs against defined rulesets.

Evaluation Order: Rules are evaluated top-to-bottom in definition order, where the last matching rule takes precedence. If no rule matches an invoked tool, the default fallback is ask.

Permission Mappings

Key	Mapped Pi Tools
read	read, hash_read
grep	grep
glob	find
list	ls
edit	write, edit, delete_file, hash_edit
bash	bash, shell, run, exec
websearch	web_search, source_check, get_search_content
webfetch	fetch_content
task	subagent, subagent_wait, subagent_supervisor, intercom
question	questionnaire, ask_user_question

Unlisted custom or MCP tools map directly to their exact tool name.

---

Custom Agents

Add custom agent definition files (.md) with YAML frontmatter to ~/.pi/agent/agents/:

---
name: reviewer
description: Reviews code for quality, performance, and security issues
permissions:
  "*": deny
  read: allow
  grep: allow
  glob: allow
  list: allow
  websearch: allow
icon: ★
color: success
---

You are a Code Reviewer: focus on security, performance, and maintainability.
Read freely and suggest improvements, but never edit files or run commands.

Frontmatter Schema

Field	Required	Description
description	Yes	Short summary displayed in the selection picker and help views.
permissions	Yes	Preset name (plan, build, read), ruleset array, or full rule object.
name	No	Unique identifier (defaults to filename without .md).
type	No	primary (default) or subagent.
icon	No	Display icon/glyph placed before the agent name.
color	No	Theme color token (accent, success, warning, error, info, dim).
hidden	No	Set to true to exclude from cycle shortcuts and the picker menu.
steps	No	Maximum tool execution turns permitted before requesting a response summary.
prompt	No	Overrides markdown body text as the system prompt instructions.

Permission Definition Formats

1. Preset Strings

permissions: plan # Read/web/subagent allowed; edit and bash denied
permissions: build # Full access; destructive bash commands gated with ask
permissions: read # Inspection tools only

2. Legacy Array (Auto-converted to ruleset)

permissions: [read, web, ask]

3. Full Ruleset Object (OpenCode Compatible)

permissions:
  "*": deny
  read: allow
  grep: allow
  glob: allow
  list: allow
  websearch: allow
  bash:
    "*": deny
    "npm test*": allow
    "npm run build*": allow

---

Directory Layout

src/
├── index.ts              # Extension entry point, lifecycle hooks, and commands
├── constants.ts          # Key definitions, default values, and XML tags
├── agent/
│   ├── types.ts          # Agent state, configuration, and type definitions
│   ├── builtin.ts        # Default built-in agent definitions
│   ├── manager.ts        # Agent state machine and tool guard enforcement
│   └── config.ts         # User markdown agent and keybinding loaders
├── permission/
│   ├── types.ts          # Ruleset schemas, actions, and evaluation types
│   ├── evaluate.ts       # Core rule evaluation algorithms and state merging
│   ├── wildcard.ts       # Glob pattern matching engine
│   ├── mapping.ts        # Built-in tool-to-permission maps
│   └── presets.ts        # Preset profiles and legacy format converters
└── cli/
    ├── picker.ts         # Interactive TUI selection interface
    ├── help.ts           # Help renderer, permission badges, and validators
    └── logger.ts         # Wrapper for pi notification rendering