@raidou/pi-pm-subagents 0.1.1

package/.prettierrc

@@ -0,0 +1,7 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "arrowParens": "always",
+  "semi": false,
+  "printWidth": 80
+}

package/AGENTS.md

@@ -0,0 +1 @@
+- use `pnpm test` to check and fix after edit, always test types, lint, and unit (if have)

package/README.md

@@ -0,0 +1,85 @@
+# pi-pm-subagents
+
+pi-pm-subagents extension for [pi](https://pi.dev):
+
+a **coordinator** mode that drives subagents.
+
+## Installation
+
+```bash
+pi install @raidou/pi-pm-subagents
+```
+
+## Usage
+
+Enter Coordinator mode
+
+`/pm` or `/coordinator`
+
+or enable it as the default:
+
+```
+/pm-default or /coordinator-default
+```
+
+Then the agent will delegate some subagents to work and supervise them.
+
+### Built-in agent roles
+
+- explorer
+- researcher
+- reviewer
+- planner
+- worker (default built-in role)
+
+**/plan <request>** delegates a planner subagent (in coordinator mode) that explores the code and produces a plan.
+
+## Configuration
+
+### Prompts
+
+**Coordinator**
+
+`~/.pi/agent/pm-subagents-prompts/coordinator.md`
+`~/.pi/agent/pm-subagents-prompts/coordinator-append.md`
+
+**Roles**
+
+Load precedence (later overrides earlier):
+
+1. Built-in `worker`
+2. Plugin `agents/` directory
+3. Global `~/.pi/agent/agents`
+4. Project `<cwd>/.pi/agents`
+
+Set `"skipPluginAgents": true` in `pi-pm-subagents.json` to skip loading the built-in roles (including `planner`).
+
+### Options in `pi-pm-subagents.json`
+
+- `"subagentModel": "<model>"` — default subagent model
+- `"subagentModelScoped": ["<model>", ...]` — subagent scoped model pool
+- `"defaultMode": "coordinator"` — enter coordinator mode on startup (persistent equivalent of `/pm-default`)
+
+### Model command
+
+**Model priority (spawn time):** `role.model > session subagent model (initial value from pi-pm-subagents.json, can be overridden via /pm-subagent-model or Alt+N) > ctx.model`
+
+- **`/pm-subagent-model`** — Change subagent model
+- **`/pm-subagent-scoped`** — Manage the subagent scoped model
+  - `Alt+N` Cycle pool of models. Can include `DEFAULT` (use pi default model) marker.
+
+## Note
+
+**Terminal/tmux compatibility note**:
+
+> `Alt+N` requires terminal support for Kitty keyboard protocol,
+> or enable `set -g extended-keys on` in tmux.
+> In standard xterm and similar terminals, `Alt+letter` is sent as an ESC sequence and may be unreliable.
+
+## Development
+
+```bash
+PI_DEMO=1 pi
+```
+
+`/subagent-demo` is a UI fixture for development. It is only registered when pi is launched with `PI_DEMO=1`.

package/README.zh-CN.md

@@ -0,0 +1,85 @@
+# pi-pm-subagents
+
+[pi](https://pi.dev) 的 pi-pm-subagents 扩展：
+
+提供一个驱动子代理（subagents）的**协调者（coordinator）**模式。
+
+## 安装
+
+```bash
+pi install @raidou/pi-pm-subagents
+```
+
+## 用法
+
+进入协调者模式
+
+`/pm` or `/coordinator`
+
+或将其设为默认模式：
+
+```
+/pm-default or /coordinator-default
+```
+
+之后 agent 会派出若干子代理去工作并进行监督。
+
+### 内置代理角色
+
+- explorer
+- researcher
+- reviewer
+- planner
+- worker（默认内置角色）
+
+**/plan <request>** 会（在协调者模式下）派出一个 planner 子代理，探索代码并产出计划。
+
+## 配置
+
+### 提示词（Prompts）
+
+**Coordinator**
+
+`~/.pi/agent/pm-subagents-prompts/coordinator.md`
+`~/.pi/agent/pm-subagents-prompts/coordinator-append.md`
+
+**Roles**
+
+加载优先级（后者覆盖前者）：
+
+1. 内置 `worker`
+2. 插件 `agents/` 目录
+3. 全局 `~/.pi/agent/agents`
+4. 项目 `<cwd>/.pi/agents`
+
+在 `pi-pm-subagents.json` 中设置 `"skipPluginAgents": true` 可跳过加载内置角色（包括 `planner`）。
+
+### `pi-pm-subagents.json` 中的配置项
+
+- `"subagentModel": "<model>"` — 默认子代理模型
+- `"subagentModelScoped": ["<model>", ...]` — 子代理 scoped 模型池
+- `"defaultMode": "coordinator"` — 启动时进入协调者模式（即 `/pm-default` 的持久化形式）
+
+### 模型命令
+
+**模型优先级（spawn 时）：** `role.model > session subagent model（初始值来自 pi-pm-subagents.json，可通过 /pm-subagent-model 或 Alt+N 覆盖） > ctx.model`
+
+- **`/pm-subagent-model`** — 更改子代理模型
+- **`/pm-subagent-scoped`** — 管理子代理 scoped 模型
+  - `Alt+N` 在模型池中循环切换。池中可包含 `DEFAULT`（使用 pi 默认模型）标记。
+
+## 注意
+
+**终端/tmux 兼容性说明**：
+
+> `Alt+N` 需要终端支持 Kitty keyboard protocol，
+> 或在 tmux 中启用 `set -g extended-keys on`。
+> 在标准 xterm 及类似终端中，`Alt+字母` 会以 ESC 序列发送，可能不可靠。
+
+## 开发
+
+```bash
+PI_DEMO=1 pi
+```
+
+`/subagent-demo` 是用于开发的 UI fixture。仅在以 `PI_DEMO=1` 启动 pi 时才会注册：

package/agents/explorer.md

@@ -0,0 +1,10 @@
+---
+description: Explore the codebase
+tools:
+  - read
+  - find
+  - grep
+  - bash_readonly
+  - web_fetch
+  - web_search
+---

package/agents/planner.md

@@ -0,0 +1,16 @@
+---
+description: Produces an implementation plan, the plan is reviewed by the user before implementation
+removeTools:
+  - write
+  - edit
+  - bash
+extraTools:
+  - bash_readonly
+reviewOnEnd: true
+---
+You are in plan mode — a read-only exploration mode. You cannot modify files.
+
+1. Investigate the request thoroughly using read-only tools.
+2. Produce a concrete implementation plan as Markdown
+
+The user will review it and choose how to proceed.

package/agents/researcher.md

@@ -0,0 +1,22 @@
+---
+description: Deep research by gathering information from multiple sources
+tools:
+  - read
+  - find
+  - grep
+  - bash_readonly
+  - web_fetch
+  - web_search
+---
+
+You are a research expert. Gather accurate, up-to-date information from multiple sources before synthesizing an answer.
+
+During research:
+
+- Search the web for the latest information and multiple perspectives.
+- Fetch documentation or specification pages for authoritative details.
+- Search the codebase for implementation details when relevant.
+- Cross-validate claims across sources.
+- Cite sources explicitly when presenting findings.
+
+Present research results clearly and concisely. Focus on actionable insights rather than exhaustive coverage.

package/agents/reviewer.md

@@ -0,0 +1,10 @@
+---
+description: Review code
+tools:
+  - read
+  - find
+  - grep
+  - bash_readonly
+  - web_fetch
+  - web_search
+---

package/eslint.config.mjs

@@ -0,0 +1,14 @@
+// @ts-check
+import { tsconfig } from '@raidou/eslint-config-base'
+import { defineConfig } from 'eslint/config'
+export default defineConfig([
+  {
+    files: [
+      'src/**/*.{mjs,ts,tsx,js,jsx}',
+      'app/*.{mjs,ts,tsx,js,jsx}',
+      'app/src/**/*.{mjs,ts,tsx,js,jsx}',
+      '*.{mjs,ts,tsx,js,jsx}',
+    ],
+    extends: [tsconfig],
+  },
+])

package/example-prompts/coordinator.md

@@ -0,0 +1,21 @@
+## Review code against the following criteria
+
+- Prefer self-documenting code over comments, do not add any comments unless the code is complex, difficult to understand, or unclear.
+- Prioritize code readability above all
+- Minimize code hierarchy and encourage early return
+- Use type-safe practices, avoid type casting (unless like `as const`...)
+- Use required types whenever possible instead of optional types.
+- Module files have clearly defined responsibilities, following the DRY + KISS principle.
+- Avoid using mocks in unit tests whenever possible, but don't make your business logic difficult to understand just for the sake of testing.
+- Tests don't need to cover everything, just ensure the main branches don't have errors.
+
+## TS code style
+
+- Don't use `export {...}` unless necessary
+- Prefer `for of` and `for (const [k, v] of array.entries())`
+- When iterating with an `if-chain`, use a switch instead
+
+## Notes
+
+- Don't use git mv to rename files
+- Don't add the change to git staged

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@raidou/pi-pm-subagents",
+  "version": "0.1.1",
+  "description": "Coordinator mode for pi: a read-only coordinator agent that drives isolated subagents, including a planner role.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "subagents",
+    "pm",
+    "coordinator"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "pnpm test:types && pnpm test:lint && pnpm test:unit",
+    "test:types": "tsc --noEmit",
+    "test:lint": "eslint --fix .",
+    "test:unit": "vitest run"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.83.0",
+    "@earendil-works/pi-ai": "0.83.0",
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "@earendil-works/pi-tui": "0.83.0",
+    "@raidou/eslint-config-base": "4.4.4",
+    "@types/lodash-es": "^4.17.12",
+    "@types/node": "26.1.2",
+    "eslint": "10.8.0",
+    "prettier": "3.9.6",
+    "typescript": "6.0.3",
+    "vitest": "4.1.10"
+  },
+  "dependencies": {
+    "lodash-es": "^4.18.1",
+    "shell-quote": "^1.8.3",
+    "typebox": "1.3.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/pm-subagents-prompts/coordinator.md

@@ -0,0 +1,16 @@
+---
+tools: []
+extraTools: []
+removeTools: [find, grep, bash, web_search, web_fetch]
+---
+
+You are a COORDINATOR agent; you are readonly, delegate subagents to do tasks
+
+## Responsibilities
+
+- Delegate tasks and wait for me to tell you subagent's last message when it finishes.
+- Do not trust a subagent's self-reported result blindly.
+- Don't do the work yourself; let subagents explore, research, code, test, review, etc.
+- Don't skip lint checks
+- Ask for the user's consent before modifying package.json, tsconfig, or eslint etc project settings
+- After changing code, always have the reviewer check it

package/pnpm-workspace.yaml

@@ -0,0 +1,5 @@
+allowBuilds:
+  '@google/genai': false
+  protobufjs: false
+minimumReleaseAgeExclude:
+  - typebox@1.3.9

package/src/bash-readonly.test.ts

@@ -0,0 +1,331 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent'
+import { describe, expect, it } from 'vitest'
+
+import {
+  BASH_READONLY_TOOL_NAME,
+  checkBashSafety,
+  isBashReadonlyCommand,
+} from './bash-readonly.js'
+import { calculateModeTools } from './pm-mode.js'
+import { createState } from './utils/state.js'
+
+function fakePi(initialActive: string[]): ExtensionAPI & {
+  activeTools: string[]
+} {
+  const pi = {
+    activeTools: initialActive,
+    getActiveTools() {
+      return [...pi.activeTools]
+    },
+    setActiveTools(names: string[]) {
+      pi.activeTools = [...names]
+    },
+  }
+  return pi as ExtensionAPI & { activeTools: string[] }
+}
+
+describe('isBashReadonlyCommand', () => {
+  it('allows read-only commands', () => {
+    expect(isBashReadonlyCommand('ls -la')).toBe(true)
+    expect(isBashReadonlyCommand('git status')).toBe(true)
+    expect(isBashReadonlyCommand('cat README.md')).toBe(true)
+    expect(isBashReadonlyCommand('rg "foo" src/')).toBe(true)
+    expect(isBashReadonlyCommand('pnpm test')).toBe(true)
+    expect(isBashReadonlyCommand('npm test')).toBe(true)
+    expect(isBashReadonlyCommand('yarn test')).toBe(true)
+    expect(isBashReadonlyCommand('pnpm run test')).toBe(true)
+    expect(isBashReadonlyCommand('pnpm test:unit')).toBe(true)
+    expect(isBashReadonlyCommand('yarn run test')).toBe(true)
+    expect(isBashReadonlyCommand('cd /some/path')).toBe(true)
+    expect(
+      isBashReadonlyCommand(
+        'cd /home/raidou/repos/raidou/pi-notify && pnpm test 2>&1 | tail -30',
+      ),
+    ).toBe(true)
+    expect(isBashReadonlyCommand('cd .. && ls')).toBe(true)
+  })
+
+  it('validates each shell subcommand independently', () => {
+    expect(isBashReadonlyCommand('cat README.md && echo done')).toBe(true)
+    expect(isBashReadonlyCommand('cat README.md; rm file')).toBe(false)
+    expect(isBashReadonlyCommand('ls || rm -rf /')).toBe(false)
+    expect(isBashReadonlyCommand('cat foo | grep bar')).toBe(true)
+    expect(isBashReadonlyCommand('cat README.md; echo "rm -rf /"')).toBe(true)
+    expect(isBashReadonlyCommand('pnpm test | tail')).toBe(true)
+    expect(isBashReadonlyCommand('pnpm test 2>&1 | tail -60')).toBe(true)
+    expect(isBashReadonlyCommand('pnpm test | grep FAIL')).toBe(true)
+    expect(isBashReadonlyCommand('pnpm test | rm file')).toBe(false)
+  })
+
+  it('rejects empty shell subcommands', () => {
+    expect(isBashReadonlyCommand('')).toBe(false)
+    expect(isBashReadonlyCommand('cat README.md &&')).toBe(false)
+  })
+
+  it('allows read-only commands with forward prefix', () => {
+    expect(isBashReadonlyCommand('rtk ls -la')).toBe(true)
+    expect(isBashReadonlyCommand('rtk git status')).toBe(true)
+    expect(isBashReadonlyCommand('rtk git diff path/to')).toBe(true)
+    expect(
+      isBashReadonlyCommand(
+        `export RTK_DB_PATH='/tmp/pi-rtk-optimizer/history.db'; rtk ls -la`,
+      ),
+    ).toBe(true)
+  })
+
+  it('blocks destructive commands', () => {
+    expect(isBashReadonlyCommand('rm -rf /')).toBe(false)
+    expect(isBashReadonlyCommand('npm install')).toBe(false)
+    expect(isBashReadonlyCommand('git commit -m x')).toBe(false)
+    expect(isBashReadonlyCommand('echo hi > out.txt')).toBe(false)
+    expect(isBashReadonlyCommand('sudo apt-get install evil')).toBe(false)
+  })
+
+  it('blocks destructive commands even with forward prefix', () => {
+    expect(isBashReadonlyCommand('rtk rm -rf /')).toBe(false)
+    expect(isBashReadonlyCommand('rtk npm install')).toBe(false)
+    expect(isBashReadonlyCommand('rtk git commit -m x')).toBe(false)
+  })
+
+  it('allows git stash read-only subcommands', () => {
+    expect(isBashReadonlyCommand('git stash list')).toBe(true)
+    expect(isBashReadonlyCommand('git stash show')).toBe(true)
+    expect(isBashReadonlyCommand('git stash list -n 5')).toBe(true)
+    expect(isBashReadonlyCommand('git stash show -p stash@{0}')).toBe(true)
+    expect(isBashReadonlyCommand('git stash')).toBe(false)
+    expect(isBashReadonlyCommand('git stash push -m "wip"')).toBe(false)
+    expect(isBashReadonlyCommand('git stash pop')).toBe(false)
+    expect(isBashReadonlyCommand('git stash apply')).toBe(false)
+    expect(isBashReadonlyCommand('git stash drop')).toBe(false)
+    expect(isBashReadonlyCommand('git stash clear')).toBe(false)
+    expect(isBashReadonlyCommand('git stash save "msg"')).toBe(false)
+  })
+})
+
+describe('calculateModeTools', () => {
+  it('drops write tools, replaces bash, and merges extras', () => {
+    expect(
+      calculateModeTools(
+        fakePi(['read', 'edit', 'write', 'bash']),
+        createState(),
+        {
+          extraTools: ['subagent_delegate'],
+        },
+      ),
+    ).toEqual(['read', BASH_READONLY_TOOL_NAME, 'subagent_delegate'])
+  })
+
+  it('deduplicates', () => {
+    expect(
+      calculateModeTools(fakePi(['read', 'read', 'edit']), createState(), {
+        extraTools: ['read'],
+      }),
+    ).toEqual(['read'])
+  })
+
+  it('does not inject bash_readonly when bash is not present', () => {
+    expect(
+      calculateModeTools(fakePi(['read', 'grep']), createState(), {}),
+    ).toEqual(['read', 'grep'])
+  })
+
+  it('passes through bash_readonly unchanged when already present', () => {
+    expect(
+      calculateModeTools(
+        fakePi(['read', BASH_READONLY_TOOL_NAME]),
+        createState(),
+        {},
+      ),
+    ).toEqual(['read', BASH_READONLY_TOOL_NAME])
+  })
+
+  it('removes specified tools', () => {
+    expect(
+      calculateModeTools(fakePi(['read', 'bash', 'grep']), createState(), {
+        removeTools: ['grep'],
+      }),
+    ).toEqual(['read', BASH_READONLY_TOOL_NAME])
+  })
+
+  it('restricts to tools list when provided', () => {
+    expect(
+      calculateModeTools(fakePi(['read', 'bash', 'grep']), createState(), {
+        extraTools: ['subagent_delegate'],
+        tools: ['read', 'subagent_delegate'],
+      }),
+    ).toEqual(['read', 'subagent_delegate'])
+  })
+
+  it('returns empty when tools list is empty', () => {
+    expect(
+      calculateModeTools(fakePi(['read', 'bash', 'grep']), createState(), {
+        tools: [],
+      }),
+    ).toEqual([])
+  })
+})
+
+describe('checkBashSafety', () => {
+  it('returns allowed: true for safe commands', () => {
+    expect(checkBashSafety('ls -la')).toEqual({ allowed: true })
+    expect(checkBashSafety('git status')).toEqual({ allowed: true })
+    expect(checkBashSafety('cat README.md')).toEqual({ allowed: true })
+    expect(checkBashSafety('rg "foo" src/')).toEqual({ allowed: true })
+    expect(checkBashSafety('pnpm test')).toEqual({ allowed: true })
+  })
+
+  it('reports the failed subcommand for destructive commands', () => {
+    expect(checkBashSafety('rm file')).toEqual({
+      allowed: false,
+      subCommand: 'rm file',
+    })
+    expect(checkBashSafety('rm -rf /')).toEqual({
+      allowed: false,
+      subCommand: 'rm -rf /',
+    })
+  })
+
+  it('reports the failed subcommand for output redirect commands', () => {
+    expect(checkBashSafety('ls > out.txt')).toEqual({
+      allowed: false,
+      subCommand: 'ls',
+    })
+  })
+
+  it('reports the failed subcommand for sudo commands', () => {
+    expect(checkBashSafety('sudo apt-get install evil')).toEqual({
+      allowed: false,
+      subCommand: 'sudo apt-get install evil',
+    })
+  })
+
+  it('reports the first failed subcommand in chain', () => {
+    expect(checkBashSafety('cat README.md; rm file')).toEqual({
+      allowed: false,
+      subCommand: 'rm file',
+    })
+    expect(checkBashSafety('ls && echo hi && rm file')).toEqual({
+      allowed: false,
+      subCommand: 'rm file',
+    })
+    expect(checkBashSafety('rm file && ls')).toEqual({
+      allowed: false,
+      subCommand: 'rm file',
+    })
+  })
+
+  it('returns (empty) for trailing empty subcommands', () => {
+    expect(checkBashSafety('cat README.md &&')).toEqual({
+      allowed: false,
+      subCommand: '(empty)',
+    })
+    expect(checkBashSafety('ls ;')).toEqual({
+      allowed: false,
+      subCommand: '(empty)',
+    })
+  })
+
+  it('returns the original command for empty input', () => {
+    expect(checkBashSafety('')).toEqual({ allowed: false, subCommand: '' })
+  })
+
+  it('strips rtk prefix when checking for destructive patterns', () => {
+    expect(checkBashSafety('rtk git commit -m x')).toEqual({
+      allowed: false,
+      subCommand: 'git commit -m x',
+    })
+    expect(checkBashSafety('rtk rm -rf /')).toEqual({
+      allowed: false,
+      subCommand: 'rm -rf /',
+    })
+  })
+
+  it('allows safe commands with rtk prefix', () => {
+    expect(checkBashSafety('rtk ls -la')).toEqual({ allowed: true })
+    expect(checkBashSafety('rtk git status')).toEqual({ allowed: true })
+  })
+
+  it('handles complex multi-subcommand scenarios', () => {
+    expect(checkBashSafety('cat README.md && echo done && ls -la')).toEqual({
+      allowed: true,
+    })
+    expect(checkBashSafety('cat README.md | grep foo | tail')).toEqual({
+      allowed: true,
+    })
+    expect(checkBashSafety('pnpm test | grep FAIL | tail -20')).toEqual({
+      allowed: true,
+    })
+  })
+
+  it('allows stderr redirects but blocks stdout redirects', () => {
+    expect(
+      checkBashSafety("find /home/raidou -name 'foo' 2>/dev/null"),
+    ).toEqual({ allowed: true })
+    expect(checkBashSafety('rtk find . 2>/dev/null')).toEqual({
+      allowed: true,
+    })
+    expect(checkBashSafety('ls > out.txt')).toEqual({
+      allowed: false,
+      subCommand: 'ls',
+    })
+    expect(checkBashSafety('ls 1>/dev/null')).toEqual({ allowed: true })
+    expect(checkBashSafety('ls 2>&1 | grep x')).toEqual({ allowed: true })
+    expect(checkBashSafety('cat foo 2>&1')).toEqual({
+      allowed: false,
+      subCommand: 'cat foo',
+    })
+    expect(checkBashSafety('ls &> out.txt')).toEqual({
+      allowed: false,
+      subCommand: 'ls',
+    })
+    expect(checkBashSafety('ls &>> out.txt')).toEqual({
+      allowed: false,
+      subCommand: 'ls',
+    })
+  })
+
+  it('allows git stash list and show, rejects destructive stash subcommands', () => {
+    expect(checkBashSafety('git stash list')).toEqual({ allowed: true })
+    expect(checkBashSafety('git stash show')).toEqual({ allowed: true })
+    expect(checkBashSafety('git stash list -n 5')).toEqual({ allowed: true })
+    expect(checkBashSafety('git stash show -p stash@{0}')).toEqual({
+      allowed: true,
+    })
+    expect(checkBashSafety('git stash push -m x')).toEqual({
+      allowed: false,
+      subCommand: 'git stash push -m x',
+    })
+    expect(checkBashSafety('git stash pop')).toEqual({
+      allowed: false,
+      subCommand: 'git stash pop',
+    })
+    expect(checkBashSafety('git stash apply')).toEqual({
+      allowed: false,
+      subCommand: 'git stash apply',
+    })
+    expect(checkBashSafety('git stash drop')).toEqual({
+      allowed: false,
+      subCommand: 'git stash drop',
+    })
+    expect(checkBashSafety('git stash clear')).toEqual({
+      allowed: false,
+      subCommand: 'git stash clear',
+    })
+    expect(checkBashSafety('git stash save msg')).toEqual({
+      allowed: false,
+      subCommand: 'git stash save msg',
+    })
+    expect(checkBashSafety('git stash create')).toEqual({
+      allowed: false,
+      subCommand: 'git stash create',
+    })
+    expect(checkBashSafety('git stash branch')).toEqual({
+      allowed: false,
+      subCommand: 'git stash branch',
+    })
+    expect(checkBashSafety('git stash store')).toEqual({
+      allowed: false,
+      subCommand: 'git stash store',
+    })
+  })
+})