@letta-ai/letta-code 0.27.5 → 0.27.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.27.5",
+  "version": "0.27.6",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "packageManager": "bun@1.3.0",

package/skills/creating-extensions/SKILL.md

@@ -26,6 +26,7 @@ Capabilities vary by surface. TUI/headless may load tools, commands, events, UI,
 | 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) |
 | Change the bottom statusline appearance | Use `customizing-statusline`, not this skill |
 
@@ -40,8 +41,9 @@ Default to a **tool** when the model should decide when to use the capability. D
    - commands: `references/commands.md`
    - local custom providers: `references/providers.md`
    - events: `references/events.md`
+   - permissions: `references/permissions.md`
    - panels/status/capabilities: `references/ui.md`
-   - busy side-question pattern: `references/btw-command.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.
 6. Return disposers for registered providers/commands/tools/events, timers, subscriptions, and panels that should close on reload.
@@ -76,6 +78,7 @@ letta.capabilities.commands
 letta.capabilities.events.lifecycle
 letta.capabilities.events.tools
 letta.capabilities.events.turns
+letta.capabilities.permissions
 letta.capabilities.providers
 letta.capabilities.ui.panels
 letta.capabilities.ui.statusValues
@@ -140,6 +143,7 @@ Before finishing, verify:
 | `references/commands.md` | The human should invoke `/foo` |
 | `references/providers.md` | Adding a custom model/API provider for local agents |
 | `references/events.md` | Reacting to lifecycle/tool/turn events or transforming turns/tools |
+| `references/permissions.md` | Enforcing dynamic tool allow/ask/deny policy before approval/execution |
 | `references/ui.md` | Panels, status values, or statusline capability guards are involved |
-| `references/btw-command.md` | Building a busy-safe side-question command with a forked conversation |
+| `references/plan-mode.md` | Recreating plan mode with commands, tools, events, permissions, and local state |
 | `references/architecture.md` | Multiple capabilities, local state, cleanup, background model work, or non-trivial composition |

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

@@ -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 complete side-question example, see `btw-command.md`.
+For a worked multi-capability extension that combines commands, tools, events, permissions, and local state, see `plan-mode.md`.

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

@@ -6,7 +6,7 @@ Use events when trusted local code should react to app/session changes or transf
 
 - Capabilities
 - Supported events
-- Tool argument transforms and denial
+- Tool argument transforms
 - Turn input transforms
 - Event handler context
 - Conversation status example
@@ -44,7 +44,7 @@ letta.events.on("event_name", (event, ctx) => {
 });
 ```
 
-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.
+Tool events use this same API. Use `letta.permissions.register` for allow/ask/deny policy; use `tool_start` for last-mile argument transforms and lifecycle reactions.
 
 ```ts
 letta.events.on("tool_start", (event, ctx) => {
@@ -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.
+`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.
 
 Handlers can inspect `event.args`, mutate it directly, or return replacement args:
 
@@ -138,20 +138,6 @@ Handlers run in registration order. Later handlers see the current args after ea
 
 `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.
 
-### Denying tool execution
-
-Handlers can deny a tool by returning `{ deny: true, reason?: "..." }`. All handlers still run (for side effects like logging or state updates), but if any handler denies, the tool is blocked. The first denial reason is shown to the model as the tool error message.
-
-```ts
-letta.events.on("tool_start", (event) => {
-  if (event.toolName === "Bash" && String(event.args.command).includes("rm -rf")) {
-    return { deny: true, reason: "Destructive command blocked." };
-  }
-});
-```
-
-Denial runs before `PreToolUse` hooks. If an extension denies a tool, hooks are not invoked for that tool call.
-
 `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:

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

