@letta-ai/letta-code 0.27.7 → 0.27.9

package/skills/{creating-extensions → creating-mods}/SKILL.md

@@ -1,42 +1,42 @@
 ---
-name: creating-extensions
-description: Creates and edits trusted local Letta Code extensions, including tools, slash commands, local-only model providers, lifecycle/turn events, scoped conversation helpers, panels, status values, and capability-gated behavior. Use when asked to make an extension, add an agent-callable tool, add a slash command, add a local provider/model adapter, transform turns, react to app events, or add lightweight extension UI outside the dedicated /statusline flow.
+name: creating-mods
+description: Creates and edits trusted local Letta Code mods, including tools, slash commands, local-only model providers, lifecycle/turn events, scoped conversation helpers, panels, status values, and capability-gated behavior. Use when asked to make a mod, add an agent-callable tool, add a slash command, add a local provider/model adapter, transform turns, react to app events, or add lightweight mod UI outside the dedicated /statusline flow.
 ---
 
-# Creating Extensions
+# Creating Mods
 
-Use this skill to create or update trusted global Letta Code extensions in:
+Use this skill to create or update trusted global Letta Code mods in:
 
 ```text
-~/.letta/extensions/
+~/.letta/mods/
 ```
 
-Extensions are trusted local apps for Letta Code. They add small composable capabilities through extension APIs, not by importing app internals. Prefer scoped handles (`ctx.conversation`, `ctx.cwd`, `ctx.agent`, `letta.getContext()`) and guard optional UI with `letta.capabilities`.
+Mods are trusted local code for Letta Code. They add small composable capabilities through mod APIs, not by importing app internals. Prefer scoped handles (`ctx.conversation`, `ctx.cwd`, `ctx.agent`, `letta.getContext()`) and guard optional UI with `letta.capabilities`.
 
-Capabilities vary by surface. TUI/headless may load tools, commands, events, UI, and providers; the desktop listener loads provider-only extensions for local provider discovery. Always guard optional capabilities.
+Capabilities vary by surface. TUI/headless may load tools, commands, events, UI, and providers; the desktop listener loads provider-only mods for local provider discovery. Always guard optional capabilities.
 
 ## Choose the right capability
 
 | User wants | Build |
 | --- | --- |
-| Agent/model should autonomously call a local capability | Extension tool |
-| User wants `/foo` to send a prompt or run local UI logic | Extension command |
-| Slash command represents a reusable agent workflow | Skill + thin extension command |
+| Agent/model should autonomously call a local capability | Mod tool |
+| User wants `/foo` to send a prompt or run local UI logic | Mod command |
+| Slash command represents a reusable agent workflow | Skill + thin mod command |
 | Command should work while the main agent is busy | Command with `runWhenBusy: true`, `handled`, panel/status, and usually `ctx.conversation.fork()` |
 | Show transient output above input | Panel, usually from a command |
 | Show small persistent state | Status value |
 | React to app/session lifecycle or transform outbound turns | Event |
 | Enforce dynamic allow/ask/deny policy for tool calls | Permission overlay |
-| Add a custom model/API provider for local agents | Provider extension (local agents only) |
+| Add a custom model/API provider for local agents | Provider mod (local agents only) |
 | Change the bottom statusline appearance | Use `customizing-statusline`, not this skill |
 
 Default to a **tool** when the model should decide when to use the capability. Default to a **command** when the human explicitly invokes it. Compose capabilities when the UX needs it, e.g. command + panel + scoped conversation fork.
 
 ## Workflow
 
-1. Inspect `~/.letta/extensions/` for related files.
-2. Preserve unrelated extension code. Prefer a focused new file if merging would be messy.
-3. Choose the extension shape and load only the needed recipe:
+1. Inspect `~/.letta/mods/` for related files.
+2. Preserve unrelated mod code. Prefer a focused new file if merging would be messy.
+3. Choose the mod shape and load only the needed recipe:
    - tools: `references/tools.md`
    - commands: `references/commands.md`
    - local custom providers: `references/providers.md`
@@ -44,13 +44,13 @@ Default to a **tool** when the model should decide when to use the capability. D
    - permissions: `references/permissions.md`
    - panels/status/capabilities: `references/ui.md`
    - complex plan-mode composition: `references/plan-mode.md`
-4. For multi-capability or stateful extensions, also read `references/architecture.md`.
-5. Write a single-file extension unless the user asks for something larger.
+4. For multi-capability or stateful mods, also read `references/architecture.md`.
+5. Write a single-file mod unless the user asks for something larger.
 6. Return disposers for registered providers/commands/tools/events, timers, subscriptions, and panels that should close on reload.
 7. Do a basic review: valid names, descriptions present, schemas are object schemas, optional capabilities guarded, scoped APIs used, cleanup returned.
