pi-landstrip 0.20.3 → 0.20.5

package/README.md

@@ -65,7 +65,7 @@ and `/landstrip-subagents` for subagent/task management (`Tasks`, `Log`, `Subage
 `Primary`, `Settings`, `Help`). Task IDs accept unique prefixes; bare IDs open logs.
 `/landstrip-subagents tasks kill <id>` terminates a task. `Ctrl+Shift+A` cycles
 primary agents while idle. The `task` tool accepts `background: true`, `include_context: true`,
-and `task_id` to continue a saved task; the `tasks` tool supports `list`, `inspect`, `wait`,
+and `task_id` to continue a saved task; the `tasks` tool supports `list`, `inspect`,
 `steer`, and `cancel`. Press `S` in `Tasks` or `Enter` in running/queued logs to steer workers.
 
 ### Worker environment and authentication

package/dist/index.ts

@@ -2711,23 +2711,25 @@ var taskParameters = Type.Object({
   subagent_type: Type.String({ description: "Subagent name" }),
   task_id: Type.Optional(Type.String({ description: "Task ID to resume" })),
   command: Type.Optional(Type.String({ description: "Originating command, if any" })),
-  background: Type.Optional(Type.Boolean({ description: "Return immediately and run in background" })),
+  background: Type.Optional(Type.Boolean({
+    description: "Return immediately and run in background; completion automatically triggers a follow-up turn"
+  })),
   include_context: Type.Optional(Type.Boolean({
     description: "Seed the subagent prompt with a bounded summary of recent parent conversation"
   }))
 });
+var BACKGROUND_LAUNCH_GUIDANCE = [
+  "Terminal notification: enabled.",
+  "Automatic follow-up turn: enabled.",
+  "Next action: do not poll or sleep to wait; continue only independent useful work, otherwise end this turn and wait for the completion notification."
+].join(`
+`);
 var TasksToolSchema = Type.Object({
-  action: Type.Union([
-    Type.Literal("list"),
-    Type.Literal("inspect"),
-    Type.Literal("wait"),
-    Type.Literal("steer"),
-    Type.Literal("cancel")
-  ], {
-    description: 'Task management action: "list" to view task sessions, "inspect" for status/output, "wait" to await completion, "steer" to guide a running subagent, or "cancel" to stop an active task'
+  action: Type.Union([Type.Literal("list"), Type.Literal("inspect"), Type.Literal("steer"), Type.Literal("cancel")], {
+    description: 'Task management action: "list" to view task sessions, "inspect" for point-in-time status/output, "steer" to guide a running subagent, or "cancel" to stop an active task'
   }),
   task_id: Type.Optional(Type.String({
-    description: 'Task ID or unique prefix (required for "inspect", "wait", "steer", and "cancel")'
+    description: 'Task ID or unique prefix (required for "inspect", "steer", and "cancel")'
   })),
   mode: Type.Optional(Type.Union([Type.Literal("all"), Type.Literal("background"), Type.Literal("foreground")], {
     description: 'Optional execution mode filter for "list": "all", "background", or "foreground"'
@@ -2745,17 +2747,12 @@ var TasksToolSchema = Type.Object({
   lines: Type.Optional(Type.Integer({
     minimum: 1,
     maximum: 500,
-    description: 'Number of transcript lines to return for "inspect" or "wait" (default 100)'
+    description: 'Number of transcript lines to return for "inspect" (default 100)'
   })),
   offset: Type.Optional(Type.Integer({
     minimum: 0,
     description: '0-indexed starting line offset for "inspect" (omit for tail)'
   })),
-  timeout_ms: Type.Optional(Type.Integer({
-    minimum: 1,
-    maximum: 600000,
-    description: 'Optional timeout in milliseconds for "wait"'
-  })),
   message: Type.Optional(Type.String({
     description: 'Steering message to send to a running subagent (required for "steer")'
   }))
@@ -3537,6 +3534,10 @@ function registerSubagentWorker(pi, config) {
       name: "task",
       label: "Task",
       description: "Delegate a task to a Pi subagent process.",
+      promptSnippet: "Delegate a task to a sandboxed Pi subagent process",
+      promptGuidelines: [
+        "After launching a task with background: true, continue only independent work that does not wait on the subagent; otherwise end the current turn and wait for the automatic completion follow-up turn. Do not poll tasks to wait."
+      ],
       parameters: taskParameters,
       executionMode: "parallel",
       async execute(_id, input, signal, _onUpdate, ctx) {
@@ -3964,6 +3965,32 @@ ${this.primaryAgent.prompt}` };
         unsubscribe();
         done(undefined);
       };
