@narumitw/pi-plan-mode 0.58.2 → 0.58.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -121,16 +121,25 @@ Plan mode registers `plan_mode_question` and `plan_mode_complete` during extensi
121
121
  Another active-tool policy may hide them, in which case Plan start or restore fails without widening that policy.
122
122
  By default, the Plan policy allows active safe built-ins such as `read`, limited `bash`, limited `powershell`, `grep`, `find`, and `ls`.
123
123
  The optional native `powershell` tool must be active when an automatic Plan policy starts, for example through Pi's Windows `defaultTools` setting, unless its name was explicitly retained for first-request resolution.
124
- Built-in `edit` and `write`, `update_plan`, tools still inactive at the first request, and deselected tools are blocked at execution time even though active schemas remain visible.
125
- Extension and custom tools are denied by default because Pi tools do not expose standardized mutability metadata; explicitly allow a custom-tool name before starting only when you accept the risk.
126
- For example, you can opt into `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` when you want to use the effective active tool during planning.
127
- An active selectable tool omitted from the Plan policy reports that it needs explicit selection through `/plan tools` or `defaultPlanTools` before the next workflow.
128
- Registered but inactive, unregistered, metadata-free, and built-in blocked tools report their distinct fail-closed reasons instead of suggesting that every denial is a missing selection.
124
+ Tools named `edit`, `write`, or `update_plan` and deselected tools are blocked at execution time even though active schemas remain visible.
125
+ Tools outside the reviewed core policy—including native MCP tools, native orchestration, extensions, and custom tools—are denied by default; explicitly allow their names before starting only when you accept the risk.
126
+ Server annotations such as `readOnlyHint` are unverified hints, not permission or a safety guarantee.
127
+ For example, opt into `mcp__docs__read`, `firecrawl_scrape`, or `lsp_diagnostics` through `/plan tools` or `defaultPlanTools` before the next workflow.
128
+
129
+ Direct and `model-only` tools must be active in Pi; `model-only` tools cannot be called by another tool.
130
+ Registered `codemode` and `deferred` tools are selectable without direct activation and can run through Pi's nested tool pipeline.
131
+ MCP `codemode-deferred` follows its public `deferred` exposure.
132
+ Select an orchestrator such as `codemode` or `tool_search` separately when needed: allowing it does not authorize its callees, and selecting an MCP tool does not enable its orchestrator.
133
+ Pi's `tool_search` may declare tools independently, but declaration does not admit unselected names to the frozen Plan policy.
134
+ Every nested call remains individually gated, including editing and limited-shell restrictions.
135
+ Hidden tools remain unavailable even when selected or listed as active; unsupported exposure and unavailable policy metadata fail closed.
136
+ Registered but inactive direct tools, unregistered tools, blocked core tools, and unselected tools report distinct denial guidance.
129
137
  A tool admitted before later deactivation can be reactivated and reused in the current workflow without restarting.
130
138
  After they become visible, the Plan-only helpers remain visible in Normal mode, but their handlers and the `tool_call` policy reject calls unless Plan mode owns the active workflow.
131
139
 
132
140
  Limited `bash` uses a fail-closed Bash policy, including when an extension overrides the canonical `bash` tool name.
133
141
  It accepts common inspection commands, read-only Git and npm queries, pipelines and command lists composed entirely of accepted commands, plus selected checks such as `npm test`, `npm run typecheck`, and `cargo test`.
142
+ Case-insensitive `-i` is allowed for inspection commands such as `rg`, `grep`, and `git grep`. Commands where `-i` edits in place, including `sed`, stay blocked.
134
143
  It also accepts `hostname` without arguments and local Windows `tasklist` queries using reviewed display, filter, module, and service flags.
135
144
  Reviewed Git inspections may place `--no-pager` before the accepted subcommand.
136
145
  They may also place one or more complete `-C <path>` pairs before the accepted subcommand only when every path is `.` or the exact current Pi working directory.
@@ -166,9 +175,10 @@ RPC keeps the existing sequential `select` and `editor` dialogs because Pi RPC c
166
175
  If you cancel or no interactive UI is available, the agent should ask a concise plain-text question or proceed only with a clearly stated low-risk assumption instead of prematurely producing a final plan.
167
176
 
168
177
  Pi identifies tools by tool name.
169
- The pre-start selector stores accepted session policy names and shows each effective tool's source from Pi metadata, such as `built-in`, a user extension path, or a project extension path.
170
- A selected name can run in Plan mode only when Pi has registered and activated the effective selectable tool by that workflow's first provider-bound context.
171
- The allowlist freezes at that boundary, so a tool registered or activated later waits for the next Plan workflow.
178
+ The pre-start selector stores accepted session policy names and shows each effective tool's source and availability from Pi metadata, including native built-in extension registrations.
179
+ A selected name can run in Plan mode only when the effective tool is registered, available through its exposure, and permitted by policy at the workflow's first provider-bound context.
180
+ The allowlist freezes at that boundary and restores without admitting new names after reload, resume, or tree navigation.
181
+ A tool registered or first made available later waits for the next Plan workflow; an admitted callable tool later declared to the model keeps its existing admission.
172
182
  If an extension overrides a built-in tool with the same name, Pi exposes the effective tool for that name and the selector shows that source.
