@narumitw/pi-plan-mode 0.58.3 → 0.59.0
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 +25 -12
- package/dist/chunks/{chunk-L2CXUWCH.ts → chunk-MJV6WNHK.ts} +76 -7
- package/dist/chunks/{chunk-L2CXUWCH.ts.map → chunk-MJV6WNHK.ts.map} +3 -3
- package/dist/chunks/{interactive-ui-OZA4BHGS.ts → interactive-ui-F7FMN7FT.ts} +25 -27
- package/dist/chunks/interactive-ui-F7FMN7FT.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 +78 -15
- 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 +14 -4
- package/src/tool-selection.ts +55 -3
- package/dist/chunks/interactive-ui-OZA4BHGS.ts.map +0 -7
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
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
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.
|
|
@@ -147,7 +156,8 @@ Use canonical cmdlet names because PowerShell aliases are intentionally outside
|
|
|
147
156
|
A rejected parsed command list or pipeline identifies its first blocked command segment; malformed or unsupported shell syntax reports the complete submitted input instead.
|
|
148
157
|
Tests and builds may still write ignored caches or build artifacts and may execute project-defined hooks; enable or invoke them only when the repository is trusted.
|
|
149
158
|
Both limited-shell policies reduce risk but do not provide an OS sandbox or confidentiality boundary.
|
|
150
|
-
A configured `safeSubcommands` match
|
|
159
|
+
A configured `safeSubcommands` match trusts only its parsed command segment and arguments; neighboring segments must pass their own policy, and parser-unsupported syntax remains blocked.
|
|
160
|
+
Trusted commands can still mutate data or execute code with Pi's permissions; see [safe shell subcommands](./docs/settings.md#safe-shell-subcommands) for the trust boundary and migration guidance.
|
|
151
161
|
|
|
152
162
|
## 🧭 Planning and implementation
|
|
153
163
|
|
|
@@ -166,9 +176,10 @@ RPC keeps the existing sequential `select` and `editor` dialogs because Pi RPC c
|
|
|
166
176
|
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
177
|
|
|
168
178
|
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,
|
|
170
|
-
A selected name can run in Plan mode only when
|
|
171
|
-
The allowlist freezes at that boundary
|
|
179
|
+
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.
|
|
180
|
+
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.
|
|
181
|
+
The allowlist freezes at that boundary and restores without admitting new names after reload, resume, or tree navigation.
|
|
182
|
+
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
183
|
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
184
|
|
|
174
185
|
A complete Plan mode answer should appear only after the agent has resolved discoverable facts and high-impact user decisions.
|
|
@@ -285,6 +296,7 @@ During a guaranteed-plan implementation, it removes both the original implementa
|
|
|
285
296
|
Plan and Normal requests share one append-only conversation.
|
|
286
297
|
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
298
|
Ordinary linear turns do not rewrite or duplicate these contracts.
|
|
299
|
+
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
300
|
**Implement here** retains the Plan dialogue, structured questions, tool calls, completion evidence, and `Implement the plan.` kickoff in order.
|
|
289
301
|
**Start fresh and implement** is the isolation path and transfers only the approved plan plus the Normal contract to a linked session.
|
|
290
302
|
|
|
@@ -362,11 +374,12 @@ The shortcut is disabled unless configured; enabling, changing, or removing it t
|
|
|
362
374
|
Until then, the current shortcut binding stays unchanged.
|
|
363
375
|
Settings saves apply to later workflows; an active implementation keeps its captured reinjection policy.
|
|
364
376
|
The export destination affects the next export immediately.
|
|
377
|
+
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.
|
|
365
378
|
|
|
366
379
|
> [!WARNING]
|
|
367
|
-
> `safeSubcommands` is a JSON-only
|
|
368
|
-
>
|
|
369
|
-
> Configure it only for commands and repositories you fully trust.
|
|
380
|
+
> `safeSubcommands` is a JSON-only segment-scoped trust override, not a read-only allowlist.
|
|
381
|
+
> It trusts a matching command and its arguments, not trailing commands or parser-unsupported syntax such as redirects.
|
|
382
|
+
> Configure it only for commands and repositories you fully trust; trusted arguments can still cause mutation or code execution.
|
|
370
383
|
|
|
371
384
|
Saves are ordered within one Pi process, preserve unknown fields, and publish atomically; separate Pi processes can still race.
|
|
372
385
|
Invalid settings remain untouched and make Settings read-only; session-start failures use safe defaults.
|
|
@@ -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
|
-
|
|
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";
|
|
@@ -1225,13 +1250,11 @@ function readCommand(input) {
|
|
|
1225
1250
|
return typeof command?.command === "string" ? command.command : "";
|
|
1226
1251
|
}
|
|
1227
1252
|
function findBlockedCommandSegment(command, safeSubcommands = {}, workingDirectory, platform = process.platform) {
|
|
1228
|
-
if (matchesConfiguredSafeSubcommand(command, safeSubcommands)) return void 0;
|
|
1229
1253
|
const segments = splitShellSegments(command);
|
|
1230
1254
|
if (!segments || segments.length === 0) return command.trim() || "(empty command)";
|
|
1231
1255
|
return segments.find((segment) => !isSafeSegment(segment, safeSubcommands, workingDirectory, platform));
|
|
1232
1256
|
}
|
|
1233
1257
|
function findBlockedPowerShellCommandSegment(command, safeSubcommands = {}, workingDirectory) {
|
|
1234
|
-
if (matchesConfiguredSafeSubcommand(command, safeSubcommands)) return void 0;
|
|
1235
1258
|
const segments = splitPowerShellSegments(command);
|
|
1236
1259
|
if (!segments || segments.length === 0) return command.trim() || "(empty command)";
|
|
1237
1260
|
return segments.find((segment) => !isSafePowerShellSegment(segment, safeSubcommands, workingDirectory));
|
|
@@ -1295,6 +1318,7 @@ function splitPowerShellSegments(command) {
|
|
|
1295
1318
|
return segments;
|
|
1296
1319
|
}
|
|
1297
1320
|
function isSafePowerShellSegment(segment, safeSubcommands, workingDirectory) {
|
|
1321
|
+
if (matchesConfiguredSafeSubcommand(segment, safeSubcommands)) return true;
|
|
1298
1322
|
const tokens = powerShellWords(segment);
|
|
1299
1323
|
if (!tokens || tokens.length === 0 || tokens.includes("--%")) return false;
|
|
1300
1324
|
const command = tokens[0]?.toLowerCase();
|
|
@@ -1392,6 +1416,7 @@ function splitShellSegments(command) {
|
|
|
1392
1416
|
return segments;
|
|
1393
1417
|
}
|
|
1394
1418
|
function isSafeSegment(segment, safeSubcommands, workingDirectory, platform) {
|
|
1419
|
+
if (matchesConfiguredSafeSubcommand(segment, safeSubcommands)) return true;
|
|
1395
1420
|
if (hasShellExpansion(segment) || /(^|\s)[A-Za-z_][A-Za-z0-9_]*=/.test(segment)) {
|
|
1396
1421
|
return false;
|
|
1397
1422
|
}
|
|
@@ -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(["
|
|
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
|
-
|
|
1874
|
+
planModeToolSelection,
|
|
1875
|
+
filterAvailableSelectedToolNames,
|
|
1807
1876
|
defaultPlanModeToolNames,
|
|
1808
1877
|
snapshotPlanModeSelectedNames
|
|
1809
1878
|
};
|
|
1810
|
-
//# sourceMappingURL=chunk-
|
|
1879
|
+
//# sourceMappingURL=chunk-MJV6WNHK.ts.map
|