+      const runSaving = (errorPrefix, action) => {
+        saving = true;
+        action().catch((error) => ctx.ui.notify(`${errorPrefix}: ${formatError(error)}`, "error")).finally(() => {
+          saving = false;
+          tui.requestRender();
+        });
+      };
+      const startSteering = (task) => {
+        const input = new Input;
+        input.focused = true;
+        input.onEscape = () => {
+          steering = undefined;
+          tui.requestRender();
+        };
+        input.onSubmit = (value) => {
+          const message = value.trim();
+          if (!message) {
+            ctx.ui.notify("Steering message must not be empty", "warning");
+            return;
+          }
+          steering = undefined;
+          this.steerTask(task, message).then(() => ctx.ui.notify(`Steered task ${task.id.slice(0, 8)}`, "info")).catch((error) => ctx.ui.notify(`Could not steer task: ${formatError(error)}`, "error")).finally(() => tui.requestRender());
+          tui.requestRender();
+        };
+        steering = input;
+      };
       const renderAgentsTab = (frame) => {
         const { tabs, pane, contentWidth, pad } = frame;
         const listedAgents = agentsForTab();
@@ -4118,8 +4145,7 @@ ${this.primaryAgent.prompt}` };
             ctx.ui.notify("Agent editing requires a trusted project", "warning");
             return;
           }
-          saving = true;
-          (async () => {
+          runSaving("Could not edit agent", async () => {
             const document = prepareProjectAgentEditor(ctx.cwd, agent);
             const edited = await ctx.ui.editor(document.title, document.content);
             if (edited === undefined)
@@ -4127,9 +4153,6 @@ ${this.primaryAgent.prompt}` };
             await document.save(edited);
             await refreshAgentRuntime(agent.name);
             ctx.ui.notify(`Updated project agent ${agent.name}`, "info");
-          })().catch((error) => ctx.ui.notify(`Could not edit agent: ${formatError(error)}`, "error")).finally(() => {
-            saving = false;
-            tui.requestRender();
           });
           return;
         } else if (data === " " && agent && !saving) {
@@ -4138,13 +4161,10 @@ ${this.primaryAgent.prompt}` };
             return;
           }
           const disabled = !agent.disabled;
-          saving = true;
-          setAgentDisabledForScope(ctx.cwd, agent.name, disabled, "project").then(async () => {
+          runSaving("Could not update agent", async () => {
+            await setAgentDisabledForScope(ctx.cwd, agent.name, disabled, "project");
             await refreshAgentRuntime(agent.name);
             ctx.ui.notify(`${agent.name} ${disabled ? "disabled" : "enabled"} in project settings`, "info");
-          }).catch((error) => ctx.ui.notify(`Could not update agent: ${formatError(error)}`, "error")).finally(() => {
-            saving = false;
-            tui.requestRender();
           });
           return;
         } else if (data.toLowerCase() === "i" && agent && !saving) {
@@ -4154,13 +4174,10 @@ ${this.primaryAgent.prompt}` };
           }
           if (!disabledOverrides.project.has(agent.name))
             return;