173
183
 
174
184
  A complete Plan mode answer should appear only after the agent has resolved discoverable facts and high-impact user decisions.
@@ -285,6 +295,7 @@ During a guaranteed-plan implementation, it removes both the original implementa
285
295
  Plan and Normal requests share one append-only conversation.
286
296
  The extension appends one hidden, model-visible, versioned Plan contract before the first Plan prompt and one Normal contract before the first post-Plan Normal or implementation prompt.
287
297
  Ordinary linear turns do not rewrite or duplicate these contracts.
298
+ The Plan contract explains native-tool opt-in and per-call nested enforcement; this wording changes future Plan transitions without rewriting existing transition messages.
288
299
  **Implement here** retains the Plan dialogue, structured questions, tool calls, completion evidence, and `Implement the plan.` kickoff in order.
289
300
  **Start fresh and implement** is the isolation path and transfers only the approved plan plus the Normal contract to a linked session.
290
301
 
@@ -358,9 +369,11 @@ The optional file is read at session start and watched for changes; only an expl
358
369
  ```
359
370
 
360
371
  By default, Plan mode inherits thinking, allows active safe built-ins, uses the planning model and thinking level for fresh implementation, exports to `PLAN.md`, and relies on ordinary conversation history after implementation starts.
361
- The shortcut is disabled unless configured.
372
+ The shortcut is disabled unless configured; enabling, changing, or removing it takes effect after `/reload` or restarting Pi.
373
+ Until then, the current shortcut binding stays unchanged.
362
374
  Settings saves apply to later workflows; an active implementation keeps its captured reinjection policy.
363
375
  The export destination affects the next export immediately.
376
+ Inactive built-in `grep`, `find`, and `ls` must be [enabled in Pi settings](./docs/settings.md#enable-inactive-built-in-search-tools-in-pi); Plan policy only grants execution permission.
364
377
 
365
378
  > [!WARNING]
366
379
  > `safeSubcommands` is a JSON-only full-command trust override, not a read-only allowlist.
@@ -1107,6 +1107,27 @@ function stringField(value) {
1107
1107
  return typeof value === "string" ? value.trim() : void 0;
1108
1108
  }
1109
1109
 
1110
+ // src/tool-availability.ts
1111
+ function planModeToolAvailability(tool, activeNames, route = "selection") {
1112
+ switch (tool.exposure) {
1113
+ case "hidden":
1114
+ return "hidden";
1115
+ case "model-only":
1116
+ if (route === "nested") return "model-only";
1117
+ return activeNames.has(tool.name) ? "available" : "inactive";
1118
+ case "codemode":
1119
+ case "deferred":
1120
+ if (route !== "model") return "available";
1121
+ return activeNames.has(tool.name) ? "available" : "inactive";
1122
+ case void 0:
1123
+ // Older Pi versions exposed only directly active tools.
1124
+ case "direct":
1125
+ return activeNames.has(tool.name) ? "available" : "inactive";
1126
+ default:
1127
+ return "unsupported";
1128
+ }
1129
+ }
1130
+
1110
1131
  // src/tool-policy.ts
1111
1132
  import { isAbsolute, normalize } from "node:path";
1112
1133
  var BUILTIN_SAFE_GIT_SUBCOMMANDS = [
@@ -1208,10 +1229,14 @@ var READ_ONLY_COMMANDS = /* @__PURE__ */ new Set([
1208
1229
  "bat",
1209
1230
  "eza"
1210
1231
  ]);
1232
+ var INSPECTION_CASE_FLAG_COMMANDS = /* @__PURE__ */ new Set(["rg", "grep", "git", "diff", "fd", "ls", "sort", "find", "bat", "eza"]);
1211
1233
  function isBuiltinTool(tool) {
1212
- return tool.sourceInfo.source === "builtin";
1234
+ const source = tool.sourceInfo;
1235
+ if (source?.source !== "builtin") return false;
1236
+ return !source.path || source.path === `builtin:${tool.name}` && tool.exposure !== "model-only";
1213
1237
  }
1214
1238
  function classifyPlanModeTool(tool) {
1239
+ if (!tool.sourceInfo?.source) return "blocked";
1215
1240
  if (!isBuiltinTool(tool)) return "user-opt-in";
1216
1241
  if (BLOCKED_BUILTIN_TOOLS.has(tool.name)) return "blocked";
1217
1242
  if (tool.name === "bash" || tool.name === "powershell") return "limited";
@@ -1462,7 +1487,8 @@ function shellWords(segment) {
1462
1487
  return words;
1463
1488
  }
1464
1489
  function hasSafeArguments(command, args) {
1465
- const forbidden = /* @__PURE__ */ new Set(["-i", "--in-place", "--fix", "--write", "-delete", "--delete"]);
1490
+ const forbidden = /* @__PURE__ */ new Set(["--in-place", "--fix", "--write", "-delete", "--delete"]);
1491
+ if (!INSPECTION_CASE_FLAG_COMMANDS.has(command)) forbidden.add("-i");
1466
1492
  if (args.some((argument) => forbidden.has(argument))) return false;
1467
1493
  if (command === "sed" && args.some(
1468
1494
  (argument) => argument.startsWith("--in-place=") || /^-[^-]+/.test(argument) && argument.slice(1).includes("i")
@@ -1734,9 +1760,44 @@ function toolPolicyLabel(tool) {
1734
1760
  const policy = classifyPlanModeTool(tool);
1735
1761
  if (policy === "read-only") return "built-in read-only";
1736
1762
  if (policy === "limited") return "built-in limited";
1737
- if (policy === "blocked") return "built-in blocked";
1763
+ if (policy === "blocked") return tool.sourceInfo?.source ? "built-in blocked" : "policy metadata unavailable";
1738
1764
  return `user opt-in: ${toolSourceLabel(tool)}`;
1739
1765
  }
1766
+ function planModeToolSelection(tool, activeNames, retained) {
1767
+ const availability = planModeToolAvailability(tool, activeNames);
1768
+ const policyBlocked = !canSelectToolInPlanMode(tool);
1769
+ let unavailable;
1770
+ switch (availability) {
1771
+ case "inactive":
1772
+ unavailable = "Not active in Pi; Plan mode will not activate it";
1773
+ if (!policyBlocked && isBuiltinTool(tool) && ["grep", "find", "ls"].includes(tool.name)) {
1774
+ 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`;
1775
+ }
1776
+ if (retained) unavailable += "; retained and resolved before the first request";
1777
+ break;
1778
+ case "hidden":
1779
+ unavailable = "Hidden in Pi; retained selection cannot enable it";
1780
+ break;
1781
+ case "unsupported":
1782
+ unavailable = "Unsupported tool exposure; Plan mode cannot enable it";
1783
+ break;
1784
+ }
1785
+ const policy = (policyBlocked ? void 0 : unavailable) ?? [
1786
+ toolPolicyLabel(tool),
1787
+ ...tool.exposure === "codemode" || tool.exposure === "deferred" ? ["callable via other tools"] : [],
1788
+ ...tool.exposure === "model-only" ? ["model calls only"] : []
1789
+ ].join(" \xB7 ");
1790
+ const description = tool.description ?? "No description available";
1791
+ const disabledReason = policyBlocked ? "Blocked by Plan-mode policy" : unavailable;
1792
+ const label = policyBlocked ? `${tool.name} \u2014 blocked by Plan policy` : availability === "inactive" ? `${tool.name} \u2014 inactive in Pi` : tool.name;
1793
+ return {
1794
+ label,
1795
+ description: `${policy} \xB7 ${description}`,
1796
+ searchText: `${policy} ${description}`,
1797
+ disabled: disabledReason !== void 0,
1798
+ disabledReason
1799
+ };
1800
+ }
1740
1801
  function toolSourceLabel(tool) {
1741
1802
  const sourceInfo = tool.sourceInfo;
1742
1803
  const source = `${sourceInfo.scope}/${sourceInfo.source}`;
@@ -1745,6 +1806,12 @@ function toolSourceLabel(tool) {
1745
1806
  function unique(values) {
1746
1807
  return Array.from(new Set(values));
1747
1808
  }
1809
+ function filterAvailableSelectedToolNames(names, tools, activeNames = new Set(tools.map((tool) => tool.name))) {
1810
+ const availableNames = new Set(
1811
+ tools.filter((tool) => canSelectToolInPlanMode(tool) && planModeToolAvailability(tool, activeNames) === "available").map((tool) => tool.name)
1812
+ );
1813
+ return unique(names.filter((name) => availableNames.has(name)));
1814
+ }
1748
1815
  function defaultPlanModeToolNames(tools, configuredNames) {
1749
1816
  if (configuredNames !== void 0) return unique(configuredNames);
1750
1817
  return tools.filter((tool) => isBuiltinTool(tool) && SAFE_BUILTIN_PLAN_TOOLS.has(tool.name)).map((tool) => tool.name);
@@ -1797,14 +1864,16 @@ export {
1797
1864
  normalizePlanModeQuestionParams,
1798
1865
  answerPlanModeQuestions,
1799
1866
  planModeQuestionCancelled,
1867
+ planModeToolAvailability,
1800
1868
  classifyPlanModeTool,
1801
1869
  canSelectToolInPlanMode,
1802
1870
  readCommand,
1803
1871
  findBlockedCommandSegment,
1804
1872
  findBlockedPowerShellCommandSegment,
1805
1873
  compareTools,
1806
- toolPolicyLabel,
1874
+ planModeToolSelection,
1875
+ filterAvailableSelectedToolNames,
1807
1876
  defaultPlanModeToolNames,
1808
1877
  snapshotPlanModeSelectedNames
1809
1878
  };
1810
- //# sourceMappingURL=chunk-L2CXUWCH.ts.map
1879
+ //# sourceMappingURL=chunk-VLNCRAFL.ts.map