-8. Tell the user the absolute file path changed and to run `/reload`. If an extension breaks startup or command handling, recover with `letta --no-extensions` or `LETTA_DISABLE_EXTENSIONS=1 letta`.
+8. Tell the user the absolute file path changed and to run `/reload`. If a mod breaks startup or command handling, recover with `letta --no-mods` or `LETTA_DISABLE_MODS=1 letta`.
 
-## Core extension shape
+## Core mod shape
 
 ```ts
 export default function activate(letta) {
@@ -93,25 +93,25 @@ letta.capabilities.ui.customStatuslineRenderer
   - `forked.sendMessageStream([...])` to stream from a fork
 - In tools, use `ctx.conversation.getHistory()` when the tool needs recent context.
 - Use `letta.client` only for server-specific Letta API calls; do not use it as a substitute for scoped conversation helpers.
-- Do not import `@/backend`, `@/cli`, or other Letta Code internals from extension files.
+- Do not import `@/backend`, `@/cli`, or other Letta Code internals from mod files.
 
 ## Diagnostics
 
-Use `letta.diagnostics.report({ message, severity })` sparingly as a debug utility for extension setup/runtime problems an agent should inspect, such as missing required environment variables or failed local configuration. Default severity is `"error"`; use `severity: "warning"` only for optional/degraded behavior. Keep messages short and actionable, and do not dump routine logs or large state.
+Use `letta.diagnostics.report({ message, severity })` sparingly as a debug utility for mod setup/runtime problems an agent should inspect, such as missing required environment variables or failed local configuration. Default severity is `"error"`; use `severity: "warning"` only for optional/degraded behavior. Keep messages short and actionable, and do not dump routine logs or large state.
 
-Agents can inspect local extension diagnostics at:
+Agents can inspect local mod diagnostics at:
 
 ```text
-~/.letta/extensions/diagnostics/latest.json
+~/.letta/mods/diagnostics/latest.json
 ```
 
 ## Rules
 
-- Global trusted code only for now. Do not create project extensions.
-- Custom provider extensions are local-backend/local-agent only. They do not add providers for Constellation/cloud agents.
-- Provider extensions may run in a provider-only listener context; keep provider registration independent from commands/tools/UI and guard everything else.
+- Global trusted code only for now. Do not create project mods.
+- Custom provider mods are local-backend/local-agent only. They do not add providers for Constellation/cloud agents.
+- Provider mods may run in a provider-only listener context; keep provider registration independent from commands/tools/UI and guard everything else.
 - Do not assume extra npm packages are available.
-- Do not do surprising side effects on startup; extensions activate on app start and `/reload`.
+- Do not do surprising side effects on startup; mods activate on app start and `/reload`.
 - Keep user-facing output short and intentional.
 - Prefer Node/Bun standard APIs (`node:child_process`, `node:fs`, etc.) for local work.
 - For shell execution, prefer `execFile`/`spawn` over shell strings.
@@ -119,16 +119,16 @@ Agents can inspect local extension diagnostics at:
 - For `runWhenBusy: true`, do not return `prompt`; return `handled` and own the UI/background work.
 - Treat `turn_start` as powerful trusted code: keep transforms narrow and unsurprising.
 
-## Pre-flight checklist for complex extensions
+## Pre-flight checklist for complex mods
 
 Before finishing, verify:
 
-- The extension has one clear owner/file and does not mix unrelated features.
+- The mod has one clear owner/file and does not mix unrelated features.
 - Command/tool IDs are valid; command overrides of built-ins are intentional, and tool IDs do not collide with built-ins.
 - Tool descriptions explain when the model should call them.
 - JSON schemas are object schemas with useful descriptions.
 - Optional UI/event/statusline APIs are capability-guarded.
-- Provider extensions are capability-guarded and clearly documented as local-agent only.
+- Provider mods are capability-guarded and clearly documented as local-agent only.
 - Timers, intervals, event registrations, and panels are cleaned up in a disposer.
 - Busy commands return `{ type: "handled" }` quickly and avoid main-conversation sends.
 - Conversation work uses `ctx.conversation` or forked handles, not app internals.

package/skills/{creating-extensions → creating-mods}/references/architecture.md

@@ -1,6 +1,6 @@
-# Extension architecture patterns
+# Mod architecture patterns
 
-Use this reference for non-trivial extensions: multiple capabilities, local state, timers, background model work, or UI.
+Use this reference for non-trivial mods: multiple capabilities, local state, timers, background model work, or UI.
 
 ## Contents
 
@@ -14,14 +14,14 @@ Use this reference for non-trivial extensions: multiple capabilities, local stat
 
 ## Mental model
 
-An extension is trusted local code that registers capabilities during activation and cleans them up on reload/shutdown. Keep the public surface small:
+A mod is trusted local code that registers capabilities during activation and cleans them up on reload/shutdown. Keep the public surface small:
 
 - activation registers commands/tools/events/UI
 - command/tool/event handlers receive scoped context
 - state is local and explicit
 - cleanup is returned from activation
 
-Do not import Letta Code internals. If the extension API does not expose a capability yet, avoid reaching around it.
+Do not import Letta Code internals. If the mod API does not expose a capability yet, avoid reaching around it.
 
 Capabilities vary by host surface. Keep each registration behind the matching `letta.capabilities` guard so one file can run in TUI, headless, and provider-only listener contexts.
 
@@ -92,14 +92,14 @@ if (letta.capabilities.events.lifecycle && letta.capabilities.ui.statusValues) {
 
 ### `turn_start` transform
 
-Use `turn_start` only when the extension needs to inspect or transform the outbound user-message turn. Keep transforms local and predictable. Prefer appending/prepending focused context or replacing explicit shortcuts over broad rewrites.
+Use `turn_start` only when the mod needs to inspect or transform the outbound user-message turn. Keep transforms local and predictable. Prefer appending/prepending focused context or replacing explicit shortcuts over broad rewrites.
 
 ## Local state
 
-For small persistent state, use a clearly named file under `~/.letta/extensions/`, for example:
+For small persistent state, use a clearly named file under `~/.letta/mods/`, for example:
 
 ```text
