@narumitw/pi-plan-mode 0.51.1 → 0.53.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/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 manages built-in tool safety only. Non-built-in tools are disabled by default and may be enabled 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. 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.
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
@@ -30,6 +30,8 @@ You are in Plan Mode, a Codex-like collaboration mode for producing a decision-c
30
30
 
31
31
  - Once intent is stable, keep asking until the spec is decision-complete: approach, interfaces, data flow, edge cases/failure modes, testing and acceptance criteria, and any migration or compatibility constraints.
32
32
  - Use plan_mode_question for important preferences, tradeoffs, or assumption locks that cannot be discovered by non-mutating exploration. Ask 1-3 concise questions with 2-4 meaningful options. Do not include filler options.
33
+ - Treat plan_mode_question and plan_mode_complete as callable when they are listed in the current request's active tools. Do not infer that they are unavailable from earlier modes or conversation history.
34
+ - If a Plan tool call returns an actual error, respond to that error. Do not replace an available structured tool call with prose claiming that the tool is unavailable.
33
35
  - If plan_mode_question returns cancelled or ui_unavailable, do not jump straight to a final plan when the missing answer is high impact. Ask one concise plain-text question or proceed only with a clearly stated low-risk assumption.
34
36
 
35
37
  ## Ending each turn
@@ -10,10 +10,6 @@ export function withRequiredPlanModeTools(toolNames: string[]) {
10
10
  ]);
11
11
  }
12
12
 
