@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.
@@ -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
- Blocked, inactive, or not-yet-registered tools remain distinguishable, and selected names awaiting metadata stay selected for first-request resolution.
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 registered and active tools and freezes the executable allowlist.
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
- Unknown, inactive, and Plan-mode-blocked names remain unavailable after that resolution, and a later registration or activation waits for the next Plan workflow rather than a new session.
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
- Non-built-in names in this global setting are an explicit user-risk opt-in, just like selecting them in the pre-start workflow selector.
64
- Plan mode does not interpret a selected custom tool's arguments or actions: allowing one trusts the whole effective tool.
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
- An effective active tool named `bash` or `powershell` remains subject to its limited-shell policy regardless of its source metadata.
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` controls the global Plan-mode keybinding used by the TUI shortcut.
121
- Omit this setting to keep the shortcut disabled.
122
- Set `toggleShortcut` to the key string you want.
123
- Avoid values that conflict with editor shortcuts.
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.2",
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.86.0",
40
- "@earendil-works/pi-tui": "0.86.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
  },
@@ -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
 
@@ -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
- "Active tools can be chosen now; retained names resolve before the first request.",
58
- "Plan mode never activates tools, and non-built-ins run at user risk.",
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 { compareTools, snapshotPlanModeSelectedNames, toolPolicyLabel } from "./tool-selection.js";
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 toggleShortcut: ReturnType<typeof configuredPlanModeToggleShortcut>;
175
- const clearPlanModeShortcutHandler = () => {};
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 applyPlanModeShortcut = (nextShortcut: ReturnType<typeof configuredPlanModeToggleShortcut>) => {
393
- if (toggleShortcut && toggleShortcut !== nextShortcut) {
394
- pi.registerShortcut(toggleShortcut, {
395
- handler: clearPlanModeShortcutHandler,
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
- if (!nextShortcut) {
399
- toggleShortcut = undefined;
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 (classifyPlanModeTool(calledTool) === "blocked") {
665
+ if (!calledTool.sourceInfo?.source) {
665
666
  return {
666
667
  block: true,
667
- reason: `Plan mode blocks tool '${event.toolName}' because its built-in policy is blocked and settings cannot enable it.`,
668
+ reason: `Plan mode blocks tool '${event.toolName}' because its safe policy metadata is unavailable.`,
668
669
  };
669
670
  }
670
- const allowedToolNames = new Set(planModePolicyToolNames());
671
- if (!activeToolNames.has(event.toolName)) {
671
+ if (classifyPlanModeTool(calledTool) === "blocked") {
672
672
  return {
673
673
  block: true,
674
- reason: allowedToolNames.has(event.toolName)
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 active.`
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) => activeToolNames.has(tool.name) && selectedNames.has(tool.name) && canSelectToolInPlanMode(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
- description: `${policy} · ${description}`,
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) => activeToolNames.has(name) || retainedInactiveNames.has(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 = activePlanPolicyTools();
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(activePlanPolicyTools(), {}));
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 activePlanPolicyTools()
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 activePlanPolicyTools() {
1625
+ function availablePlanPolicyTools() {
1623
1626
  const activeNames = new Set(safeGetActiveTools());
1624
- return selectableTools().filter((tool) => activeNames.has(tool.name));
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. Non-built-in tools are denied by default and may be allowed only when already active in Pi and explicitly selected by the user at their own risk.
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
@@ -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, toolPolicyLabel } from "./tool-selection.js";
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 active tools or retain names to resolve before the first request.",
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: "Set the global shortcut used to toggle Plan mode.",
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, and non-built-ins run at user risk.",
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
- "Use Pi key identifiers.",
226
- "Submit an empty value to clear the shortcut.",
227
- "When unset, Plan mode has no global shortcut.",
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 cleared (no global 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 (!tool || !activeToolNames.has(tool.name) || !canSelectToolInPlanMode(tool)) {
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 active = activeToolNames.has(tool.name);
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
- disabled: !selectable,
496
- disabledReason: !active
497
- ? selected.has(tool.name)
498
- ? "Not active yet; retained and resolved before the first request"
499
- : "Not active in Pi; Plan mode will not activate it"
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 = safeTerminalText(value) || "(unnamed tool)";
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
+ }
@@ -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
- return tool.sourceInfo.source === "builtin";
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(["-i", "--in-place", "--fix", "--write", "-delete", "--delete"]);
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" &&