-~/.letta/extensions/my-extension.state.json
+~/.letta/mods/my-mod.state.json
 ```
 
 Use atomic-ish writes when practical: write the full JSON file from an in-memory object after each change. Validate parsed state and fall back gracefully if the file is missing or malformed.
@@ -108,7 +108,7 @@ Keep state separate from source code. Do not store secrets in plain JSON; use ex
 
 ## Timers and subscriptions
 
-Timers are okay for active-session behavior, but they only run while the extension engine is alive. Always clear them:
+Timers are okay for active-session behavior, but they only run while the mod engine is alive. Always clear them:
 
 ```ts
 const timer = setInterval(update, 30_000);
@@ -147,4 +147,4 @@ Tools currently receive `ctx.conversation.getHistory()` but not fork/send helper
 - `runWhenBusy: true` commands return `handled`, not `prompt`.
 - Background model work uses a forked conversation.
 - Local filesystem and shell work uses scoped paths and `execFile`/`spawn`.
-- Extension output is concise and actionable.
+- Mod output is concise and actionable.

package/skills/{creating-extensions → creating-mods}/references/commands.md

@@ -1,8 +1,8 @@
-# Extension command recipes
+# Mod command recipes
 
 Use commands when the human explicitly invokes `/foo`.
 
-For complex command-driven extensions with panels, timers, local state, or background model work, also read `architecture.md`.
+For complex command-driven mods with panels, timers, local state, or background model work, also read `architecture.md`.
 
 ## Contents
 
@@ -17,10 +17,10 @@ For complex command-driven extensions with panels, timers, local state, or backg
 
 | Need | Use |
 | --- | --- |
-| `/foo` expands to a prompt | Extension command |
-| `/foo` starts a complex reusable workflow | Skill + thin extension command |
-| Model should call the capability by itself | Extension tool |
-| Command needs transient UI while doing local work | Extension command + panel |
+| `/foo` expands to a prompt | Mod command |
+| `/foo` starts a complex reusable workflow | Skill + thin mod command |
+| Model should call the capability by itself | Mod tool |
+| Command needs transient UI while doing local work | Mod command + panel |
 | Command needs model output while the main agent is busy | `runWhenBusy: true` command + forked `ctx.conversation` |
 
 If the command represents a durable agent workflow (for example `/goal`), put the workflow instructions in a skill and keep the command as a small launcher/prompt.
@@ -29,8 +29,8 @@ If the command represents a durable agent workflow (for example `/goal`), put th
 
 - Do not include the leading slash. Use `id: "review"`, not `id: "/review"`.
 - Use a lowercase slug with letters, numbers, and hyphens only.