-          saving = true;
-          clearAgentDisabledForScope(ctx.cwd, agent.name, "project").then(async () => {
+          runSaving("Could not update agent", async () => {
+            await clearAgentDisabledForScope(ctx.cwd, agent.name, "project");
             await refreshAgentRuntime(agent.name);
             ctx.ui.notify(`${agent.name} now inherits its global state`, "info");
-          }).catch((error) => ctx.ui.notify(`Could not update agent: ${formatError(error)}`, "error")).finally(() => {
-            saving = false;
-            tui.requestRender();
           });
           return;
         } else if (tab === "primary" && matchesKey(data, "return") && agent && !agent.disabled && isPrimaryAgent(agent)) {
@@ -4218,16 +4235,16 @@ ${this.primaryAgent.prompt}` };
           ...footer
         ]);
       };
+      const item = (label, value) => `  ${theme.fg("dim", label.padEnd(20))} ${value}`;
+      const shellReadLabel = (current) => current.windowsMode !== undefined ? "Policy (required)" : current.shellReadMode === "host" ? "Host-aligned" : "Policy";
       const renderTab = {
         overview: (frame) => renderSandboxTab(frame, () => {
           if (!overview)
             return [];
           const { contentWidth } = frame;
           const status = overview.noSandboxFlag ? { color: "warning", label: "Disabled by --no-sandbox" } : !overview.enabled ? { color: "warning", label: "Disabled by configuration" } : !overview.running ? { color: "warning", label: "Inactive" } : { color: "success", label: "Active" };
-          const shellReadMode = overview.windowsMode !== undefined ? "Policy (required)" : overview.shellReadMode === "host" ? "Host-aligned" : "Policy";
           const changePath = overview.changeScope === "project" ? overview.paths.project : overview.paths.global;
           const valueWidth = Math.max(10, contentWidth - 23);
-          const item = (label, value) => `  ${theme.fg("dim", label.padEnd(20))} ${value}`;
           const body = [
             `${theme.fg(status.color, "●")} ${theme.fg("text", status.label)}`,
             item("Configured", overview.enabled ? theme.fg("text", "Enabled") : theme.fg("warning", "Disabled")),
@@ -4236,7 +4253,7 @@ ${this.primaryAgent.prompt}` };
             "",
             theme.fg("accent", "Protection"),
             item("Network", overview.networkMode),
-            item("Shell reads", shellReadMode),
+            item("Shell reads", shellReadLabel(overview)),
             item("Read rules", `${overview.config.filesystem.denyRead.length + overview.config.filesystem.denyReadAlways.length + overview.config.filesystem.allowRead.length} · ${overview.readRuleScope}`),
             item("Write rules", String(overview.config.filesystem.allowWrite.length + overview.config.filesystem.denyWrite.length + overview.config.filesystem.denyWriteAlways.length)),
             item("Session grants", String(overview.sessionDomains.length + overview.sessionReadPaths.length + overview.sessionWritePaths.length)),
@@ -4256,8 +4273,6 @@ ${this.primaryAgent.prompt}` };
           if (!overview)
             return [];
           const { listValue } = frame;
-          const shellReadMode = overview.windowsMode !== undefined ? "Policy (required)" : overview.shellReadMode === "host" ? "Host-aligned" : "Policy";
-          const item = (label, value) => `  ${theme.fg("dim", label.padEnd(20))} ${value}`;
           return [
             theme.fg("accent", "Network"),
             item("Mode", overview.networkMode),
@@ -4266,7 +4281,7 @@ ${this.primaryAgent.prompt}` };
             item("Unix sockets", overview.config.network.allowAllUnixSockets ? "all" : listValue(overview.config.network.allowUnixSockets)),
             "",
             theme.fg("accent", "Filesystem"),
-            item("Shell reads", shellReadMode),
+            item("Shell reads", shellReadLabel(overview)),
             item("Read rules for", overview.readRuleScope),
             item("Denied reads", listValue(overview.config.filesystem.denyRead)),
             item("Always denied reads", listValue(overview.config.filesystem.denyReadAlways)),
