@narumitw/pi-subagents 2.0.6 → 2.1.1

package/dist/chunks/{config-ui-2YUCUEBM.ts → config-ui-ABHYNGQ7.ts}

@@ -1,17 +1,18 @@
 // @generated by scripts/build-runtime.mjs; do not edit.
 // @ts-nocheck -- generated JavaScript uses a .ts extension for Pi's Jiti loader.
-import "./chunk-SCZ33MYW.ts";
+import "./chunk-PGLSFLYW.ts";
 import {
   formatStatefulAgentLine
-} from "./chunk-CBP76ARQ.ts";
-import "./chunk-S2IWVK3J.ts";
+} from "./chunk-2LMJU25E.ts";
+import "./chunk-TZ34IQ3M.ts";
+import "./chunk-ILEQ27AL.ts";
 import "./chunk-P7OH4XMF.ts";
 import "./chunk-N7BLVXKK.ts";
 import "./chunk-ONDTY4EL.ts";
-import "./chunk-O4VO6JUJ.ts";
+import "./chunk-TM2R67J3.ts";
 import {
   discoverAgents
-} from "./chunk-PSK43Y6A.ts";
+} from "./chunk-LASD73CM.ts";
 import "./chunk-RSUXZD6S.ts";
 import {
   applyStatefulLimitSetting,
@@ -31,7 +32,7 @@ import {
   statefulLimitListScreen,
   statusLines,
   workflowLabel
-} from "./chunk-EFBPISNT.ts";
+} from "./chunk-PBZMBTNJ.ts";
 import "./chunk-KMGKCEO4.ts";
 import {
   sameToolSet,
@@ -43,8 +44,12 @@ import {
   updateConsultResourceSetting,
   updateCwdPolicySetting,
   updateDelegationWorkflowSetting,
-  updateStatefulTransportSetting
-} from "./chunk-7QPPBBXZ.ts";
+  updateStatefulTransportSetting,
+  updateUsageRecordingSetting
+} from "./chunk-D4CR7T73.ts";
+import {
+  USAGE_RECORDING_RETENTION_DAYS
+} from "./chunk-N2T5IN4X.ts";
 import {
   hasOwn,
   inspectBlockingParallelLimitSettings,
@@ -53,20 +58,22 @@ import {
   inspectCwdPolicySettings,
   inspectDelegationWorkflowSettings,
   inspectStatefulTransportSettings,
+  inspectUsageRecordingSettings,
   readSubagentSettings
-} from "./chunk-QBORTI4W.ts";
+} from "./chunk-TMZRHIIK.ts";
 import {
   isStatefulLimitField
-} from "./chunk-7OBINKFM.ts";
-import "./chunk-DPPVEQAM.ts";
-import "./chunk-434NII74.ts";
-import "./chunk-C4L6P266.ts";
-import "./chunk-QDVGH2X7.ts";
+} from "./chunk-VDG7LTYE.ts";
+import "./chunk-4AQSF7AS.ts";
+import "./chunk-YU53SHA7.ts";
+import "./chunk-LEOYDZI3.ts";
+import "./chunk-IWC32VPY.ts";
 import "./chunk-BFK2Z4ZF.ts";
+import "./chunk-NLT67IZS.ts";
 import {
   safeTerminalLine
 } from "./chunk-SWGQLFSD.ts";
