@vellumai/assistant 0.6.0 → 0.6.2

package/src/config/bundled-skills/app-builder/SKILL.md

@@ -238,7 +238,7 @@ export const Header: FunctionComponent<HeaderProps> = ({ title, count }) => (
 
 file_write("{workspaceDir}/data/apps/project-tracker/src/styles.css", `.app { padding: var(--v-spacing-lg); }
 .header { display: flex; justify-content: space-between; align-items: center; }
-.badge { background: var(--v-accent); color: white; padding: var(--v-spacing-xs) var(--v-spacing-sm); border-radius: var(--v-radius-pill); }`)
+.badge { background: var(--v-accent); color: var(--v-aux-white); padding: var(--v-spacing-xs) var(--v-spacing-sm); border-radius: var(--v-radius-pill); }`)
 
 # After all files are written, compile and refresh:
 app_refresh(app_id)
@@ -290,9 +290,12 @@ Available design tokens:
 | **Typography**  | `--v-font-family`, `--v-font-mono`, `--v-font-size-xs` (10px) / `-sm` (11px) / `-base` (14px) / `-lg` (17px) / `-xl` (22px) / `-2xl` (26px), `--v-line-height` |
 | **Animation**   | `--v-duration-fast` (0.15s) / `-standard` (0.25s) / `-slow` (0.4s)                                                                                             |
 | **Palettes**    | `--v-slate-{950..50}`, `--v-emerald-*`, `--v-violet-*`, `--v-indigo-*`, `--v-rose-*`, `--v-amber-*`                                                            |
+| **Constant**    | `--v-aux-white` (always `#FFFFFF` in both modes — use for text on filled/accent backgrounds)                                                                    |
 
 Utility classes: `.v-button` (`.secondary`/`.danger`/`.ghost`), `.v-card`, `.v-list`/`.v-list-item`, `.v-badge` (`.success`/`.warning`/`.danger`), `.v-input-row`, `.v-empty-state`, `.v-toggle`.
 
+**Never hardcode `color: white` or `color: #fff`.** Use `var(--v-aux-white)` for text on filled/accent backgrounds, or `var(--v-text)` / `var(--v-text-secondary)` for text on surface backgrounds. Hardcoded white causes invisible text on light surfaces.
+
 **Custom themes:** When the user wants a specific branded look, write complete CSS with hardcoded colors and `@media (prefers-color-scheme: dark)` for dark variants. Don't mix `--v-*` auto-switching variables with hardcoded colors in the same element.
 
 **Theme detection in JavaScript:**
@@ -445,9 +448,91 @@ Important:
 - All operations are async - use `async/await`
 - Wrap all calls in `try/catch`
 
+#### Custom route handlers (user-defined routes)
+
+When the app needs server-side persistence, custom API logic, or workspace file access, use **user-defined routes**. Route handlers are TypeScript or JavaScript files that live in the workspace `routes/` directory and are served under the `/v1/x/` URL path.
+
+**Common use cases:** CRUD storage, file-based persistence, search/aggregation, external API proxying, webhook receivers.
+
+**Handler file convention:**
+
+Each handler file exports named functions for the HTTP methods it supports (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`). Handlers use the standard Web API `Request`/`Response` signature.
+
+```
+{workspaceDir}/routes/
+  items.ts               # Handles /v1/x/items
+  items/
+    [id].ts              # Not supported — use query params instead
+    index.ts             # Also handles /v1/x/items (index convention)
+```
+
+**Example handler — JSON file persistence:**
+
+```typescript
+// routes/items.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+
+export const description = "Item CRUD — stores records as a JSON file";
+
+const DATA_DIR = join(process.env.VELLUM_WORKSPACE_DIR!, "data");
+const DATA_FILE = join(DATA_DIR, "items.json");
+
+function loadItems(): Array<Record<string, unknown>> {
+  mkdirSync(DATA_DIR, { recursive: true });
+  if (!existsSync(DATA_FILE)) return [];
+  return JSON.parse(readFileSync(DATA_FILE, "utf-8"));
+}
+
+function saveItems(items: Array<Record<string, unknown>>): void {
+  mkdirSync(DATA_DIR, { recursive: true });
+  writeFileSync(DATA_FILE, JSON.stringify(items, null, 2));
+}
+
+export function GET(): Response {
+  return Response.json(loadItems());
+}
+
+export async function POST(request: Request): Promise<Response> {
+  const body = await request.json();
+  const items = loadItems();
+  const item = { id: crypto.randomUUID(), ...body, createdAt: new Date().toISOString() };
+  items.push(item);
+  saveItems(items);
+  return Response.json(item, { status: 201 });
+}
+```
+
+**Calling routes from the app frontend:**
+
+Apps call custom routes via `fetch()` using the `/v1/x/` prefix. The assistant's runtime HTTP server requires the `/v1/` namespace for all API requests.
+
+```typescript
+// In a TSX component or HTML script
+const res = await fetch("/v1/x/items");
+const items = await res.json();
+
+// Create a new item
+await fetch("/v1/x/items", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ name: "New item", status: "active" }),
+});
+```
+
+**Key rules:**
+
+- Always create the route handler files via `file_write` before calling `app_refresh`
+- Export an optional `description` string for CLI discoverability (`assistant routes list`)
+- Handlers have full Node.js API access — `fs`, `path`, `crypto`, etc.
+- Handlers get a 30-second timeout per request
+- Files are hot-reloaded on change (mtime-based cache)
+- Use `.ts` (preferred) or `.js` extensions
+- Route resolution: `routes/foo.ts` → `/v1/x/foo`, `routes/bar/index.ts` → `/v1/x/bar`
+
 #### Client-side state management
 
-`localStorage` and `sessionStorage` are available for ephemeral UI state (filters, view modes, collapsed state, preferences, form drafts). Use `window.vellum.data` for persistent app records, `localStorage` for UI preferences.
+`localStorage` and `sessionStorage` are available for ephemeral UI state (filters, view modes, collapsed state, preferences, form drafts). Use custom routes for persistent app records, `localStorage` for UI preferences.
 
 <!-- feature:app-builder-multifile:alt -->
 
@@ -464,7 +549,8 @@ let allRecords = [];
 
 async function loadRecords() {
   try {
-    allRecords = await window.vellum.data.query();
+    const res = await fetch("/v1/x/records");
+    allRecords = await res.json();
     render();
   } catch (err) {
     console.error("Failed to load:", err);
@@ -553,7 +639,7 @@ Every app must meet these baselines:
 
 ## Presentation Slide Design
 
-Slides are a different domain from apps. Skip app-specific patterns (contextual headers, search/filter, toast notifications, form validation, data bridge). Slides are static content — build navigation and layouts with custom HTML/CSS.
+Slides are a different domain from apps. Skip app-specific patterns (contextual headers, search/filter, toast notifications, form validation, custom routes). Slides are static content — build navigation and layouts with custom HTML/CSS.
 
 **Key principles:**
 
@@ -566,7 +652,7 @@ Slides are a different domain from apps. Skip app-specific patterns (contextual
 
 ## Error Handling
 
-- All `window.vellum.data` calls must be wrapped in `try/catch` with user-friendly feedback.
+- All `fetch()` calls to custom routes must be wrapped in `try/catch` with user-friendly feedback.
 - Never let a failed operation silently pass - always show a toast or inline error.
 - If the page loads with no data, show a designed empty state (`.v-empty-state`).
 - For forms, show validation errors inline next to the relevant field.

package/src/config/bundled-skills/gmail/SKILL.md

@@ -110,22 +110,27 @@ When a user asks to declutter, clean up, or organize their email - start scannin
 
 ### Workflow
 
-1. **Scan**: Call `gmail_sender_digest`. Default query targets promotions from the last 90 days.
+1. **Scan**: Call `gmail_sender_digest`. Default query targets promotions currently in the inbox from the last 90 days (`in:inbox category:promotions newer_than:90d`). Counts shown in the table reflect only what is currently in the inbox — these are the emails that will be archived.
 2. **Present**: Show results as a `ui_show` table with `selectionMode: "multiple"`:
    - **Columns (exactly 3)**: Sender, Emails Found, Unsub?
      - **Unsub? cell values**: Use rich cell format: `{ "text": "Yes", "icon": "checkmark.circle.fill", "iconColor": "success" }` when `has_unsubscribe` is true, `{ "text": "No", "icon": "minus.circle", "iconColor": "muted" }` when false.
    - **Pre-select all rows** (`selected: true`) - users deselect what they want to keep
    - **Caption**: Include two parts separated by a newline: (1) data scope, e.g. "Newsletters, notifications, and outreach from last 90 days. Deselect anything you want to keep." (adjusted to match the query used), and (2) the Unsub? column legend: "Unsub? - \"Yes\" means these emails contain an unsubscribe link, so I can opt you out automatically. \"No\" means no unsubscribe link was found - these will be archived but you may continue receiving them."
    - **Action buttons (exactly 2)**: "Archive & Unsubscribe" (primary), "Archive Only" (secondary). **NEVER offer Delete, Trash, or any destructive action.**
-3. **Wait for user action**: Stop and wait. Do NOT proceed to archiving or unsubscribing until the user clicks one of the action buttons on the table. When the user clicks an action button:
+3. **Embed scan_id in button data**: When constructing the action buttons in `ui_show`, include the `scan_id` from the `gmail_sender_digest` result in each button's `data` field. This ensures `scan_id` is forwarded automatically when the user clicks — the LLM does not need to recall it from earlier context:
+   ```json
+   { "id": "archive_unsubscribe", "label": "Archive & Unsubscribe", "style": "primary", "data": { "scan_id": "<scan_id value here>" } }
+   ```
+4. **Wait for user action**: Stop and wait. Do NOT proceed to archiving or unsubscribing until the user clicks one of the action buttons on the table. When the user clicks an action button you will receive a surface action message containing `action data: { scan_id, selectedIds }`:
+   - `selectedIds` are **sender IDs** (the `id` values from the scan result rows, base64-encoded email addresses) — NOT Gmail message IDs. Always use them as `sender_ids` with `scan_id`, never as `message_ids`.
    - **Dismiss the table immediately** with `ui_dismiss` - it collapses to a completion chip
    - **Show a `task_progress` card** with steps for each phase (e.g., "Archiving 89 senders (2,400 emails)", "Unsubscribing from 72 senders"). Update each step from `in_progress` → `completed` as each phase finishes.
    - When all senders are processed, set the progress card's `status: "completed"`.
-4. **Act on selection** - batch, don't loop:
-   - **Archive all at once**: Call `gmail_archive` **once** with `scan_id` + **all** selected senders' `id` values in the `sender_ids` array. The tool resolves message IDs server-side and batches the Gmail API calls internally - never loop sender-by-sender.
+5. **Act on selection** - batch, don't loop:
+   - **Archive all at once**: Call `gmail_archive` **once** with `scan_id` (from action data) + `sender_ids` set to all `selectedIds` from the action data. The tool resolves message IDs server-side and batches the Gmail API calls internally - never loop sender-by-sender. **Never** pass `selectedIds` as `message_ids` — they are sender IDs, not Gmail message IDs.
    - **Unsubscribe in bulk**: If the action is "Archive & Unsubscribe", call `gmail_unsubscribe` for each sender that has `has_unsubscribe: true` - but emit **all** unsubscribe tool calls in a **single assistant response** (parallel tool use) rather than one-at-a-time across separate turns.
-5. **Accurate summary**: The scan counts are exact - the `message_count` shown in the table matches the number of messages archived. Format: "Cleaned up [total_archived] emails from [sender_count] senders. Unsubscribed from [unsub_count]."
-6. **Ongoing protection offer**: After reporting results, offer auto-archive filters:
+6. **Accurate summary**: The scan counts are exact - the `message_count` shown in the table matches the number of messages archived. Format: "Cleaned up [total_archived] emails from [sender_count] senders. Unsubscribed from [unsub_count]."
+7. **Ongoing protection offer**: After reporting results, offer auto-archive filters:
    - "Want me to set up auto-archive filters so future emails from these senders skip your inbox?"
    - If yes, call `gmail_filters` with `action: "create"` for each sender with `from` set to the sender's email and `remove_label_ids: ["INBOX"]`.
    - Then offer a recurring declutter schedule: "Want me to scan for new clutter monthly?" If yes, use `schedule_create` to set up a monthly declutter check.
@@ -156,9 +161,9 @@ Scan tools (`gmail_sender_digest`, `gmail_outreach_scan`) return a `scan_id` tha
 
 Before composing any email that references a date or time:
 
-1. Check the `<temporal_context>` block in the current turn for today's date and timezone
+1. Check the `timestamp:` field in the `<turn_context>` block for today's date and timezone
 2. Verify that "tomorrow" means the day after today's date, "next week" means the upcoming Monday–Friday, etc.
-3. If the email references a date from another message, cross-check it against the temporal context to ensure it's in the future
+3. If the email references a date from another message, cross-check it against the turn context to ensure it's in the future
 
 ## Confidence Scores
 

package/src/config/bundled-skills/gmail/TOOLS.json

@@ -490,7 +490,7 @@
         "properties": {
           "query": {
             "type": "string",
-            "description": "Gmail search query (default 'category:promotions newer_than:90d')"
+            "description": "Gmail search query (default 'in:inbox category:promotions newer_than:90d')"
           },
           "max_messages": {
             "type": "number",

package/src/config/bundled-skills/gmail/tools/gmail-sender-digest.ts

@@ -49,7 +49,8 @@ export async function run(
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
   const account = input.account as string | undefined;
-  const query = (input.query as string) ?? "category:promotions newer_than:90d";
+  const query =
+    (input.query as string) ?? "in:inbox category:promotions newer_than:90d";
   const maxMessages = Math.min(
     (input.max_messages as number) ?? 5000,
     MAX_MESSAGES_CAP,

package/src/config/bundled-skills/messaging/SKILL.md

@@ -148,6 +148,7 @@ Telegram is supported as a messaging provider with limited capabilities compared
 - `send_notification` is provided by the **notifications** skill (always active) -- use it when the user asks for an alert/notification (for example "send this as a desktop notification").
 - Use `messaging_send` when the user asks to send a message into a specific chat/email destination.
 - `send_notification` channel routing is LLM-driven; `preferred_channels` are hints, not hard channel forcing.
+- Before using `messaging_send` or `send_notification`, look up the recipient's contact record with `contact_search` to inform tone and content (see **Recipient Context** below).
 
 ## Personalized Drafting
 
@@ -157,6 +158,12 @@ If no style items exist and the user asks you to draft a message, suggest runnin
 
 > "I can analyze your sent messages to learn your writing style so drafts sound like you. Want me to do that?"
 
+## Recipient Context
+
+Before composing or sending a message to someone, look up their contact record with `contact_search` using their name or channel address. If the contact has notes (e.g. relationship context, communication preferences, response expectations), use that context to inform the message's tone, level of detail, and content. This ensures outbound messages are personalized to the recipient — not just the sender's style.
+
+If no contact record exists, proceed without recipient context.
+
 ## Confidence Scores
 
 Medium and high risk tools require a confidence score between 0 and 1:

package/src/config/bundled-skills/schedule/SKILL.md

@@ -87,6 +87,14 @@ The `mode` parameter controls what happens when a schedule fires:
 
 Use `notify` for simple reminders ("remind me to take medicine at 9am") and `execute` for tasks that need assistant action ("check my calendar at 8am and send me a digest").
 
+## Conversation Reuse
+
+By default, each schedule run creates a new conversation. For recurring schedules that benefit from accumulating context across runs (e.g. polling-style jobs, daily digests that reference prior results), set `reuse_conversation: true`. When enabled, subsequent runs reuse the conversation from the last successful run instead of creating a new one.
+
+- Only applies to **recurring** schedules; ignored for one-shot schedules.
+- If the prior conversation has been deleted, a new one is created automatically.
+- On the first run (no prior conversation), a new conversation is created as usual.
+
 ## Routing (notify mode)
 
 Control how notify-mode schedules are delivered at trigger time with `routing_intent`:
@@ -101,9 +109,20 @@ Optionally pass `routing_hints` (a JSON object) to influence routing decisions (
 
 - **Default to `all_channels`** for most notifications. Users usually want to be notified wherever they are.
 - **Use `single_channel`** only when the user explicitly specifies a single channel (e.g. "remind me on Telegram").
-- **Check `user_message_channel` (or `channel` when all channels are the same)** from the turn context. If the user is currently active on a specific channel, include it as a routing hint:
+- **Determine the originating channel** for routing hints using this priority:
+  1. **`source_channel`** from `<turn_context>` — use directly if present. This is the authoritative channel name.
+  2. **`interface` fallback** — if `source_channel` is absent (common for guardian/direct users), map the `interface` value to a channel name:
+     | `interface` value | Channel name |
+     | --- | --- |
+     | `macos`, `ios` | `vellum` |
+     | `telegram` | `telegram` |
+     | `slack` | `slack` |
+     | `cli` | _(omit — no routable channel)_ |
+  3. If neither field is present or the interface is `cli`, omit `preferred_channels`.
+
+  When a channel is determined, include it as a routing hint:
   ```
