@pi-unipi/unipi 3.0.0-alpha.21 → 3.0.0-alpha.22

package/packages/ask-user/README.md

@@ -1,72 +1,115 @@
-# @pi-unipi/ask-user
+# Ask User
 
-The `ask_user` tool (off by default — enable it in `/unipi:settings` → Ask User): when the agent needs a decision from you, it asks 1–4 multiple-choice questions in one dialog and waits. Modelled on Devin's question UI.
+Let the agent stop and ask you multiple-choice questions when it needs a decision.
 
-```
+`@pi-unipi/ask-user` · part of [UniPi](../../README.md)
+
+## What it does
+
+- Adds the `ask_user` tool. The tool is **off** by default.
+- Shows 1 to 4 questions in one dialog. Each question has 2 to 4 options.
+- Adds an "Other (type your own)" option, so you can type a free answer. You can paste or drop images and files into this answer.
+- Sends a question that you do not answer as "skipped". A skipped question does not stop the dialog.
+- Shows each answer in the transcript as a short tree.
+- Can send a notification while it waits for you, through [Notify](../notify/README.md).
+
+```text
 ── Planet ✓ · Foods 2 · Last book ─────────────────────────────────────
   What was the last book you read?
     Can't remember
     Don't read books
   ❭ Other (type your own)
     └ Dune, cover: [Image #1]
-      [Image #1] red-cube.png · 570 KB
 ───────────────────────────────────────────────────────────────────────
 ↑↓ navigate · ↵ select · ctrl+v image · ←→ switch question · esc cancel
 ? Not ready to answer, help me out!
 ```
 
-## Answering
+## Quick start
+
+UniPi installs this package:
+
+```bash
+pi install npm:@pi-unipi/unipi
+```
+
+To install this package alone:
+
+```bash
+pi install npm:@pi-unipi/ask-user
+```
+
+To turn on the tool:
+
+1. Open `/unipi:settings`.
+2. Select the **Ask User** group.
+3. Set **Enable ask_user** to on.
+
+When the tool is off, it tells the agent to ask in its reply.
+
+## Answer the questions
 
-| Key | Action |
-|-----|--------|
-| `↑` `↓` | Move between options |
-| `1`–`9` | Pick that option (single choice: picks and moves on; multi-select: toggles) |
-| `space` | Toggle (multi-select) |
-| `enter` | Select and go to the next question; on the last one, send everything |
-| `←` `→`, `tab` | Switch question (in a non-empty "Other" they move the text cursor) |
-| type | On "Other", just type — no Enter needed. The option numbers hide so digits are text |
-| paste / drop / `ctrl+v` | In "Other": a pasted or dropped image/file path, or a clipboard image (Ctrl+V), becomes `[Image #N]` / `[File #N]`; images are sent to the model with your answer |
-| `?` | Not ready to answer: the agent is told you want to clarify first |
-| `esc` | Cancel and stop the agent's turn (or send what's answered — see Settings) |
+| Key | What it does |
+|---|---|
+| `↑` / `↓` | Moves between options. |
+| `1`–`9` | Selects that option. In a multi-select question, it toggles the option. |
+| `Space` | Toggles an option in a multi-select question. |
+| `Enter` | Selects and goes to the next question. On the last question, it sends all answers. |
+| `←` / `→`, `Tab`, `Shift+Tab` | Goes to another question. In an "Other" field with text, `←` and `→` move the cursor. |
+| `Ctrl+V` | Pastes an image from the clipboard into the "Other" field. |
+| `?` | Tells the agent that you are not ready to answer and want to talk first. |
+| `Esc` | Stops the agent turn. A setting can make `Esc` send your answers. |
 
-Questions you leave unanswered are sent as **skipped** — skipping never blocks. The header chips show progress: `✓` answered, a number for multi-select picks.
+In the "Other" field, you type text directly. The option numbers disappear, so digits go into the text. A pasted image becomes `[Image #N]`, and a file path becomes `[File #N]`. The tool sends images to the model with your answers.
 
-In the transcript the answers stay as a short tree (`● Asked user 3 questions` / `│ Planet: Mars` / `└ Last book: Dune`). In the **simple** render style the collapsed `• Asked user` row keeps the same answers as compact `header: answer` rows underneath — answering never makes them disappear.
+## Agent tools
 
-## For the agent
+| Tool | What it does |
+|---|---|
+| `ask_user` | Asks 1 to 4 questions in one dialog and waits for the answers. |
 
 ```ts
 ask_user({
   questions: [{
-    header: "Database",                       // ≤16 chars, shown as a chip
+    header: "Database",                       // 16 characters or fewer
     question: "Which database should the service use?",
-    options: [                                // 2–4; "Other" is added automatically
+    options: [                                // 2–4 options
       { label: "Postgres", description: "JSON columns, full-text search" },
-      { label: "SQLite", description: "Zero setup; single writer" },
+      { label: "SQLite", description: "No setup, single writer" },
     ],
     multi_select: false,                      // optional
-    other: true,                              // optional; false removes "Other"
+    other: true,                              // optional, false removes "Other"
   }],
 })
 ```
 
-The result is `User answered your questions:` followed by a JSON object keyed by question: `{ "selected": [...], "custom_text": "...", "skipped": false }`. Attached images follow as image content.
+The result starts with `User answered your questions:`. A JSON object follows, with one key for each question: `{ "selected": [...], "custom_text": "...", "skipped": false }`. Images follow as image content.
 
-- Tool calls from one message run one at a time, so several `ask_user` calls can never hide each other (they used to: only the last dialog was answerable and the turn hung).
-- Options can carry `action: "end_turn"` or `action: "new_session"` with a `prefill` — the workflow skills use these for handoffs; a launcher offers **Compact & run** or **Run directly**.
-- The older single-question form (`question`, `context`, `options`, `allowMultiple`, `allowFreeform`) is still accepted; `timeout` is ignored — you answer in your own time.
-- Inside a subagent the tool fails with instructions to report the question to the lead instead.
+Other facts:
+
+- An option can have `action: "end_turn"`. This option ends the turn.
+- An option can have `action: "new_session"` and a `prefill` message. You then select **Compact & run** or **Run directly**. Workflow skills use this to start the next step.
+- The tool runs one dialog at a time. Thus several calls in one message cannot hide each other.
+- The tool also accepts the older single-question form: `question`, `context`, `options`, `allowMultiple`, `allowFreeform`. It ignores `timeout`.
+- In a subagent, the tool fails. The error tells the subagent to give the question to its lead.
+- With no interactive UI, the tool tells the agent to ask in its reply.
 
 ## Settings
 
-`/unipi:settings` → Ask User (changes apply to the next question, no restart):
-
-| Setting | Default | What it does |
-|---------|---------|--------------|
-| Enable ask_user | **off** | Give the agent the tool; when off, the agent is told to ask in its reply instead |
-| Notify when asked | on | Send a notification while the agent waits for you |
-| Questions per call | 4 | How many questions one dialog may hold (1–4; the tool description updates in new sessions) |
-| Esc | stop the agent's turn | Or: send what's answered, the rest as skipped |
-| Number keys move on | on | In a single-choice question, 1–9 also goes to the next question |
-| "Other" choice | agent decides | Or: always / never offer "Other (type your own)", whatever the agent asked for |
-| "Not ready" line | on | Show "? Not ready to answer, help me out!" (the `?` key works either way) |
+Open `/unipi:settings` → **Ask User**. A change applies to the next question.
+
+| Key | Default | What it does |
+|---|---|---|
+| `enabled` | `false` | Gives the agent the `ask_user` tool. |
+| `notifyOnAsk` | `true` | Sends a notification while the agent waits. |
+| `maxQuestions` | `4` | Maximum questions in one dialog (1–4). The tool description changes in new sessions. |
+| `escape` | `stop` | `stop` ends the agent turn. `send` sends your answers and skips the rest. |
+| `digitAdvance` | `true` | In a single-choice question, a number key also goes to the next question. |
+| `other` | `agent` | `agent` lets the agent decide. `always` and `never` override the agent. |
+| `helpLine` | `true` | Shows the "Not ready to answer" line. The `?` key works in all cases. |
+
+## See also
+
+- [Notify](../notify/README.md)
+- [BTW](../btw/README.md)
+- [Tools reference](../../docs/reference/tools.md)

package/packages/ask-user/index.ts

@@ -15,7 +15,8 @@ import {
   emitEvent,
   getPackageVersion,
 } from "@pi-unipi/core";
-import { registerAskUserTools } from "./tools.js";
+import { getAskUserSettings } from "./config.js";
+import { isSubagentChild, registerAskUserTools, syncAskUserTool } from "./tools.js";
 
 /** Package version */
 const VERSION = getPackageVersion(dirname(fileURLToPath(import.meta.url)));
@@ -25,8 +26,18 @@ export default function (pi: ExtensionAPI) {
   // Register tools
   registerAskUserTools(pi);
 
+  const sync = (cwd?: string) => {
+    try {
+      const want = getAskUserSettings(cwd).enabled && !isSubagentChild();
+      syncAskUserTool(pi, want);
+    } catch {
+      // tools may not be ready
+    }
+  };
+
   // Session lifecycle — announce module
-  pi.on("session_start", async () => {
+  pi.on("session_start", async (_event, ctx) => {
+    sync(ctx?.cwd);
     emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
       name: MODULES.ASK_USER,
       version: VERSION,
@@ -34,4 +45,8 @@ export default function (pi: ExtensionAPI) {
       tools: [ASK_USER_TOOLS.ASK],
     });
   });
+
+  pi.on("before_agent_start", async (_event, ctx) => {
+    sync(ctx?.cwd);
+  });
 }

package/packages/ask-user/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/ask-user",
-  "version": "3.0.0-alpha.21",
+  "version": "3.0.0-alpha.22",
   "description": "Structured user input tool for Pi coding agent — single-select, multi-select, freeform",
   "type": "module",
   "main": "index.ts",
@@ -40,7 +40,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "3.0.0-alpha.21"
+    "@pi-unipi/core": "3.0.0-alpha.22"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.87.1",

package/packages/ask-user/tools.ts

@@ -28,11 +28,29 @@ export interface AskDetails {
   questions: AskQuestion[];
   answers?: QuestionAnswer[];
   outcome: "answered" | "clarify" | "cancelled" | "action" | "unavailable";
+  reason?: "disabled" | "no-ui";
   /** Legacy single-question fields, kept for older consumers (compactor, notify). */
   question?: string;
   attachments?: Array<Pick<Attachment, "id" | "kind" | "path" | "name">>;
 }
 
+/**
+ * Adds the ask_user tool to pi's active set when enabled, removes it otherwise,
+ * touching ONLY `ask_user`, never another module's tools. Skips `setActiveTools`
+ * when nothing would change.
+ */
+export function syncAskUserTool(
+  pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">,
+  want: boolean,
+): void {
+  const current = pi.getActiveTools();
+  if (current.includes(ASK_USER_TOOLS.ASK) === want) return;
+  const set = new Set(current);
+  if (want) set.add(ASK_USER_TOOLS.ASK);
+  else set.delete(ASK_USER_TOOLS.ASK);
+  pi.setActiveTools([...set]);
+}
+
 const OPTION = Type.Object({
   label: Type.String({ description: "Display text (1–5 words)" }),
   description: Type.Optional(Type.String({ description: "What this option means or its trade-offs" })),
@@ -51,8 +69,8 @@ const QUESTION = Type.Object({
   other: Type.Optional(Type.Boolean({ description: "Offer \"Other (type your own)\" (default true)" })),
 });
 
-function unavailable(questions: AskQuestion[], text: string) {
-  return { content: [{ type: "text" as const, text }], details: { questions, outcome: "unavailable" } as AskDetails };
+function unavailable(questions: AskQuestion[], text: string, reason?: "disabled" | "no-ui") {
+  return { content: [{ type: "text" as const, text }], details: { questions, outcome: "unavailable", reason } as AskDetails };
 }
 
 function imageParts(attachments: readonly Attachment[]) {
@@ -120,8 +138,8 @@ export function registerAskUserTools(pi: ExtensionAPI): void {
           "ask_user is not available inside a subagent. You cannot talk to the user directly — only your lead can. Do not guess an answer: state the question, the options you considered and your recommendation in your report.",
         );
       }
-      if (!settings.enabled) return unavailable(questions, "ask_user is turned off in settings — ask in your reply instead.");
-      if (!ctx.hasUI) return unavailable(questions, "No interactive UI (non-interactive mode) — ask in your reply instead.");
+      if (!settings.enabled) return unavailable(questions, "ask_user is turned off in settings — ask in your reply instead.", "disabled");
+      if (!ctx.hasUI) return unavailable(questions, "No interactive UI (non-interactive mode) — ask in your reply instead.", "no-ui");
       if (questions.length === 0) throw new Error("ask_user needs at least one question with a question text.");
 
       if (settings.notifyOnAsk) {
@@ -186,7 +204,15 @@ export function askRows(details: AskDetails | undefined, theme: Theme): string[]
   if (details === undefined || questions.length === 0) return [];
   if (details.outcome === "cancelled") return [`   ${theme.fg("error", "Canceled by the user")}`];
   if (details.outcome === "clarify") return [`   ${theme.fg("warning", "Not ready to answer — wants to clarify first")}`];
-  if (details.outcome === "unavailable") return [`   ${theme.fg("dim", "not shown (no interactive UI or turned off)")}`];
+  if (details.outcome === "unavailable") {
+    const text =
+      details.reason === "disabled"
+        ? "not shown — ask_user is turned off in settings"
+        : details.reason === "no-ui"
+          ? "not shown — no interactive UI"
+          : "not shown (no interactive UI or turned off)";
+    return [`   ${theme.fg("dim", text)}`];
+  }
   if (details.outcome === "action") return [`   ${theme.fg("muted", "picked an action")}`];
   return questions.map((q, i) => `   ${theme.fg("muted", `${q.header}: ${answerSummary(q, details.answers?.[i])}`)}`);
 }
@@ -228,7 +254,15 @@ export function renderAskResult(details: AskDetails | undefined, theme: Theme):
   const rows: string[] = [];
   if (details!.outcome === "cancelled") rows.push(t.fg("error", "Canceled by the user"));
   else if (details!.outcome === "clarify") rows.push(t.fg("warning", "Not ready to answer — wants to clarify first"));
-  else if (details!.outcome === "unavailable") rows.push(t.fg("dim", "not shown (no interactive UI or turned off)"));
+  else if (details!.outcome === "unavailable") {
+    const text =
+      details!.reason === "disabled"
+        ? "not shown — ask_user is turned off in settings"
+        : details!.reason === "no-ui"
+          ? "not shown — no interactive UI"
+          : "not shown (no interactive UI or turned off)";
+    rows.push(t.fg("dim", text));
+  }
   else {
     questions.forEach((q, i) => {
       const a = details!.answers?.[i];

package/packages/autocomplete/README.md

@@ -1,37 +1,62 @@
-# @pi-unipi/command-enchantment
+# Command Enchantment
 
-Enhanced autocomplete for Unipi commands. It wraps Pi's base autocomplete provider and makes `/unipi:*` suggestions easier to scan with package grouping, stable sorting, short descriptions, and package colors.
+Command Enchantment makes `/unipi:*` suggestions in the editor easy to scan, with package tags, colors and a stable order.
 
-## Commands
+`@pi-unipi/command-enchantment` · part of [UniPi](../../README.md) · source folder `packages/autocomplete`
 
-Command Enchantment has no user commands. It improves the editor autocomplete experience automatically when the package is installed.
+## What it does
 
-## What It Does
+- Adds a colored package tag, for example `[workflow]`, to each `/unipi:*` suggestion. The tag replaces the pi source tag.
+- Sorts suggestions by match quality: exact, then prefix, then fuzzy.
+- Puts `/unipi:settings` first when you type `/settings`.
+- Hides `/skill:*` suggestions until you type `/skill:`.
+- Keeps argument suggestions for `/unipi:*` commands, also when you press Tab after a space.
 
-- Groups `/unipi:*` commands by package so workflow, memory, web, footer, and other commands are visually distinct.
-- Shows full command values like `unipi:permission` while replacing Pi source tags with concise package tags like `[workflow]`.
-- Sorts matches in predictable tiers: exact Unipi matches first, then other Unipi matches, then system commands.
-- Preserves dynamic argument completions from command providers (per-command `getArgumentCompletions`).
-- Ships an audit test that checks registered Unipi commands are represented in the autocomplete registry and have descriptions.
+## Quick start
 
-## Development Checks
-
-Run the registry audit before releases:
+Command Enchantment ships in `@pi-unipi/unipi`. To install it alone:
 
 ```bash
-npm --workspace packages/autocomplete test -- src/__tests__/command-registry.audit.test.ts
+pi install npm:@pi-unipi/command-enchantment
 ```
 
-Run all autocomplete tests:
+1. Type `/unipi:` in the editor.
+2. Read the package tag next to each suggestion.
+3. Type a short name, for example `/plan`. The exact match `/unipi:plan` comes first.
+
+The package has no commands and no agent tools.
+
+## Settings
+
+Open `/unipi:settings` → Command Enchantment. The namespace is `command-enchantment`.
+
+| Key | Default | What it does |
+|---|---|---|
+| `autocompleteEnhanced` | `true` | Turns the enhanced suggestions on or off. Applies at the next session start. |
+
+With `false`, the package does not add its provider. Pi suggestions stay as they are.
+
+## How it works
+
+At session start, Command Enchantment wraps the pi autocomplete provider. It changes only text that starts with `/`. Other text goes to the pi provider without a change.
+
+For a command name, it uses this order:
+
+1. A UniPi command that replaces a pi command with the same name (`settings`).
+2. An exact match of the full command.
+3. An exact match of the short name after `unipi:`.
+4. A prefix match.
+5. A fuzzy match. A shorter name comes first.
+
+In the same tier, pi commands come before UniPi commands. UniPi commands then follow a fixed package order.
+
+The command list is in `src/constants.ts`. An audit test checks that each registered `/unipi:*` command is in this list and has a description. Run it before a release:
 
 ```bash
 npm --workspace packages/autocomplete test
 ```
 
-## Configuration
-
-Autocomplete enhancement is enabled by default. The package stores its toggle in the Unipi config and can be disabled by setting `autocompleteEnhanced` to `false`.
-
-## License
+## See also
 
-MIT
+- [Commands reference](../../docs/reference/commands.md)
+- [Settings reference](../../docs/reference/settings.md)

package/packages/autocomplete/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/command-enchantment",
-  "version": "3.0.0-alpha.21",
+  "version": "3.0.0-alpha.22",
   "description": "Enhanced TUI autocomplete for /unipi:* commands — colored, sorted, and grouped by package",
   "type": "module",
   "main": "src/index.ts",

package/packages/background-tasks/README.md

@@ -1,76 +1,79 @@
-# @pi-unipi/background-tasks
+# Background Tasks
 
-Background tasks for UniPi — durable background shell jobs plus one read-only
-delegated background agent, with a footer dock the user can manage while the
-agent keeps working. Originally adopted from
-[pi-background-tasks](https://github.com/ismailsaleekh/pi-background-tasks);
-the Fusion council, attested Pi runs, and Anthropic attribution surfaces were
-removed in 2.17.0 so the module does exactly one thing.
+Background Tasks runs long shell commands in the background, so the agent can
+continue to work. When a task finishes, the agent gets a notice.
 
-## Master toggle
+`@pi-unipi/background-tasks` · part of [UniPi](../../README.md)
 
-One config key disables the entire module — no tools, no commands, no hooks, no UI:
+## What it does
 
-```json
-// ~/.unipi/config/background-tasks.json (global)
-// <workspace>/.unipi/config/background-tasks.json (override; workspace wins)
-{
-  "enabled": true
-}
-```
-
-Open `/unipi:settings` (Background Tasks group) for the master toggle,
-defaults, output caps, delegate defaults).
-
-## Surfaces
+- Starts a named shell command and returns at once with a task ID and an output file.
+- When the task stops, sends a `<background-task-notification>` message. By
+  default, this message starts a new agent turn.
+- Gives the agent bounded log reads, so large output does not fill the context.
+- Stops a task when its output is more than 20 MiB.
+- Shows a start card, a completion card and a task dock.
+- Shows a wait line above the editor while the agent waits for a task.
 
-### Tools
+## Quick start
 
-| Tool | Purpose |
-| --- | --- |
-| `bg_run` | Start a named long-running shell command; terminal notification wakes a follow-up turn by default |
-| `bg_status` / `bg_logs` / `bg_kill` | Point-in-time inspection, bounded log reads, stop — never polling primitives |
-| `bg_delegate` + `bg_result` | One read-only child Pi agent seeded with a frozen projection of this conversation; hash-verified answer retrieval |
+1. Install UniPi: `pi install npm:@pi-unipi/unipi`. You can also install this
+   package alone: `pi install npm:@pi-unipi/background-tasks`.
+2. Ask the agent to run a long test suite in the background. The agent calls `bg_run`.
+3. Push `Shift+Down` to open the task dock.
 
-### Commands
+## Commands
 
-`/unipi:bg` (start a shell task), `/unipi:bg-tasks` (open the dock),
-`/unipi:settings` (Background Tasks group).
+| Command or key | What it does |
+|---|---|
+| `/unipi:bg [--agent] [--name "Name"] <command>` | Starts a background task. It sends a notice, but does not start a turn. |
+| `/unipi:bg-tasks` | Opens the task manager. |
+| `Shift+Down` | Opens the task dock. |
+| `Ctrl+Alt+C` | Clears the notices of finished tasks. |
 
-Shortcuts: `Shift↓` opens the task manager dock; `Ctrl+Alt+C` clears finished notices.
+## Agent tools
 
-## What the user sees
+| Tool | What it does |
+|---|---|
+| `bg_run` | Starts a named shell command. Set `isAgent` to `true` only for a command that starts an LLM agent. |
+| `bg_status` | Shows the state of one task or all tasks at one time. |
+| `bg_logs` | Reads bounded output from a task. |
+| `bg_kill` | Stops a running task by ID. |
 
-- **Launch card** — `bg_run` results render as a tinted card (`● bg started <name> · wakes agent on completion`) so the start of a task is visible in the transcript.
-- **Pending-wake line** — while the agent is idle but a task that will wake it is still running, a spinner line sits above the editor: `⠋ waiting on 1 bg task · <name> 12s — agent resumes automatically when done`. Without this the UI looks finished and users assume the turn is over.
-- **Completion card** — the terminal notification renders as a tinted card (`✓ bg done <name> · exit 0 · 25s · agent woken`) with the last three output lines. Failed / stopped tasks use the error tint.
-- **Dock** (`Shift↓`) — rows show `⏰ wakes agent` for tasks that will resume the agent, and the last output line for running shell tasks.
+Do not call `bg_status` or `bg_logs` in a loop to wait. The notification
+message is the final state of the task.
 
-## Storage layout (ours — never `.pi/`)
+| `notifyOnCompletion` | `triggerOnCompletion` | Result |
+|---|---|---|
+| `true` | `true` (`bg_run` default) | A notice and a new agent turn. |
+| `true` | `false` (`/unipi:bg` default) | A notice only. |
+| `false` | any | No notice. Check the task yourself. |
 
-- Runtime artifacts (task output/metadata): `$TMPDIR/unipi-bg-tasks/<session>-<pid>-<nonce>/`
-- Durable delegate artifacts: `<workspace>/.unipi/delegate/<session>-<pid>/<task-id>/`
-- Config: `~/.unipi/config/background-tasks.json` + workspace override
+## Settings
 
-## Environment
+Namespace `background-tasks`. Open it with `/unipi:settings`.
 
-`UNIPI_BG_*` prefix (replaces the reference `PI_BG_*`):
-`UNIPI_BG_TMP_DIR`, `UNIPI_BG_MAX_OUTPUT_BYTES`, `UNIPI_BG_SHELL`,
-`UNIPI_BG_SHELL_PATH`, `UNIPI_BG_DISABLE_PI_TELEMETRY`, `UNIPI_BG_DELEGATE_*`.
+| Key | Default | What it does |
+|---|---|---|
+| `enabled` | `true` | Master switch. When it is `false`, the package registers no tools, commands or UI. |
+| `notifyOnCompletion` | `true` | Sends a notice when a task stops. |
+| `triggerOnCompletion` | `true` | Starts an agent turn when a task stops. |
+| `defaultTimeoutSeconds` | `0` | Stops a task after this time. `0` means no limit. |
+| `maxFinishedTasks` | `30` | Number of finished tasks to keep. |
+| `maxOutputBytes` | `20971520` | Stops and fails a task above this output size. Minimum 1024. |
 
-## Completion delivery
+| Variable | What it does |
+|---|---|
+| `UNIPI_BG_TMP_DIR` | Folder for task output. The default is `TMPDIR` or `/tmp`. |
+| `UNIPI_BG_MAX_OUTPUT_BYTES` | Default output limit. The `maxOutputBytes` setting wins. |
+| `UNIPI_BG_SHELL`, `UNIPI_BG_SHELL_PATH` | On Windows, sets the shell: `cmd` or `bash`. |
+| `UNIPI_BG_DISABLE_PI_TELEMETRY` | Set to `1` to stop the telemetry wrap of agent commands. |
 
-| `notifyOnCompletion` | `triggerOnCompletion` | Mode |
-| --- | --- | --- |
-| true (default) | true (bg_run default) | Durable terminal notification + automatic follow-up turn |
-| true | false (`/unipi:bg` default) | Notification only |
-| false | — | Manual monitoring |
+Task output goes to `<tmp>/unipi-bg-tasks/<session>-<pid>-<nonce>/`.
 
-Treat `<background-task-notification>` as durable terminal truth — do not poll.
+## For other packages
 
-## Shared registry (for sibling extensions)
-
-Other packages can read the live task registry synchronously — no events, no polling:
+Read the live task list without events:
 
 ```ts
 import { getSharedTaskRegistry } from "@pi-unipi/background-tasks";
@@ -79,19 +82,18 @@ const tasks = getSharedTaskRegistry()?.allTasks() ?? [];
 const running = tasks.filter((t) => t.status === "running").length;
 ```
 
-The registry is published on `globalThis` under a `Symbol.for` key at extension
-init and `session_start`, and cleared on `session_shutdown` (counts are
-per-session). Returns `undefined` when the module is disabled — callers must
-treat that as "no data", e.g. the footer's glance process line does.
+The function returns `undefined` when the package is off. Treat that as "no data".
+
+## How it works
+
+Read [Turn arbiter](../../docs/architecture/turn-arbiter.md) and
+[Harness messages](../../docs/architecture/harness-messages.md).
 
-## Differences from the reference
+## See also
 
-- Commands live in the `/unipi:*` namespace; env prefix is `UNIPI_BG_*`.
-- Runtime artifacts under the OS temp root (per-registry nonce) and durable
-  delegate artifacts under workspace `.unipi/` — never `.pi/`.
-- The reference's `update-check` footer surface is dropped (unipi's updater
-  module owns updates).
-- Removed: attested Pi runs, the five-slot Fusion council tools, and the
-  Anthropic attribution provider override.
+- [Subagents](../subagents/README.md)
+- [Tools reference](../../docs/reference/tools.md)
+- [Shortcuts reference](../../docs/reference/shortcuts.md)
 
-ISC-licensed reference: Copyright Ismail <ismailsalikhodjaev@gmail.com>.
+Based on [pi-background-tasks](https://github.com/ismailsaleekh/pi-background-tasks)
+(ISC license, Copyright Ismail).

package/packages/background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/background-tasks",
-  "version": "3.0.0-alpha.21",
+  "version": "3.0.0-alpha.22",
   "description": "Background tasks for UniPi — durable shell jobs and delegated background agents with a footer dock",
   "type": "module",
   "main": "src/index.ts",
@@ -10,7 +10,7 @@
   },
   "dependencies": {
     "@earendil-works/pi-ai": "^0.87.1",
-    "@pi-unipi/core": "3.0.0-alpha.21",
+    "@pi-unipi/core": "3.0.0-alpha.22",
     "turndown": "^7.2.4"
   },
   "devDependencies": {