-import "./chunk-I2FAK44T.ts";
+import "./chunk-JSZIP73U.ts";
 import {
   MAX_BLOCKING_PARALLEL_CONCURRENCY,
   MAX_CONFIGURABLE_PARALLEL_TASKS,
@@ -79,8 +86,8 @@ function executionAgentPickerScreen(agents) {
   const configured = readSubagentSettings()?.agents ?? {};
   return {
     kind: "actions",
-    title: "Agent Execution Defaults",
-    lines: ["Choose an agent to edit its inherited model, thinking, or timeout."],
+    title: "Model, Thinking, and Time Limit",
+    lines: ["Choose a subagent. A specific request can override these starting values."],
     items: [
       ...agents.map((agent) => {
         const value = configured[agent.name];
@@ -88,7 +95,7 @@ function executionAgentPickerScreen(agents) {
           id: agent.name,
           label: safeTerminalLine(agent.name),
           description: safeTerminalLine(
-            `${agent.source} \xB7 model ${value?.model ?? agent.model ?? "inherited"} \xB7 thinking ${value?.thinkingLevel ?? agent.thinkingLevel ?? "inherited"} \xB7 timeout ${value?.timeoutMs ?? agent.timeoutMs ?? "inherited"}`
+            `${agent.source} \xB7 model ${value?.model ?? agent.model ?? "default"} \xB7 thinking ${value?.thinkingLevel ?? agent.thinkingLevel ?? "default"} \xB7 time limit ${value?.timeoutMs ?? agent.timeoutMs ?? "default"}`
           ),
           action: "pick-execution-agent"
         };
@@ -102,8 +109,8 @@ function executionAgentScreen(agent) {
   if (!agent) {
     return {
       kind: "actions",
-      title: "Agent Execution Defaults",
-      lines: ["No agent selected."],
+      title: "Model, Thinking, and Time Limit",
+      lines: ["No subagent selected."],
       items: [{ id: "back", label: "Back", action: "back" }],
       hint: "back"
     };
@@ -111,21 +118,21 @@ function executionAgentScreen(agent) {
   const configured = readSubagentSettings()?.agents?.[agent.name];
   return {
     kind: "actions",
-    title: `${safeTerminalLine(agent.name)} execution`,
+    title: `${safeTerminalLine(agent.name)} defaults`,
     lines: [
-      `Model: ${safeTerminalLine(configured?.model ?? agent.model ?? "inherited")}`,
-      `Thinking: ${configured?.thinkingLevel ?? agent.thinkingLevel ?? "inherited"}`,
-      `Timeout: ${configured?.timeoutMs ?? agent.timeoutMs ?? "inherited"}`,
-      "Explicit tool-call values remain authoritative."
+      `Model: ${safeTerminalLine(configured?.model ?? agent.model ?? "agent or Pi default")}`,
+      `Thinking: ${configured?.thinkingLevel ?? agent.thinkingLevel ?? "agent or Pi default"}`,
+      `Time limit: ${configured?.timeoutMs ?? agent.timeoutMs ?? "agent or Pi default"}`,
+      "A specific subagent request can override these defaults."
     ],
     items: [
       { id: "thinking", label: "Thinking level", to: "execution-thinking" },
       { id: "model", label: "Model", to: "execution-model" },
-      { id: "timeout", label: "Timeout", to: "execution-timeout" },
+      { id: "timeout", label: "Time limit", to: "execution-timeout" },
       {
         id: "reset",
-        label: "Reset execution defaults",
-        description: "Restore frontmatter or Pi inheritance without changing tools",
+        label: "Use agent or Pi defaults",
+        description: "Remove custom model, thinking, and time limit without changing tools",
         action: "reset-agent-execution"
       },
       { id: "back", label: "Back", action: "back" }
@@ -142,9 +149,18 @@ function executionThinkingScreen(agent) {
       {
         id: "thinking",
         label: "Default thinking level",
-        description: "Explicit spawn or blocking call values still win.",
-        currentValue: configured?.thinkingLevel ?? agent.thinkingLevel ?? "Inherited",
-        values: ["Inherited", "off", "minimal", "low", "medium", "high", "xhigh", "max"],
+        description: "A specific subagent request can override this value.",
+        currentValue: configured?.thinkingLevel ?? agent.thinkingLevel ?? "Use agent or Pi default",
+        values: [
+          "Use agent or Pi default",
+          "off",
+          "minimal",
+          "low",
+          "medium",
+          "high",
+          "xhigh",
+          "max"
+        ],
         action: "set-agent-thinking"
       }
     ] : [],
@@ -158,14 +174,14 @@ function executionModelScreen(agent, ctx) {
     kind: "actions",
     title: agent ? `${safeTerminalLine(agent.name)} model` : "Agent model",
     lines: [
-      `Current: ${safeTerminalLine(configured?.model ?? agent?.model ?? "inherited")}`,
-      "Choose a session-available model or enter a custom Pi model pattern."
+      `Current: ${safeTerminalLine(configured?.model ?? agent?.model ?? "agent or Pi default")}`,
+      "Choose an available model or enter a custom Pi model pattern."
     ],
     items: agent ? [
       {
         id: "model:__inherited__",
-        label: "Inherited",
-        description: "Use frontmatter or active Pi model resolution",
+        label: "Use agent or Pi default",
+        description: "Remove the custom model setting",
         action: "set-agent-model"
       },
       ...models.map((model) => ({
@@ -190,9 +206,9 @@ function executionModelInputScreen(agent) {
     kind: "input",
     title: agent ? `${safeTerminalLine(agent.name)} model` : "Agent model",
     lines: [
-      `Current: ${safeTerminalLine(configured?.model ?? agent?.model ?? "inherited")}`,
+      `Current: ${safeTerminalLine(configured?.model ?? agent?.model ?? "agent or Pi default")}`,
       "Enter a Pi CLI model pattern, including an optional :thinking suffix.",
-      "Use Reset execution defaults to restore inheritance."
+      "Use agent or Pi defaults to remove this custom value."
     ],
     placeholder: "provider/model or model pattern",
     action: "set-agent-model",
@@ -203,20 +219,20 @@ function executionTimeoutInputScreen(agent) {
   const configured = agent ? readSubagentSettings()?.agents?.[agent.name] : void 0;
   return {
     kind: "input",
-    title: agent ? `${safeTerminalLine(agent.name)} timeout` : "Agent timeout",
+    title: agent ? `${safeTerminalLine(agent.name)} time limit` : "Agent time limit",
     lines: [
-      `Current: ${configured?.timeoutMs ?? agent?.timeoutMs ?? "inherited"}`,
+      `Current: ${configured?.timeoutMs ?? agent?.timeoutMs ?? "agent or Pi default"}`,
       `Allowed: 1-${MAX_SUBAGENT_TIMEOUT_MS} milliseconds.`,
-      "Use Reset execution defaults to restore inheritance."
+      "Use agent or Pi defaults to remove this custom value."
     ],
-    placeholder: "Timeout in milliseconds",
+    placeholder: "Time limit in milliseconds",
     action: "set-agent-timeout",
     hint: "back"
   };
 }
 function applyAgentThinking(agent, value, ctx) {
   if (!agent) return { kind: "rejected" };
-  const thinkingLevel = value === "Inherited" ? void 0 : value;
+  const thinkingLevel = value === "Use agent or Pi default" ? void 0 : value;
   if (thinkingLevel !== void 0 && !["off", "minimal", "low", "medium", "high", "xhigh", "max"].includes(thinkingLevel)) {
     return { kind: "rejected" };
   }
@@ -236,12 +252,12 @@ function applyAgentTimeout(agent, value, ctx) {
   if (!agent) return { kind: "rejected" };
   const normalized = value?.trim() ?? "";
   if (!/^\d+$/u.test(normalized)) {
-    ctx.ui.notify("Timeout must be a whole number of milliseconds.", "warning");
+    ctx.ui.notify("Time limit must be a whole number of milliseconds.", "warning");
     return { kind: "rejected" };
   }
   const timeoutMs = Number(normalized);
   if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_SUBAGENT_TIMEOUT_MS) {
-    ctx.ui.notify(`Timeout must be between 1 and ${MAX_SUBAGENT_TIMEOUT_MS}.`, "warning");
+    ctx.ui.notify(`Time limit must be between 1 and ${MAX_SUBAGENT_TIMEOUT_MS}.`, "warning");
     return { kind: "rejected" };
   }
   return saveAgentPatch(agent.name, { timeoutMs }, ctx, "timeout");
@@ -283,11 +299,12 @@ function blockingParallelLimitScreen(runtime) {
   const limit = inspectBlockingParallelLimitSettings();
   return {
     kind: "input",
-    title: "Maximum Parallel Workers",
+    title: "Blocking Worker Limit",
     lines: [
-      `Current: ${runtime.getMaxParallelTasks()} worker tasks per blocking call`,
+      "This applies only to requests that make Pi wait for delegated work.",
+      `Current: ${runtime.getMaxParallelTasks()} subagents per blocking request`,
       `Allowed: 1-${MAX_CONFIGURABLE_PARALLEL_TASKS}`,
-      `Parallel execution still starts at most ${MAX_BLOCKING_PARALLEL_CONCURRENCY} workers at once.`,
+      `Pi still starts at most ${MAX_BLOCKING_PARALLEL_CONCURRENCY} of them at once.`,
       safeTerminalText(limit.path)
     ],
     placeholder: "Enter a whole number",
@@ -352,14 +369,14 @@ function applyBlockingParallelLimitSetting(value, ctx, runtime) {
     }
   }
   ctx.ui.notify(
-    `${settingsChanged ? "Saved and " : ""}applied: maximum ${next} parallel workers per blocking call.`,
+    `${settingsChanged ? "Saved and " : ""}applied: maximum ${next} subagents per blocking request.`,
     "info"
   );
   return { kind: "back" };
 }
 function notifyValidationError(ctx) {
   ctx.ui.notify(
-    `Maximum parallel workers must be a whole number from 1 to ${MAX_CONFIGURABLE_PARALLEL_TASKS}.`,
+    `Blocking worker limit must be a whole number from 1 to ${MAX_CONFIGURABLE_PARALLEL_TASKS}.`,
     "warning"
   );
 }
@@ -374,23 +391,23 @@ function formatError2(error) {
 var TRANSPORT_OPTIONS = [
   {
     value: "subprocess",
-    label: "Fresh subprocess",
-    description: "Compatibility path with a fresh isolated Pi process for every turn."
+    label: "Fresh process",
+    description: "Start a separate Pi process for every turn. Most compatible, but slower for follow-ups."
   },
   {
     value: "in-process",
-    label: "In process",
-    description: "Lowest follow-up overhead for built-in tools, with shared memory and crash boundary."
+    label: "Inside Pi",
+    description: "Run built-in tools inside Pi for faster follow-ups. Shares Pi's memory and crash boundary."
   },
   {
     value: "rpc",
-    label: "Persistent RPC process",
-    description: "Retain native history in one isolated Pi process per active retained agent."
+    label: "Persistent process (RPC)",
+    description: "Keep one separate Pi process per background subagent so follow-ups preserve history."
   },
   {
     value: "auto",
-    label: "Automatic",
-    description: "Read-only built-ins use in-process, write-capable built-ins use RPC, and custom tools use subprocess."
+    label: "Automatic \xB7 Recommended",
+    description: "Let Pi choose a compatible method for each subagent and its tools."
   }
 ];
 function transportSettingsScreen(runtime) {
@@ -398,12 +415,13 @@ function transportSettingsScreen(runtime) {
   const current = runtime.getRuntimeStatus();
   return {
     kind: "actions",
-    title: configured.error ? "Detached Transport \xB7 Read only" : "Detached Transport",
+    title: configured.error ? "Background Agent Transport \xB7 Read only" : "Background Agent Transport",
     lines: [
+      "Advanced: choose how Pi hosts background subagents.",
       `Current session: ${transportLabel(current.transport)}`,
       `Configured after reload: ${transportLabel(configured.value)} (${configured.source})`,
-      "Transport isolation is not a filesystem or network sandbox.",
-      "RPC v1 disables child extensions and supports built-in Pi tools only.",
+      "Separate processes do not restrict filesystem or network access.",
+      "Persistent process (RPC) supports built-in Pi tools and does not load child extensions.",
       ...configured.error ? [
         `Settings cannot be edited: ${safeTerminalLine(configured.error)}`,
         `Repair ${safeTerminalLine(configured.path)} and retry.`
@@ -429,7 +447,7 @@ async function applyTransportSetting(value, ctx, runtime, signal, isCurrent) {
   const status = runtime.getRuntimeStatus();
   if (status.retainedAgents > 0) {
     ctx.ui.notify(
-      `Cannot change transport while ${status.retainedAgents} detached agent${status.retainedAgents === 1 ? " is" : "s are"} retained. Clear Current agents first.`,
+      `Cannot change transport while ${status.retainedAgents} subagent${status.retainedAgents === 1 ? " is" : "s are"} saved for follow-up. Clear Current subagents first.`,
       "warning"
     );
     return { kind: "rejected" };
@@ -451,7 +469,7 @@ This saves the setting but does not reload Pi automatically.`,
   }
   if (runtime.getRuntimeStatus().retainedAgents > 0) {
     ctx.ui.notify(
-      "Detached agents appeared while confirming; clear them before changing transport.",
+      "New subagents were saved for follow-up while confirming. Clear them before changing transport.",
       "warning"
     );
     return { kind: "rejected" };
@@ -468,37 +486,6 @@ This saves the setting but does not reload Pi automatically.`,
     return { kind: "rejected" };
   }
 }
-function responsivenessSetupScreen(runtime) {
-  const current = runtime.getRuntimeStatus();
-  const configured = inspectStatefulTransportSettings();
-  return {
-    kind: "actions",
-    title: "Responsiveness Setup",
-    lines: [
-      `Current transport: ${transportLabel(current.transport)}`,
-      `Configured transport: ${transportLabel(configured.value)}`,
-      "Transport, completion delivery, and thinking defaults are separate explicit choices.",
-      "Use Automatic to reduce retained follow-up startup while keeping custom-tool compatibility."
-    ],
-    items: [
-      {
-        id: "auto",
-        label: "Preview Automatic transport",
-        description: "Choose a deterministic transport before each retained agent starts",
-        action: "set-transport"
-      },
-      { id: "transport", label: "Compare all transports", to: "transport" },
-      {
-        id: "completion",
-        label: "Completion delivery",
-        description: "Choose separately whether an idle root resumes for synthesis",
-        to: "settings"
-      },
-      { id: "back", label: "Back", action: "back" }
-    ],
-    hint: "back"
-  };
-}
 function transportLabel(value) {
   return TRANSPORT_OPTIONS.find((option) => option.value === value)?.label ?? value;
 }
@@ -508,9 +495,9 @@ function isTransport(value) {
 
 // src/config-ui.ts
 var SUBCOMMANDS = [
-  { value: "settings", label: "settings", description: "Configure subagent user settings" },
-  { value: "status", label: "status", description: "Show effective subagent settings" },
-  { value: "help", label: "help", description: "Show subagent settings help" }
+  { value: "settings", label: "settings", description: "Open grouped subagent settings" },
+  { value: "status", label: "status", description: "Show detailed subagent diagnostics" },
+  { value: "help", label: "help", description: "Show subagent first steps and safety help" }
 ];
 var TOOL_VIEWPORT_SIZE = 10;
 function registerSubagentConfigLifecycle(pi) {
@@ -531,7 +518,7 @@ function registerSubagentConfigCommand(pi, runtime, owner = registerSubagentConf
 }
 function registerSubagentPrimaryCommand(pi, runtime, owner) {
   pi.registerCommand("subagents", {
-    description: "Manage current-session subagents and user settings",
+    description: "Manage subagents, settings, diagnostics, and help",
     getArgumentCompletions(prefix) {
       const normalized = prefix.trim().toLowerCase();
       const matches = SUBCOMMANDS.filter((item) => item.value.startsWith(normalized));
@@ -545,7 +532,7 @@ function registerSubagentPrimaryCommand(pi, runtime, owner) {
       }
       switch (subcommand) {
         case "settings":
-          await showSubagentSettings(ctx, runtime, owner);
+          await showSubagentSettings(pi, ctx, runtime, owner);
           return;
         case "status":
           showSubagentStatus(ctx, runtime);
@@ -561,7 +548,7 @@ function registerSubagentPrimaryCommand(pi, runtime, owner) {
     }
   });
 }
-async function showSubagentManager(pi, ctx, runtime, owner) {
+async function showSubagentManager(pi, ctx, runtime, owner, start = "main") {
   if (ctx.mode !== "tui") {
     showSubagentStatus(ctx, runtime);
     return;
@@ -575,7 +562,7 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
   let selectedExecutionAgent;
   let selectedStatefulLimit = "maxAgents";
   const menu = defineMenu({
-    start: "main",
+    start,
     screens: {
       main: () => {
         const status = runtime.getRuntimeStatus();
@@ -587,29 +574,34 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
           items: [
             {
               id: "workflow",
-              label: "Change delegation",
-              description: "Choose async only (recommended) or a compatibility workflow",
+              label: "How subagents run",
+              description: "Choose whether Pi stays available while subagents work",
               to: "workflow"
             },
             {
               id: "agents",
-              label: "Current agents",
-              description: `${status.activeAgents} active \xB7 ${status.retainedAgents} retained`,
+              label: "Current subagents",
+              description: `${status.activeAgents} working \xB7 ${status.retainedAgents} saved for follow-up`,
               to: "agents"
             },
             {
               id: "settings",
               label: "Settings",
-              description: "Configure targets, trusted resources, and async completion",
-              to: "settings"
+              description: "Folders, completion, privacy, agent defaults, and advanced options",
+              to: "settings-hub"
             },
             {
-              id: "advanced",
-              label: "Advanced settings",
-              description: "Agent permissions, parallel limit, runtime details, and settings path",
-              to: "advanced"
+              id: "status",
+              label: "Diagnostics",
+              description: "Detailed runtime values, setting sources, and file paths",
+              to: "status"
             },
-            { id: "help", label: "Help", to: "help" }
+            {
+              id: "help",
+              label: "Help",
+              description: "First steps, settings behavior, commands, and safety",
+              to: "help"
+            }
           ],
           hint: "close"
         };
@@ -619,11 +611,13 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
         const active = currentWorkflow(runtime, runtime.getRuntimeStatus());
         return {
           kind: "actions",
-          title: "Change Delegation",
+          title: "How Subagents Run",
           lines: [
             `Current: ${workflowLabel(active)}`,
-            "Recommended: Async only keeps the main agent responsive and omits blocking delegation and consultation.",
-            "Final-answer-dependent detached work needs automatic resume.",
+            "Choose a workflow based on the tools and blocking behavior you need.",
+            "The blocking subagent tool is deprecated and remains available only for compatibility.",
+            "subagent_consult and subagent_await remain supported blocking helpers.",
+            "For results needed in the current answer, enable automatic continuation in Settings.",
             ...snapshot.value !== active ? [`Configured after reload: ${workflowLabel(snapshot.value)}`] : [],
             ...snapshot.error ? [
               `Settings cannot be edited: ${safeTerminalLine(snapshot.error)}`,
@@ -632,21 +626,21 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
           ],
           items: snapshot.error ? [] : [
             {
-              id: "async-only",
-              label: "Async only \xB7 Recommended",
-              description: "Detached lifecycle plus inspection; omit blocking and consultation",
+              id: "all",
+              label: workflowLabel("all"),
+              description: "Background agents plus deprecated subagent and supported blocking helpers",
               action: "set-workflow"
             },
             {
-              id: "all",
-              label: "All delegation methods",
-              description: "Compatibility: async, blocking, inspection, and consultation",
+              id: "async-only",
+              label: workflowLabel("async-only"),
+              description: "Subagents work in the background while you continue using Pi",
               action: "set-workflow"
             },
             {
               id: "blocking-only",
-              label: "Blocking only",
-              description: "Compatibility: blocking and consultation without async lifecycle",
+              label: workflowLabel("blocking-only"),
+              description: "No background agents; deprecated subagent plus read-only consultation",
               action: "set-workflow"
             }
           ],
@@ -658,14 +652,17 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
         const status = runtime.getRuntimeStatus();
         return {
           kind: "actions",
-          title: "Current-session Subagents",
-          lines: agents.length ? agents.map(formatStatefulAgentLine) : [formatEmptyStatefulRuntime(status)],
+          title: "Current Subagents",
+          lines: agents.length ? [
+            "Working subagents and subagents saved for follow-up in this session.",
+            ...agents.map(formatStatefulAgentLine)
+          ] : [formatEmptyStatefulRuntime(status)],
           items: [
             ...agents.length > 0 ? [
               {
                 id: "clear",
-                label: "Clear current-session agents",
-                description: "Close and delete retained agents for this session",
+                label: "Clear current subagents",
+                description: "Stop running work and remove subagents saved for follow-up",
                 action: "clear-agents"
               }
             ] : [],
@@ -674,72 +671,97 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
           hint: "back"
         };
       },
-      settings: () => subagentSettingsScreen(runtime),
-      advanced: () => {
+      "settings-hub": () => ({
+        kind: "actions",
+        title: "Subagent Settings",
+        lines: [
+          "Changes are saved immediately.",
+          "Transport and background-agent limits take effect after /reload."
+        ],
+        items: [
+          {
+            id: "access",
+            label: "Folders and trusted resources",
+            description: "Where subagents can start and what trusted consultations can load",
+            to: "access-settings"
+          },
+          {
+            id: "behavior",
+            label: "Completion and privacy",
+            description: "What Pi does when work finishes and optional local recording",
+            to: "behavior-settings"
+          },
+          {
+            id: "agents",
+            label: "Agent defaults",
+            description: "Tools, model, thinking effort, and time limit for each subagent",
+            to: "agent-settings"
+          },
+          {
+            id: "runtime",
+            label: "Advanced runtime settings",
+            description: "Transport and capacity controls that most users can leave unchanged",
+            to: "runtime-settings"
+          },
+          { id: "back", label: "Back", action: "back" }
+        ],
+        hint: "back"
+      }),
+      "access-settings": () => subagentAccessSettingsScreen(runtime),
+      "behavior-settings": () => subagentBehaviorSettingsScreen(runtime),
+      "agent-settings": () => ({
+        kind: "actions",
+        title: "Agent Defaults",
+        lines: ["Choose the starting settings for each subagent."],
+        items: [
+          {
+            id: "agent-tools",
+            label: "Tool permissions",
+            description: "Choose which tools each subagent may use",
+            action: "load-agent-picker"
+          },
+          {
+            id: "execution",
+            label: "Model, thinking, and time limit",
+            description: "Choose how each subagent starts unless a request overrides it",
+            to: "execution-agent-picker"
+          },
+          { id: "back", label: "Back", action: "back" }
+        ],
+        hint: "back"
+      }),
+      "runtime-settings": () => {
         const limit = inspectBlockingParallelLimitSettings();
         return {
           kind: "actions",
-          title: "Advanced Subagent Settings",
+          title: "Advanced Runtime Settings",
+          lines: ["Most users can leave these settings unchanged."],
           items: [
             {
-              id: "agent-tools",
-              label: "Agent tool permissions",
-              description: "Customize persistent per-agent tool allow-lists",
-              action: "load-agent-picker"
-            },
-            {
-              id: "status",
-              label: "Runtime details",
-              description: "Show transport, configured source, and settings path",
-              to: "status"
+              id: "transport",
+              label: "Transport",
+              description: `How Pi hosts background subagents \xB7 Current: ${transportLabel(runtime.getRuntimeStatus().transport)}`,
+              to: "transport"
             },
             {
               id: "parallel-limit",
-              label: "Maximum parallel workers",
-              description: `Current: ${runtime.getMaxParallelTasks()} per blocking call`,
+              label: "Blocking worker limit",
+              description: `Maximum subagents per blocking request \xB7 Current: ${runtime.getMaxParallelTasks()}`,
               to: "parallel-limit",
               disabled: limit.error !== void 0,
               disabledReason: limit.error ? `Repair ${safeTerminalLine(limit.path)} before editing this setting` : void 0
             },
             {
               id: "stateful-limits",
-              label: "Detached agent limits",
+              label: "Background agent limits",
               description: formatDetachedLimitSummary(runtime.getRuntimeStatus()),
               to: "stateful-limits"
             },
-            {
-              id: "performance",
-              label: "Performance and execution",
-              description: "Transport, responsiveness, and agent defaults",
-              to: "performance"
-            },
             { id: "back", label: "Back", action: "back" }
           ],
           hint: "back"
         };
       },
-      performance: () => ({
-        kind: "actions",
-        title: "Performance and Execution",
-        items: [
-          {
-            id: "responsiveness",
-            label: "Responsiveness setup",
-            description: "Preview automatic retained transport and completion guidance",
-            to: "responsiveness"
-          },
-          { id: "transport", label: "Detached transport", to: "transport" },
-          {
-            id: "agents",
-            label: "Agent execution defaults",
-            description: "Model, thinking level, and timeout",
-            to: "execution-agent-picker"
-          },
-          { id: "back", label: "Back", action: "back" }
-        ],
-        hint: "back"
-      }),
-      responsiveness: () => responsivenessSetupScreen(runtime),
       transport: () => transportSettingsScreen(runtime),
       "execution-agent-picker": () => executionAgentPickerScreen(availableAgents),
       "execution-agent": () => executionAgentScreen(selectedExecutionAgent),
@@ -752,13 +774,13 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
       "stateful-limit-input": () => statefulLimitInputScreen(selectedStatefulLimit, runtime),
       status: () => ({
         kind: "detail",
-        title: "Subagent runtime details",
+        title: "Subagent Diagnostics",
         lines: statusLines(runtime),
         hint: "back"
       }),
       help: () => ({
         kind: "detail",
-        title: "Subagents help",
+        title: "Subagents Help",
         lines: helpLines(runtime),
         hint: "back"
       }),
@@ -767,8 +789,8 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
         const configured = settings.agents ?? {};
         return {
           kind: "actions",
-          title: "Subagent Tool Configuration",
-          lines: ["Select an agent to configure its allowed tools."],
+          title: "Tool Permissions",
+          lines: ["Choose a subagent to change which tools it may use."],
           items: availableAgents.map((agent) => {
             const override = configured[agent.name];
             const hasOverride = override ? hasOwn(override, "tools") : false;
@@ -820,7 +842,7 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
         if (snapshot.error) return { kind: "rejected" };
         const active = currentWorkflow(runtime, runtime.getRuntimeStatus());
         if (itemId === active && itemId === snapshot.value) {
-          ctx.ui.notify(`Delegation already uses ${workflowLabel(itemId)}.`, "info");
+          ctx.ui.notify(`Subagents already use ${workflowLabel(itemId)}.`, "info");
           return { kind: "stay" };
         }
         const requiresReload = itemId !== active;
@@ -838,7 +860,7 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
           updateDelegationWorkflowSetting(itemId);
         } catch (error) {
           ctx.ui.notify(
-            `Delegation settings were not saved: ${formatError3(error)}. The current workflow is unchanged.`,
+            `How subagents run was not saved: ${formatError3(error)}. The current choice is unchanged.`,
             "error"
           );
           return { kind: "rejected" };
@@ -861,25 +883,22 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
         const agents = runtime.listAgents();
         if (agents.length === 0) return { kind: "stay" };
         const confirmed = await ctx.ui.confirm(
-          "Clear current-session subagents?",
-          `Close and delete ${agents.length} retained agent${agents.length === 1 ? "" : "s"}?`,
+          "Clear current subagents?",
+          `Stop work and remove ${agents.length} subagent${agents.length === 1 ? "" : "s"} saved for follow-up?`,
           { signal }
         );
         if (signal.aborted || !isCurrent()) return { kind: "close" };
         if (!confirmed) return { kind: "rejected" };
         if (runtime.listAgents().map((agent) => agent.id).join("\0") !== agents.map((agent) => agent.id).join("\0")) {
           ctx.ui.notify(
-            "Detached agents changed while confirming; review the list again.",
+            "Current subagents changed while confirming; review the list again.",
             "warning"
           );
           return { kind: "rejected" };
         }
         const cleared = await runtime.clearAgents();
         if (signal.aborted || !isCurrent()) return { kind: "close" };
-        ctx.ui.notify(
-          `Cleared ${cleared} current-session subagent${cleared === 1 ? "" : "s"}.`,
-          "info"
-        );
+        ctx.ui.notify(`Cleared ${cleared} current subagent${cleared === 1 ? "" : "s"}.`, "info");
         return { kind: "stay" };
       },
       "set-transport": async ({ itemId, signal }) => applyTransportSetting(itemId, ctx, runtime, signal, isCurrent),
@@ -912,6 +931,7 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
       "set-consult-resources": async ({ value }) => applyConsultResourceSetting(value, ctx, runtime),
       "set-consultation-cwd": async ({ value }) => applyConsultationCwdSetting(value, ctx, runtime),
       "set-delegation-cwd": async ({ value }) => applyDelegationCwdSetting(value, ctx, runtime),
+      "set-usage-recording": async ({ value, signal }) => applyUsageRecordingSetting(value, ctx, runtime, { signal, isCurrent }),
       "load-agent-picker": async () => {
         availableAgents = discoverAgents(ctx.cwd, "user", readSubagentSettings() ?? {}).agents;
         if (availableAgents.length === 0) {
@@ -980,7 +1000,7 @@ async function showSubagentManager(pi, ctx, runtime, owner) {
     isCurrent
   });
 }
-async function showSubagentSettings(ctx, runtime, owner) {
+async function showSubagentSettings(pi, ctx, runtime, owner) {
   const snapshot = inspectConsultResourceSettings();
   if (ctx.mode !== "tui") {
     if (ctx.hasUI) {
@@ -991,84 +1011,130 @@ async function showSubagentSettings(ctx, runtime, owner) {
     }
     return;
   }
-  const generation = owner.generation;
-  const isCurrent = () => generation === owner.generation && !owner.controller.signal.aborted;
-  const { defineMenu, runMenu } = await import("@narumitw/pi-tui-kit");
-  if (!isCurrent()) return;
-  const menu = defineMenu({
-    start: "settings",
-    screens: { settings: () => subagentSettingsScreen(runtime) },
-    actions: {
-      "set-completion": async ({ value }) => applyCompletionSetting(value, ctx, runtime),
-      "set-consult-resources": async ({ value }) => applyConsultResourceSetting(value, ctx, runtime),
-      "set-consultation-cwd": async ({ value }) => applyConsultationCwdSetting(value, ctx, runtime),
-      "set-delegation-cwd": async ({ value }) => applyDelegationCwdSetting(value, ctx, runtime)
-    }
-  });
-  await runMenu(ctx, menu, {
-    getState: () => void 0,
-    signal: owner.controller.signal,
-    isCurrent
-  });
+  await showSubagentManager(pi, ctx, runtime, owner, "settings-hub");
 }
-function subagentSettingsScreen(runtime) {
-  const completion = inspectCompletionDeliverySettings();
+function subagentAccessSettingsScreen(runtime) {
   const consult = inspectConsultResourceSettings();
   const cwdPolicy = inspectCwdPolicySettings();
-  const error = completion.error ?? consult.error ?? cwdPolicy.error;
+  const error = consult.error ?? cwdPolicy.error;
   return {
     kind: "settings",
-    title: error ? "Subagent User Settings \xB7 Read only" : "Subagent User Settings",
+    title: error ? "Folders and Trusted Resources \xB7 Read only" : "Folders and Trusted Resources",
     lines: [
-      "Applies now and to future sessions",
-      "Target and trust settings control startup resources, not filesystem access or sandboxing.",
-      "Manage folder trust with Pi /trust; restart Pi after changing it.",
+      "Choose where subagents may start and what read-only consultations may load.",
+      "These settings do not restrict files, shell commands, network access, or OS permissions.",
+      "Manage saved folder trust with Pi /trust, then restart Pi.",
       safeTerminalLine(consult.path),
       ...error ? [`Settings cannot be edited: ${safeTerminalLine(error)}`] : []
     ],
     items: error ? [] : [
       {
         id: "consultationCwd",
-        label: "Read-only consultation target",
-        description: "Untrusted external targets inherit no target/project resources; agent and package read-only prompts remain.",
+        label: "Where read-only consultations can start",
+        description: "Use only this workspace, or allow other folders without loading untrusted project resources.",
         currentValue: consultationCwdLabel(runtime.getConsultationCwdPolicy()),
-        values: ["Anywhere \xB7 untrusted targets inherit nothing", "Current workspace only"],
+        values: ["Any folder \xB7 no project resources when untrusted", "This workspace only"],
         action: "set-consultation-cwd"
       },
       {
         id: "delegationCwd",
-        label: "General delegation target",
-        description: "Controls starting directories, not absolute paths, shell commands, or OS permissions.",
+        label: "Where subagents can start",
+        description: "Limit subagents to this workspace, saved-trusted folders, or any folder Pi can access.",
         currentValue: delegationCwdLabel(runtime.getDelegationCwdPolicy()),
         values: [
-          "Current or saved-trusted folders",
-          "Current workspace only",
-          "Anywhere \xB7 normal Pi permissions"
+          "This workspace or saved-trusted folders",
+          "This workspace only",
+          "Any folder Pi can access"
         ],
         action: "set-delegation-cwd"
       },
       {
         id: "consultResources",
-        label: "Consultation resources for trusted targets",
-        description: "Choose which trusted context, system, skill, and prompt resources a consultation inherits.",
+        label: "Resources for trusted read-only consultations",
+        description: "Choose how much project context, skills, and prompt guidance a trusted consultation may load.",
         currentValue: consultResourceLabel(runtime.getConsultResourcePolicy()),
-        values: ["Project context only", "No inherited resources", "All trusted resources"],
+        values: ["Project context only", "No project resources", "All trusted resources"],
         action: "set-consult-resources"
-      },
+      }
+    ]
+  };
+}
+function subagentBehaviorSettingsScreen(runtime) {
+  const completion = inspectCompletionDeliverySettings();
+  const usageRecording = inspectUsageRecordingSettings();
+  const error = completion.error ?? usageRecording.error;
+  return {
+    kind: "settings",
+    title: error ? "Completion and Privacy \xB7 Read only" : "Completion and Privacy",
+    lines: [
+      "These changes apply immediately and to future sessions.",
+      safeTerminalLine(completion.path),
+      ...error ? [`Settings cannot be edited: ${safeTerminalLine(error)}`] : []
+    ],
+    items: error ? [] : [
       {
         id: "completionDelivery",
-        label: "When async work finishes",
-        description: "Wait for your next turn, or request one synthesis turn after the root settles.",
+        label: "When background work finishes",
+        description: "Wait for your next message, or steer results into active work and continue automatically from idle.",
         currentValue: completionLabel(runtime.getCompletionDelivery()),
-        values: ["Wait until my next turn", "Resume automatically when finished"],
+        values: ["Wait for my next message", "Continue automatically when work finishes"],
         action: "set-completion"
+      },
+      {
+        id: "usageRecording",
+        label: "Local usage recording",
+        description: `Optionally keep content-free timing and lifecycle events on this device for ${USAGE_RECORDING_RETENTION_DAYS} days.`,
+        currentValue: runtime.getUsageRecordingEnabled?.() ? "On \xB7 local only" : "Off",
+        values: ["Off", "On \xB7 local only"],
+        action: "set-usage-recording"
       }
     ]
   };
 }
+async function applyUsageRecordingSetting(value, ctx, runtime, options) {
+  if (options.signal.aborted || !options.isCurrent()) return { kind: "close" };
+  const previous = runtime.getUsageRecordingEnabled?.() ?? false;
+  const next = value === "On \xB7 local only";
+  if (next === previous) return { kind: "stay" };
+  if (!runtime.setUsageRecordingEnabled) {
+    ctx.ui.notify("Usage recording is unavailable in this session.", "error");
+    return { kind: "rejected" };
+  }
+  try {
+    updateUsageRecordingSetting(next);
+  } catch (error) {
+    ctx.ui.notify(`Subagent settings were not saved: ${formatError3(error)}`, "error");
+    return { kind: "rejected" };
+  }
+  try {
+    await runtime.setUsageRecordingEnabled(next);
+    if (options.signal.aborted || !options.isCurrent()) return { kind: "close" };
+    ctx.ui.notify(
+      next ? `Local content-free usage recording enabled. Records stay on this device for ${USAGE_RECORDING_RETENTION_DAYS} days.` : "Local usage recording disabled. Existing records expire under the retention policy.",
+      "info"
+    );
+    return { kind: "stay" };
+  } catch (error) {
+    if (options.signal.aborted || !options.isCurrent()) return { kind: "close" };
+    try {
+      updateUsageRecordingSetting(previous);
+      await runtime.setUsageRecordingEnabled(previous);
+      if (options.signal.aborted || !options.isCurrent()) return { kind: "close" };
+    } catch (rollbackError) {
+      if (options.signal.aborted || !options.isCurrent()) return { kind: "close" };
+      ctx.ui.notify(
+        `Usage recording could not be applied or rolled back: ${formatError3(new AggregateError([error, rollbackError]))}`,
+        "error"
+      );
+      return { kind: "rejected" };
+    }
+    ctx.ui.notify(`Subagent settings were not applied: ${formatError3(error)}`, "error");
+    return { kind: "rejected" };
+  }
+}
 function applyCompletionSetting(value, ctx, runtime) {
   const previous = runtime.getCompletionDelivery();
-  const next = value === "Resume automatically when finished" ? "auto-resume" : "next-turn";
+  const next = value === "Continue automatically when work finishes" ? "auto-resume" : "next-turn";
   if (next === previous) return { kind: "stay" };
   try {
     updateCompletionDeliverySetting(next);
@@ -1082,7 +1148,7 @@ function applyCompletionSetting(value, ctx, runtime) {
 }
 function applyConsultResourceSetting(value, ctx, runtime) {
   const previous = runtime.getConsultResourcePolicy();
-  const next = value === "No inherited resources" ? "none" : value === "All trusted resources" ? "all" : "project-context";
+  const next = value === "No project resources" ? "none" : value === "All trusted resources" ? "all" : "project-context";
   if (next === previous) return { kind: "stay" };
   try {
     updateConsultResourceSetting(next);
@@ -1096,7 +1162,7 @@ function applyConsultResourceSetting(value, ctx, runtime) {
 }
 function applyConsultationCwdSetting(value, ctx, runtime) {
   const previous = runtime.getConsultationCwdPolicy();
-  const next = value === "Current workspace only" ? "current-workspace" : "anywhere";
+  const next = value === "This workspace only" ? "current-workspace" : "anywhere";
   if (next === previous) return { kind: "stay" };
   try {
     updateCwdPolicySetting("consultation", next);
@@ -1110,7 +1176,7 @@ function applyConsultationCwdSetting(value, ctx, runtime) {
 }
 function applyDelegationCwdSetting(value, ctx, runtime) {
   const previous = runtime.getDelegationCwdPolicy();
-  const next = value === "Current workspace only" ? "current-workspace" : value === "Anywhere \xB7 normal Pi permissions" ? "anywhere" : "trusted-targets";
+  const next = value === "This workspace only" ? "current-workspace" : value === "Any folder Pi can access" ? "anywhere" : "trusted-targets";
   if (next === previous) return { kind: "stay" };
   try {
     updateCwdPolicySetting("delegation", next);
@@ -1126,7 +1192,7 @@ function blockReloadWithRetainedAgents(ctx, runtime) {
   const status = runtime.getRuntimeStatus();
   if (status.retainedAgents === 0) return false;
   ctx.ui.notify(
-    `Cannot reload while ${status.retainedAgents} detached subagent${status.retainedAgents === 1 ? " is" : "s are"} retained (${status.activeAgents} active). Open Current agents and clear them after their work is safe to discard, then change delegation.`,
+    `Cannot reload while ${status.retainedAgents} subagent${status.retainedAgents === 1 ? " is" : "s are"} saved for follow-up (${status.activeAgents} working). Open Current subagents and clear them after their work is safe to discard, then change how subagents run.`,
     "warning"
   );
   return true;
@@ -1143,4 +1209,4 @@ export {
   showSubagentManager,
   showSubagentSettings
 };
-//# sourceMappingURL=config-ui-2YUCUEBM.ts.map
+//# sourceMappingURL=config-ui-ABHYNGQ7.ts.map