-  routing_hints: { preferred_channels: ["vellum"] }
+  routing_hints: { preferred_channels: ["<resolved channel>"] }
   routing_intent: "all_channels"
   ```
 
@@ -119,6 +138,7 @@ Use `syntax` + `expression` to specify the schedule type explicitly, or just `ex
 
 ## Tips
 
+- **When the user specifies a name for the schedule, use it exactly as given.** Do not paraphrase, embellish, or generate a descriptive name.
 - Use `schedule_create` for both recurring automation ("every day at 9am") and one-time reminders ("remind me at 3pm").
 - For task tracking ("add to my tasks", "add to my queue"), use task_list_add instead.
 - `fire_at` must be a strict ISO 8601 timestamp with timezone offset or Z (e.g. `2025-03-15T09:00:00-05:00`).

package/src/config/bundled-skills/schedule/TOOLS.json

@@ -56,6 +56,10 @@
             "type": "boolean",
             "description": "When true, suppress completion notifications for this schedule. The job still runs and produces output, but no notification or conversation message is sent on completion. Useful for high-frequency recurring jobs that report findings separately. Defaults to false."
           },
+          "reuse_conversation": {
+            "type": "boolean",
+            "description": "When true, reuse the same conversation across recurring schedule runs instead of creating a new one each time. Useful for polling-style schedules that accumulate context over time. Ignored for one-shot schedules. Defaults to false."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -147,6 +151,10 @@
             "type": "boolean",
             "description": "When true, suppress completion notifications for this schedule. Useful for high-frequency jobs that report findings separately."
           },