@@ -4557,35 +4572,7 @@ ${this.primaryAgent.prompt}` };
             tab = "log";
             follow = true;
             scroll = 0;
-            const input = new Input;
-            input.focused = true;
-            input.onEscape = () => {
-              steering = undefined;
-              tui.requestRender();
-            };
-            input.onSubmit = (value) => {
-              const message = value.trim();
-              if (!message) {
-                ctx.ui.notify("Steering message must not be empty", "warning");
-                return;
-              }
-              steering = undefined;
-              (async () => {
-                const running = this.running.get(task.id);
-                if (running) {
-                  await running.rpc.steer(message);
-                } else if ((task.state === "queued" || task.state === "running") && this.runPromises.has(task.id)) {
-                  const pending = this.pendingSteers.get(task.id) ?? [];
-                  pending.push(message);
-                  this.pendingSteers.set(task.id, pending);
-                } else {
-                  throw new Error("Task is no longer active");
-                }
-                ctx.ui.notify(`Steered task ${task.id.slice(0, 8)}`, "info");
-              })().catch((error) => ctx.ui.notify(`Could not steer task: ${formatError(error)}`, "error")).finally(() => tui.requestRender());
-              tui.requestRender();
-            };
-            steering = input;
+            startSteering(task);
           } else if (data.toLowerCase() === "r") {
             const finished = tasks.filter((t) => t.state === "completed" || t.state === "error" || t.state === "cancelled" || t.state === "interrupted");
             if (finished.length === 0) {
@@ -4634,35 +4621,7 @@ ${this.primaryAgent.prompt}` };
             });
             return;
           } else if (matchesKey(data, "return") && (task.state === "queued" || task.state === "running") && task.kind !== "command") {
-            const input = new Input;
-            input.focused = true;
-            input.onEscape = () => {
-              steering = undefined;
-              tui.requestRender();
-            };
-            input.onSubmit = (value) => {
-              const message = value.trim();
-              if (!message) {
-                ctx.ui.notify("Steering message must not be empty", "warning");
-                return;
-              }
-              steering = undefined;
-              (async () => {
-                const running = this.running.get(task.id);
-                if (running) {
-                  await running.rpc.steer(message);
-                } else if ((task.state === "queued" || task.state === "running") && this.runPromises.has(task.id)) {
-                  const pending = this.pendingSteers.get(task.id) ?? [];
-                  pending.push(message);
-                  this.pendingSteers.set(task.id, pending);
-                } else {
-                  throw new Error("Task is no longer active");
-                }
-                ctx.ui.notify(`Steered task ${task.id.slice(0, 8)}`, "info");
-              })().catch((error) => ctx.ui.notify(`Could not steer task: ${formatError(error)}`, "error")).finally(() => tui.requestRender());
-              tui.requestRender();
-            };
-            steering = input;
+            startSteering(task);
           } else if (data.toLowerCase() === "f") {
             follow = !follow;
           } else if (matchesKey(data, "up")) {
@@ -4760,15 +4719,12 @@ ${this.primaryAgent.prompt}` };
                 tui.requestRender();
                 return;
               }
-              saving = true;
-              deleteProjectAgent(ctx.cwd, agent).then(async (deleted) => {
+              runSaving("Could not delete agent", async () => {
+                const deleted = await deleteProjectAgent(ctx.cwd, agent);
                 if (!deleted)
                   return;
                 await refreshAgentRuntime(name);
                 ctx.ui.notify(`Deleted project agent ${name}`, "info");
-              }).catch((error) => ctx.ui.notify(`Could not delete agent: ${formatError(error)}`, "error")).finally(() => {
-                saving = false;
-                tui.requestRender();
               });
               return;
             }
@@ -4863,7 +4819,12 @@ ${this.primaryAgent.prompt}` };
     return {
       name: "tasks",
       label: "Tasks",
-      description: "Inspect, list, and cancel background tasks and subagents managed by Landstrip.",
+      description: "Inspect, list, steer, and cancel background tasks and subagents managed by Landstrip. Point-in-time management only, not a waiting primitive; background tasks automatically notify and trigger a follow-up turn when done.",
+      promptSnippet: "Inspect, list, steer, or cancel background tasks and subagents without polling",
+      promptGuidelines: [
+        "Use tasks for point-in-time inspection, steering, or cancellation, not as a waiting primitive.",
+        "Do not poll tasks with list or inspect while waiting for a background task to finish; completion automatically triggers a follow-up turn."
+      ],
       parameters: TasksToolSchema,
       executionMode: "parallel",
       renderCall: (input, theme) => {
@@ -4871,7 +4832,7 @@ ${this.primaryAgent.prompt}` };
         const target = input.task_id ? ` ${input.task_id.slice(0, 8)}` : "";
         return new Text(`${theme.fg("toolTitle", theme.bold("Tasks"))} ${theme.fg("accent", action)}${theme.fg("dim", target)}`, 0, 0);
       },
-      execute: async (_toolCallId, input, signal, _onUpdate, callCtx) => {
+      execute: async (_toolCallId, input, _signal, _onUpdate, callCtx) => {
         const ctx = boundCtx ?? callCtx;
         if (!ctx)
           throw new Error("Task context is unavailable");
@@ -4886,7 +4847,7 @@ ${this.primaryAgent.prompt}` };
             throw new Error(`Task ID prefix "${input.task_id}" matches ${matched.length} tasks`);
           return matched[0];
         };
