@narumitw/pi-plan-mode 0.58.3 → 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 +20 -8
- 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-OZA4BHGS.ts → interactive-ui-JEXFZHRD.ts} +25 -27
- package/dist/chunks/interactive-ui-JEXFZHRD.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 +58 -5
- 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 +12 -2
- 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.
|
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";
|
|
@@ -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";
|
|
@@ -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" &&
|
package/src/tool-selection.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { ToolInfo } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import { planModeToolAvailability } from "./tool-availability.js";
|
|
2
3
|
import {
|
|
3
4
|
canSelectToolInPlanMode,
|
|
4
5
|
classifyPlanModeTool,
|
|
@@ -24,10 +25,53 @@ export function toolPolicyLabel(tool: ToolInfo) {
|
|
|
24
25
|
const policy = classifyPlanModeTool(tool);
|
|
25
26
|
if (policy === "read-only") return "built-in read-only";
|
|
26
27
|
if (policy === "limited") return "built-in limited";
|
|
27
|
-
if (policy === "blocked") return "built-in blocked";
|
|
28
|
+
if (policy === "blocked") return tool.sourceInfo?.source ? "built-in blocked" : "policy metadata unavailable";
|
|
28
29
|
return `user opt-in: ${toolSourceLabel(tool)}`;
|
|
29
30
|
}
|
|
30
31
|
|
|
32
|
+
export function planModeToolSelection(tool: ToolInfo, activeNames: ReadonlySet<string>, retained: boolean) {
|
|
33
|
+
const availability = planModeToolAvailability(tool, activeNames);
|
|
34
|
+
const policyBlocked = !canSelectToolInPlanMode(tool);
|
|
35
|
+
let unavailable: string | undefined;
|
|
36
|
+
switch (availability) {
|
|
37
|
+
case "inactive":
|
|
38
|
+
unavailable = "Not active in Pi; Plan mode will not activate it";
|
|
39
|
+
if (!policyBlocked && isBuiltinTool(tool) && ["grep", "find", "ls"].includes(tool.name)) {
|
|
40
|
+
// ExtensionContext does not expose host-owned Pi settings; plain names also work before Pi 0.99.
|
|
41
|
+
unavailable += `; on Pi with defaultTools support, use a full list including "${tool.name}" in this session's Pi settings (preserve existing/default tools), then restart Pi`;
|
|
42
|
+
}
|
|
43
|
+
if (retained) unavailable += "; retained and resolved before the first request";
|
|
44
|
+
break;
|
|
45
|
+
case "hidden":
|
|
46
|
+
unavailable = "Hidden in Pi; retained selection cannot enable it";
|
|
47
|
+
break;
|
|
48
|
+
case "unsupported":
|
|
49
|
+
unavailable = "Unsupported tool exposure; Plan mode cannot enable it";
|
|
50
|
+
break;
|
|
51
|
+
}
|
|
52
|
+
const policy =
|
|
53
|
+
(policyBlocked ? undefined : unavailable) ??
|
|
54
|
+
[
|
|
55
|
+
toolPolicyLabel(tool),
|
|
56
|
+
...(tool.exposure === "codemode" || tool.exposure === "deferred" ? ["callable via other tools"] : []),
|
|
57
|
+
...(tool.exposure === "model-only" ? ["model calls only"] : []),
|
|
58
|
+
].join(" · ");
|
|
59
|
+
const description = tool.description ?? "No description available";
|
|
60
|
+
const disabledReason = policyBlocked ? "Blocked by Plan-mode policy" : unavailable;
|
|
61
|
+
const label = policyBlocked
|
|
62
|
+
? `${tool.name} — blocked by Plan policy`
|
|
63
|
+
: availability === "inactive"
|
|
64
|
+
? `${tool.name} — inactive in Pi`
|
|
65
|
+
: tool.name;
|
|
66
|
+
return {
|
|
67
|
+
label,
|
|
68
|
+
description: `${policy} · ${description}`,
|
|
69
|
+
searchText: `${policy} ${description}`,
|
|
70
|
+
disabled: disabledReason !== undefined,
|
|
71
|
+
disabledReason,
|
|
72
|
+
};
|
|
73
|
+
}
|
|
74
|
+
|
|
31
75
|
function toolSourceLabel(tool: ToolInfo) {
|
|
32
76
|
const sourceInfo = tool.sourceInfo;
|
|
33
77
|
const source = `${sourceInfo.scope}/${sourceInfo.source}`;
|
|
@@ -38,8 +82,16 @@ export function unique(values: string[]) {
|
|
|
38
82
|
return Array.from(new Set(values));
|
|
39
83
|
}
|
|
40
84
|
|
|
41
|
-
export function filterAvailableSelectedToolNames(
|
|
42
|
-
|
|
85
|
+
export function filterAvailableSelectedToolNames(
|
|
86
|
+
names: string[],
|
|
87
|
+
tools: ToolInfo[],
|
|
88
|
+
activeNames: ReadonlySet<string> = new Set(tools.map((tool) => tool.name)),
|
|
89
|
+
) {
|
|
90
|
+
const availableNames = new Set(
|
|
91
|
+
tools
|
|
92
|
+
.filter((tool) => canSelectToolInPlanMode(tool) && planModeToolAvailability(tool, activeNames) === "available")
|
|
93
|
+
.map((tool) => tool.name),
|
|
94
|
+
);
|
|
43
95
|
return unique(names.filter((name) => availableNames.has(name)));
|
|
44
96
|
}
|
|
45
97
|
|