@@ -0,0 +1,90 @@
+# Extension 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.
+
+## Capability
+
+```ts
+letta.capabilities.permissions
+```
+
+Guard registrations when writing portable extensions:
+
+```ts
+export default function activate(letta) {
+  if (!letta.capabilities.permissions) return;
+
+  return letta.permissions.register({
+    id: "plan-mode",
+    description: "Allow read-only tools and writes only to the active plan file.",
+    check(event) {
+      if (!isPlanModeActive(event.conversationId)) return;
+
+      if (isReadOnlyTool(event.toolName, event.args)) {
+        return { decision: "allow" };
+      }
+
+      if (isActivePlanFileWrite(event.toolName, event.args)) {
+        return { decision: "allow", reason: "active plan file" };
+      }
+
+      return {
+        decision: "deny",
+        reason: "Plan mode is active. You can only read files or update the plan file.",
+      };
+    },
+  });
+}
+```
+
+## Event shape
+
+```ts
+{
+  agentId: string | null;
+  conversationId: string | null;
+  toolCallId: string | null;
+  toolName: string;
+  args: Record<string, unknown>;
+  cwd: string;
+  workingDirectory: string;
+  permissionMode: string | null;
+  phase: "approval" | "execution";
+}
+```
+
+## Return values
+
+Return one of:
+
+```ts
+{ decision: "allow", reason?: string }
+{ decision: "ask", reason?: string }
+{ decision: "deny", reason?: string }
+undefined // no opinion
+```
+
+Composition rules across overlays:
+
+- `deny` wins
+- then `ask`
+- 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.
+
+## Two phases
+
+Permission overlays run during approval classification (`phase: "approval"`) and again immediately before execution (`phase: "execution"`) after any `tool_start` argument transforms.
+
+During execution, `ask` cannot reopen approval yet, so use `deny` for execution-time blocking behavior.
+
+## Rules
+
+- Keep checks fast and deterministic.
+- Return `undefined` when the overlay is not active for the current conversation/state.
+- Prefer path-scoped allow rules over broad allow rules.
+- Do not mutate `event.args`; use `tool_start` for argument transforms.
+- For policy decisions, prefer this API over `tool_start` denial.
+
+For a complete worked example that uses permission overlays for plan-mode enforcement, see `plan-mode.md`.

package/skills/creating-extensions/references/plan-mode.md