-        const formatInspectResult = (task, timedOut = false) => {
+        const formatInspectResult = (task) => {
           const details = taskDetails(task);
           const transcript = taskTranscript(task);
           const maxLines = Math.max(1, Math.min(500, input.lines ?? 100));
@@ -4894,18 +4855,18 @@ ${this.primaryAgent.prompt}` };
           const outputText = sliced.join(`
 `);
           const modeLabel = details.background ? "background" : "foreground";
-          const timeoutNote = timedOut ? `
-Wait: timed out (task still active)` : "";
+          const activeGuidance = details.background && (details.state === "queued" || details.state === "running") ? `
+Next action: task is still active; do not poll inspect in a loop—end this turn and wait for the automatic completion follow-up turn.` : "";
           const header = task.kind === "command" ? `$ bash ${task.command ?? task.description}
 Mode: ${modeLabel}
 CWD: ${task.cwd}
 State: ${details.state}
 Duration: ${taskDuration(details) ?? "unknown"}
-Exit code: ${details.exitCode ?? "none"}${timeoutNote}` : `@${task.agent}: ${task.description}
+Exit code: ${details.exitCode ?? "none"}${activeGuidance}` : `@${task.agent}: ${task.description}
 Mode: ${modeLabel}
 State: ${details.state}
 Duration: ${taskDuration(details) ?? "unknown"}
-Tool calls: ${task.toolCalls ?? 0}${timeoutNote}`;
+Tool calls: ${task.toolCalls ?? 0}${activeGuidance}`;
           return {
             content: [
               { type: "text", text: `${header}
@@ -4951,49 +4912,6 @@ ${outputText}` }
           const task = resolveSingleTask("inspect");
           return formatInspectResult(task);
         }
-        if (action === "wait") {
-          const task = resolveSingleTask("wait");
-          let timedOut = false;
-          const runPromise = this.runPromises.get(task.id);
-          if (runPromise && (task.state === "queued" || task.state === "running")) {
-            const waiters = [
-              runPromise.then(() => {
-                return;
-              }, () => {
-                return;
-              })
-            ];
-            let timer;
-            if (input.timeout_ms && input.timeout_ms > 0) {
-              waiters.push(new Promise((resolveWait) => {
-                timer = setTimeout(() => {
-                  timedOut = true;
-                  resolveWait();
-                }, input.timeout_ms);
-              }));
-            }
-            let onAbort;
-            if (signal) {
-              waiters.push(new Promise((_, rejectWait) => {
-                if (signal.aborted) {
-                  rejectWait(new Error("Wait aborted"));
-                  return;
-                }
-                onAbort = () => rejectWait(new Error("Wait aborted"));
-                signal.addEventListener("abort", onAbort, { once: true });
-              }));
-            }
-            try {
-              await Promise.race(waiters);
-            } finally {
-              if (timer !== undefined)
-                clearTimeout(timer);
-              if (onAbort && signal)
-                signal.removeEventListener("abort", onAbort);
-            }
-          }
-          return formatInspectResult(task, timedOut);
-        }
         if (action === "steer") {
           const task = resolveSingleTask("steer");
           const message = input.message?.trim();
@@ -5004,16 +4922,7 @@ ${outputText}` }
           if (task.state !== "running" && task.state !== "queued") {
             throw new Error(`Task ${task.id.slice(0, 8)} is no longer active (${task.state})`);
           }
-          const running = this.running.get(task.id);
-          if (running) {
-            await running.rpc.steer(message);
-          } else if (this.runPromises.has(task.id)) {
-            const pending = this.pendingSteers.get(task.id) ?? [];
-            pending.push(message);
-            this.pendingSteers.set(task.id, pending);
-          } else {
-            throw new Error(`Task ${task.id.slice(0, 8)} is no longer active`);
-          }
+          await this.steerTask(task, message, `Task ${task.id.slice(0, 8)} is no longer active`);
           return {
             content: [
               {
@@ -5041,6 +4950,18 @@ ${outputText}` }
       }
     };
   }