+          "reuse_conversation": {
+            "type": "boolean",
+            "description": "When true, reuse the same conversation across recurring schedule runs instead of creating a new one each time. Useful for polling-style schedules that accumulate context over time. Ignored for one-shot schedules."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"

package/src/config/bundled-skills/settings/TOOLS.json

@@ -72,7 +72,7 @@
               "Sounds",
               "Permissions & Privacy",
               "Billing",
-              "Archived Conversations",
+              "Archive",
               "Schedules",
               "Developer"
             ],

package/src/config/bundled-skills/settings/tools/avatar-get.ts

@@ -7,27 +7,17 @@ import type {
   ToolContext,
   ToolExecutionResult,
 } from "../../../../tools/types.js";
-import { getWorkspaceDir } from "../../../../util/platform.js";
+import { getAvatarDir, getAvatarImagePath } from "../../../../util/platform.js";
 
 export async function run(
   _input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const avatarPath = join(
-    getWorkspaceDir(),
-    "data",
-    "avatar",
-    "avatar-image.png",
-  );
+  const avatarPath = getAvatarImagePath();
 
   if (!existsSync(avatarPath)) {
     // Check for native character traits and regenerate the static PNG
-    const traitsPath = join(
-      getWorkspaceDir(),
-      "data",
-      "avatar",
-      "character-traits.json",
-    );
+    const traitsPath = join(getAvatarDir(), "character-traits.json");
     if (existsSync(traitsPath)) {
       try {
         const traits = JSON.parse(readFileSync(traitsPath, "utf-8"));

package/src/config/bundled-skills/settings/tools/avatar-remove.ts

@@ -1,5 +1,4 @@
 import { existsSync, unlinkSync } from "node:fs";
-import { join } from "node:path";
 
 import { buildAssistantEvent } from "../../../../runtime/assistant-event.js";
 import { assistantEventHub } from "../../../../runtime/assistant-event-hub.js";
@@ -9,7 +8,7 @@ import type {
   ToolExecutionResult,
 } from "../../../../tools/types.js";
 import { getLogger } from "../../../../util/logger.js";
-import { getWorkspaceDir } from "../../../../util/platform.js";
+import { getAvatarImagePath } from "../../../../util/platform.js";
 import { updateIdentityAvatarSection } from "./identity-avatar.js";
 
 const log = getLogger("avatar-remove");
@@ -18,8 +17,7 @@ export async function run(
   _input: Record<string, unknown>,
   _context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const avatarDir = join(getWorkspaceDir(), "data", "avatar");
-  const avatarPath = join(avatarDir, "avatar-image.png");
+  const avatarPath = getAvatarImagePath();
 
   if (!existsSync(avatarPath)) {
     return {

package/src/config/bundled-skills/settings/tools/avatar-update.ts

@@ -9,14 +9,17 @@ import type {
   ToolExecutionResult,
 } from "../../../../tools/types.js";
 import { getLogger } from "../../../../util/logger.js";
-import { getWorkspaceDir } from "../../../../util/platform.js";
+import {
+  getAvatarImagePath,
+  getWorkspaceDir,
+} from "../../../../util/platform.js";
 import { updateIdentityAvatarSection } from "./identity-avatar.js";
 
 const log = getLogger("avatar-update");
 
 /** Canonical path where the custom avatar PNG is stored. */
 function getAvatarPath(): string {
-  return join(getWorkspaceDir(), "data", "avatar", "avatar-image.png");
+  return getAvatarImagePath();
 }
 
 export async function run(

package/src/config/bundled-skills/settings/tools/navigate-settings-tab.ts

@@ -10,21 +10,26 @@ const SETTINGS_TABS = [
   "Sounds",
   "Permissions & Privacy",
   "Billing",
-  "Archived Conversations",
+  "Archive",
   "Schedules",
   "Developer",
 ] as const;
 
 type SettingsTab = (typeof SETTINGS_TABS)[number];
 
+const LEGACY_TAB_ALIASES: Record<string, SettingsTab> = {
+  "Archived Conversations": "Archive",
+};
+
 export async function run(
   input: Record<string, unknown>,
   context: ToolContext,
 ): Promise<ToolExecutionResult> {
-  const tab = input.tab as string;
+  const rawTab = input.tab as string;
+  const tab = LEGACY_TAB_ALIASES[rawTab] ?? rawTab;
   if (!SETTINGS_TABS.includes(tab as SettingsTab)) {
     return {
-      content: `Error: unknown tab "${tab}". Valid tabs: ${SETTINGS_TABS.join(
+      content: `Error: unknown tab "${rawTab}". Valid tabs: ${SETTINGS_TABS.join(
         ", ",
       )}`,
       isError: true,

package/src/config/bundled-skills/slack/SKILL.md

@@ -68,6 +68,8 @@ When you need to send a DM or look up a Slack user by name, check contacts first
 
 1. **Before calling `users.list`**: Use `contact_search` with `query: "<name>"` and `channel_type: "slack"`. If a matching contact has `externalUserId` (Slack user ID) and `externalChatId` (DM channel ID), skip the API lookups and use those IDs directly with `chat.postMessage`.
 
+   When `contact_search` returns notes for the recipient, use them to inform the message's tone, formality, and content. Contact notes capture relationship context and communication preferences that should shape how you write to this person.
+
 2. **After resolving via API**: When you had to call `users.list` or `conversations.open` to resolve a user, save the contact with `contact_upsert` so you can find them by name next time. External Slack IDs (user ID, DM channel ID) are cached automatically by the messaging layer and should not be passed through `contact_upsert`.
 
 ## Privacy Rules

package/src/config/bundled-skills/subagent/SKILL.md

@@ -6,6 +6,9 @@ metadata:
   emoji: "🤖"
   vellum:
     display-name: "Subagent"
+    activation-hints:
+      - "Run tasks in parallel, delegate work to background agents, or do multiple things at once"
+      - "Spawn a researcher, coder, or planner agent for independent work"
 ---
 
 Subagent orchestration -- spawn background agents to work on tasks in parallel.
@@ -14,9 +17,43 @@ Subagent orchestration -- spawn background agents to work on tasks in parallel.
 
 Subagents follow this status flow: `pending` -> `running` -> `completed` / `failed` / `aborted`
 
-- **Spawn**: Use `subagent_spawn` with a label and objective. The subagent runs autonomously.
-- **Auto-notification**: The parent conversation is automatically notified when a subagent reaches a terminal status. Do NOT poll `subagent_status`.
-- **Read output**: Use `subagent_read` only after the subagent reaches a terminal status (completed/failed/aborted).
+- **Spawn**: Use `subagent_spawn` with a label, objective, and role. The subagent runs autonomously.
+- **Mid-run communication**: Subagents can send notifications to the parent via `notify_parent` while still running -- useful for sharing interim findings or signaling that they are blocked.
+- **Auto-notification**: The parent conversation is automatically notified when a subagent reaches a terminal status (completed/failed/aborted). Do NOT poll `subagent_status`.
+- **Read output**: Use `subagent_read` after the subagent reaches a terminal status to retrieve its full output.
+
+## Roles
+
+Each subagent is spawned with a role that determines its tool access. Choose the most restrictive role that can accomplish the task.
+
+| Role | Tools | When to use |
+|---|---|---|
+| `general` | Full tool access | Task genuinely needs unrestricted capabilities (rare -- prefer a specialized role) |
+| `researcher` | `web_search`, `web_fetch`, `file_read`, `file_list`, `recall`, `notify_parent` | Information gathering, web research, codebase exploration, reading documentation |
+| `coder` | `bash`, `file_read`, `file_write`, `file_edit`, `web_search`, `recall`, `notify_parent` | Code changes, file editing, running commands, build/test tasks |
+| `planner` | `file_read`, `file_list`, `web_search`, `web_fetch`, `recall`, `notify_parent` | Analysis, planning, synthesizing information, reviewing approaches |
+
+All specialized roles (`researcher`, `coder`, `planner`) include `notify_parent` for mid-run communication with the parent.
+
+## Parent Communication
+
+Subagents use `notify_parent` to send messages to the parent conversation while still running. Each notification has an urgency level:
+
+- **`info`** -- Progress updates, minor findings. The parent is informed but does not need to act.
+- **`important`** -- Key findings, significant results. The parent should review when convenient.
+- **`blocked`** -- The subagent needs guidance or a decision from the parent to continue.
+
+Use notifications judiciously -- one per major finding or milestone. Do not send a notification for every small step.
+
+## Naming
+
+Subagents can be referenced by label instead of UUID. The `label` parameter is accepted on `subagent_message`, `subagent_status`, `subagent_read`, and `subagent_abort` as an alternative to `subagent_id`. Label lookup is case-insensitive.
+
+Use descriptive labels when spawning subagents (e.g., "research-auth-libraries", "implement-login-form") so they are easy to reference later.
+
+## Reading Output
+
+`subagent_read` returns the subagent's assistant text output. Use the `last_n` parameter to retrieve only the most recent N assistant messages instead of the full history. This is useful for large outputs where you only need the final result.
 
 ## Ownership
 
@@ -29,5 +66,8 @@ Set `send_result_to_user: false` when spawning a subagent whose result is for in
 ## Tips
 
 - Do NOT poll `subagent_status` in a loop. You will be notified automatically when a subagent completes.
+- Use roles to scope tool access and minimize blast radius. Default to the most restrictive role that works.
+- Spawn a `researcher` and `coder` in parallel for research-then-implement workflows -- the researcher gathers context while the coder starts on the known parts.
+- Use `notify_parent` for interim findings instead of waiting for completion. This lets the parent act on partial results early.
 - Use `subagent_message` to send follow-up instructions to a running subagent.
 - Use `subagent_abort` to cancel a subagent that is no longer needed.

package/src/config/bundled-skills/subagent/TOOLS.json

@@ -25,6 +25,11 @@
             "type": "boolean",
             "description": "Whether to present the subagent's result to the user when it completes. Defaults to true. Set to false for internal/silent processing."
           },
+          "role": {
+            "type": "string",
+            "enum": ["general", "researcher", "coder", "planner"],
+            "description": "Agent specialization that controls tool access. 'researcher': read-only (web, files, memory). 'coder': file and bash access. 'planner': read-only analysis. 'general': full access (default)."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -47,6 +52,10 @@
             "type": "string",
             "description": "Optional subagent ID to query. If omitted, returns all subagents for this conversation."
           },
+          "label": {
+            "type": "string",
+            "description": "The label of the subagent (alternative to subagent_id). Case-insensitive."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
@@ -59,7 +68,7 @@
     },
     {
       "name": "subagent_abort",
-      "description": "Abort a running subagent by ID.",
+      "description": "Abort a running subagent by ID or label.",
       "category": "orchestration",
       "risk": "low",
       "input_schema": {
@@ -69,12 +78,16 @@
             "type": "string",
             "description": "The ID of the subagent to abort."
           },
+          "label": {
+            "type": "string",
+            "description": "The label of the subagent (alternative to subagent_id). Case-insensitive."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
-        "required": ["subagent_id"]
+        "required": []
       },
       "executor": "tools/subagent-abort.ts",
       "execution_target": "host"
@@ -91,6 +104,10 @@
             "type": "string",
             "description": "The ID of the subagent to send a message to."
           },
+          "label": {
+            "type": "string",
+            "description": "The label of the subagent (alternative to subagent_id). Case-insensitive."
+          },
           "content": {
             "type": "string",
             "description": "The message content to send to the subagent."
@@ -100,7 +117,7 @@
             "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
-        "required": ["subagent_id", "content"]
+        "required": ["content"]
       },
       "executor": "tools/subagent-message.ts",
       "execution_target": "host"
@@ -117,12 +134,20 @@
             "type": "string",
             "description": "The ID of the subagent whose output to read."
           },
+          "label": {
+            "type": "string",
+            "description": "The label of the subagent (alternative to subagent_id). Case-insensitive."
+          },
+          "last_n": {
+            "type": "integer",
+            "description": "Number of recent assistant messages to return. Omit to return all messages (current behavior)."
+          },
           "activity": {
             "type": "string",
             "description": "Brief non-technical explanation of why this tool is being called"
           }
         },
-        "required": ["subagent_id"]
+        "required": []
       },
       "executor": "tools/subagent-read.ts",
       "execution_target": "host"