@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.
@@ -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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-plan-mode",
3
- "version": "0.58.3",
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";
@@ -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 (classifyPlanModeTool(calledTool) === "blocked") {
665
+ if (!calledTool.sourceInfo?.source) {
660
666
  return {
661
667
  block: true,
662
- 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.`,
663
669
  };
664
670
  }
665
- const allowedToolNames = new Set(planModePolicyToolNames());
666
- if (!activeToolNames.has(event.toolName)) {
671
+ if (classifyPlanModeTool(calledTool) === "blocked") {
667
672
  return {
668
673
  block: true,
669
- reason: allowedToolNames.has(event.toolName)
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 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.`
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) => 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),
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
- description: `${policy} · ${description}`,
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) => activeToolNames.has(name) || retainedInactiveNames.has(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 = activePlanPolicyTools();
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(activePlanPolicyTools(), {}));
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 activePlanPolicyTools()
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 activePlanPolicyTools() {
1625
+ function availablePlanPolicyTools() {
1618
1626
  const activeNames = new Set(safeGetActiveTools());
1619
- return selectableTools().filter((tool) => activeNames.has(tool.name));
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. 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";
@@ -122,7 +123,7 @@ export async function showPlanModeSettings(
122
123
  {
123
124
  id: "defaultPlanTools",
124
125
  label: "Plan policy tools",
125
- 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.",
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, and non-built-ins run at user risk.",
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 (!tool || !activeToolNames.has(tool.name) || !canSelectToolInPlanMode(tool)) {
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 active = activeToolNames.has(tool.name);
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
- disabled: !selectable,
499
- disabledReason: !active
500
- ? selected.has(tool.name)
501
- ? "Not active yet; retained and resolved before the first request"
502
- : "Not active in Pi; Plan mode will not activate it"
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 = safeTerminalText(value) || "(unnamed tool)";
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
+ }
@@ -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" &&
@@ -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(names: string[], tools: ToolInfo[]) {
42
- const availableNames = new Set(tools.filter(canSelectToolInPlanMode).map((tool) => tool.name));
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