13
- export function withoutPlanModeQuestionTool(toolNames: string[]) {
14
- return toolNames.filter((toolName) => toolName !== PLAN_MODE_QUESTION_TOOL_NAME);
15
- }
16
-
17
13
  export function withoutRequiredPlanModeTools(toolNames: string[]) {
18
14
  return toolNames.filter(
19
15
  (toolName) =>
@@ -8,9 +8,11 @@ import {
8
8
  configuredImplementationPlanRetention,
9
9
  configuredPlanExportPath,
10
10
  configuredPlanModeToggleShortcut,
11
+ configuredPlanModeToolVisibility,
11
12
  IMPLEMENTATION_PLAN_RETENTIONS,
12
13
  normalizeKeyId,
13
14
  PLAN_MODE_THINKING_LEVELS,
15
+ PLAN_MODE_TOOL_VISIBILITIES,
14
16
  type PlanModeSettings,
15
17
  type PlanModeSettingsLoadResult,
16
18
  type PlanModeSettingsPatch,
@@ -31,6 +33,7 @@ interface SettingsMenuState {
31
33
 
32
34
  export interface PlanModeSettingsMenuOptions {
33
35
  tools: readonly ToolInfo[];
36
+ activeToolNames?: readonly string[];
34
37
  signal: AbortSignal;
35
38
  isCurrent(): boolean;
36
39
  settingsPath?: string;
@@ -46,6 +49,7 @@ export interface PlanModeSettingsMenuOptions {
46
49
  type Screen = "settings" | "tools" | "export" | "shortcut";
47
50
  type Action =
48
51
  | "set-thinking"
52
+ | "set-tool-visibility"
49
53
  | "open-tools"
50
54
  | "toggle-tool"
51
55
  | "reset-tools"
@@ -62,6 +66,9 @@ export async function showPlanModeSettings(
62
66
  const settingsPath = options.settingsPath ?? planModeSettingsPath();
63
67
  const readSettings = options.readSettings ?? readPlanModeSettings;
64
68
  const updateSettings = options.updateSettings ?? updatePlanModeSettings;
69
+ const activeToolNames = new Set(
70
+ options.activeToolNames ?? options.tools.map((tool) => tool.name),
71
+ );
65
72
  const tools = options.tools.filter(
66
73
  (tool) =>
67
74
  tool.name !== PLAN_MODE_QUESTION_TOOL_NAME && tool.name !== PLAN_MODE_COMPLETE_TOOL_NAME,
@@ -105,16 +112,17 @@ export async function showPlanModeSettings(
105
112
  },
106
113
  {
107
114
  id: "defaultPlanTools",
108
- label: "Plan tools",
115
+ label: "Plan policy tools",
109
116
  description:
110
- "Choose persistent defaults; a launch-time selection still overrides them for that session.",
117
+ "Choose which already-active tools Plan mode may execute by default.",
111
118
  currentValue: defaultToolsValue(state.settings.defaultPlanTools),
112
119
  action: "open-tools",
113
120
  },
114
121
  {
115
122
  id: "implementationPlanRetention",
116
- label: "After Implement",
117
- description: "Choose how long the accepted plan keeps guiding implementation.",
123
+ label: "Plan reinjection",
124
+ description:
125
+ "Choose how long Plan mode restores the exact plan when ordinary context no longer contains it.",
118
126
  currentValue: retentionLabel(
119
127
  configuredImplementationPlanRetention(state.settings),
120
128
  ),
@@ -135,18 +143,29 @@ export async function showPlanModeSettings(
135
143
  currentValue: configuredPlanModeToggleShortcut(state.settings) ?? "none",
136
144
  action: "open-shortcut",
137
145
  },
146
+ {
147
+ id: "toolVisibility",
148
+ label: "Plan tools",
149
+ description:
150
+ "Keep Plan helper tools visible, or reveal them after the first plan.",
151
+ currentValue: toolVisibilityLabel(
152
+ configuredPlanModeToolVisibility(state.settings),
153
+ ),
154
+ values: PLAN_MODE_TOOL_VISIBILITIES.map(toolVisibilityLabel),
155
+ action: "set-tool-visibility",
156
+ },
138
157
  ],
139
158
  },
140
159
  tools: ({ state }) => ({
141
160
  kind: "multiSelect",
142
- title: "Default Plan-mode tools",
161
+ title: "Default Plan policy allowlist",
143
162
  lines: [
144
- "Changes apply when a later Plan workflow starts; required Plan tools stay enabled.",
145
- "Non-built-in tools run at user risk.",
163
+ "Changes apply when a later Plan workflow starts; model-visible tools stay unchanged.",
164
+ "Only tools already active in Pi can be allowed; non-built-ins run at user risk.",
146
165
  ],
147
166
  enableSearch: true,
148
167
  viewportSize: 10,
149
- items: defaultToolItems(tools, state.settings.defaultPlanTools),
168
+ items: defaultToolItems(tools, state.settings.defaultPlanTools, activeToolNames),
150
169
  action: "toggle-tool",
151
170
  actions: [
152
171
  {
@@ -201,6 +220,16 @@ export async function showPlanModeSettings(
201
220
  `Plan mode thinking level: ${value}. Applies to the next Plan workflow.`,
202
221
  );
203
222
  },
223
+ "set-tool-visibility": async ({ ctx: actionCtx, value, signal }) => {
224
+ const toolVisibility = toolVisibilityFromLabel(value);
225
+ if (!toolVisibility) return { kind: "rejected" };
226
+ return savePatch(
227
+ actionCtx,
228
+ { toolVisibility },
229
+ signal,
230
+ `Plan tools: ${toolVisibilityLabel(toolVisibility)}.`,
231
+ );
232
+ },
204
233
  "open-tools": async () => ({ kind: "to", screen: "tools" }),
205
234
  "set-retention": async ({ ctx: actionCtx, value, signal }) => {
206
235
  const implementationPlanRetention = retentionFromLabel(value);
@@ -209,7 +238,7 @@ export async function showPlanModeSettings(
209
238
  actionCtx,
210
239
  { implementationPlanRetention },
211
240
  signal,
212
- `After Implement: ${retentionLabel(implementationPlanRetention)}. Applies to the next Implement action.`,
241
+ `Plan reinjection: ${retentionLabel(implementationPlanRetention)}. Applies to the next Implement action.`,
213
242
  );
214
243
  },
215
244
  "open-export": async () => ({ kind: "to", screen: "export" }),
@@ -248,7 +277,9 @@ export async function showPlanModeSettings(
248
277
  },
249
278
  "toggle-tool": async ({ ctx: actionCtx, state, itemId, selected, signal }) => {
250
279
  const tool = tools.find((candidate) => candidate.name === itemId);
251
- if (!tool || !canSelectToolInPlanMode(tool)) return { kind: "rejected" };
280
+ if (!tool || !activeToolNames.has(tool.name) || !canSelectToolInPlanMode(tool)) {
281
+ return { kind: "rejected" };
282
+ }
252
283
  const names = explicitToolNames(tools, state.settings.defaultPlanTools);
253
284
  const next = selected
254
285
  ? Array.from(new Set([...names, tool.name]))
@@ -257,7 +288,7 @@ export async function showPlanModeSettings(
257
288
  actionCtx,
258
289
  { defaultPlanTools: next },
259
290
  signal,
260
- `Default Plan-mode tools: ${next.length === 0 ? "required tools only" : `${next.length} selected`}.`,
291
+ `Default Plan policy: ${next.length === 0 ? "no optional tools" : `${next.length} allowed`}.`,
261
292
  );
262
293
  },
263
294
  "reset-tools": async ({ ctx: actionCtx, state, signal }) => {
@@ -310,7 +341,7 @@ export async function showPlanModeSettings(
310
341
  function settingsLines(settingsPath: string, notice: string | undefined) {
311
342
  return [
312
343
  `User settings · ${safeTerminalText(settingsPath)}`,
313
- "Plan defaults apply to the next workflow; handoff and export choices apply to their next action.",
344
+ "Plan defaults apply to the next workflow; reinjection and export choices apply to their next action.",
314
345
  ...(notice ? [safeTerminalText(notice)] : []),
315
346
  ];
316
347
  }
@@ -332,18 +363,33 @@ function retentionFromLabel(value: string | undefined) {
332
363
  return IMPLEMENTATION_PLAN_RETENTIONS.find((retention) => retentionLabel(retention) === value);
333
364
  }
334
365
 
366
+ function toolVisibilityLabel(value: PlanModeSettings["toolVisibility"] | "after-first-plan") {
367
+ return value === "always" ? "Always" : "After first plan";
368
+ }
369
+
370
+ function toolVisibilityFromLabel(value: string | undefined) {
371
+ return PLAN_MODE_TOOL_VISIBILITIES.find(
372
+ (visibility) => toolVisibilityLabel(visibility) === value,
373
+ );
374
+ }
375
+
335
376
  function defaultToolsValue(configured: string[] | undefined) {
336
377
  if (configured === undefined) return "Automatic safe built-ins";
337
- if (configured.length === 0) return "Required tools only";
378
+ if (configured.length === 0) return "No optional tools";
338
379
  return `${configured.length} selected`;
339
380
  }
340
381
 
341
- function defaultToolItems(tools: readonly ToolInfo[], configured: string[] | undefined) {
382
+ function defaultToolItems(
383
+ tools: readonly ToolInfo[],
384
+ configured: string[] | undefined,
385
+ activeToolNames: ReadonlySet<string>,
386
+ ) {
342
387
  const selected = new Set(explicitToolNames(tools, configured));
343
388
  const availableNames = new Set(tools.map((tool) => tool.name));
344
389
  const items = tools.map((tool) => {
345
- const selectable = canSelectToolInPlanMode(tool);
346
- const policy = toolPolicyLabel(tool);
390
+ const active = activeToolNames.has(tool.name);
391
+ const selectable = active && canSelectToolInPlanMode(tool);
392
+ const policy = active ? toolPolicyLabel(tool) : "not active in this Pi session";
347
393
  const description = tool.description ?? "No description available";
348
394
  return {
349
395
  id: tool.name,
@@ -352,7 +398,11 @@ function defaultToolItems(tools: readonly ToolInfo[], configured: string[] | und
352
398
  searchText: `${policy} ${description}`,
353
399
  selected: selected.has(tool.name),
354
400
  disabled: !selectable,
355
- disabledReason: selectable ? undefined : "Blocked by Plan-mode policy",
401
+ disabledReason: !active
402
+ ? "Not active in Pi; Plan mode will not activate it"
403
+ : selectable
404
+ ? undefined
405
+ : "Blocked by Plan-mode policy",
356
406
  };
357
407
  });
358
408
  for (const name of configured ?? []) {
package/src/settings.ts CHANGED
@@ -26,10 +26,12 @@ export const PLAN_MODE_THINKING_LEVELS = [
26
26
  "max",
27
27
  ] as const;
28
28
  export const IMPLEMENTATION_PLAN_RETENTIONS = [
29
- "keep",
30
29
  "clear-on-start",
31
30
  "clear-after-first-run",
31
+ "keep",
32
32
  ] as const;
33
+ export const PLAN_MODE_TOOL_VISIBILITIES = ["always", "after-first-plan"] as const;
34
+ export const DEFAULT_PLAN_MODE_TOOL_VISIBILITY = "after-first-plan";
33
35
  export const DEFAULT_PLAN_EXPORT_PATH = "PLAN.md";
34
36
  const MODIFIERS = new Set(["ctrl", "shift", "alt", "super"]);
35
37
  const BASE_KEYS = new Set([
@@ -89,9 +91,11 @@ const MAX_PLAN_EXPORT_PATH_LENGTH = 4096;
89
91
 
90
92
  export type PlanModeThinkingLevel = (typeof PLAN_MODE_THINKING_LEVELS)[number];
91
93
  export type ImplementationPlanRetention = (typeof IMPLEMENTATION_PLAN_RETENTIONS)[number];
94
+ export type PlanModeToolVisibility = (typeof PLAN_MODE_TOOL_VISIBILITIES)[number];
92
95
  export type PlanModeFixedThinkingLevel = Exclude<PlanModeThinkingLevel, "inherit">;
93
96
  export interface PlanModeSettings {
94
97
  thinkingLevel: PlanModeThinkingLevel;
98
+ toolVisibility?: PlanModeToolVisibility;
95
99
  defaultPlanTools?: string[];
96
100
  implementationPlanRetention?: ImplementationPlanRetention;
97
101
  defaultPlanExportPath?: string;
@@ -100,6 +104,7 @@ export interface PlanModeSettings {
100
104
  }
101
105
  export interface PlanModeSettingsPatch {
102
106
  thinkingLevel?: PlanModeThinkingLevel;
107
+ toolVisibility?: PlanModeToolVisibility;
103
108
  defaultPlanTools?: readonly string[] | null;
104
109
  implementationPlanRetention?: ImplementationPlanRetention;
105
110
  defaultPlanExportPath?: string | null;
@@ -143,6 +148,13 @@ export function normalizePlanModeSettings(value: unknown): PlanModeSettings | un
143
148
  const settings: PlanModeSettings = {
144
149
  thinkingLevel: thinkingLevel as PlanModeThinkingLevel,
145
150
  };
151
+ if (Object.hasOwn(value, "toolVisibility")) {
152
+ const toolVisibility = Reflect.get(value, "toolVisibility");
153
+ if (!PLAN_MODE_TOOL_VISIBILITIES.includes(toolVisibility as PlanModeToolVisibility)) {
154
+ return undefined;
155
+ }
156
+ settings.toolVisibility = toolVisibility as PlanModeToolVisibility;
157
+ }
146
158
  if (Object.hasOwn(value, "defaultPlanTools")) {
147
159
  const defaultPlanTools = normalizeToolNames(Reflect.get(value, "defaultPlanTools"));
148
160
  if (!defaultPlanTools) return undefined;
@@ -299,6 +311,7 @@ export function updatePlanModeSettings(
299
311
  const current = await readSettingsDocumentForUpdate(settingsPath, legacySettingsPath);
300
312
  const updated: SettingsDocument = { ...current };
301
313
  if (patch.thinkingLevel !== undefined) updated.thinkingLevel = patch.thinkingLevel;
314
+ if (patch.toolVisibility !== undefined) updated.toolVisibility = patch.toolVisibility;
302
315
  if (patch.defaultPlanTools === null) delete updated.defaultPlanTools;
303
316
  else if (patch.defaultPlanTools !== undefined) {
304
317
  updated.defaultPlanTools = [...patch.defaultPlanTools];
@@ -482,10 +495,16 @@ export function configuredThinkingLevel(
482
495
  return settings.thinkingLevel === "inherit" ? undefined : settings.thinkingLevel;
483
496
  }
484
497
 
498
+ export function configuredPlanModeToolVisibility(
499
+ settings: PlanModeSettings,
500
+ ): PlanModeToolVisibility {
501
+ return settings.toolVisibility ?? DEFAULT_PLAN_MODE_TOOL_VISIBILITY;
502
+ }
503
+
485
504
  export function configuredImplementationPlanRetention(
486
505
  settings: PlanModeSettings,
487
506
  ): ImplementationPlanRetention {
488
- return settings.implementationPlanRetention ?? "keep";
507
+ return settings.implementationPlanRetention ?? "clear-on-start";
489
508
  }
490
509
 
491
510
  export function configuredPlanExportPath(settings: PlanModeSettings) {
@@ -1,7 +1,4 @@
1
1
  import type { ToolInfo } from "@earendil-works/pi-coding-agent";
2
- import { PLAN_MODE_COMPLETE_TOOL_NAME } from "./completion-tool.js";
3
- import { PLAN_MODE_QUESTION_TOOL_NAME } from "./question-tool.js";
4
- import { withRequiredPlanModeTools } from "./required-tools.js";
5
2
  import {
6
3
  canSelectToolInPlanMode,
7
4
  classifyPlanModeTool,
@@ -76,23 +73,3 @@ export function snapshotPlanModeSelectedNames(
76
73
  : filterAvailableSelectedToolNames(selectedToolNames, tools),
77
74
  );
78
75
  }
79
-
80
- export function snapshotPlanModeToolNames(
81
- tools: ToolInfo[],
82
- selectedNames: ReadonlySet<string>,
83
- selection: PlanModeToolSelectionSnapshot,
84
- ) {
85
- if (
86
- tools.length === 0 &&
87
- selection.selectedToolNames === undefined &&
88
- selection.selectedToolKeys === undefined &&
89
- selection.defaultPlanTools === undefined
90
- ) {
91
- return ["read", "bash", PLAN_MODE_QUESTION_TOOL_NAME, PLAN_MODE_COMPLETE_TOOL_NAME];
92
- }
93
- return withRequiredPlanModeTools(
94
- tools
95
- .filter((tool) => selectedNames.has(tool.name) && canSelectToolInPlanMode(tool))
96
- .map((tool) => tool.name),
97
- );
98
- }
@@ -0,0 +1,87 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+
3
+ export const WORKFLOW_MUTEX_CHANNEL = "workflow:mutex:v1";
4
+ export const AGENT_WORKFLOW_GROUP = "agent-workflow";
5
+
6
+ export type WorkflowMutexOwner = symbol;
7
+
8
+ interface WorkflowMutexAttemptV1 {
9
+ session: object;
10
+ group: string;
11
+ busy: boolean;
12
+ }
13
+
14
+ export class WorkflowMutex {
15
+ private session: object | undefined;
16
+ private readonly heldGroups = new Map<string, WorkflowMutexOwner>();
17
+ private generation = 0;
18
+
19
+ constructor(private readonly pi: Pick<ExtensionAPI, "events">) {
20
+ pi.events.on(WORKFLOW_MUTEX_CHANNEL, (payload) => {
21
+ this.answer(payload);
22
+ });
23
+ }
24
+
25
+ bindSession(session: object): void {
26
+ this.generation += 1;
27
+ this.heldGroups.clear();
28
+ this.session = session;
29
+ }
30
+
31
+ unbindSession(session: object): void {
32
+ if (this.session !== session) return;
33
+ this.generation += 1;
34
+ this.heldGroups.clear();
35
+ this.session = undefined;
36
+ }
37
+
38
+ acquire(group = AGENT_WORKFLOW_GROUP): WorkflowMutexOwner | undefined {
39
+ const session = this.session;
40
+ const generation = this.generation;
41
+ if (!session || this.heldGroups.has(group)) return undefined;
42
+
43
+ const attempt: WorkflowMutexAttemptV1 = { session, group, busy: false };
44
+ try {
45
+ this.pi.events.emit(WORKFLOW_MUTEX_CHANNEL, attempt);
46
+ } catch {
47
+ return undefined;
48
+ }
49
+ if (
50
+ this.session !== session ||
51
+ this.generation !== generation ||
52
+ attempt.session !== session ||
53
+ attempt.group !== group ||
54
+ attempt.busy !== false ||
55
+ this.heldGroups.has(group)
56
+ ) {
57
+ return undefined;
58
+ }
59
+
60
+ const owner = Symbol(group);
61
+ this.heldGroups.set(group, owner);
62
+ return owner;
63
+ }
64
+
65
+ isOwner(owner: WorkflowMutexOwner | undefined, group = AGENT_WORKFLOW_GROUP): boolean {
66
+ return owner !== undefined && this.heldGroups.get(group) === owner;
67
+ }
68
+
69
+ release(owner: WorkflowMutexOwner | undefined, group = AGENT_WORKFLOW_GROUP): void {
70
+ if (!this.isOwner(owner, group)) return;
71
+ this.heldGroups.delete(group);
72
+ }
73
+
74
+ private answer(payload: unknown): void {
75
+ try {
76
+ if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return;
77
+ const attempt = payload as Partial<WorkflowMutexAttemptV1>;
78
+ if (attempt.session !== this.session) return;
79
+ if (attempt.group !== AGENT_WORKFLOW_GROUP) return;
80
+ if (typeof attempt.busy !== "boolean") return;
81
+ if (!this.heldGroups.has(attempt.group)) return;
82
+ attempt.busy = true;
83
+ } catch {
84
+ // Protocol listeners must ignore unusual objects without interrupting sibling listeners.
85
+ }
86
+ }
87
+ }