@letta-ai/letta-code 0.26.2 → 0.26.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.26.2",
+  "version": "0.26.4",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.0",
@@ -36,6 +36,7 @@
   },
   "dependencies": {
     "@letta-ai/letta-client": "^1.10.2",
+    "@pierre/diffs": "1.2.2",
     "glob": "^13.0.0",
     "ink-link": "^5.0.0",
     "node-pty": "^1.1.0",

package/skills/creating-extensions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: creating-extensions
-description: Creates and edits Letta Code local extensions, including extension tools, slash commands, panels, status values, and capability-gated behavior. Use when the user asks to make an extension, add a tool the agent can call, add a slash command, or add lightweight extension UI outside the dedicated /statusline flow.
+description: Creates and edits trusted local Letta Code extensions, including extension tools, slash commands, lifecycle/turn events, scoped conversation helpers, panels, status values, and capability-gated behavior. Use when the user asks to make an extension, add a tool the agent can call, add a slash command, transform turns, react to app events, or add lightweight extension UI outside the dedicated /statusline flow.
 ---
 
 # Creating Extensions
@@ -11,7 +11,7 @@ Use this skill to create or update trusted global Letta Code extensions in:
 ~/.letta/extensions/
 ```
 
-Extensions are local runtime capabilities, not TUI-only plugins. Prefer portable APIs and guard optional UI with `letta.capabilities`.
+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`.
 
 ## Choose the right capability
 
@@ -20,24 +20,31 @@ Extensions are local runtime capabilities, not TUI-only plugins. Prefer portable
 | 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 |
+| 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 |
 | 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.
+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 one capability recipe:
+3. Choose the extension shape:
+   - simple tool/command/event: read the specific recipe below
+   - multi-capability or stateful extension: also read `references/architecture.md`
+4. Load only the needed recipe:
    - tools: `references/tools.md`
    - commands: `references/commands.md`
+   - events: `references/events.md`
    - panels/status/capabilities: `references/ui.md`
-4. Write a single-file extension unless the user asks for something larger.
-5. Return disposers for registered commands/tools, timers, subscriptions, and panels that should close on reload.
-6. Do a basic syntax/shape review: valid names, descriptions present, JSON schemas are object schemas, capability guards around optional UI.
-7. Tell the user the absolute file path changed and to run `/reload`.
+   - busy side-question pattern: `references/btw-command.md`
+5. Write a single-file extension unless the user asks for something larger.
+6. Return disposers for registered 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`.
 
 ## Core extension shape
 
@@ -64,24 +71,56 @@ Use `letta.capabilities` for optional behavior:
 ```ts
 letta.capabilities.tools
 letta.capabilities.commands
+letta.capabilities.events.lifecycle
+letta.capabilities.events.tools
+letta.capabilities.events.turns
 letta.capabilities.ui.panels
 letta.capabilities.ui.statusValues
 letta.capabilities.ui.customStatuslineRenderer
 ```
 
+## Scoped API model
+
+- In commands and events, use `ctx.conversation` for conversation operations:
+  - `ctx.conversation.getHistory()` for recent messages
+  - `ctx.conversation.fork()` for independent/background model work
+  - `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.
+
 ## Rules
 
 - Global trusted code only for now. Do not create project extensions.
-- Do not import Letta Code app internals from extension files.
 - Do not assume extra npm packages are available.
 - Do not do surprising side effects on startup; extensions 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.
 - Do not use emojis for loading states; use text or spinner-like characters if the user asks for loading UI.
+- 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
+
+Before finishing, verify:
+
+- The extension has one clear owner/file and does not mix unrelated features.
+- Command/tool IDs are valid and 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.
+- 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.
+- Local shell/file work is scoped to `ctx.cwd` / `ctx.workingDirectory` unless intentionally global.
+- Errors shown to the user are short and actionable.
 
 ## References
 
+- `references/architecture.md` - composition, state, cleanup, scoped conversation, and review checklist for complex extensions
 - `references/tools.md` - extension tools the model can call
 - `references/commands.md` - slash commands, command results, and skill-backed commands
+- `references/events.md` - lifecycle and turn event handlers
 - `references/ui.md` - panels, status values, capability guards
+- `references/btw-command.md` - advanced busy-safe side-question command using scoped conversation helpers

package/skills/creating-extensions/references/architecture.md

@@ -0,0 +1,138 @@
+# Extension architecture patterns
+
+Use this reference for non-trivial extensions: multiple capabilities, local state, timers, background model work, or UI.
+
+## 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:
+
+- 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.
+
+## Capability composition patterns
+
+### Tool + command
+
+Use a tool for autonomous model use and a command for explicit human invocation. Keep shared local helper functions inside the same file.
+
+```ts
+function summarizeBranch(cwd) {
+  // local implementation
+}
+
+export default function activate(letta) {
+  const disposers = [];
+
+  if (letta.capabilities.tools) {
+    disposers.push(letta.tools.register({
+      name: "branch_summary",
+      description: "Summarize the current git branch when repository state matters.",
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      requiresApproval: false,
+      async run(ctx) {
+        return summarizeBranch(ctx.cwd);
+      },
+    }));
+  }
+
+  if (letta.capabilities.commands) {
+    disposers.push(letta.commands.register({
+      id: "branch-summary",
+      description: "Show current branch summary",
+      async run(ctx) {
+        return { type: "output", output: await summarizeBranch(ctx.cwd) };
+      },
+    }));
+  }
+
+  return () => disposers.reverse().forEach((dispose) => dispose());
+}
+```
+
+### Command + panel + background conversation
+
+Use this for side questions, long local work, or busy-safe commands. For commands with `runWhenBusy: true`, return `{ type: "handled" }` quickly and update a panel/status asynchronously. If model output is needed while the main agent is busy, fork first:
+
+```ts
+const forked = await ctx.conversation.fork({ hidden: true });
+const stream = await forked.sendMessageStream([
+  { role: "user", content: prompt },
+]);
+```
+
+Do not call `ctx.conversation.sendMessageStream()` on the active conversation from a busy command; direct sends can conflict with the active run.
+
+### Event + status value
+
+Use lifecycle events to maintain small status values such as active conversation state. Guard both event and status capabilities.
+
+```ts
+if (letta.capabilities.events.lifecycle && letta.capabilities.ui.statusValues) {
+  disposers.push(letta.events.on("conversation_open", (event) => {
+    letta.ui.setStatus("conversation", event.reason);
+  }));
+}
+```
+
+### `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.
+
+## Local state
+
+For small persistent state, use a clearly named file under `~/.letta/extensions/`, for example:
+
+```text
+~/.letta/extensions/my-extension.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.
+
+Keep state separate from source code. Do not store secrets in plain JSON; use existing secret/provider mechanisms when credentials are needed.
+
+## Timers and subscriptions
+
+Timers are okay for active-session behavior, but they only run while the extension host is alive. Always clear them:
+
+```ts
+const timer = setInterval(update, 30_000);
+return () => clearInterval(timer);
+```
+
+For long async loops, check `letta.signal.aborted` or `ctx.signal.aborted` and stop quietly.
+
+## Scoped conversation handles
+
+Commands and events receive `ctx.conversation`:
+
+```ts
+ctx.conversation.id                 // string | null
+ctx.conversation.getHistory(opts)   // recent messages
+ctx.conversation.fork(opts)         // returns a scoped handle
+ctx.conversation.sendMessageStream(messages, opts)
+```
+
+A forked handle keeps the same agent/backend defaults and targets the forked conversation. Use forked handles for background model work. Use `getHistory({ limit, order, includeErrors })` when local logic needs conversation context.
+
+Tools currently receive `ctx.conversation.getHistory()` but not fork/send helpers. If a tool needs model-side follow-up, return information for the model to act on instead of starting a hidden run from the tool.
+
+## Error handling
+
+- Catch expected local errors and return short user-facing text.
+- Let unexpected errors throw when diagnostics are better than hiding the failure.
+- For panel workflows, update the panel with a concise error and close it after a delay.
+- For tools, return `{ status: "error", content: "..." }` or throw depending on whether the model can recover.
+
+## Final review checklist
+
+- Capability guards are present for commands/tools/events/UI.
+- Activation does not do heavy work unless the feature needs startup state.
+- All disposers/timers/subscriptions are cleaned up.
+- `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.

package/skills/creating-extensions/references/btw-command.md

@@ -1,11 +1,18 @@
 # `/btw` side-question extension example
 
-This example runs while the main agent is busy because it forks the conversation, uses the SDK directly, renders progress in a panel when panels are available, and returns `{ type: "handled" }` immediately.
+This example runs while the main agent is busy because it forks the scoped conversation, streams a response in the fork, renders progress in a panel when panels are available, and returns `{ type: "handled" }` immediately.
 
 ```ts
 export default function activate(letta) {
   if (!letta.capabilities.commands) return;
 
+  function createOtid() {
+    return (
+      globalThis.crypto?.randomUUID?.() ??
+      `btw-${Date.now()}-${Math.random().toString(16).slice(2)}`
+    );
+  }
+
   function appendAssistantText(chunk, parts) {
     if (chunk.message_type !== "assistant_message") return;
     const content = chunk.content;
@@ -19,6 +26,10 @@ export default function activate(letta) {
           parts.push(String(part.text));
         }
       }
+      return;
+    }
+    if (content && typeof content === "object" && "text" in content) {
+      parts.push(String(content.text));
     }
   }
 
@@ -45,29 +56,34 @@ export default function activate(letta) {
 
       void (async () => {
         try {
-          const forked = await letta.client.conversations.fork(
-            ctx.conversation.id || "default",
-            { agent_id: ctx.agent.id },
-          );
-          const stream = await letta.client.conversations.messages.create(
-            forked.id,
+          const forked = await ctx.conversation.fork({ hidden: true });
+          const stream = await forked.sendMessageStream(
+            [
+              {
+                role: "user",
+                content: `${question}\n\nAnswer briefly in 1-3 short sentences.`,
+                otid: createOtid(),
+              },
+            ],
             {
-              agent_id: ctx.agent.id,
-              input: `${question}
-
-Answer briefly in 1-3 short sentences.`,
-              streaming: true,
+              overrideModel: ctx.model.id ?? undefined,
+              workingDirectory: ctx.cwd,
             },
           );
 
           const parts = [];
           for await (const chunk of stream) {
             appendAssistantText(chunk, parts);
-            panel?.update({ content: [`/btw ${question}`, parts.join("") || "..."] });
+            panel?.update({
+              content: [`/btw ${question}`, parts.join("") || "..."],
+            });
           }
 
           panel?.update({
-            content: [`done /btw ${question}`, parts.join("").trim() || "No response."],
+            content: [
+              `done /btw ${question}`,
+              parts.join("").trim() || "No response.",
+            ],
           });
           if (panel) setTimeout(() => panel.close(), 10_000);
         } catch (error) {

package/skills/creating-extensions/references/commands.md

@@ -2,6 +2,8 @@
 
 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`.
+
 ## Decide command vs skill vs tool
 
 | Need | Use |
@@ -10,6 +12,7 @@ Use commands when the human explicitly invokes `/foo`.
 | `/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 |
+| 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.
 
@@ -22,6 +25,8 @@ If the command represents a durable agent workflow (for example `/goal`), put th
 
 ## Prompt command
 
+Use `prompt` for normal slash shortcuts that should become the next agent turn. Prompt commands are not busy-safe.
+
 ```ts
 export default function activate(letta) {
   if (!letta.capabilities.commands) return;
@@ -46,6 +51,8 @@ export default function activate(letta) {
 
 ## Output-only command
 
+Use `output` for local results that do not need the model.
+
 ```ts
 export default function activate(letta) {
   if (!letta.capabilities.commands) return;
@@ -91,24 +98,22 @@ export default function activate(letta) {
 }
 ```
 
-## Busy-safe SDK command
+## Busy-safe conversation command
 
-For commands with `runWhenBusy: true`, do not return `prompt` while the agent is running. Use the SDK directly, update a panel if available, and return `{ type: "handled" }` quickly.
+For commands with `runWhenBusy: true`, do not return `prompt` while the agent is running. Use the scoped conversation handle directly, update a panel/status if available, and return `{ type: "handled" }` quickly.
 
-Use `letta.client` or `await letta.getClient()` instead of raw `fetch`; SDK initialization is lazy and uses the current backend/auth context.
+Use `ctx.conversation` for conversation operations that should work across local and Constellation backends. The handle is bound to the active conversation and backend for that command invocation, so composed flows like fork-then-send stay on the same backend. Use `letta.client` only for server-specific API calls.
 
-Common calls:
+Common pattern:
 
 ```ts
-await letta.client.conversations.fork(ctx.conversation.id || "default", {
-  agent_id: ctx.agent.id,
-});
-
-await letta.client.conversations.messages.create(conversationId, {
-  agent_id: ctx.agent.id,
-  input,
-  streaming: true,
-});
+const forked = await ctx.conversation.fork({ hidden: true });
+
+const stream = await forked.sendMessageStream([
+  { role: "user", content: input },
+]);
 ```
 
+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 complete side-question example, see `btw-command.md`.

package/skills/creating-extensions/references/events.md

@@ -0,0 +1,215 @@
+# Extension 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`.
+
+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.
+
+## Capabilities
+
+```ts
+letta.capabilities.events.lifecycle
+letta.capabilities.events.tools
+letta.capabilities.events.turns
+```
+
+Guard events when writing portable extensions:
+
+```ts
+export default function activate(letta) {
+  if (!letta.capabilities.events.lifecycle) return;
+
+  return letta.events.on("conversation_open", (event, ctx) => {
+    console.log(`conversation ${event.reason}: ${event.agentName ?? event.agentId}`);
+    console.log(`cwd: ${ctx.context.workspace.currentDir}`);
+  });
+}
+```
+
+The API intentionally follows the Pi-style event shape:
+
+```ts
+letta.events.on("event_name", (event, ctx) => {
+  // event is specific to event_name
+  // ctx contains host context and an AbortSignal
+});
+```
+
+Tool events use this same API. Existing settings-based hooks still own blocking decisions and model feedback injection until those contracts are explicitly added to extension events.
+
+```ts
+letta.events.on("tool_start", (event, ctx) => {
+  if (event.toolName !== "Bash") return;
+  if (String(event.args.command).startsWith("npm test")) {
+    return { args: { ...event.args, command: "bun test" } };
+  }
+});
+```
+
+Lifecycle, turn-start, and tool-start events are wired today.
+
+Lifecycle handlers are notification-only and should not return values. `turn_start` handlers can transform the outbound input for the next model turn. `tool_start` handlers can transform the tool arguments before execution.
+
+## Supported events
+
+```ts
+"conversation_open"
+"conversation_close"
+"tool_start"
+"turn_start"
+```
+
+`conversation_open` event:
+
+```ts
+{
+  agentId: string | null;
+  agentName: string | null;
+  conversationId: string | null;
+  previousConversationId?: string | null;
+  reason: "startup" | "new" | "resume" | "fork";
+}
+```
+
+`conversation_close` event:
+
+```ts
+{
+  agentId: string | null;
+  conversationId: string | null;
+  durationMs: number | null;
+  messageCount: number | null;
+  reason: "quit" | "new" | "resume" | "fork";
+  toolCallCount: number | null;
+}
+```
+
+`turn_start` event:
+
+```ts
+{
+  agentId: string | null;
+  conversationId: string | null;
+  input: Array<MessageCreate | ApprovalCreate>;
+}
+```
+
+`tool_start` event:
+
+```ts
+{
+  agentId: string | null;
+  conversationId: string | null;
+  toolCallId: string | null;
+  toolName: string;
+  args: Record<string, unknown>;
+}
+```
+
+`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.
+
+Handlers can inspect `event.args`, mutate it directly, or return replacement args:
+
+```ts
+letta.events.on("tool_start", (event) => {
+  if (event.toolName !== "Bash") return;
+  event.args = {
+    ...event.args,
+    command: String(event.args.command).replaceAll("npm test", "bun test"),
+  };
+});
+
+letta.events.on("tool_start", (event) => {
+  if (event.toolName !== "Read") return;
+  return { args: { ...event.args, limit: 200 } };
+});
+```
+
+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.
+
+`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. It does not support blocking; use existing hooks for blocking safety decisions.
+
+`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.
+
+Handlers can mutate `event.input` directly or return replacement input:
+
+```ts
+function replaceTextContent(content, from, to) {
+  if (typeof content === "string") return content.replaceAll(from, to);
+  if (!Array.isArray(content)) return content;
+  return content.map((part) =>
+    part?.type === "text" && typeof part.text === "string"
+      ? { ...part, text: part.text.replaceAll(from, to) }
+      : part,
+  );
+}
+
+letta.events.on("turn_start", (event) => {
+  event.input = event.input.map((item) =>
+    item.type !== "approval" && item.role === "user"
+      ? { ...item, content: replaceTextContent(item.content, "??", new Date().toLocaleString()) }
+      : item,
+  );
+});
+
+letta.events.on("turn_start", (event) => {
+  return { input: event.input };
+});
+```
+
+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.
+
+`turn_start` is intentionally a trusted local extension point: it can rewrite user messages, approval results, and ordering. Keep transforms focused and unsurprising.
+
+Handlers also receive:
+
+```ts
+{
+  conversation: {
+    id: string | null;
+    fork(options?): Promise<conversation>;
+    getHistory(options?): Promise<Message[]>;
+    sendMessageStream(messages, options?): Promise<AsyncIterable<chunk>>;
+  };
+  context: letta.getContext();
+  getContext: () => letta.getContext();
+  signal: AbortSignal;
+}
+```
+
+`ctx.conversation` is bound when the event is dispatched. Use it for scoped conversation calls made while handling that event. If an event needs background model work, prefer `ctx.conversation.fork()` and send to the fork. Do not send to the active conversation from `turn_start`; that event is already in the path of sending a turn.
+
+Respect `ctx.signal` for long-running async work. It is aborted on `/reload` and app shutdown.
+
+## Conversation status example
+
+```ts
+export default function activate(letta) {
+  if (!letta.capabilities.events.lifecycle) return;
+
+  const disposers = [];
+
+  disposers.push(
+    letta.events.on("conversation_open", (event) => {
+      letta.ui.setStatus("conversation", event.reason);
+    }),
+  );
+
+  disposers.push(
+    letta.events.on("conversation_close", (event) => {
+      console.log(`conversation ${event.reason}: ${event.durationMs ?? 0}ms`);
+    }),
+  );
+
+  return () => {
+    for (const dispose of disposers.reverse()) dispose();
+    letta.ui.clearStatus("conversation");
+  };
+}
+```
+
+## Rules
+
+- 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.
+- Return disposers from activation for event registrations, timers, subscriptions, and status values.

package/skills/creating-extensions/references/tools.md

@@ -2,6 +2,8 @@
 
 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`.
+
 ## Defaults
 
 - Name: lowercase/underscore tool name, e.g. `branch_summary`.
@@ -10,7 +12,9 @@ Use tools when the agent/model should call a local capability autonomously.
 - `requiresApproval: false` only for read-only, low-risk local introspection.
 - `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.
 - Respect `ctx.signal` for long-running work when practical.
+- Tools should return information for the model to use; they should not start hidden model runs.
 
 ## Read-only shell tool
 

package/skills/creating-extensions/references/ui.md

@@ -2,6 +2,8 @@
 
 UI capabilities are optional. Always guard UI work with `letta.capabilities.ui.*` when writing portable extensions.
 
+For UI that belongs to a larger command/event extension, also read `architecture.md` for cleanup and composition patterns.
+
 ## Capabilities
 
 ```ts
@@ -31,6 +33,8 @@ if (letta.capabilities.ui.panels) {
 
 Panel content is plain text: a string or string array. Keep it short; use command `output` for longer text.
 
+Close panels when they are transient, and close/replace long-lived panels from the activation disposer if reload should remove them.
+
 ## Status values
 
 ```ts
@@ -39,7 +43,7 @@ if (letta.capabilities.ui.statusValues) {
 }
 ```
 
-Clear status values in disposers if they are owned by timers or external state:
+Clear status values in disposers if they are owned by timers, events, or external state:
 
 ```ts
 return () => {