+  async steerTask(task, message, inactiveMessage = "Task is no longer active") {
+    const running = this.running.get(task.id);
+    if (running) {
+      await running.rpc.steer(message);
+    } else if ((task.state === "queued" || task.state === "running") && this.runPromises.has(task.id)) {
+      const pending = this.pendingSteers.get(task.id) ?? [];
+      pending.push(message);
+      this.pendingSteers.set(task.id, pending);
+    } else {
+      throw new Error(inactiveMessage);
+    }
+  }
   async runBackgroundShellTask(params, ctx) {
     const taskId = randomUUID();
     const sessionId = this.activeSessionId ?? ctx.sessionManager.getSessionId();
@@ -5113,17 +5034,22 @@ ${outputText}` }
           text: `$ bash ${task.description} ${exitMsg} (${durationSec})`,
           finishedAt: Date.now()
         });
-        const commandOutput = task.outputFile && existsSync5(task.outputFile) ? readFileSync6(task.outputFile, "utf8").trim() : task.output ?? "";
-        const deliveryText = `Background command ${task.state === "completed" ? "completed" : "failed"}: ${task.description}
+        if (!this.shuttingDown && !task.delivered && task.state !== "cancelled") {
+          const rawOutput = task.outputFile && existsSync5(task.outputFile) ? readFileSync6(task.outputFile, "utf8").trim() : task.output ?? "";
+          const commandOutput = rawOutput ? this.storeTaskText(task, rawOutput, "output") : "";
+          if (commandOutput)
+            task.output = commandOutput;
+          const deliveryText = `Background command ${task.state === "completed" ? "completed" : "failed"}: ${task.description}
 
 ${renderTaskResult(task.id, task.state, commandOutput || (task.error ?? ""))}`;
-        const delivered = await this.deliverBackground(task, deliveryText);
-        if (delivered) {
-          task.delivered = true;
-          this.persist(task);
-        }
-        if (task.state === "error") {
-          ctx.ui.notify(`Background command failed: ${task.description}`, "error");
+          const delivered = await this.deliverBackground(task, deliveryText);
+          if (delivered) {
+            task.delivered = true;
+            this.persist(task);
+          }
+          if (task.state === "error") {
+            ctx.ui.notify(`Background command failed: ${task.description}`, "error");
+          }
         }
         this.notifyTaskUpdate();
         this.updateTaskWidget(ctx);
@@ -5135,10 +5061,14 @@ ${renderTaskResult(task.id, task.state, commandOutput || (task.error ?? ""))}`;
       content: [
         {
           type: "text",
-          text: `Command launched in background.
-Task ID: ${taskId}
-Output file: ${outputFile}
-Use /landstrip-subagents tasks to view live progress or cancel.`
+          text: [
+            "Command launched in background.",
+            `Task ID: ${taskId}`,
+            `Output file: ${outputFile}`,
+            BACKGROUND_LAUNCH_GUIDANCE,
+            "Use /landstrip-subagents tasks to view live progress or cancel."
+          ].join(`
+`)
         }
       ],
       details: {
@@ -5162,6 +5092,10 @@ Use /landstrip-subagents tasks to view live progress or cancel.`
 
 Available subagents:
 ${descriptions}` : ""),
+      promptSnippet: "Delegate a task to a sandboxed Pi subagent process",
+      promptGuidelines: [
+        "After launching a task with background: true, continue only independent work that does not wait on the subagent; otherwise end the current turn and wait for the automatic completion follow-up turn. Do not poll tasks to wait."
+      ],
       parameters: taskParameters,
       executionMode: "parallel",
       renderCall: (input, theme) => {
@@ -5326,7 +5260,8 @@ ${catalog.diagnostics.join(`
             this.notifyWhenDone(task, existingRun, ctx);
           }
           const state = task.state === "queued" ? "queued" : "running";
-          const status = state === "queued" ? "Background task queued" : "Background task updated";
+          const status = `${state === "queued" ? "Background task queued" : "Background task updated"}
+${BACKGROUND_LAUNCH_GUIDANCE}`;
           return { task, text: renderTaskResult(task.id, state, status), state };
         }
         this.claimForeground(task.id);
