@narumitw/pi-plan-mode 0.58.2 → 0.58.4
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 +22 -9
- package/dist/chunks/{chunk-L2CXUWCH.ts → chunk-VLNCRAFL.ts} +74 -5
- package/dist/chunks/{chunk-L2CXUWCH.ts.map → chunk-VLNCRAFL.ts.map} +3 -3
- package/dist/chunks/{interactive-ui-VHZ5GODE.ts → interactive-ui-JEXFZHRD.ts} +31 -32
- package/dist/chunks/interactive-ui-JEXFZHRD.ts.map +7 -0
- package/dist/index.ts +49 -47
- package/dist/index.ts.map +3 -3
- package/docs/command-workflows.md +6 -1
- package/docs/settings.md +67 -9
- 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 +58 -55
- package/src/prompt.ts +1 -1
- package/src/settings-menu.ts +25 -30
- package/src/tool-availability.ts +27 -0
- package/src/tool-policy.ts +12 -2
- package/src/tool-selection.ts +55 -3
- package/dist/chunks/interactive-ui-VHZ5GODE.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.
|
|
@@ -117,10 +170,15 @@ Long previews wrap or truncate to the available terminal width without changing
|
|
|
117
170
|
|
|
118
171
|
### Toggle shortcut
|
|
119
172
|
|
|
120
|
-
`toggleShortcut`
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
173
|
+
`toggleShortcut` configures the Plan-mode toggle in TUI mode; it is disabled by default.
|
|
174
|
+
Set it to a Pi key identifier, or omit it to disable the shortcut on the next load.
|
|
175
|
+
Enabling, changing, or removing the shortcut requires `/reload` or restarting Pi, whether saved through Settings or edited in JSON.
|
|
176
|
+
The current binding stays unchanged until then; Settings shows the configured value separately from the value loaded at startup.
|
|
177
|
+
Pi snapshots shortcut registrations when binding the editor, so Plan mode registers once per extension runtime rather than attempting live rebinding.
|
|
178
|
+
Other settings retain their existing watched reload behavior, and `/plan` commands are unchanged.
|
|
179
|
+
|
|
180
|
+
Avoid conflicts with Pi or other extension shortcuts; the startup value is a registration preference, not a guarantee that Pi accepts it or the terminal sends that key combination.
|
|
181
|
+
Tree navigation and compaction do not apply pending shortcut changes.
|
|
124
182
|
|
|
125
183
|
### Safe shell subcommands
|
|
126
184
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@narumitw/pi-plan-mode",
|
|
3
|
-
"version": "0.58.
|
|
3
|
+
"version": "0.58.4",
|
|
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.0",
|
|
40
|
+
"@earendil-works/pi-tui": "1.0.0",
|
|
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";
|
|
@@ -171,8 +177,8 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
171
177
|
const explicitPlanModeSettingsPath = dependencies.settingsPath;
|
|
172
178
|
let state: PlanModeState = { enabled: false, awaitingAction: false };
|
|
173
179
|
let settings: PlanModeSettings = { thinkingLevel: "inherit" };
|
|
174
|
-
let
|
|
175
|
-
|
|
180
|
+
let startupToggleShortcut: ReturnType<typeof configuredPlanModeToggleShortcut>;
|
|
181
|
+
let shortcutInitialized = false;
|
|
176
182
|
let workflowAllowedToolNames: string[] | undefined;
|
|
177
183
|
let pendingWorkflowToolPolicy: PendingWorkflowToolPolicy | undefined;
|
|
178
184
|
let publishedContractMode: PlanModeContract | undefined;
|
|
@@ -389,24 +395,19 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
389
395
|
},
|
|
390
396
|
});
|
|
391
397
|
|
|
392
|
-
const
|
|
393
|
-
if (
|
|
394
|
-
|
|
395
|
-
|
|
398
|
+
const initializePlanModeShortcut = () => {
|
|
399
|
+
if (shortcutInitialized) return;
|
|
400
|
+
// Pi snapshots registrations when binding the editor. Keep even an unset shortcut stable
|
|
401
|
+
// for this runtime; settings saves and file watches take effect after /reload or restart.
|
|
402
|
+
const shortcut = configuredPlanModeToggleShortcut(settings);
|
|
403
|
+
if (shortcut) {
|
|
404
|
+
pi.registerShortcut(shortcut, {
|
|
405
|
+
description: "Toggle Plan mode",
|
|
406
|
+
handler: (ctx) => togglePlanMode(ctx),
|
|
396
407
|
});
|
|
397
408
|
}
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
return;
|
|
401
|
-
}
|
|
402
|
-
if (toggleShortcut === nextShortcut) return;
|
|
403
|
-
pi.registerShortcut(nextShortcut, {
|
|
404
|
-
description: "Toggle Plan mode",
|
|
405
|
-
handler: (ctx) => {
|
|
406
|
-
togglePlanMode(ctx);
|
|
407
|
-
},
|
|
408
|
-
});
|
|
409
|
-
toggleShortcut = nextShortcut;
|
|
409
|
+
startupToggleShortcut = shortcut;
|
|
410
|
+
shortcutInitialized = true;
|
|
410
411
|
};
|
|
411
412
|
|
|
412
413
|
const readPlanModeRuntimeSettings = async () => {
|
|
@@ -426,7 +427,6 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
426
427
|
loadedSettings.kind === "loaded"
|
|
427
428
|
? loadedSettings.settings
|
|
428
429
|
: ({ thinkingLevel: "inherit" } satisfies PlanModeSettings);
|
|
429
|
-
applyPlanModeShortcut(configuredPlanModeToggleShortcut(settings));
|
|
430
430
|
if (!ctx || !showWarnings) return loadedSettings;
|
|
431
431
|
if (loadedSettings.kind === "invalid") {
|
|
432
432
|
ctx.ui.notify(`pi-plan-mode settings ignored: ${loadedSettings.reason}`, "warning");
|
|
@@ -503,6 +503,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
503
503
|
state = { enabled: false, awaitingAction: false };
|
|
504
504
|
await applyPlanModeSettings(generation, ctx, true);
|
|
505
505
|
if (generation !== menuGeneration || menuController.signal.aborted) return;
|
|
506
|
+
initializePlanModeShortcut();
|
|
506
507
|
startPlanModeSettingsWatch(generation);
|
|
507
508
|
if (!installRestoredState(restoredState, ctx)) return;
|
|
508
509
|
implementationRetention.restore(state.activeImplementation);
|
|
@@ -661,26 +662,42 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
661
662
|
: `Plan mode blocks tool '${event.toolName}' because it is not registered or active. Register and activate it before starting the next Plan workflow.`,
|
|
662
663
|
};
|
|
663
664
|
}
|
|
664
|
-
if (
|
|
665
|
+
if (!calledTool.sourceInfo?.source) {
|
|
665
666
|
return {
|
|
666
667
|
block: true,
|
|
667
|
-
reason: `Plan mode blocks tool '${event.toolName}' because its
|
|
668
|
+
reason: `Plan mode blocks tool '${event.toolName}' because its safe policy metadata is unavailable.`,
|
|
668
669
|
};
|
|
669
670
|
}
|
|
670
|
-
|
|
671
|
-
if (!activeToolNames.has(event.toolName)) {
|
|
671
|
+
if (classifyPlanModeTool(calledTool) === "blocked") {
|
|
672
672
|
return {
|
|
673
673
|
block: true,
|
|
674
|
-
reason:
|
|
675
|
-
? `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.`
|
|
676
|
-
: `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.`,
|
|
677
675
|
};
|
|
678
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
|
+
}
|
|
679
696
|
if (!allowedToolNames.has(event.toolName)) {
|
|
680
697
|
return {
|
|
681
698
|
block: true,
|
|
682
699
|
reason: workflowDesiredToolNames().has(event.toolName)
|
|
683
|
-
? `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.`
|
|
684
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.`,
|
|
685
702
|
};
|
|
686
703
|
}
|
|
@@ -1309,7 +1326,10 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1309
1326
|
toolSummary: (selectedNames) => {
|
|
1310
1327
|
const allowed = tools
|
|
1311
1328
|
.filter(
|
|
1312
|
-
(tool) =>
|
|
1329
|
+
(tool) =>
|
|
1330
|
+
planModeToolAvailability(tool, activeToolNames) === "available" &&
|
|
1331
|
+
selectedNames.has(tool.name) &&
|
|
1332
|
+
canSelectToolInPlanMode(tool),
|
|
1313
1333
|
)
|
|
1314
1334
|
.map((tool) => tool.name);
|
|
1315
1335
|
const pending = pendingNames.filter((name) => selectedNames.has(name)).map(terminalToolName);
|
|
@@ -1323,27 +1343,9 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1323
1343
|
},
|
|
1324
1344
|
tools: [
|
|
1325
1345
|
...tools.map((tool) => {
|
|
1326
|
-
const selectable = canSelectToolInPlanMode(tool);
|
|
1327
|
-
const active = activeToolNames.has(tool.name);
|
|
1328
|
-
const retained = retainedInactiveNames.has(tool.name);
|
|
1329
|
-
const policy = active
|
|
1330
|
-
? toolPolicyLabel(tool)
|
|
1331
|
-
: retained
|
|
1332
|
-
? "not active yet; retained for first-request resolution"
|
|
1333
|
-
: "not active in this Pi session";
|
|
1334
|
-
const description = tool.description ?? "No description available";
|
|
1335
1346
|
return {
|
|
1336
1347
|
name: tool.name,
|
|
1337
|
-
|
|
1338
|
-
searchText: [policy, description].join(" "),
|
|
1339
|
-
disabled: !selectable || !active,
|
|
1340
|
-
disabledReason: !active
|
|
1341
|
-
? retained
|
|
1342
|
-
? "Not active yet; retained and resolved before the first request"
|
|
1343
|
-
: "Not active in Pi; Plan mode will not activate it"
|
|
1344
|
-
: selectable
|
|
1345
|
-
? undefined
|
|
1346
|
-
: "Blocked by Plan-mode policy",
|
|
1348
|
+
...planModeToolSelection(tool, activeToolNames, retainedInactiveNames.has(tool.name)),
|
|
1347
1349
|
};
|
|
1348
1350
|
}),
|
|
1349
1351
|
...pendingNames.map((name) => {
|
|
@@ -1368,8 +1370,9 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1368
1370
|
},
|
|
1369
1371
|
startWithTools: (names, signal) => {
|
|
1370
1372
|
if (signal.aborted || !lifecycle.isCurrent()) return;
|
|
1373
|
+
const availableNames = new Set(filterAvailableSelectedToolNames(names, tools, activeToolNames));
|
|
1371
1374
|
const selectedToolNames = Array.from(
|
|
1372
|
-
new Set(names.filter((name) =>
|
|
1375
|
+
new Set(names.filter((name) => availableNames.has(name) || retainedInactiveNames.has(name))),
|
|
1373
1376
|
);
|
|
1374
1377
|
if (enterPlanMode(ctx, { selectedToolNames, selectedToolKeys: undefined })) {
|
|
1375
1378
|
ctx.ui.notify("Plan mode enabled with the selected tools.", "info");
|
|
@@ -1418,10 +1421,10 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1418
1421
|
isCurrent,
|
|
1419
1422
|
settingsPath: dependencies.settingsPath,
|
|
1420
1423
|
updateSettings: dependencies.updateSettings ?? updatePlanModeSettings,
|
|
1424
|
+
startupToggleShortcut,
|
|
1421
1425
|
onSaved: (saved) => {
|
|
1422
1426
|
if (!isCurrent()) return;
|
|
1423
1427
|
settings = saved;
|
|
1424
|
-
applyPlanModeShortcut(configuredPlanModeToggleShortcut(saved));
|
|
1425
1428
|
},
|
|
1426
1429
|
...(dependencies.readSettings
|
|
1427
1430
|
? { readSettings: async () => dependencies.readSettings?.() ?? { kind: "missing" } }
|
|
@@ -1528,12 +1531,12 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1528
1531
|
}
|
|
1529
1532
|
|
|
1530
1533
|
function desiredPlanModeToolNames() {
|
|
1531
|
-
const tools =
|
|
1534
|
+
const tools = availablePlanPolicyTools();
|
|
1532
1535
|
return Array.from(snapshotPlanModeSelectedNames(tools, toolSelectionSnapshot()));
|
|
1533
1536
|
}
|
|
1534
1537
|
|
|
1535
1538
|
function automaticPlanModeToolNames() {
|
|
1536
|
-
return Array.from(snapshotPlanModeSelectedNames(
|
|
1539
|
+
return Array.from(snapshotPlanModeSelectedNames(availablePlanPolicyTools(), {}));
|
|
1537
1540
|
}
|
|
1538
1541
|
|
|
1539
1542
|
function resolveWorkflowToolPolicy(policy: PlanModeWorkflowToolPolicy) {
|
|
@@ -1600,7 +1603,7 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1600
1603
|
|
|
1601
1604
|
function resolvePlanModePolicyToolNames(desiredNames: readonly string[]) {
|
|
1602
1605
|
const selectedNames = new Set(desiredNames);
|
|
1603
|
-
return
|
|
1606
|
+
return availablePlanPolicyTools()
|
|
1604
1607
|
.filter((tool) => selectedNames.has(tool.name) && canSelectToolInPlanMode(tool))
|
|
1605
1608
|
.map((tool) => tool.name);
|
|
1606
1609
|
}
|
|
@@ -1619,9 +1622,9 @@ export default function planMode(pi: ExtensionAPI, dependencies: PlanModeDepende
|
|
|
1619
1622
|
.sort(compareTools);
|
|
1620
1623
|
}
|
|
1621
1624
|
|
|
1622
|
-
function
|
|
1625
|
+
function availablePlanPolicyTools() {
|
|
1623
1626
|
const activeNames = new Set(safeGetActiveTools());
|
|
1624
|
-
return selectableTools().filter((tool) =>
|
|
1627
|
+
return selectableTools().filter((tool) => planModeToolAvailability(tool, activeNames) === "available");
|
|
1625
1628
|
}
|
|
1626
1629
|
|
|
1627
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";
|
|
@@ -45,6 +46,7 @@ export interface PlanModeSettingsMenuOptions {
|
|
|
45
46
|
isCurrent(): boolean;
|
|
46
47
|
settingsPath?: string;
|
|
47
48
|
legacySettingsPath?: string;
|
|
49
|
+
startupToggleShortcut?: PlanModeSettings["toggleShortcut"];
|
|
48
50
|
readSettings?: (settingsPath?: string) => Promise<PlanModeSettingsLoadResult>;
|
|
49
51
|
updateSettings?: (patch: PlanModeSettingsPatch, options?: UpdatePlanModeSettingsOptions) => Promise<PlanModeSettings>;
|
|
50
52
|
onSaved(settings: PlanModeSettings): void;
|
|
@@ -121,7 +123,7 @@ export async function showPlanModeSettings(
|
|
|
121
123
|
{
|
|
122
124
|
id: "defaultPlanTools",
|
|
123
125
|
label: "Plan policy tools",
|
|
124
|
-
description: "Choose
|
|
126
|
+
description: "Choose available tools or retain names to resolve before the first request.",
|
|
125
127
|
currentValue: defaultToolsValue(state.settings.defaultPlanTools),
|
|
126
128
|
action: "open-tools",
|
|
127
129
|
},
|
|
@@ -159,7 +161,8 @@ export async function showPlanModeSettings(
|
|
|
159
161
|
{
|
|
160
162
|
id: "toggleShortcut",
|
|
161
163
|
label: "Plan mode shortcut",
|
|
162
|
-
description:
|
|
164
|
+
description:
|
|
165
|
+
"Saved TUI shortcut. Changes require /reload or restarting Pi; the current binding stays unchanged.",
|
|
163
166
|
currentValue: configuredPlanModeToggleShortcut(state.settings) ?? "none",
|
|
164
167
|
action: "open-shortcut",
|
|
165
168
|
},
|
|
@@ -171,7 +174,7 @@ export async function showPlanModeSettings(
|
|
|
171
174
|
lines: [
|
|
172
175
|
"Changes apply when a later Plan workflow starts; model-visible tools stay unchanged.",
|
|
173
176
|
"Retained inactive names resolve before that workflow's first request.",
|
|
174
|
-
"Plan mode never activates tools
|
|
177
|
+
"Plan mode never activates tools; tools outside its reviewed core policy run at user risk.",
|
|
175
178
|
],
|
|
176
179
|
enableSearch: true,
|
|
177
180
|
viewportSize: 10,
|
|
@@ -222,9 +225,10 @@ export async function showPlanModeSettings(
|
|
|
222
225
|
title: "Plan mode shortcut",
|
|
223
226
|
lines: [
|
|
224
227
|
`Configured: ${configuredPlanModeToggleShortcut(state.settings) ?? "none"}`,
|
|
225
|
-
|
|
226
|
-
"
|
|
227
|
-
"
|
|
228
|
+
`Loaded at startup: ${safeTerminalText(options.startupToggleShortcut ?? "none")}`,
|
|
229
|
+
"TUI only. Use Pi key identifiers; Pi may reject conflicting shortcuts.",
|
|
230
|
+
"Submit an empty value to remove the saved shortcut.",
|
|
231
|
+
"Run /reload or restart Pi to apply changes; the current binding stays unchanged until then.",
|
|
228
232
|
],
|
|
229
233
|
placeholder: configuredPlanModeToggleShortcut(state.settings) ?? "",
|
|
230
234
|
action: "set-shortcut",
|
|
@@ -322,14 +326,18 @@ export async function showPlanModeSettings(
|
|
|
322
326
|
{ toggleShortcut },
|
|
323
327
|
signal,
|
|
324
328
|
toggleShortcut
|
|
325
|
-
? `Plan mode shortcut: ${safeTerminalText(toggleShortcut)}.`
|
|
326
|
-
: "Plan mode shortcut
|
|
329
|
+
? `Plan mode shortcut saved: ${safeTerminalText(toggleShortcut)}. Run /reload or restart Pi to apply; the current binding is unchanged.`
|
|
330
|
+
: "Plan mode shortcut removal saved. Run /reload or restart Pi to apply; the current binding is unchanged.",
|
|
327
331
|
);
|
|
328
332
|
return result.kind === "stay" ? { kind: "to", screen: "settings" } : result;
|
|
329
333
|
},
|
|
330
334
|
"toggle-tool": async ({ ctx: actionCtx, state, itemId, selected, signal }) => {
|
|
331
335
|
const tool = itemId ? toolsByItemId.get(itemId) : undefined;
|
|
332
|
-
if (
|
|
336
|
+
if (
|
|
337
|
+
!tool ||
|
|
338
|
+
planModeToolAvailability(tool, activeToolNames) !== "available" ||
|
|
339
|
+
!canSelectToolInPlanMode(tool)
|
|
340
|
+
) {
|
|
333
341
|
return { kind: "rejected" };
|
|
334
342
|
}
|
|
335
343
|
const names = explicitToolNames(tools, state.settings.defaultPlanTools);
|
|
@@ -478,28 +486,15 @@ function defaultToolItems(
|
|
|
478
486
|
const selected = new Set(explicitToolNames(tools, configured));
|
|
479
487
|
const availableNames = new Set(tools.map((tool) => tool.name));
|
|
480
488
|
const items = tools.map((tool) => {
|
|
481
|
-
const
|
|
482
|
-
const selectable = active && canSelectToolInPlanMode(tool);
|
|
483
|
-
const policy = active
|
|
484
|
-
? toolPolicyLabel(tool)
|
|
485
|
-
: selected.has(tool.name)
|
|
486
|
-
? "not active yet; retained for first-request resolution"
|
|
487
|
-
: "not active in this Pi session";
|
|
488
|
-
const description = tool.description ?? "No description available";
|
|
489
|
+
const presentation = planModeToolSelection(tool, activeToolNames, selected.has(tool.name));
|
|
489
490
|
return {
|
|
490
491
|
id: toolItemIds.get(tool.name) as string,
|
|
491
|
-
label: tool.name,
|
|
492
|
-
description: `${policy} · ${description}`,
|
|
493
|
-
searchText: `${policy} ${description}`,
|
|
494
492
|
selected: selected.has(tool.name),
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
: selectable
|
|
501
|
-
? undefined
|
|
502
|
-
: "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,
|
|
503
498
|
};
|
|
504
499
|
});
|
|
505
500
|
for (const [index, name] of (configured ?? []).entries()) {
|
|
@@ -523,7 +518,7 @@ function explicitToolNames(tools: readonly ToolInfo[], configured: string[] | un
|
|
|
523
518
|
}
|
|
524
519
|
|
|
525
520
|
function terminalToolName(value: string) {
|
|
526
|
-
const safe =
|
|
521
|
+
const safe = sanitizeTerminalText(value).trim() || "(unnamed tool)";
|
|
527
522
|
return safe.length > 120 ? `${safe.slice(0, 119)}…` : safe;
|
|
528
523
|
}
|
|
529
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";
|
|
@@ -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" &&
|