@letta-ai/letta-code 0.27.8 → 0.27.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.27.8",
+  "version": "0.27.9",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.0",
@@ -14,11 +14,20 @@
     "scripts",
     "skills",
     "vendor",
+    "dist/app-server-client.js",
+    "dist/app-server-client.js.map",
     "dist/types",
     "docs"
   ],
   "exports": {
     ".": "./letta.js",
+    "./app-server-protocol": {
+      "types": "./dist/types/app-server-protocol.d.ts"
+    },
+    "./app-server-client": {
+      "types": "./dist/types/app-server-client.d.ts",
+      "import": "./dist/app-server-client.js"
+    },
     "./protocol": {
       "types": "./dist/types/protocol.d.ts"
     }
@@ -35,8 +44,8 @@
     "access": "public"
   },
   "dependencies": {
+    "@earendil-works/pi-ai": "^0.79.1",
     "@letta-ai/letta-client": "^1.10.2",
-    "@earendil-works/pi-ai": "^0.78.1",
     "@pierre/diffs": "1.2.2",
     "glob": "^13.0.0",
     "ink-link": "^5.0.0",

package/scripts/check-test-coverage.cjs

@@ -73,9 +73,9 @@ const ciDirs = [
   "src/cli",
   "src/cron",
   "src/experiments",
-  "src/extensions",
   "src/hooks",
   "src/lsp",
+  "src/mods",
   "src/permissions",
   "src/providers",
   "src/queue",

package/scripts/run-unit-tests.cjs

@@ -13,9 +13,9 @@ const dirs = [
   "src/cli",
   "src/cron",
   "src/experiments",
-  "src/extensions",
   "src/hooks",
   "src/lsp",
+  "src/mods",
   "src/permissions",
   "src/providers",
   "src/queue",

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
 
@@ -46,7 +46,7 @@ Do not use panels for persistent mode state. Panels are transient UI and can be
 
 ## 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";
@@ -54,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 = {
@@ -81,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));
 }
 ```
@@ -279,7 +279,9 @@ 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 read the plan file, present the full current plan text with `AskUserQuestion`, 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) {
@@ -288,7 +290,7 @@ if (letta.capabilities.tools) {
     description:
       "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);

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.";
+  },
+});
+```

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

@@ -1,8 +1,8 @@
-# Extension UI recipes
+# Mod UI recipes
 
-UI capabilities are optional. Always guard UI work with `letta.capabilities.ui.*` when writing portable extensions.
+UI capabilities are optional. Always guard UI work with `letta.capabilities.ui.*` when writing portable mods.
 
-For UI that belongs to a larger command/event extension, also read `architecture.md` for cleanup and composition patterns.
+For UI that belongs to a larger command/event mod, also read `architecture.md` for cleanup and composition patterns.
 
 ## Capabilities
 
@@ -21,7 +21,7 @@ letta.capabilities.ui.customStatuslineRenderer
 ```ts
 if (letta.capabilities.ui.panels) {
   const panel = letta.ui.openPanel({
-    id: "my-extension",
+    id: "my-mod",
     content: ["Working…"],
     order: 100,
   });

package/skills/customizing-commands/SKILL.md

@@ -1,36 +1,36 @@
 ---
 name: customizing-commands
-description: Creates, edits, and enables Letta Code extension-provided slash commands. Use when the user asks to add a custom /command, slash command, command shortcut, scoped conversation-backed command, or command-driven panel behavior.
+description: Creates, edits, and enables Letta Code mod-provided slash commands. Use when the user asks to add a custom /command, slash command, command shortcut, scoped conversation-backed command, or command-driven panel behavior.
 ---
 
 # Customizing Commands
 
-Use this as the command-specific entrypoint for local extension slash commands. For broader extension work, recipes live in `../creating-extensions/references/commands.md`, `../creating-extensions/references/architecture.md`, `../creating-extensions/references/ui.md`, and `../creating-extensions/references/plan-mode.md`.
+Use this as the command-specific entrypoint for local mod slash commands. For broader mod work, recipes live in `../creating-mods/references/commands.md`, `../creating-mods/references/architecture.md`, `../creating-mods/references/ui.md`, and `../creating-mods/references/plan-mode.md`.
 
-Extension files live in:
+Mod files live in:
 
 ```text
-~/.letta/extensions/
+~/.letta/mods/
 ```
 
-Use a focused file name, e.g. `~/.letta/extensions/review.ts` or `~/.letta/extensions/commands.ts`.
+Use a focused file name, e.g. `~/.letta/mods/review.ts` or `~/.letta/mods/commands.ts`.
 
 ## First decide whether a command is right
 
 | User wants | Build |
 | --- | --- |
-| `/foo` sends a prompt or shows local output | Extension command |
-| `/foo` starts a reusable agent workflow | Skill + thin extension command |
-| Agent/model should autonomously call the capability | Extension tool, not a command |
-| Command shows transient progress/results | Extension command + panel |
+| `/foo` sends a prompt or shows local output | Mod command |
+| `/foo` starts a reusable agent workflow | Skill + thin mod command |
+| Agent/model should autonomously call the capability | Mod tool, not a command |
+| Command shows transient progress/results | Mod command + panel |
 | Command needs model output while the main agent is busy | `runWhenBusy: true` command + forked `ctx.conversation` |
 
-If the command is a durable workflow like `/goal`, put the workflow instructions in a skill and keep the extension command as a small launcher/prompt.
+If the command is a durable workflow like `/goal`, put the workflow instructions in a skill and keep the mod command as a small launcher/prompt.
 
 ## Workflow
 
-1. Inspect `~/.letta/extensions/` for related command files.
-2. Preserve unrelated extension code; create a focused new file if merging is messy.
+1. Inspect `~/.letta/mods/` for related command files.
+2. Preserve unrelated mod code; create a focused new file if merging is messy.
 3. Register with `letta.commands.register()` and guard with `letta.capabilities.commands`.
 4. Return the unregister function, or a disposer that calls it plus any timer/panel cleanup.
 5. Tell the user the exact file path changed and to run `/reload`.
@@ -62,7 +62,7 @@ export default function activate(letta) {
 ## Command result types
 
 ```ts
-type ExtensionCommandResult =
+type ModCommandResult =
   | { type: "prompt"; content: string; systemReminder?: boolean }
   | { type: "output"; output: string; success?: boolean }
   | { type: "handled" };
@@ -80,11 +80,11 @@ type ExtensionCommandResult =
 - `runWhenBusy: true` commands must not return `prompt` while the main agent is busy; use scoped conversation helpers/panels and return `handled`.
 - `showInTranscript: false` commands should usually return `handled`, not `prompt`.
 - Do not import Letta Code app internals.
-- 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`.
 
 ## More recipes
 
-- Simple output command, panel command, busy-safe conversation command: `../creating-extensions/references/commands.md`
-- Complex command architecture, state, cleanup: `../creating-extensions/references/architecture.md`
-- Panel/status UI patterns: `../creating-extensions/references/ui.md`
-- Worked plan-mode command/tool composition: `../creating-extensions/references/plan-mode.md`
+- Simple output command, panel command, busy-safe conversation command: `../creating-mods/references/commands.md`
+- Complex command architecture, state, cleanup: `../creating-mods/references/architecture.md`
+- Panel/status UI patterns: `../creating-mods/references/ui.md`
+- Worked plan-mode command/tool composition: `../creating-mods/references/plan-mode.md`