@@ -5379,7 +5314,8 @@ ${catalog.diagnostics.join(`
       this.notifyWhenDone(task, run, ctx);
       return {
         task,
-        text: renderTaskResult(task.id, "queued", "Background task queued"),
+        text: renderTaskResult(task.id, "queued", `Background task queued
+${BACKGROUND_LAUNCH_GUIDANCE}`),
         state: "queued"
       };
     }
@@ -6351,7 +6287,7 @@ var LandstripBashSchema = Type2.Object({
   command: Type2.String({ description: "Shell command to execute" }),
   timeout: Type2.Optional(Type2.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
   background: Type2.Optional(Type2.Boolean({
-    description: "Run command asynchronously in the background and return a task ID"
+    description: "Run command asynchronously in the background and return a task ID immediately; completion automatically triggers a follow-up turn"
   })),
   name: Type2.Optional(Type2.String({
     description: "Concise label for the background command execution"
@@ -8042,6 +7978,10 @@ ${message}
       ...localBash,
       label: "bash (landstrip)",
       description: "Execute commands with the active Landstrip shell provider.",
+      promptGuidelines: [
+        ...localBash.promptGuidelines ?? [],
+        "After launching a bash command with background: true, continue only independent work that does not wait on the command; otherwise end the current turn and wait for the automatic completion follow-up turn. Do not sleep or poll tasks to wait."
+      ],
       parameters: LandstripBashSchema,
       renderCall(args, theme, context) {
         const bashArgs = args;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-landstrip",
-  "version": "0.20.3",
+  "version": "0.20.5",
   "description": "Sandboxed Bash and process-backed agents for Pi",
   "keywords": [
     "landstrip",
@@ -39,7 +39,7 @@
     "ci:test": "npm run test"
   },
   "dependencies": {
-    "@landstrip/landstrip-api": "^0.20.3",
+    "@landstrip/landstrip-api": "^0.20.5",
     "jsonc-parser": "^3.3.1",
     "minimatch": "^10.2.5",
     "undici": "^8.9.0",