pi-sessions 0.16.0 → 0.17.0

package/README.md

@@ -74,6 +74,8 @@ Open the frontend implementation task in a session to the right.
 | Session Index      | `/session-index` slash command                                         | Shows index status and rebuilds the local session index |
 | Session Auto Title | in background, `/title` slash command                                  | Give sessions titles                                    |
 
+Settings live under `sessions` in `~/.pi/agent/settings.json`. A project's `.pi/settings.json` overrides them the way pi merges its own settings: nested objects merge key by key, and the project wins.
+
 Every feature is on by default. Turn one off with `enable: false` under its own settings namespace. Index recovery and startup/switch sync always run, including when search is disabled. `hooks.enable` controls turn, tree, and compaction sync, not startup recovery.
 
 ```json
@@ -199,6 +201,7 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
       "thinkingLevel": "low",
       "roster": ["anthropic/*", "openai-codex/gpt-5.6-terra:high"],
       "deferred": {
+        "enable": true,
         "copyToClipboard": true
       }
     }
@@ -210,6 +213,8 @@ If you want to override the shortcut, put this in your `~/.pi/agent/settings.jso
 
 `roster` limits which models a handoff may launch a child session on. Defaults to pi's own `enabledModels` scoping, then to all configured models. May optionally include a thinking level; listing a model more than once adds to the levels it allows.
 
+`deferred.enable` (default `true`) offers the `deferred` launch. Turn it off, along with `sessions.subagents.enable`, to leave only host and split launches.
+
 `deferred.copyToClipboard` (default `true`) controls whether deferred handoffs copy the resume command to the clipboard. When off, the resume command is only shown in the tool call.
 
 Subagents require the handoff and messaging features. Limit recursive delegation depth with `sessions.subagents.maxDepth` (default `2`), or cap the context a subagent runs in with `sessions.subagents.contextLimit`:

package/extensions/session-handoff/install.ts

@@ -28,7 +28,11 @@ import {
 } from "./tool.ts";
 import { HANDOFF_TOOL_DETAILS_SCHEMA } from "./tool-contract.ts";
 import { HandoffToolComponent } from "./tool-renderer.ts";
-import { buildHandoffLaunchSchema, buildHandoffPromptGuidelines } from "./tool-schema.ts";
+import {
+  buildHandoffLaunchSchema,
+  buildHandoffPromptGuidelines,
+  offersSubagentLaunch,
+} from "./tool-schema.ts";
 import { buildHandoffToolView } from "./tool-view-model.ts";
 import { formatHandoffError } from "./ui.ts";
 