-- Built-in commands like `/reload`, `/model`, `/statusline`, etc. can be overridden by trusted local extensions. Do this intentionally and keep recovery in mind: start with `--no-extensions` or `LETTA_DISABLE_EXTENSIONS=1` if an override breaks command handling.
-- Duplicate extension command IDs fail unless `override: true` is intentional.
+- Built-in commands like `/reload`, `/model`, `/statusline`, etc. can be overridden by trusted local mods. Do this intentionally and keep recovery in mind: start with `--no-mods` or `LETTA_DISABLE_MODS=1` if an override breaks command handling.
+- Duplicate mod command IDs fail unless `override: true` is intentional.
 
 ## Prompt command
 
@@ -68,7 +68,7 @@ export default function activate(letta) {
 
   return letta.commands.register({
     id: "whereami",
-    description: "Show the active extension command context",
+    description: "Show the active mod command context",
     run(ctx) {
       return {
         type: "output",
@@ -125,4 +125,4 @@ const stream = await forked.sendMessageStream([
 
 Do not send directly to the active conversation from a busy command; fork first unless the user explicitly asked to affect the main conversation later.
 
-For a worked multi-capability extension that combines commands, tools, events, permissions, and local state, see `plan-mode.md`.
+For a worked multi-capability mod that combines commands, tools, events, permissions, and local state, see `plan-mode.md`.

package/skills/{creating-extensions → creating-mods}/references/events.md

@@ -1,6 +1,6 @@
-# Extension event recipes
+# Mod event recipes
 
-Use events when trusted local code should react to app/session changes or transform outbound turns without the human explicitly invoking a command. For event-driven extensions with state, timers, panels, or background model work, also read `architecture.md`.
+Use events when trusted local code should react to app/session changes or transform outbound turns without the human explicitly invoking a command. For event-driven mods with state, timers, panels, or background model work, also read `architecture.md`.
 
 ## Contents
 
@@ -12,7 +12,7 @@ Use events when trusted local code should react to app/session changes or transf
 - Conversation status example
 - Rules
 
-This is the first slice of the hooks-v2 direction. The long-term goal is for typed extension events to replace settings-based hooks. Existing hooks still own blocking decisions and model feedback injection until each event has a typed return contract.
+This is the first slice of the hooks-v2 direction. The long-term goal is for typed mod events to replace settings-based hooks. Existing hooks still own blocking decisions and model feedback injection until each event has a typed return contract.
 
 ## Capabilities
 
@@ -22,7 +22,7 @@ letta.capabilities.events.tools
 letta.capabilities.events.turns
 ```
 
-Guard events when writing portable extensions:
+Guard events when writing portable mods:
 
 ```ts
 export default function activate(letta) {
@@ -115,7 +115,7 @@ Lifecycle handlers are notification-only and should not return values. `turn_sta
 }
 ```
 
-`tool_start` fires immediately before a client-side tool executes. This includes built-in tools, extension tools, and external tools executed through the local tool manager. It runs after permission/approval classification and before `PreToolUse` hooks, so trusted local extensions can change the actual executed arguments after the approval UI has already classified the original request. Extension permission overlays are rechecked after `tool_start` on the final args.
+`tool_start` fires immediately before a client-side tool executes. This includes built-in tools, mod tools, and external tools executed through the local tool manager. It runs after permission/approval classification and before `PreToolUse` hooks, so trusted local mods can change the actual executed arguments after the approval UI has already classified the original request. Mod permission overlays are rechecked after `tool_start` on the final args.
 
 Handlers can inspect `event.args`, mutate it directly, or return replacement args:
 
@@ -134,9 +134,9 @@ letta.events.on("tool_start", (event) => {
 });
 ```
 
-Handlers run in registration order. Later handlers see the current args after earlier mutations/returns. If a handler throws, its partial `event.args` mutation is rolled back and the error is recorded as an extension diagnostic.
+Handlers run in registration order. Later handlers see the current args after earlier mutations/returns. If a handler throws, its partial `event.args` mutation is rolled back and the error is recorded as a mod diagnostic.
 
-`tool_start` is intentionally a trusted local extension point: it can rewrite commands, file paths, and other tool inputs before execution. Keep transforms focused and unsurprising.
+`tool_start` is intentionally a trusted local mod point: it can rewrite commands, file paths, and other tool inputs before execution. Keep transforms focused and unsurprising.
 
 `turn_start` fires before outbound turns that include a user message. In the TUI this includes normal submits and prompt-style command turns. In headless it includes one-shot prompts and bidirectional user turns.
 
@@ -166,9 +166,9 @@ letta.events.on("turn_start", (event) => {
 });
 ```
 
-Handlers run in registration order. Later handlers see the current input after earlier mutations/returns. If a handler throws, its partial `event.input` mutation is rolled back and the error is recorded as an extension diagnostic.
+Handlers run in registration order. Later handlers see the current input after earlier mutations/returns. If a handler throws, its partial `event.input` mutation is rolled back and the error is recorded as a mod diagnostic.
 
-`turn_start` is intentionally a trusted local extension point: it can rewrite user messages, approval results, and ordering. Keep transforms focused and unsurprising.
+`turn_start` is intentionally a trusted local mod point: it can rewrite user messages, approval results, and ordering. Keep transforms focused and unsurprising.
 
 Handlers also receive:
 
@@ -221,5 +221,5 @@ export default function activate(letta) {
 
 - Do not block user flow unless the event's typed contract explicitly supports blocking.
 - Do not use lifecycle events for safety decisions yet. Existing hooks still own blocking behavior.
-- Catch expected local errors if the user-facing outcome matters. Uncaught errors are isolated and recorded as extension diagnostics.
+- Catch expected local errors if the user-facing outcome matters. Uncaught errors are isolated and recorded as mod diagnostics.
 - Return disposers from activation for event registrations, timers, subscriptions, and status values.

package/skills/{creating-extensions → creating-mods}/references/permissions.md

@@ -1,4 +1,4 @@
-# Extension permission recipes
+# Mod permission recipes
 
 Use permission overlays when trusted local code should participate in tool approval decisions. Prefer permissions over `tool_start` denial for policy: permissions run before approval UI and again before execution on final tool arguments.
 
@@ -8,7 +8,7 @@ Use permission overlays when trusted local code should participate in tool appro
 letta.capabilities.permissions
 ```
 
-Guard registrations when writing portable extensions:
+Guard registrations when writing portable mods:
 
 ```ts
 export default function activate(letta) {
@@ -71,7 +71,7 @@ Composition rules across overlays:
 - then `allow`
 - `undefined` means no opinion
 
-User/configured hard denials still win before extension overlays. Extension overlays can override normal auto-allow/default approval behavior, including unrestricted/yolo mode.
+User/configured hard denials still win before mod overlays. Mod overlays can override normal auto-allow/default approval behavior, including unrestricted/yolo mode.
 
 ## Two phases
 

package/skills/{creating-extensions → creating-mods}/references/plan-mode.md

@@ -1,8 +1,8 @@
-# Plan mode extension example
+# Plan mode mod example
 
-Use this as the canonical multi-capability extension example. It composes a slash command, model-callable tools, turn reminders, permission overlays, and local state to recreate the old built-in plan-mode flow with extension APIs.
+Use this as the canonical multi-capability mod example. It composes a slash command, model-callable tools, turn reminders, permission overlays, and local state to recreate the old built-in plan-mode flow with mod APIs.
 
-This is a pattern reference, not a full product implementation. Keep local extensions self-contained and avoid importing Letta Code internals.
+This is a pattern reference, not a full product implementation. Keep local mods self-contained and avoid importing Letta Code internals.
 
 ## Contents
 
@@ -24,13 +24,15 @@ This is a pattern reference, not a full product implementation. Keep local exten
 -> remind the agent that only read-only tools and plan-file writes are allowed
 -> permission overlay denies mutations outside ~/.letta/plans/*.md
 -> agent writes the plan with normal Write/Edit/ApplyPatch tools
--> agent reads the plan and calls AskUserQuestion with Approve / Revise
+-> agent reads the plan and calls AskUserQuestion with the full current plan text and Approve / Revise
 -> if approved, agent calls exit_plan_mode
 -> exit_plan_mode clears state and returns the approved-plan execution handoff
 ```
 
 Plan files are normal markdown files. Do not add a special `update_plan_file` tool unless the user explicitly wants that abstraction. Let the agent use normal write tools and constrain those tools with permissions.
 
+Plan approval must show the user the full current plan text. Do not ask "does this look right?" with only a summary. After every revision, read the plan file again and present the full revised plan in the `AskUserQuestion.question` body before exiting plan mode.
+
 ## Capabilities used
 
 Guard each registration with the matching capability:
@@ -38,13 +40,13 @@ Guard each registration with the matching capability:
 - `commands`: `/plan` for explicit human entry
 - `tools`: `enter_plan_mode` and `exit_plan_mode` for model-driven entry/exit
 - `events.turns`: append a focused plan-mode reminder while active
-- `permissions`: block mutating tools except plan-file writes
+- `permissions`: block mutating tools except planning coordination tools and plan-file writes
 
 Do not use panels for persistent mode state. Panels are transient UI and can be noisy/fragile for mode indicators. Do not add a custom statusline renderer just to show plan mode; `setStatuslineRenderer` is a single global renderer, not an additive slot. This example intentionally keeps visible mode state out of scope.
 
 ## State
 
-Use small local state under `~/.letta/extensions/`, keyed by conversation ID:
+Use small local state under `~/.letta/mods/`, keyed by conversation ID:
 
 ```ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
@@ -52,7 +54,7 @@ import { homedir } from "node:os";
 import { join, relative } from "node:path";
 
 const PLANS_DIR = join(homedir(), ".letta", "plans");
-const STATE_PATH = join(homedir(), ".letta", "extensions", "plan-mode.state.json");
+const STATE_PATH = join(homedir(), ".letta", "mods", "plan-mode.state.json");
 const GLOBAL_CONVERSATION_ID = "__global__";
 
 type PlanSession = {
@@ -79,7 +81,7 @@ function readState(): PlanState {
 }
 
 function writeState(state: PlanState): void {
-  mkdirSync(join(homedir(), ".letta", "extensions"), { recursive: true });
+  mkdirSync(join(homedir(), ".letta", "mods"), { recursive: true });
   writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
 }
 ```
@@ -99,9 +101,10 @@ In plan mode, you should:
 1. Thoroughly explore the codebase to understand existing patterns
 2. Identify similar features and architectural approaches
 3. Consider multiple approaches and their trade-offs
-4. Use AskUserQuestion if you need to clarify the approach
-5. Design a concrete implementation strategy
-6. When ready, write the plan to the plan file, use AskUserQuestion to present the full plan for approval, and call exit_plan_mode after the user approves
+4. Use direct read-only tools for exploration. Do not launch coding, general-purpose, or fork subagents in plan mode; they may mutate files and should be denied. Only recall-style subagents are allowed if available.
+5. Use AskUserQuestion if you need to clarify the approach
+6. Design a concrete implementation strategy
+7. When ready, write the plan to the plan file, read the plan file, use AskUserQuestion to present the full current plan text for approval, and call exit_plan_mode after the user approves
 
 Remember: DO NOT write or edit any files except the plan file. This is a read-only exploration and planning phase.
 
@@ -159,8 +162,9 @@ Plan mode is active. The user indicated that they do not want you to execute yet
 1. Answer the user's query comprehensively, using the AskUserQuestion tool if you need to ask the user clarifying questions.
 2. Write your implementation plan to the plan file. Plan file path: ${session.planFilePath}
 3. If using apply_patch, use this exact relative path in patch headers: ${relativePatchPath}
-4. When the plan is complete, read the plan file and present the full plan to the user with AskUserQuestion. The question should offer at least "Approve" and "Revise" options.
-5. If the user approves, call exit_plan_mode immediately. If the user asks to revise, stay in plan mode and update the plan file.
+4. Use direct read-only tools for exploration. Do not launch coding, general-purpose, or fork subagents in plan mode; they may mutate files and should be denied. Only recall-style subagents are allowed if available.
+5. When the plan is complete, read the plan file and present the full current plan text to the user with AskUserQuestion. The question body must include the entire plan, not a summary. The question should offer at least "Approve" and "Revise" options.
+6. If the user approves, call exit_plan_mode immediately. If the user asks to revise, stay in plan mode, update the plan file, then read and present the full revised plan again.
 Do NOT make any file changes outside the plan file or run any tools that modify the system state until the user has approved the plan and you have called exit_plan_mode.
 </system-reminder>`;
 }
@@ -176,35 +180,58 @@ if (letta.capabilities.events.turns) {
 
 ## Permission overlay
 
-Use a permission overlay, not `tool_start`, for policy. Normalize tool names by family; UI display names and provider-specific tool names drift (`Read`, `read`, `read_file`, `ReadFile`, `SearchFileContent`, etc.).
+Use a permission overlay, not `tool_start`, for policy. Normalize tool names by family; UI display names and provider-specific tool names drift (`Read`, `read`, `read_file`, `ReadFile`, `SearchFileContent`, etc.). Keep pure read-only tools separate from planning coordination tools like `AskUserQuestion` and todo/plan updates so the policy stays honest.
 
 ```ts
 const readOnlyToolNames = new Set([
-  "askuserquestion",
-  "ask_user_question",
   "glob",
+  "globgemini",
   "grep",
+  "grepfiles",
+  "list",
   "listdir",
-  "list_directory",
+  "listdirectory",
   "ls",
+  "notebookread",
   "read",
-  "read_file",
   "readfile",
+  "readfilegemini",
+  "readlsp",
+  "readmanyfiles",
   "search",
-  "search_file_content",
+  "searchfilecontent",
+  "searchfiles",
   "skill",
   "taskoutput",
-  "update_plan",
-  "view_image",
+  "viewimage",
 ]);
 
+const planningToolNames = new Set([
+  "askuserquestion",
+  "enterplanmode",
+  "exitplanmode",
+  "todowrite",
+  "updateplan",
+  "writetodos",
+]);
+
+const readOnlySubagentTypes = new Set(["recall"]);
+
 function normalizedToolName(toolName) {
-  return toolName.replace(/[\s-]/g, "").toLowerCase();
+  return toolName.replace(/[^a-z0-9]/gi, "").toLowerCase();
 }
 
 function isReadOnlyToolName(toolName) {
-  const raw = toolName.toLowerCase();
-  return readOnlyToolNames.has(raw) || readOnlyToolNames.has(normalizedToolName(toolName));
+  return readOnlyToolNames.has(normalizedToolName(toolName));
+}
+
+function isPlanningToolName(toolName) {
+  return planningToolNames.has(normalizedToolName(toolName));
+}
+
+function isAllowedReadOnlySubagent(args) {
+  const subagentType = args?.subagent_type;
+  return typeof subagentType === "string" && readOnlySubagentTypes.has(normalizedToolName(subagentType));
 }
 
 function isPlanFileWrite(toolName, args, cwd) {
@@ -220,18 +247,28 @@ if (letta.capabilities.permissions) {
     check(event) {
       const session = getSession(event.conversationId);
       if (!session) return;
+      const toolName = String(event.toolName);
+      const args = event.args ?? {};
+
+      if (isReadOnlyToolName(toolName)) return { decision: "allow" };
+      if (isPlanningToolName(toolName)) return { decision: "allow", reason: "planning" };
 
-      if (isReadOnlyToolName(event.toolName)) return { decision: "allow" };
-      if (isPlanFileWrite(event.toolName, event.args, event.workingDirectory || event.cwd)) {
+      const normalized = normalizedToolName(toolName);
+      if ((normalized === "agent" || normalized === "task") && isAllowedReadOnlySubagent(args)) {
+        return { decision: "allow", reason: "read-only subagent" };
+      }
+
+      if (isPlanFileWrite(toolName, args, event.workingDirectory || event.cwd)) {
         return { decision: "allow", reason: "plan file" };
       }
 
       return {
         decision: "deny",
         reason:
-          `Plan mode is active. You can only use read-only tools (Read, Grep, Glob, etc.) and write to the plan file. ` +
+          `Plan mode is active. Use direct read-only tools (Read, Grep, Glob, List, Search, Skill, TaskOutput, safe read-only Bash), planning tools (AskUserQuestion, TodoWrite/UpdatePlan), or recall-style subagents only. ` +
+          `Do not use coding, general-purpose, or fork subagents in plan mode. ` +
           `Write your plan to: ${session.planFilePath}. ` +
-          `Use AskUserQuestion when your plan is ready for user approval, then call exit_plan_mode after approval.`,
+          `When ready, read the plan file and include the full current plan text in AskUserQuestion for approval, then call exit_plan_mode after approval.`,
       };
     },
   }));
@@ -242,16 +279,18 @@ Shell allowlists are easy to get wrong. Start conservative: allow clearly read-o
 
 ## Exit tool
 
-In the extension version, `exit_plan_mode` is not the approval UI. The agent should present the plan with `AskUserQuestion` first, then call `exit_plan_mode` only after the user approves.
+In the mod version, `exit_plan_mode` is not the approval UI. The agent should read the plan file, present the full current plan text with `AskUserQuestion`, then call `exit_plan_mode` only after the user approves.
+
+Use `approvalPolicy: "alwaysAsk"` so the final state transition still pauses for human confirmation in unrestricted/yolo mode.
 
 ```ts
 if (letta.capabilities.tools) {
   disposers.push(letta.tools.register({
     name: "exit_plan_mode",
     description:
-      "Exit plan mode only after the plan file has been written, the full plan has been presented with AskUserQuestion, and the user has approved it.",
+      "Exit plan mode only after the plan file has been written, the full current plan text has been presented with AskUserQuestion, and the user has approved it.",
     parameters: { type: "object", properties: {}, additionalProperties: false },
-    requiresApproval: false,
+    approvalPolicy: "alwaysAsk",
     parallelSafe: false,
     run(ctx) {
       const session = getSession(ctx.conversation.id);
@@ -282,4 +321,6 @@ if (letta.capabilities.tools) {
 ## Notes
 
 - Keep `exit_plan_mode` as the final state transition and execution handoff. The approved-plan text in its tool return is useful model context.
+- Plan approval must include the full current plan text in `AskUserQuestion.question`, not just a summary or "does this look right?". After revisions, re-read the file and present the full revised plan again.
+- Keep arbitrary coding subagents denied in plan mode unless the runtime has a true read-only child mode. With the current subagent set, allow only recall-style subagents.
 - If the user renames the plan file, exit logic can use the newest non-empty `~/.letta/plans/*.md` modified after plan mode started, or accept an optional plan path. Keep the user-facing flow normal: write plan file, ask approval, then exit.

package/skills/{creating-extensions → creating-mods}/references/providers.md

@@ -1,15 +1,15 @@
-# Extension provider recipes
+# Mod provider recipes
 
-Use provider extensions when the user wants a **local agent** to use a model provider that is not built into `/connect` and `/model`.
+Use provider mods when the user wants a **local agent** to use a model provider that is not built into `/connect` and `/model`.
 
-Important: provider extensions are local-backend/local-agent only. They register local provider metadata for the TUI, headless local runtime, and desktop listener. They do not add providers for Constellation/cloud agents.
+Important: provider mods are local-backend/local-agent only. They register local provider metadata for the TUI, headless local runtime, and desktop listener. They do not add providers for Constellation/cloud agents.
 
-For multi-capability extensions that combine a provider with commands, tools, UI, or state, also read `architecture.md`.
+For multi-capability mods that combine a provider with commands, tools, UI, or state, also read `architecture.md`.
 
 ## Quick pattern
 
 ```ts
-// ~/.letta/extensions/kilo.ts
+// ~/.letta/mods/kilo.ts
 export default function activate(letta) {
   if (!letta.capabilities.providers) return;
 
@@ -48,10 +48,10 @@ After `/reload`, the provider appears in local `/connect` and desktop Connect mo
 
 - Always guard with `letta.capabilities.providers`.
 - Prefer `letta.providers.register(...)` over legacy `letta.registerProvider(...)`.
-- Keep provider registration independent from commands/tools/UI/events and `letta.client`; the desktop listener loads provider-only extensions.
+- Keep provider registration independent from commands/tools/UI/events and `letta.client`; the desktop listener loads provider-only mods.
 - Do not hardcode real secrets. `apiKey: "ENV_VAR"` resolves `process.env.ENV_VAR` when present, or lets `/connect` save a local key.
 - Use stable lowercase provider ids. Model ids must be unprefixed and must not contain `/`.
-- Set `api` at provider or model level. Common values include `"openai-completions"`, `"openai-responses"`, `"anthropic-messages"`, and `"bedrock-converse-stream"`; check `src/backend/dev/pi-provider-extension-types.ts` and pi-ai model types before using uncommon values.
+- Set `api` at provider or model level. Common values include `"openai-completions"`, `"openai-responses"`, `"anthropic-messages"`, and `"bedrock-converse-stream"`; check `src/backend/dev/pi-provider-mod-types.ts` and pi-ai model types before using uncommon values.
 
 ## Model metadata
 

package/skills/{creating-extensions → creating-mods}/references/tools.md

@@ -1,8 +1,8 @@
-# Extension tool recipes
+# Mod tool recipes
 
 Use tools when the agent/model should call a local capability autonomously.
 
-For tools that are part of a larger extension with commands, UI, local state, or events, also read `architecture.md`.
+For tools that are part of a larger mod with commands, UI, local state, or events, also read `architecture.md`.
 
 ## Contents
 
@@ -17,6 +17,7 @@ For tools that are part of a larger extension with commands, UI, local state, or
 - Description: explain when the model should use it.
 - Parameters: JSON Schema object. Use `additionalProperties: false` when possible.
 - `requiresApproval: false` only for read-only, low-risk local introspection.
+- `approvalPolicy: "alwaysAsk"` only for tools that must pause for human approval even in unrestricted/yolo mode.
 - `parallelSafe: true` only for read-only tools with no shared mutation or long-lived exclusive resource.
 - Use `ctx.cwd` / `ctx.workingDirectory` as the workspace.
 - Use `await ctx.conversation.getHistory()` when a tool needs recent conversation context. It returns the most recent messages in chronological order by default.
@@ -124,3 +125,20 @@ letta.tools.register({
   },
 });
 ```
+
+## Always-ask tool
+
+Use `approvalPolicy: "alwaysAsk"` when a tool represents a human gate rather than a risky operation. Deny rules and permission overlays still win, but unrestricted/yolo mode will not auto-approve it.
+
+```ts
+letta.tools.register({
+  name: "exit_plan_mode",
+  description: "Exit plan mode after the user has reviewed and approved the plan.",
+  parameters: { type: "object", properties: {}, additionalProperties: false },
+  approvalPolicy: "alwaysAsk",
+  parallelSafe: false,
+  run(ctx) {
+    return "Plan approved. You can now start coding.";
+  },
+});
+```