@@ -0,0 +1,285 @@
+# Plan mode extension 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.
+
+This is a pattern reference, not a full product implementation. Keep local extensions self-contained and avoid importing Letta Code internals.
+
+## Contents
+
+- Flow
+- Capabilities used
+- State
+- Entry command and tool
+- Turn reminder
+- Permission overlay
+- Exit tool
+- Notes
+
+## Flow
+
+```text
+/plan or enter_plan_mode
+-> create ~/.letta/plans/<random>.md
+-> remember active plan state for this conversation
+-> 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
+-> 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.
+
+## Capabilities used
+
+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
+
+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:
+
+```ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+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 GLOBAL_CONVERSATION_ID = "__global__";
+
+type PlanSession = {
+  conversationId: string;
+  planFilePath: string;
+  startedAt: number;
+  cwd: string;
+};
+
+type PlanState = { sessions: Record<string, PlanSession> };
+
+function conversationKey(id: string | null | undefined): string {
+  return id || GLOBAL_CONVERSATION_ID;
+}
+
+function readState(): PlanState {
+  try {
+    if (!existsSync(STATE_PATH)) return { sessions: {} };
+    const parsed = JSON.parse(readFileSync(STATE_PATH, "utf8"));
+    return parsed?.sessions ? { sessions: parsed.sessions } : { sessions: {} };
+  } catch {
+    return { sessions: {} };
+  }
+}
+
+function writeState(state: PlanState): void {
+  mkdirSync(join(homedir(), ".letta", "extensions"), { recursive: true });
+  writeFileSync(STATE_PATH, JSON.stringify(state, null, 2));
+}
+```
+
+Generate plan paths under `~/.letta/plans/`. The old built-in used random adjective/adjective/noun names like `zesty-dazzling-coral.md`; any collision-resistant readable name is fine.
+
+## Entry command and tool
+
+`/plan` and `enter_plan_mode` should call the same activation helper. The command returns a prompt/system reminder so the agent receives the path. The tool returns the same text as a tool result.
+
+```ts
+function buildEnterPlanModeMessage(session, cwd) {
+  const relativePatchPath = relative(cwd, session.planFilePath).replace(/\\/g, "/");
+  return `Entered plan mode. You should now focus on exploring the codebase and designing an implementation approach.
+
+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
+
+Remember: DO NOT write or edit any files except the plan file. This is a read-only exploration and planning phase.
+
+Plan file path: ${session.planFilePath}
+If using apply_patch, use this exact relative patch path: ${relativePatchPath}`;
+}
+
+export default function activate(letta) {
+  const disposers = [];
+
+  if (letta.capabilities.commands) {
+    disposers.push(letta.commands.register({
+      id: "plan",
+      description: "Enter plan mode",
+      override: true,
+      run(ctx) {
+        const session = activatePlanMode(ctx.conversation.id, ctx.cwd);
+        return {
+          type: "prompt",
+          systemReminder: true,
+          content: buildEnterPlanModeMessage(session, ctx.cwd),
+        };
+      },
+    }));
+  }
+
+  if (letta.capabilities.tools) {
+    disposers.push(letta.tools.register({
+      name: "enter_plan_mode",
+      description:
+        "Enter plan mode before a non-trivial implementation task. Use this for new features, multi-file changes, architectural decisions, unclear requirements, or tasks where the user should approve the approach before implementation.",
+      parameters: { type: "object", properties: {}, additionalProperties: false },
+      requiresApproval: true,
+      parallelSafe: false,
+      run(ctx) {
+        const session = activatePlanMode(ctx.conversation.id, ctx.cwd);
+        return buildEnterPlanModeMessage(session, ctx.cwd);
+      },
+    }));
+  }
+
+  return () => disposers.reverse().forEach((dispose) => dispose());
+}
+```
+
+## Turn reminder
+
+Append a reminder while plan mode is active. Keep it narrow and explicit about the allowed plan-file exception:
+
+```ts
+function buildActiveReminder(session, cwd) {
+  const relativePatchPath = relative(cwd, session.planFilePath).replace(/\\/g, "/");
+  return `<system-reminder>
+Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supersedes any other instructions you have received. Instead, you should:
+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.
+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>`;
+}
+
+if (letta.capabilities.events.turns) {
+  disposers.push(letta.events.on("turn_start", (event) => {
+    const session = getSession(event.conversationId);
+    if (!session) return;
+    return { input: [{ role: "user", content: buildActiveReminder(session, session.cwd) }, ...event.input] };
+  }));
+}
+```
+
+## 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.).
+
+```ts
+const readOnlyToolNames = new Set([
+  "askuserquestion",
+  "ask_user_question",
+  "glob",
+  "grep",
+  "listdir",
+  "list_directory",
+  "ls",
+  "read",
+  "read_file",
+  "readfile",
+  "search",
+  "search_file_content",
+  "skill",
+  "taskoutput",
+  "update_plan",
+  "view_image",
+]);
+
+function normalizedToolName(toolName) {
+  return toolName.replace(/[\s-]/g, "").toLowerCase();
+}
+
+function isReadOnlyToolName(toolName) {
+  const raw = toolName.toLowerCase();
+  return readOnlyToolNames.has(raw) || readOnlyToolNames.has(normalizedToolName(toolName));
+}
+
+function isPlanFileWrite(toolName, args, cwd) {
+  // For Write/Edit-style tools, check file_path/path/notebook_path.
+  // For ApplyPatch-style tools, parse *** Add/Update/Delete File and *** Move to directives.
+  // Allow only if every target resolves to a .md file under ~/.letta/plans/.
+}
+
+if (letta.capabilities.permissions) {
+  disposers.push(letta.permissions.register({
+    id: "plan-mode",
+    description: "Allow read-only tools and writes only to ~/.letta/plans/*.md while plan mode is active.",
+    check(event) {
+      const session = getSession(event.conversationId);
+      if (!session) return;
+
+      if (isReadOnlyToolName(event.toolName)) return { decision: "allow" };
+      if (isPlanFileWrite(event.toolName, event.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. ` +
+          `Write your plan to: ${session.planFilePath}. ` +
+          `Use AskUserQuestion when your plan is ready for user approval, then call exit_plan_mode after approval.`,
+      };
+    },
+  }));
+}
+```
+
+Shell allowlists are easy to get wrong. Start conservative: allow clearly read-only shell commands if needed, plus a narrow plan-file heredoc or `mv old.md new.md` only when every target is inside `~/.letta/plans/*.md`. Deny mutating shell patterns such as `sed -i`, `find -delete`, `rm`, `cp`, `touch`, package installs, and arbitrary interpreters.
+
+## 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.
+
+```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.",
+    parameters: { type: "object", properties: {}, additionalProperties: false },
+    requiresApproval: false,
+    parallelSafe: false,
+    run(ctx) {
+      const session = getSession(ctx.conversation.id);
+      if (!session) {
+        return { status: "error", content: "Plan mode is not active for this conversation." };
+      }
+      if (!planFileExists(session)) {
+        return {
+          status: "error",
+          content:
+            `You must write your plan to a plan file before exiting plan mode.\n` +
+            `Plan file path: ${session.planFilePath}\n` +
+            `Use a write tool to create your plan in ${PLANS_DIR}, then use AskUserQuestion to present the plan to the user.`,
+        };
+      }
+
+      clearSession(ctx.conversation.id);
+      return (
+        "User has approved your plan. You can now start coding.\n" +
+        "Start with updating your todo list if applicable.\n\n" +
+        "Tip: If this plan will be referenced in the future by your future-self, other agents, or humans, consider renaming the plan file to something easily identifiable with a timestamp (e.g., `2026-01-auth-refactor.md`) rather than the random name."
+      );
+    },
+  }));
+}
+```
+
+## 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.
+- 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.