@@ -66,14 +70,16 @@ export function installHandoff(
     launchTargets: readonly HandoffLaunchTarget[],
     roster: HandoffRoster | undefined,
   ): void {
+    const offersSubagent = offersSubagentLaunch(launchTargets);
     pi.registerTool({
       name: "session_handoff",
       label: "Session Handoff",
       description: "Start a new Pi session with a self-contained task.",
       // Nested calls write no toolResult entry, so the board would never see the launch receipt.
       exposure: "model-only",
-      promptSnippet:
-        "Delegate bounded work to a background subagent or hand off context to another Pi session",
+      promptSnippet: offersSubagent
+        ? "Delegate bounded work to a background subagent or hand off context to another Pi session"
+        : "Hand off context to another Pi session",
       promptGuidelines: buildHandoffPromptGuidelines(launchTargets, models, roster),
       parameters: Type.Object({
         goal: Type.String({
@@ -93,8 +99,7 @@ export function installHandoff(
         ),
         requestResponse: Type.Optional(
           Type.Boolean({
-            description:
-              "Whether the child session should report completion/results of its task back to this session. Defaults to true for subagent launches and false otherwise.",
+            description: `Whether the child session should report completion/results of its task back to this session. ${offersSubagent ? "Defaults to true for subagent launches and false otherwise." : "Defaults to false."}`,
           }),
         ),
         provider: Type.Optional(
@@ -111,8 +116,9 @@ export function installHandoff(
           Type.Union(
             THINKING_LEVELS.map((level) => Type.Literal(level)),
             {
-              description:
-                "Thinking level for the child session. For directional or deferred, override only when the user requests it.",
+              description: offersSubagent
+                ? "Thinking level for the child session. For launches other than subagent, override only when the user requests it."
+                : "Thinking level for the child session. Override only when the user requests it.",
             },
           ),
         ),
@@ -215,7 +221,7 @@ export function installHandoff(
         createHandoffLaunchTargets({
           pi,
           splitBackend,
-          copyDeferredToClipboard: settings.handoff.deferred.copyToClipboard,
+          deferred: settings.handoff.deferred,
           additionalTargets: deps.getLaunchTargets?.() ?? [],
           hosts: deps.getHosts?.() ?? [],
         }),

package/extensions/session-handoff/launch-options.ts

@@ -1,5 +1,6 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { Host } from "../hosts/contract.ts";
+import type { HandoffSettings } from "../shared/settings.ts";
 import { createDeferredLaunchBackend } from "./launch/deferred.ts";
 import type { SplitLaunchBackend } from "./launch/resolution.ts";
 import {
@@ -18,7 +19,7 @@ export interface ResolvedHandoffLaunchTarget {
 export function createHandoffLaunchTargets(options: {
   pi: ExtensionAPI;
   splitBackend: SplitLaunchBackend | undefined;
-  copyDeferredToClipboard: boolean;
+  deferred: HandoffSettings["deferred"];
   additionalTargets: readonly HandoffLaunchTarget[];
   hosts?: readonly Host[];
 }): HandoffLaunchTarget[] {
@@ -35,11 +36,15 @@ export function createHandoffLaunchTargets(options: {
         ),
       )
     : [];
-  const deferred = createBackendLaunchTarget(
-    DEFERRED_LAUNCH,
-    createDeferredLaunchBackend({ copyToClipboard: options.copyDeferredToClipboard }),
-    "'deferred' creates the session and returns its resume command without opening anything.",
-  );
+  const deferredTargets = options.deferred.enable
+    ? [
+        createBackendLaunchTarget(
+          DEFERRED_LAUNCH,
+          createDeferredLaunchBackend({ copyToClipboard: options.deferred.copyToClipboard }),
+          "'deferred' creates the session and returns its resume command without opening anything.",
+        ),
+      ]
+    : [];
   return [
     ...hosts.map((host) =>
       createBackendLaunchTarget(
@@ -50,7 +55,7 @@ export function createHandoffLaunchTargets(options: {
       ),
     ),
     ...splitTargets,
-    deferred,
+    ...deferredTargets,
     ...options.additionalTargets,
   ];
 }

package/extensions/session-handoff/tool-schema.ts

@@ -1,6 +1,11 @@
 import type { Api, Model } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
-import { type HandoffLaunchTarget, LAUNCH_DIRECTIONS, SUBAGENT_LAUNCH } from "./launch-target.ts";
+import {
+  DEFERRED_LAUNCH,
+  type HandoffLaunchTarget,
+  LAUNCH_DIRECTIONS,
+  SUBAGENT_LAUNCH,
+} from "./launch-target.ts";
 import { formatRosterEntry, type HandoffRoster } from "./roster.ts";
 
 export function buildHandoffLaunchSchema(targets: readonly HandoffLaunchTarget[]) {
@@ -23,9 +28,6 @@ const SUBAGENT_GUIDELINES = [
   "After launching a subagent, do not sleep, poll, or repeatedly check its progress; continue useful work or finish the current turn and wait for its report.",
 ];
 
-const LAUNCH_TARGET_GUIDELINE =
-  "Use session_handoff directional or deferred launches only when the user requests one.";
-
 const MODEL_INHERITANCE_GUIDELINES = [
   "Leave provider and model unset to run the handoff on this session's current model.",
   "To run the handoff on a different model, set both provider and model together (both are required).",
@@ -35,7 +37,7 @@ const RESTRICTED_THINKING_GUIDELINE =
   'A ":level" suffix on a listed model limits it to those thinking levels; set thinkingLevel to one of them, or leave it unset when only one is listed.';
 
 const SUBAGENT_MODEL_OVERRIDE_GUIDELINE =
-  "For subagents, choose the model that best fits the delegated task; for directional or deferred handoffs, only override the model when the task clearly warrants it. When unsure, ask the user for their preference.";
+  "For subagents, choose the model that best fits the delegated task; for other launches, only override the model when the task clearly warrants it. When unsure, ask the user for their preference.";
 
 const DEFAULT_MODEL_OVERRIDE_GUIDELINE =
   "Only override the model when the task clearly warrants it.";
@@ -45,20 +47,15 @@ export function buildHandoffPromptGuidelines(
   models: readonly Model<Api>[],
   roster: HandoffRoster | undefined,
 ): string[] {
-  const hasSubagent = targets.some((target) => target.value === SUBAGENT_LAUNCH);
-  const hasHost = targets.some(
-    (target) =>
-      target.value !== "subagent" &&
-      target.value !== "deferred" &&
-      !LAUNCH_DIRECTIONS.some((direction) => direction === target.value),
-  );
+  const hasSubagent = offersSubagentLaunch(targets);
+  const userFacingKinds = describeUserFacingLaunchKinds(targets);
   const selectable =
     roster?.map(formatRosterEntry) ?? models.map((model) => `${model.provider}/${model.id}`);
   return [
     ...(hasSubagent ? SUBAGENT_GUIDELINES : []),
-    hasHost
-      ? "Use session_handoff host or deferred launches only when the user requests one."
-      : LAUNCH_TARGET_GUIDELINE,
+    ...(userFacingKinds
+      ? [`Use session_handoff ${userFacingKinds} launches only when the user requests one.`]
+      : []),
     ...MODEL_INHERITANCE_GUIDELINES,
     hasSubagent ? SUBAGENT_MODEL_OVERRIDE_GUIDELINE : DEFAULT_MODEL_OVERRIDE_GUIDELINE,
     ...(selectable.length > 0
@@ -67,3 +64,24 @@ export function buildHandoffPromptGuidelines(
     ...(roster?.some((entry) => entry.thinkingLevels) ? [RESTRICTED_THINKING_GUIDELINE] : []),
   ];
 }
+
+export function offersSubagentLaunch(targets: readonly HandoffLaunchTarget[]): boolean {
+  return targets.some((target) => target.value === SUBAGENT_LAUNCH);
+}
+
+function describeUserFacingLaunchKinds(targets: readonly HandoffLaunchTarget[]): string {
+  const isDirection = (value: string) => LAUNCH_DIRECTIONS.some((direction) => direction === value);
+  const kinds = [
+    targets.some((target) => isDirection(target.value)) ? "directional" : undefined,
+    targets.some(
+      (target) =>
+        target.value !== SUBAGENT_LAUNCH &&
+        target.value !== DEFERRED_LAUNCH &&
+        !isDirection(target.value),
+    )
+      ? "host"
+      : undefined,
+    targets.some((target) => target.value === DEFERRED_LAUNCH) ? "deferred" : undefined,
+  ];
+  return kinds.filter((kind) => kind !== undefined).join(" or ");
+}

package/extensions/shared/settings.ts

@@ -35,6 +35,7 @@ const SESSION_FILE_SETTINGS_SCHEMA = Type.Object({
       roster: Type.Optional(Type.Array(Type.String())),
       deferred: Type.Optional(
         Type.Object({
+          enable: Type.Optional(Type.Boolean()),
           copyToClipboard: Type.Optional(Type.Boolean()),
         }),
       ),
@@ -103,6 +104,7 @@ export interface HandoffSettings extends AgentModelSettings {
   /** Patterns naming the models a handoff may launch a child on. Empty means unrestricted. */
   roster: readonly ModelSelection[];
   deferred: {
+    enable: boolean;
     copyToClipboard: boolean;
   };
 }
@@ -228,9 +230,14 @@ function normalizeAutoTitlePrompt(value: string | undefined): string {
   return trimmed ? trimmed : DEFAULT_AUTO_TITLE_PROMPT;
 }
 
+/**
+ * pi's merged view: project `.pi/settings.json` deep-merged over the global file.
+ * Extensions load before `pi.getSettings()` is bound, and the trust decision it
+ * honors is not visible at load time, so project settings apply regardless of trust.
+ */
 function loadSessionFileSettings(): SessionFileSettings {
-  const globalSettings = SettingsManager.create(process.cwd()).getGlobalSettings();
-  const parsed = parseTypeBoxValue(ROOT_SETTINGS_SCHEMA, globalSettings, "Invalid settings");
+  const mergedSettings = SettingsManager.create(process.cwd()).getSettings();
+  const parsed = parseTypeBoxValue(ROOT_SETTINGS_SCHEMA, mergedSettings, "Invalid settings");
   return parsed.sessions ?? {};
 }
 
@@ -263,6 +270,7 @@ function resolveSessionSettings(fileSettings: SessionFileSettings): SessionSetti
       persistRuns: fileSettings.handoff?.persistRuns ?? false,
       roster: normalizeRoster(fileSettings.handoff?.roster),
       deferred: {
+        enable: fileSettings.handoff?.deferred?.enable ?? true,
         copyToClipboard: fileSettings.handoff?.deferred?.copyToClipboard ?? true,
       },
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-sessions",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "type": "module",
   "description": "Pi session search, ask, handoff, messaging, auto-titling, and indexing tools",
   "license": "MIT",