@narumitw/pi-plan-mode 0.58.3 → 0.59.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +25 -12
- package/dist/chunks/{chunk-L2CXUWCH.ts → chunk-MJV6WNHK.ts} +76 -7
- package/dist/chunks/{chunk-L2CXUWCH.ts.map → chunk-MJV6WNHK.ts.map} +3 -3
- package/dist/chunks/{interactive-ui-OZA4BHGS.ts → interactive-ui-F7FMN7FT.ts} +25 -27
- package/dist/chunks/interactive-ui-F7FMN7FT.ts.map +7 -0
- package/dist/index.ts +36 -26
- package/dist/index.ts.map +3 -3
- package/docs/command-workflows.md +6 -1
- package/docs/settings.md +78 -15
- package/package.json +3 -3
- package/src/mode-contract.ts +9 -0
- package/src/plan-launch-menu.ts +9 -9
- package/src/plan-mode.ts +43 -35
- package/src/prompt.ts +1 -1
- package/src/settings-menu.ts +16 -24
- package/src/tool-availability.ts +27 -0
- package/src/tool-policy.ts +14 -4
- package/src/tool-selection.ts +55 -3
- package/dist/chunks/interactive-ui-OZA4BHGS.ts.map +0 -7
|
@@ -15,7 +15,12 @@ Back, Escape, Ctrl+C, disposal, session replacement, or shutdown discards the un
|
|
|
15
15
|
Persistent defaults belong in [Settings](./settings.md).
|
|
16
16
|
|
|
17
17
|
The TUI selector supports fuzzy search and paging; RPC shows the unfiltered list.
|
|
18
|
-
|
|
18
|
+
The selector distinguishes callable tools, inactive direct tools, hidden tools, blocked policies, and pending registration.
|
|
19
|
+
**Inactive in Pi** means Pi must enable the tool separately; **blocked by Plan policy** cannot be enabled by selecting the row.
|
|
20
|
+
For inactive built-in `grep`, `find`, and `ls`, follow the [Pi settings setup](./settings.md#enable-inactive-built-in-search-tools-in-pi) before reopening the selector.
|
|
21
|
+
Native MCP tools are explicit opt-ins; registered `codemode` and `deferred` exposure is selectable without direct activation.
|
|
22
|
+
Select the needed orchestrator separately, and select every nested callee; neither choice grants the other permission.
|
|
23
|
+
Selected names awaiting metadata stay selected for first-request resolution.
|
|
19
24
|
Reopen the selector to refresh newly registered tools.
|
|
20
25
|
Active and ready workflows lock tools and settings; exit and start a new workflow to change the allowlist.
|
|
21
26
|
See [Planning and implementation](../README.md#-planning-and-implementation) for the first-request policy boundary, completion, and same-session versus fresh-session handoff.
|
package/docs/settings.md
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
[Back to README](../README.md)
|
|
4
4
|
|
|
5
5
|
- [Default Plan policy tools](#default-plan-policy-tools)
|
|
6
|
+
- [Enable inactive built-in search tools in Pi](#enable-inactive-built-in-search-tools-in-pi)
|
|
6
7
|
- [Plan reinjection](#plan-reinjection)
|
|
7
8
|
- [Fresh implementation runtime](#fresh-implementation-runtime)
|
|
8
9
|
- [Export destination](#export-destination)
|
|
@@ -55,20 +56,72 @@ Neither setting changes model-visible tool schemas.
|
|
|
55
56
|
Tool names must be non-empty strings; duplicates are removed in first-seen order.
|
|
56
57
|
Explicit configured or session-selected names remain policy intent when their tool is unknown or inactive, but Plan mode never registers or activates them.
|
|
57
58
|
The inactive menu takes a fresh registered and active tool snapshot each time it opens, while an already open picker does not update in place.
|
|
58
|
-
At the workflow's first provider-bound context, after every `before_agent_start` handler has settled, Plan mode resolves retained names against Pi's live
|
|
59
|
+
At the workflow's first provider-bound context, after every `before_agent_start` handler has settled, Plan mode resolves retained names against Pi's live registry, exposure, and active declarations and freezes the executable allowlist.
|
|
59
60
|
Automatic defaults recheck the effective source metadata at that boundary, so a custom override of a safe built-in name still requires explicit opt-in.
|
|
60
61
|
The resolved allowlist persists with the active workflow and restores without reopening the resolution boundary after reload, resume, or tree navigation.
|
|
61
|
-
|
|
62
|
+
Names unavailable at resolution wait for the next Plan workflow rather than a new session.
|
|
63
|
+
An admitted tool may be reactivated or declared later without widening that frozen policy, but current hidden exposure still blocks it.
|
|
62
64
|
Settings shows unresolved names as pending registration; resetting to automatic removes the entire override.
|
|
63
|
-
|
|
64
|
-
|
|
65
|
+
|
|
66
|
+
Direct and `model-only` tools must be active; registered `codemode` or `deferred` tools can be selected without direct activation.
|
|
67
|
+
MCP `codemode-deferred` is represented as public exposure `deferred`.
|
|
68
|
+
`model-only` tools cannot run as nested calls; hidden and unsupported exposure remain unavailable regardless of active declarations or saved names.
|
|
69
|
+
Missing exposure on older Pi versions retains the direct-tool behavior.
|
|
70
|
+
Native MCP tools and orchestration tools require explicit opt-in just like other tools outside the reviewed core policy; server annotations never grant permission.
|
|
71
|
+
For example, `"defaultPlanTools": ["read", "codemode", "mcp__docs__read"]` permits that MCP tool through an already-active `codemode` orchestrator.
|
|
72
|
+
Selecting either tool does not enable the other, and every nested call needs its own Plan-policy admission.
|
|
73
|
+
Pi's `tool_search` can declare a tool without restarting an admitted workflow, but cannot add an unselected name to its frozen Plan policy.
|
|
74
|
+
|
|
75
|
+
Allowing a custom tool trusts its effective implementation; Plan mode does not infer its side effects from arguments or annotations.
|
|
65
76
|
Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
|
|
66
|
-
|
|
77
|
+
Names `edit`, `write`, and `update_plan` stay blocked, and `bash` or `powershell` stays subject to its limited-shell policy, including nested calls and regardless of source metadata.
|
|
67
78
|
|
|
68
79
|
A selection accepted through **Choose tools, then start…** or `/plan tools` is stored in that Pi session and takes precedence over `defaultPlanTools` when the session resumes.
|
|
69
80
|
The global setting remains the policy baseline for fresh sessions and sessions without an explicit selection.
|
|
70
81
|
Settings saves immediately, but saved policy names and thinking apply only when a later Plan workflow starts; they never mutate active schemas or a workflow already in progress.
|
|
71
82
|
|
|
83
|
+
### Enable inactive built-in search tools in Pi
|
|
84
|
+
|
|
85
|
+
Pi's default selection leaves the registered built-ins `grep`, `find`, and `ls` inactive.
|
|
86
|
+
Settings and `/plan tools` label these rows **inactive in Pi**, not **blocked by Plan policy**.
|
|
87
|
+
Pi controls tool activation; `defaultPlanTools` only grants Plan-mode execution permission and never activates tools.
|
|
88
|
+
Built-in `edit` and `write` remain policy-blocked even when active in Pi.
|
|
89
|
+
|
|
90
|
+
Change the Pi settings used by the current session, **not** `pi-plan-mode.json`.
|
|
91
|
+
For the CLI, the user file is normally `~/.pi/agent/settings.json`, or `$PI_CODING_AGENT_DIR/settings.json` when configured.
|
|
92
|
+
SDK hosts can use a different `agentDir` or a custom or in-memory `SettingsManager`; ask the host which settings source and restart procedure apply rather than assuming the CLI path.
|
|
93
|
+
The picker cannot determine that source and does not display a concrete Pi settings path.
|
|
94
|
+
|
|
95
|
+
**Full selection (including Pi releases before 0.99 with `defaultTools`):** plain names replace the defaults.
|
|
96
|
+
If you use Pi's normal defaults, this full list preserves them and adds the search tools:
|
|
97
|
+
|
|
98
|
+
```json
|
|
99
|
+
{
|
|
100
|
+
"defaultTools": ["read", "bash", "edit", "write", "grep", "find", "ls"]
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
If you already have a plain-name `defaultTools` list, add `"grep"`, `"find"`, and `"ls"` to it instead of replacing your custom selection with this example.
|
|
105
|
+
|
|
106
|
+
**Additive selection (Pi 0.99 or newer only):** `+name` and `-name` modifiers change the inherited selection.
|
|
107
|
+
With no existing `defaultTools`, use:
|
|
108
|
+
|
|
109
|
+
```json
|
|
110
|
+
{
|
|
111
|
+
"defaultTools": ["+grep", "+find", "+ls"]
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
On Pi 0.99+, append these modifiers to an existing non-empty `defaultTools` array to preserve custom inclusions and exclusions.
|
|
116
|
+
If your existing list is `[]`, use plain names `["grep", "find", "ls"]` to enable only the search tools; a modifier-only list would restore the inherited defaults too.
|
|
117
|
+
Do not use modifiers on older releases: they treat them as exact names and can disable the normal built-in tools.
|
|
118
|
+
Preserve unrelated settings in either setup.
|
|
119
|
+
Releases without `defaultTools` need an upgrade for this setup; the extension's older-Pi compatibility is unchanged.
|
|
120
|
+
Restart Pi, then reopen `/plan settings` → **Plan policy tools** or `/plan tools` and select the tools if your Plan policy does not already allow them.
|
|
121
|
+
CLI tool allowlists/exclusions can override this setting, and trusted project settings can affect the effective selection.
|
|
122
|
+
If the rows remain inactive, check those overrides before changing Plan policy.
|
|
123
|
+
Custom tools and overrides of built-in names still require explicit Plan-policy opt-in; this setup does not bypass blocked policy, hidden exposure, or missing registration.
|
|
124
|
+
|
|
72
125
|
### Plan reinjection
|
|
73
126
|
|
|
74
127
|
The stable JSON field `implementationPlanRetention` controls whether and how long the `context` hook restores the exact approved plan when ordinary model context no longer contains it.
|
|
@@ -129,22 +182,32 @@ Tree navigation and compaction do not apply pending shortcut changes.
|
|
|
129
182
|
|
|
130
183
|
### Safe shell subcommands
|
|
131
184
|
|
|
132
|
-
`safeSubcommands` maps
|
|
133
|
-
For example, `"kubectl": ["get", "apply"]` trusts
|
|
185
|
+
`safeSubcommands` maps command prefixes to subcommand prefixes that the user chooses to trust within individual parsed segments of limited `bash` and `powershell` commands.
|
|
186
|
+
For example, `"kubectl": ["get", "apply"]` trusts segments beginning with `kubectl get` or `kubectl apply`, while `"npm": ["run inspect-custom"]` trusts segments beginning with `npm run inspect-custom`.
|
|
134
187
|
Command keys and subcommand entries are trimmed and must be non-empty strings.
|
|
135
|
-
Matches are literal and case-sensitive after
|
|
136
|
-
A match requires the complete `<command> <subcommand>` prefix followed by
|
|
188
|
+
Matches are literal and case-sensitive after surrounding whitespace in each segment is removed.
|
|
189
|
+
A match requires the complete `<command> <subcommand>` prefix followed by a token boundary, so `"kubectl": ["apply"]` does not match `kubectl applies`; extra whitespace or quotes inside the prefix do not match.
|
|
137
190
|
Duplicate values and command keys that become equal after trimming are merged in first-seen order.
|
|
138
191
|
Omitted `safeSubcommands`, an empty object, and empty arrays preserve the default policy.
|
|
139
192
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
193
|
+
Plan mode parses the complete submission before considering any configured exemption.
|
|
194
|
+
Bash supports `&&`, `||`, `;`, and `|`; PowerShell supports `;` and `|`, not `&&` or `||`.
|
|
195
|
+
Every segment must either match its own configured prefix or pass the built-in reviewed policy, regardless of its position in the chain.
|
|
196
|
+
For example, `"kubectl": ["apply"]` permits `git status && kubectl apply -f deployment.yaml` but does not permit `kubectl apply -f deployment.yaml && rm -rf build` unless the second segment is also explicitly trusted.
|
|
197
|
+
Parser-unsupported syntax remains blocked even after a trusted prefix, including unquoted redirects, multiline input, and unquoted substitutions such as `kubectl apply $(cat generated-args)`.
|
|
198
|
+
|
|
199
|
+
A matching segment bypasses command and argument checks: `"gh": ["pr view"]` still permits `gh pr view 218 --web`, and `"kubectl": ["apply"]` still permits deployment changes.
|
|
200
|
+
Parser-accepted Bash arguments remain trusted, including variable expansion and double-quoted substitutions; an argument such as `"$(touch output)"` can itself execute code.
|
|
201
|
+
The setting can therefore allow arbitrary code execution with Pi's permissions within a trusted segment.
|
|
144
202
|
It is not a sandbox, confirmation gate, or read-only guarantee.
|
|
145
203
|
Choose entries that are as specific as your workflow permits, and configure them only for commands and repositories you fully trust.
|
|
146
204
|
|
|
147
|
-
|
|
205
|
+
**Migration from whole-command trust:** a configured prefix no longer exempts trailing commands or unsupported syntax.
|
|
206
|
+
Simple configured commands continue to work; for supported chains, each additional segment must be reviewed independently or explicitly trusted through its own narrow entry.
|
|
207
|
+
Run workflows requiring redirects, multiline input, or other unsupported syntax outside Plan mode after review rather than relying on the old bypass.
|
|
208
|
+
The JSON schema and settings file do not need migration.
|
|
209
|
+
|
|
210
|
+
Segments that do not match still use the built-in fail-closed reviewed policy.
|
|
148
211
|
That default policy includes Git `status`, `log`, `diff`, `show`, `branch`, `remote`, `ls-files`, and `grep`, with command-specific argument checks.
|
|
149
212
|
It rejects output and input redirects, shell expansion and substitution, explicit pager or browser requests, explicit external diff, textconv, filter, or signature helpers, mutating flags, malformed command layouts, and any parsed chain containing an unsafe segment.
|
|
150
213
|
Read-dominant Git validators accept ordinary inspection flags without requiring `--no-textconv` or `--no-ext-diff`; Git may therefore invoke a helper configured by the user or trusted repository even when the command does not request one explicitly.
|
|
@@ -153,7 +216,7 @@ Mixed read/write surfaces remain narrower: use `git remote show -n` to avoid inv
|
|
|
153
216
|
|
|
154
217
|
Read-only does not mean private: Git inspection can expose repository history and tracked secrets, while configured commands can expose or modify any data available to Pi's process.
|
|
155
218
|
A built-in-policy `git -C <path>` inspection is accepted only when the path keeps Git in Pi's current working directory.
|
|
156
|
-
The default policy reduces accidental mutation and cross-repository executable configuration; configured `safeSubcommands` bypass
|
|
219
|
+
The default policy reduces accidental mutation and cross-repository executable configuration; configured `safeSubcommands` bypass command and argument protection only within matching segments.
|
|
157
220
|
A non-object `safeSubcommands`, empty command or subcommand string, non-array value, or non-string entry invalidates the entire settings file and triggers the normal warning/default fallback on session start.
|
|
158
221
|
|
|
159
222
|
### Thinking level
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@narumitw/pi-plan-mode",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.59.0",
|
|
4
4
|
"description": "Pi extension that adds a Codex-like read-only /plan collaboration mode.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -36,8 +36,8 @@
|
|
|
36
36
|
"@earendil-works/pi-tui": "*"
|
|
37
37
|
},
|
|
38
38
|
"devDependencies": {
|
|
39
|
-
"@earendil-works/pi-coding-agent": "0.
|
|
40
|
-
"@earendil-works/pi-tui": "0.
|
|
39
|
+
"@earendil-works/pi-coding-agent": "1.0.2",
|
|
40
|
+
"@earendil-works/pi-tui": "1.0.2",
|
|
41
41
|
"esbuild": "0.28.2",
|
|
42
42
|
"typescript": "7.0.2"
|
|
43
43
|
},
|
package/src/mode-contract.ts
CHANGED
|
@@ -1,9 +1,13 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
1
2
|
import { buildPlanModePrompt } from "./prompt.js";
|
|
2
3
|
|
|
3
4
|
export const MODE_CONTRACT_MESSAGE_TYPE = "plan-mode-transition";
|
|
4
5
|
export const MODE_CONTRACT_VERSION = 1;
|
|
5
6
|
export type PlanModeContract = "plan" | "normal";
|
|
6
7
|
|
|
8
|
+
// Accept only the exact previous v1 contract, not arbitrary marker-prefixed prose.
|
|
9
|
+
// This preserves retained prefixes when upgrading the native-tool policy wording.
|
|
10
|
+
const PRE_NATIVE_MCP_PLAN_CONTRACT_SHA256 = "9d1dcbca0a8641ad639e54a843d1938bae14b5dab81c826e21a03fa525355f59";
|
|
7
11
|
const PLAN_CONTRACT_MARKER = `[PI PLAN MODE CONTRACT v${MODE_CONTRACT_VERSION}: PLAN]`;
|
|
8
12
|
const NORMAL_CONTRACT_MARKER = `[PI PLAN MODE CONTRACT v${MODE_CONTRACT_VERSION}: NORMAL]`;
|
|
9
13
|
const NORMAL_CONTRACT = `${NORMAL_CONTRACT_MARKER}
|
|
@@ -39,6 +43,11 @@ export function modeContractFromMessage(message: unknown): PlanModeContract | un
|
|
|
39
43
|
if (candidate.customType !== MODE_CONTRACT_MESSAGE_TYPE) return undefined;
|
|
40
44
|
if (candidate.content === modeContractContent("plan")) return "plan";
|
|
41
45
|
if (candidate.content === modeContractContent("normal")) return "normal";
|
|
46
|
+
if (
|
|
47
|
+
typeof candidate.content === "string" &&
|
|
48
|
+
createHash("sha256").update(candidate.content).digest("hex") === PRE_NATIVE_MCP_PLAN_CONTRACT_SHA256
|
|
49
|
+
)
|
|
50
|
+
return "plan";
|
|
42
51
|
return undefined;
|
|
43
52
|
}
|
|
44
53
|
|
package/src/plan-launch-menu.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
2
|
-
import { defineMenu, runMenu } from "@narumitw/pi-tui-kit";
|
|
2
|
+
import { defineMenu, runMenu, sanitizeTerminalText } from "@narumitw/pi-tui-kit";
|
|
3
3
|
|
|
4
4
|
export interface PlanLaunchTool {
|
|
5
5
|
name: string;
|
|
@@ -39,7 +39,7 @@ export async function showPlanLaunchMenu(ctx: ExtensionContext, options: PlanLau
|
|
|
39
39
|
main: () => ({
|
|
40
40
|
kind: "actions",
|
|
41
41
|
title: "Plan mode",
|
|
42
|
-
lines: [options.statusText, options.toolSummary(selectedNames)],
|
|
42
|
+
lines: [options.statusText, options.toolSummary(selectedNames)].map(sanitizeTerminalText),
|
|
43
43
|
items: [
|
|
44
44
|
{ id: "start", label: "Start Plan mode", action: "start" },
|
|
45
45
|
{ id: "tools", label: "Choose tools, then start…", to: "tools" },
|
|
@@ -54,19 +54,19 @@ export async function showPlanLaunchMenu(ctx: ExtensionContext, options: PlanLau
|
|
|
54
54
|
lines: [
|
|
55
55
|
"Policy changes apply only when you start Plan mode; first use may also reveal Plan helpers.",
|
|
56
56
|
options.toolSummary(selectedNames),
|
|
57
|
-
"
|
|
58
|
-
"Plan mode never activates tools
|
|
59
|
-
],
|
|
57
|
+
"Available tools can be chosen now; retained names resolve before the first request.",
|
|
58
|
+
"Plan mode never activates tools; tools outside its reviewed core policy run at user risk.",
|
|
59
|
+
].map(sanitizeTerminalText),
|
|
60
60
|
enableSearch: true,
|
|
61
61
|
viewportSize: 10,
|
|
62
62
|
items: toolItems.map(({ id, tool }) => ({
|
|
63
63
|
id,
|
|
64
|
-
label: tool.label ?? tool.name,
|
|
65
|
-
description: tool.description,
|
|
66
|
-
searchText: tool.searchText,
|
|
64
|
+
label: sanitizeTerminalText(tool.label ?? tool.name),
|
|
65
|
+
description: sanitizeTerminalText(tool.description),
|
|
66
|
+
searchText: sanitizeTerminalText(tool.searchText),
|
|
67
67
|
selected: selectedNames.has(tool.name),
|
|
68
68
|
disabled: tool.disabled,
|
|
69
|
-
disabledReason: tool.disabledReason,
|
|
69
|
+
disabledReason: tool.disabledReason ? sanitizeTerminalText(tool.disabledReason) : undefined,
|
|
70
70
|
})),
|
|
71
71
|
action: "toggle-tool",
|
|
72
72
|
actions: [
|
package/src/plan-mode.ts
CHANGED
|
@@ -87,6 +87,7 @@ import {
|
|
|
87
87
|
type PlanModeWorkflowToolPolicy,
|
|
88
88
|
restorePlanModeState,
|
|
89
89
|
} from "./state.js";
|
|
90
|
+
import { planModeToolAvailability } from "./tool-availability.js";
|
|
90
91
|
import {
|
|
91
92
|
canSelectToolInPlanMode,
|
|
92
93
|
classifyPlanModeTool,
|
|
@@ -94,7 +95,12 @@ import {
|
|
|
94
95
|
findBlockedPowerShellCommandSegment,
|
|
95
96
|
readCommand,
|
|
96
97
|
} from "./tool-policy.js";
|
|
97
|
-
import {
|
|
98
|
+
import {
|
|
99
|
+
compareTools,
|
|
100
|
+
filterAvailableSelectedToolNames,
|
|
101
|
+
planModeToolSelection,
|
|
102
|
+
snapshotPlanModeSelectedNames,
|
|
103
|
+
} from "./tool-selection.js";
|
|
98
104
|
import { WorkflowMutex, type WorkflowMutexOwner } from "./workflow-mutex.js";
|
|
99
105
|
|
|
100
106
|
const STATE_ENTRY_TYPE = "plan-mode-state";
|
|
@@ -656,26 +662,42 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
656
662
|
: `Plan mode blocks tool '${event.toolName}' because it is not registered or active. Register and activate it before starting the next Plan workflow.`,
|
|
657
663
|
};
|
|
658
664
|
}
|
|
659
|
-
if (
|
|
665
|
+
if (!calledTool.sourceInfo?.source) {
|
|
660
666
|
return {
|
|
661
667
|
block: true,
|
|
662
|
-
reason: `Plan mode blocks tool '${event.toolName}' because its
|
|
668
|
+
reason: `Plan mode blocks tool '${event.toolName}' because its safe policy metadata is unavailable.`,
|
|
663
669
|
};
|
|
664
670
|
}
|
|
665
|
-
|
|
666
|
-
if (!activeToolNames.has(event.toolName)) {
|
|
671
|
+
if (classifyPlanModeTool(calledTool) === "blocked") {
|
|
667
672
|
return {
|
|
668
673
|
block: true,
|
|
669
|
-
reason:
|
|
670
|
-
? `Plan mode blocks tool '${event.toolName}' because it was admitted to the active Plan workflow but is currently inactive. Reactivate it to continue without restarting.`
|
|
671
|
-
: `Plan mode blocks tool '${event.toolName}' because it is registered but inactive. Activate it before starting the next Plan workflow.`,
|
|
674
|
+
reason: `Plan mode blocks tool '${event.toolName}' because its built-in policy is blocked and settings cannot enable it.`,
|
|
672
675
|
};
|
|
673
676
|
}
|
|
677
|
+
const allowedToolNames = new Set(planModePolicyToolNames());
|
|
678
|
+
const availability = planModeToolAvailability(
|
|
679
|
+
calledTool,
|
|
680
|
+
activeToolNames,
|
|
681
|
+
event.parentToolCallId ? "nested" : "model",
|
|
682
|
+
);
|
|
683
|
+
if (availability !== "available") {
|
|
684
|
+
const reason =
|
|
685
|
+
availability === "inactive"
|
|
686
|
+
? allowedToolNames.has(event.toolName)
|
|
687
|
+
? "it was admitted to the active Plan workflow but is currently inactive. Reactivate it to continue without restarting."
|
|
688
|
+
: "it is registered but inactive. Activate it before starting the next Plan workflow."
|
|
689
|
+
: availability === "hidden"
|
|
690
|
+
? "it is hidden in Pi. Stored selection cannot enable hidden tools."
|
|
691
|
+
: availability === "model-only"
|
|
692
|
+
? "it is model-only and cannot be called by another tool."
|
|
693
|
+
: "its tool exposure is unsupported.";
|
|
694
|
+
return { block: true, reason: `Plan mode blocks tool '${event.toolName}' because ${reason}` };
|
|
695
|
+
}
|
|
674
696
|
if (!allowedToolNames.has(event.toolName)) {
|
|
675
697
|
return {
|
|
676
698
|
block: true,
|
|
677
699
|
reason: workflowDesiredToolNames().has(event.toolName)
|
|
678
|
-
? `Plan mode blocks tool '${event.toolName}' because it was not available when the active Plan workflow froze its tool policy. Exit Plan mode, then start again after the tool is
|
|
700
|
+
? `Plan mode blocks tool '${event.toolName}' because it was not available when the active Plan workflow froze its tool policy. Exit Plan mode, then start again after the tool is available.`
|
|
679
701
|
: `Plan mode blocks tool '${event.toolName}' because it is not selected by the Plan policy. Exit Plan mode, then enable it with /plan tools or defaultPlanTools before starting again.`,
|
|
680
702
|
};
|
|
681
703
|
}
|
|
@@ -1304,7 +1326,10 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1304
1326
|
toolSummary: (selectedNames) => {
|
|
1305
1327
|
const allowed = tools
|
|
1306
1328
|
.filter(
|
|
1307
|
-
(tool) =>
|
|
1329
|
+
(tool) =>
|
|
1330
|
+
planModeToolAvailability(tool, activeToolNames) === "available" &&
|
|
1331
|
+
selectedNames.has(tool.name) &&
|
|
1332
|
+
canSelectToolInPlanMode(tool),
|
|
1308
1333
|
)
|
|
1309
1334
|
.map((tool) => tool.name);
|
|
1310
1335
|
const pending = pendingNames.filter((name) => selectedNames.has(name)).map(terminalToolName);
|
|
@@ -1318,27 +1343,9 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1318
1343
|
},
|
|
1319
1344
|
tools: [
|
|
1320
1345
|
...tools.map((tool) => {
|
|
1321
|
-
const selectable = canSelectToolInPlanMode(tool);
|
|
1322
|
-
const active = activeToolNames.has(tool.name);
|
|
1323
|
-
const retained = retainedInactiveNames.has(tool.name);
|
|
1324
|
-
const policy = active
|
|
1325
|
-
? toolPolicyLabel(tool)
|
|
1326
|
-
: retained
|
|
1327
|
-
? "not active yet; retained for first-request resolution"
|
|
1328
|
-
: "not active in this Pi session";
|
|
1329
|
-
const description = tool.description ?? "No description available";
|
|
1330
1346
|
return {
|
|
1331
1347
|
name: tool.name,
|
|
1332
|
-
|
|
1333
|
-
searchText: [policy, description].join(" "),
|
|
1334
|
-
disabled: !selectable || !active,
|
|
1335
|
-
disabledReason: !active
|
|
1336
|
-
? retained
|
|
1337
|
-
? "Not active yet; retained and resolved before the first request"
|
|
1338
|
-
: "Not active in Pi; Plan mode will not activate it"
|
|
1339
|
-
: selectable
|
|
1340
|
-
? undefined
|
|
1341
|
-
: "Blocked by Plan-mode policy",
|
|
1348
|
+
...planModeToolSelection(tool, activeToolNames, retainedInactiveNames.has(tool.name)),
|
|
1342
1349
|
};
|
|
1343
1350
|
}),
|
|
1344
1351
|
...pendingNames.map((name) => {
|
|
@@ -1363,8 +1370,9 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1363
1370
|
},
|
|
1364
1371
|
startWithTools: (names, signal) => {
|
|
1365
1372
|
if (signal.aborted || !lifecycle.isCurrent()) return;
|
|
1373
|
+
const availableNames = new Set(filterAvailableSelectedToolNames(names, tools, activeToolNames));
|
|
1366
1374
|
const selectedToolNames = Array.from(
|
|
1367
|
-
new Set(names.filter((name) =>
|
|
1375
|
+
new Set(names.filter((name) => availableNames.has(name) || retainedInactiveNames.has(name))),
|
|
1368
1376
|
);
|
|
1369
1377
|
if (enterPlanMode(ctx, { selectedToolNames, selectedToolKeys: undefined })) {
|
|
1370
1378
|
ctx.ui.notify("Plan mode enabled with the selected tools.", "info");
|
|
@@ -1523,12 +1531,12 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1523
1531
|
}
|
|
1524
1532
|
|
|
1525
1533
|
function desiredPlanModeToolNames() {
|
|
1526
|
-
const tools =
|
|
1534
|
+
const tools = availablePlanPolicyTools();
|
|
1527
1535
|
return Array.from(snapshotPlanModeSelectedNames(tools, toolSelectionSnapshot()));
|
|
1528
1536
|
}
|
|
1529
1537
|
|
|
1530
1538
|
function automaticPlanModeToolNames() {
|
|
1531
|
-
return Array.from(snapshotPlanModeSelectedNames(
|
|
1539
|
+
return Array.from(snapshotPlanModeSelectedNames(availablePlanPolicyTools(), {}));
|
|
1532
1540
|
}
|
|
1533
1541
|
|
|
1534
1542
|
function resolveWorkflowToolPolicy(policy: PlanModeWorkflowToolPolicy) {
|
|
@@ -1595,7 +1603,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1595
1603
|
|
|
1596
1604
|
function resolvePlanModePolicyToolNames(desiredNames: readonly string[]) {
|
|
1597
1605
|
const selectedNames = new Set(desiredNames);
|
|
1598
|
-
return
|
|
1606
|
+
return availablePlanPolicyTools()
|
|
1599
1607
|
.filter((tool) => selectedNames.has(tool.name) && canSelectToolInPlanMode(tool))
|
|
1600
1608
|
.map((tool) => tool.name);
|
|
1601
1609
|
}
|
|
@@ -1614,9 +1622,9 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1614
1622
|
.sort(compareTools);
|
|
1615
1623
|
}
|
|
1616
1624
|
|
|
1617
|
-
function
|
|
1625
|
+
function availablePlanPolicyTools() {
|
|
1618
1626
|
const activeNames = new Set(safeGetActiveTools());
|
|
1619
|
-
return selectableTools().filter((tool) =>
|
|
1627
|
+
return selectableTools().filter((tool) => planModeToolAvailability(tool, activeNames) === "available");
|
|
1620
1628
|
}
|
|
1621
1629
|
|
|
1622
1630
|
function safeGetAllTools() {
|
package/src/prompt.ts
CHANGED
|
@@ -11,7 +11,7 @@ You are in Plan Mode, a Codex-like collaboration mode for producing a decision-c
|
|
|
11
11
|
- Stay in Plan Mode until a developer or extension explicitly exits it.
|
|
12
12
|
- Treat requests to implement as requests to plan the implementation; do not edit files or carry out the plan.
|
|
13
13
|
- Do not use update_plan/TODO tooling in Plan Mode; Plan Mode is conversational planning, not execution progress tracking.
|
|
14
|
-
- Plan Mode keeps the session's model-visible tool schemas unchanged and enforces a runtime policy allowlist.
|
|
14
|
+
- Plan Mode keeps the session's model-visible tool schemas unchanged and enforces a runtime policy allowlist. Tools outside its reviewed core policy, including native MCP tools and orchestration tools, require explicit user opt-in at their own risk. Direct and model-only tools must be active; registered codemode or deferred tools can be selected without direct activation. Every nested call requires its own permission; selecting an orchestrator does not authorize its callees.
|
|
15
15
|
- Do not perform mutating actions: no edit/write tools, no patching, no formatting that rewrites files, no dependency installation, no commits, no migrations.
|
|
16
16
|
|
|
17
17
|
## Phase 1 — Ground in the environment
|
package/src/settings-menu.ts
CHANGED
|
@@ -28,8 +28,9 @@ import {
|
|
|
28
28
|
type UpdatePlanModeSettingsOptions,
|
|
29
29
|
updatePlanModeSettings,
|
|
30
30
|
} from "./settings.js";
|
|
31
|
+
import { planModeToolAvailability } from "./tool-availability.js";
|
|
31
32
|
import { canSelectToolInPlanMode } from "./tool-policy.js";
|
|
32
|
-
import { defaultPlanModeToolNames,
|
|
33
|
+
import { defaultPlanModeToolNames, planModeToolSelection } from "./tool-selection.js";
|
|
33
34
|
|
|
34
35
|
interface SettingsMenuState {
|
|
35
36
|
kind: "valid" | "invalid";
|
|
@@ -122,7 +123,7 @@ export async function showPlanModeSettings(
|
|
|
122
123
|
{
|
|
123
124
|
id: "defaultPlanTools",
|
|
124
125
|
label: "Plan policy tools",
|
|
125
|
-
description: "Choose
|
|
126
|
+
description: "Choose available tools or retain names to resolve before the first request.",
|
|
126
127
|
currentValue: defaultToolsValue(state.settings.defaultPlanTools),
|
|
127
128
|
action: "open-tools",
|
|
128
129
|
},
|
|
@@ -173,7 +174,7 @@ export async function showPlanModeSettings(
|
|
|
173
174
|
lines: [
|
|
174
175
|
"Changes apply when a later Plan workflow starts; model-visible tools stay unchanged.",
|
|
175
176
|
"Retained inactive names resolve before that workflow's first request.",
|
|
176
|
-
"Plan mode never activates tools
|
|
177
|
+
"Plan mode never activates tools; tools outside its reviewed core policy run at user risk.",
|
|
177
178
|
],
|
|
178
179
|
enableSearch: true,
|
|
179
180
|
viewportSize: 10,
|
|
@@ -332,7 +333,11 @@ export async function showPlanModeSettings(
|
|
|
332
333
|
},
|
|
333
334
|
"toggle-tool": async ({ ctx: actionCtx, state, itemId, selected, signal }) => {
|
|
334
335
|
const tool = itemId ? toolsByItemId.get(itemId) : undefined;
|
|
335
|
-
if (
|
|
336
|
+
if (
|
|
337
|
+
!tool ||
|
|
338
|
+
planModeToolAvailability(tool, activeToolNames) !== "available" ||
|
|
339
|
+
!canSelectToolInPlanMode(tool)
|
|
340
|
+
) {
|
|
336
341
|
return { kind: "rejected" };
|
|
337
342
|
}
|
|
338
343
|
const names = explicitToolNames(tools, state.settings.defaultPlanTools);
|
|
@@ -481,28 +486,15 @@ function defaultToolItems(
|
|
|
481
486
|
const selected = new Set(explicitToolNames(tools, configured));
|
|
482
487
|
const availableNames = new Set(tools.map((tool) => tool.name));
|
|
483
488
|
const items = tools.map((tool) => {
|
|
484
|
-
const
|
|
485
|
-
const selectable = active && canSelectToolInPlanMode(tool);
|
|
486
|
-
const policy = active
|
|
487
|
-
? toolPolicyLabel(tool)
|
|
488
|
-
: selected.has(tool.name)
|
|
489
|
-
? "not active yet; retained for first-request resolution"
|
|
490
|
-
: "not active in this Pi session";
|
|
491
|
-
const description = tool.description ?? "No description available";
|
|
489
|
+
const presentation = planModeToolSelection(tool, activeToolNames, selected.has(tool.name));
|
|
492
490
|
return {
|
|
493
491
|
id: toolItemIds.get(tool.name) as string,
|
|
494
|
-
label: tool.name,
|
|
495
|
-
description: `${policy} · ${description}`,
|
|
496
|
-
searchText: `${policy} ${description}`,
|
|
497
492
|
selected: selected.has(tool.name),
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
: selectable
|
|
504
|
-
? undefined
|
|
505
|
-
: "Blocked by Plan-mode policy",
|
|
493
|
+
...presentation,
|
|
494
|
+
label: sanitizeTerminalText(presentation.label),
|
|
495
|
+
description: sanitizeTerminalText(presentation.description),
|
|
496
|
+
searchText: sanitizeTerminalText(presentation.searchText),
|
|
497
|
+
disabledReason: presentation.disabledReason ? sanitizeTerminalText(presentation.disabledReason) : undefined,
|
|
506
498
|
};
|
|
507
499
|
});
|
|
508
500
|
for (const [index, name] of (configured ?? []).entries()) {
|
|
@@ -526,7 +518,7 @@ function explicitToolNames(tools: readonly ToolInfo[], configured: string[] | un
|
|
|
526
518
|
}
|
|
527
519
|
|
|
528
520
|
function terminalToolName(value: string) {
|
|
529
|
-
const safe =
|
|
521
|
+
const safe = sanitizeTerminalText(value).trim() || "(unnamed tool)";
|
|
530
522
|
return safe.length > 120 ? `${safe.slice(0, 119)}…` : safe;
|
|
531
523
|
}
|
|
532
524
|
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import type { ToolInfo } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
|
|
3
|
+
export type PlanModeToolAvailability = "available" | "inactive" | "hidden" | "model-only" | "unsupported";
|
|
4
|
+
|
|
5
|
+
/** Pi's active set is model declaration, not the complete callable registry. */
|
|
6
|
+
export function planModeToolAvailability(
|
|
7
|
+
tool: ToolInfo,
|
|
8
|
+
activeNames: ReadonlySet<string>,
|
|
9
|
+
route: "selection" | "model" | "nested" = "selection",
|
|
10
|
+
): PlanModeToolAvailability {
|
|
11
|
+
switch (tool.exposure) {
|
|
12
|
+
case "hidden":
|
|
13
|
+
return "hidden";
|
|
14
|
+
case "model-only":
|
|
15
|
+
if (route === "nested") return "model-only";
|
|
16
|
+
return activeNames.has(tool.name) ? "available" : "inactive";
|
|
17
|
+
case "codemode":
|
|
18
|
+
case "deferred":
|
|
19
|
+
if (route !== "model") return "available";
|
|
20
|
+
return activeNames.has(tool.name) ? "available" : "inactive";
|
|
21
|
+
case undefined: // Older Pi versions exposed only directly active tools.
|
|
22
|
+
case "direct":
|
|
23
|
+
return activeNames.has(tool.name) ? "available" : "inactive";
|
|
24
|
+
default:
|
|
25
|
+
return "unsupported";
|
|
26
|
+
}
|
|
27
|
+
}
|
package/src/tool-policy.ts
CHANGED
|
@@ -113,11 +113,20 @@ const READ_ONLY_COMMANDS = new Set([
|
|
|
113
113
|
"eza",
|
|
114
114
|
]);
|
|
115
115
|
|
|
116
|
+
// `-i` edits in place for sed. For these inspection commands it is case-insensitive
|
|
117
|
+
// search or inode output, which is how plan mode reads markdown and other text.
|
|
118
|
+
const INSPECTION_CASE_FLAG_COMMANDS = new Set(["rg", "grep", "git", "diff", "fd", "ls", "sort", "find", "bat", "eza"]);
|
|
119
|
+
|
|
116
120
|
export function isBuiltinTool(tool: ToolInfo) {
|
|
117
|
-
|
|
121
|
+
const source = tool.sourceInfo;
|
|
122
|
+
if (source?.source !== "builtin") return false;
|
|
123
|
+
// Core tools own builtin:<name>; built-in extensions may own many tools or
|
|
124
|
+
// expose model-only orchestration. Missing paths preserve legacy core policy.
|
|
125
|
+
return !source.path || (source.path === `builtin:${tool.name}` && tool.exposure !== "model-only");
|
|
118
126
|
}
|
|
119
127
|
|
|
120
128
|
export function classifyPlanModeTool(tool: ToolInfo): PlanModeToolPolicy {
|
|
129
|
+
if (!tool.sourceInfo?.source) return "blocked";
|
|
121
130
|
if (!isBuiltinTool(tool)) return "user-opt-in";
|
|
122
131
|
if (BLOCKED_BUILTIN_TOOLS.has(tool.name)) return "blocked";
|
|
123
132
|
if (tool.name === "bash" || tool.name === "powershell") return "limited";
|
|
@@ -139,7 +148,6 @@ export function findBlockedCommandSegment(
|
|
|
139
148
|
workingDirectory?: string,
|
|
140
149
|
platform: NodeJS.Platform = process.platform,
|
|
141
150
|
): string | undefined {
|
|
142
|
-
if (matchesConfiguredSafeSubcommand(command, safeSubcommands)) return undefined;
|
|
143
151
|
const segments = splitShellSegments(command);
|
|
144
152
|
if (!segments || segments.length === 0) return command.trim() || "(empty command)";
|
|
145
153
|
return segments.find((segment) => !isSafeSegment(segment, safeSubcommands, workingDirectory, platform));
|
|
@@ -159,7 +167,6 @@ export function findBlockedPowerShellCommandSegment(
|
|
|
159
167
|
safeSubcommands: SafeSubcommands = {},
|
|
160
168
|
workingDirectory?: string,
|
|
161
169
|
): string | undefined {
|
|
162
|
-
if (matchesConfiguredSafeSubcommand(command, safeSubcommands)) return undefined;
|
|
163
170
|
const segments = splitPowerShellSegments(command);
|
|
164
171
|
if (!segments || segments.length === 0) return command.trim() || "(empty command)";
|
|
165
172
|
return segments.find((segment) => !isSafePowerShellSegment(segment, safeSubcommands, workingDirectory));
|
|
@@ -235,6 +242,7 @@ function splitPowerShellSegments(command: string): string[] | undefined {
|
|
|
235
242
|
}
|
|
236
243
|
|
|
237
244
|
function isSafePowerShellSegment(segment: string, safeSubcommands: SafeSubcommands, workingDirectory?: string) {
|
|
245
|
+
if (matchesConfiguredSafeSubcommand(segment, safeSubcommands)) return true;
|
|
238
246
|
const tokens = powerShellWords(segment);
|
|
239
247
|
if (!tokens || tokens.length === 0 || tokens.includes("--%")) return false;
|
|
240
248
|
const command = tokens[0]?.toLowerCase();
|
|
@@ -342,6 +350,7 @@ function isSafeSegment(
|
|
|
342
350
|
workingDirectory: string | undefined,
|
|
343
351
|
platform: NodeJS.Platform,
|
|
344
352
|
) {
|
|
353
|
+
if (matchesConfiguredSafeSubcommand(segment, safeSubcommands)) return true;
|
|
345
354
|
if (hasShellExpansion(segment) || /(^|\s)[A-Za-z_][A-Za-z0-9_]*=/.test(segment)) {
|
|
346
355
|
return false;
|
|
347
356
|
}
|
|
@@ -415,7 +424,8 @@ function shellWords(segment: string): string[] | undefined {
|
|
|
415
424
|
}
|
|
416
425
|
|
|
417
426
|
function hasSafeArguments(command: string, args: string[]) {
|
|
418
|
-
const forbidden = new Set(["
|
|
427
|
+
const forbidden = new Set(["--in-place", "--fix", "--write", "-delete", "--delete"]);
|
|
428
|
+
if (!INSPECTION_CASE_FLAG_COMMANDS.has(command)) forbidden.add("-i");
|
|
419
429
|
if (args.some((argument) => forbidden.has(argument))) return false;
|
|
420
430
|
if (
|
|
421
431
|
command === "sed" &&
|