@letta-ai/letta-code 0.27.7 → 0.27.9

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/creating-skills/scripts/validate-skill.ts

@@ -12,7 +12,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { parse as parseYaml } from "yaml";
 
 interface ValidationResult {
   valid: boolean;
@@ -29,6 +28,131 @@ const ALLOWED_PROPERTIES = new Set([
   "allowed-tools",
 ]);
 
+export const MAX_SKILL_NAME_LENGTH = 64;
+
+type BunYamlRuntime = {
+  Bun?: {
+    YAML?: {
+      parse?: (source: string) => unknown;
+    };
+  };
+};
+
+function parseQuotedScalar(value: string): string {
+  if (value.startsWith('"')) {
+    if (!value.endsWith('"') || value.length === 1) {
+      throw new Error("Unterminated double-quoted scalar");
+    }
+    return JSON.parse(value) as string;
+  }
+
+  if (value.startsWith("'")) {
+    if (!value.endsWith("'") || value.length === 1) {
+      throw new Error("Unterminated single-quoted scalar");
+    }
+    return value.slice(1, -1).replace(/''/g, "'");
+  }
+
+  return value;
+}
+
+function parseScalar(value: string): unknown {
+  const trimmed = value.trim();
+  if (!trimmed) return "";
+
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (trimmed === "null" || trimmed === "~") return null;
+
+  if (trimmed.startsWith('"') || trimmed.startsWith("'")) {
+    return parseQuotedScalar(trimmed);
+  }
+
+  // The fallback parser intentionally accepts only the frontmatter subset this
+  // validator needs. Unquoted ": " inside a scalar is the most common YAML
+  // authoring mistake; reject it instead of silently producing a bad value.
+  if (trimmed.includes(": ")) {
+    throw new Error(`Unexpected ':' in unquoted scalar: ${trimmed}`);
+  }
+
+  if (/^-?\d+(?:\.\d+)?$/.test(trimmed)) {
+    return Number(trimmed);
+  }
+
+  return trimmed;
+}
+
+function parseFrontmatterFallback(source: string): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const lines = source.split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line === undefined) continue;
+    const trimmed = line.trim();
+
+    if (!trimmed || trimmed.startsWith("#")) {
+      continue;
+    }
+
+    if (/^\s/.test(line)) {
+      // Nested data belongs to the previous top-level key. The validator only
+      // checks top-level field names plus name/description scalar values.
+      continue;
+    }
+
+    const colonIndex = line.indexOf(":");
+    if (colonIndex <= 0) {
+      throw new Error(`Invalid frontmatter line: ${line}`);
+    }
+
+    const key = line.slice(0, colonIndex).trim();
+    const rawValue = line.slice(colonIndex + 1).trim();
+    if (!key) {
+      throw new Error(`Invalid frontmatter line: ${line}`);
+    }
+
+    if (!rawValue) {
+      result[key] = {};
+      continue;
+    }
+
+    if (rawValue === "|" || rawValue === ">") {
+      const blockLines: string[] = [];
+      for (let j = i + 1; j < lines.length; j++) {
+        const nextLine = lines[j];
+        if (nextLine === undefined) continue;
+        if (nextLine.trim() && !/^\s/.test(nextLine)) {
+          break;
+        }
+        blockLines.push(nextLine.replace(/^\s{2}/, ""));
+        i = j;
+      }
+      result[key] =
+        rawValue === ">" ? blockLines.join(" ").trim() : blockLines.join("\n");
+      continue;
+    }
+
+    result[key] = parseScalar(rawValue);
+  }
+
+  return result;
+}
+
+function parseFrontmatter(source: string): Record<string, unknown> {
+  const bunParse = (globalThis as typeof globalThis & BunYamlRuntime).Bun?.YAML
+    ?.parse;
+  if (bunParse) {
+    const parsed = bunParse(source);
+    if (typeof parsed !== "object" || parsed === null) {
+      throw new Error("Frontmatter must be a YAML dictionary");
+    }
+    return parsed as Record<string, unknown>;
+  }
+
+  return parseFrontmatterFallback(source);
+}
+
 export function validateSkill(skillPath: string): ValidationResult {
   // Check SKILL.md exists
   const skillMdPath = join(skillPath, "SKILL.md");
@@ -55,7 +179,7 @@ export function validateSkill(skillPath: string): ValidationResult {
   // Parse YAML frontmatter
   let frontmatter: Record<string, unknown>;
   try {
-    frontmatter = parseYaml(frontmatterText);
+    frontmatter = parseFrontmatter(frontmatterText);
     if (typeof frontmatter !== "object" || frontmatter === null) {
       return { valid: false, message: "Frontmatter must be a YAML dictionary" };
     }
@@ -112,11 +236,11 @@ export function validateSkill(skillPath: string): ValidationResult {
         message: `Name '${trimmedName}' cannot start/end with hyphen or contain consecutive hyphens`,
       };
     }
-    // Check name length (max 64 characters)
-    if (trimmedName.length > 64) {
+    // Check name length
+    if (trimmedName.length > MAX_SKILL_NAME_LENGTH) {
       return {
         valid: false,
-        message: `Name is too long (${trimmedName.length} characters). Maximum is 64 characters.`,
+        message: `Name is too long (${trimmedName.length} characters). Maximum is ${MAX_SKILL_NAME_LENGTH} characters.`,
       };
     }
 

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`

package/skills/customizing-statusline/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: customizing-statusline
-description: Creates, edits, and migrates Letta Code statusline extensions. Use when handling the /statusline command or continuing work started by /statusline.
+description: Creates, edits, and migrates Letta Code statusline mods. Use when handling the /statusline command or continuing work started by /statusline.
 ---
 
 # Customizing Statusline
 
-Use this skill to create or update the global Letta Code statusline extension:
+Use this skill to create or update the global Letta Code statusline mod:
 
 ```text
-~/.letta/extensions/statusline.tsx
+~/.letta/mods/statusline.tsx
 ```
 
 The statusline is a full-row idle renderer. Host UI can still temporarily preempt it for safety confirmations and transient hints.
@@ -18,7 +18,7 @@ The statusline is a full-row idle renderer. Host UI can still temporarily preemp
 ```text
 safety preemption
 else transient host hint
-else custom statusline extension
+else custom statusline mod
 else built-in default statusline
 ```
 
@@ -26,14 +26,14 @@ A custom statusline owns the whole idle row. Do not preserve legacy left/right s
 
 ## Workflow
 
-1. Check whether `~/.letta/extensions/statusline.tsx` exists.
+1. Check whether `~/.letta/mods/statusline.tsx` exists.
 2. If it exists, read it before editing and preserve unrelated code.
 3. If it does not exist, start from the built-in default template or synthesize a focused starter for the user's request.
 4. If the user asks to migrate, import a `.sh` file, or match a shell prompt, read `references/migration.md`.
 5. If API details or concrete patterns are needed, read `references/api.md` and `references/examples.md`.
-6. If the request combines statusline work with commands, tools, events, panels, or stateful extension behavior, also use `creating-extensions` and its `references/architecture.md`.
+6. If the request combines statusline work with commands, tools, events, panels, or stateful mod behavior, also use `creating-mods` and its `references/architecture.md`.
 7. Guard statusline-specific behavior with `letta.capabilities.ui.customStatuslineRenderer` when writing new files.
-8. Edit `~/.letta/extensions/statusline.tsx`.
+8. Edit `~/.letta/mods/statusline.tsx`.
 9. Summarize the absolute file path changed and tell the user to run `/reload` unless the command can reload automatically.
 
 ## Bare `/statusline` behavior
@@ -52,8 +52,8 @@ Keep this conversational. Do not build a menu UI unless the product command expl
 
 ## Rules
 
-- Global-only for now. Do not create project extensions.
-- Keep the extension single-file for MVP.
+- Global-only for now. Do not create project mods.
+- Keep the mod single-file for MVP.
 - Do not assume extra npm packages are available.
 - Do not use relative multi-file imports yet.
 - Keep renderers synchronous. Do not shell, fetch, or await inside render.
@@ -61,11 +61,11 @@ Keep this conversational. Do not build a menu UI unless the product command expl
 - Use `letta.ui.setStatus` for data and `setStatuslineRenderer` for drawing that data.
 - Guard optional APIs with `letta.capabilities.ui.statusValues` and `letta.capabilities.ui.customStatuslineRenderer` in new files.
 - Return a disposer that clears timers/subscriptions.
-- Preserve existing extension code unless the user asks to reset.
+- Preserve existing mod code unless the user asks to reset.
 - Do not delete legacy command statusline files or settings unless the user explicitly asks.
 
 ## Useful references
 
-- `references/api.md` - extension API, render context, lifecycle rules
+- `references/api.md` - mod API, render context, lifecycle rules
 - `references/examples.md` - common statusline patterns
 - `references/migration.md` - legacy command `.sh` and PS1 migration

package/skills/customizing-statusline/references/api.md

@@ -1,14 +1,14 @@
-# Statusline Extension API
+# Statusline Mod API
 
-Use this reference when creating or editing `~/.letta/extensions/statusline.tsx`.
+Use this reference when creating or editing `~/.letta/mods/statusline.tsx`.
 
 ## Location
 
 ```text
-~/.letta/extensions/statusline.tsx
+~/.letta/mods/statusline.tsx
 ```
 
-This is a trusted, user-owned global extension file. Project extensions are intentionally unsupported for now.
+This is a trusted, user-owned global mod file. Project mods are intentionally unsupported for now.
 
 ## Activation
 
@@ -59,7 +59,7 @@ letta.ui.setStatuslineRenderer((context) => {
 
 ## Async state pattern
 
-Use Node/Bun APIs directly from the trusted extension file. Do not assume helper methods like `letta.shell` exist.
+Use Node/Bun APIs directly from the trusted mod file. Do not assume helper methods like `letta.shell` exist.
 
 ```tsx
 import { execFile } from "node:child_process";
@@ -117,7 +117,7 @@ Common fields:
 
 ```ts
 context.components      // Display components such as Text, Box, Spacer
-context.statuses        // evaluated extension status strings
+context.statuses        // evaluated mod status strings
 context.app.version
 context.workspace.cwd
 context.workspace.currentDir
@@ -159,10 +159,10 @@ return (
 
 ## Reload behavior
 
-After editing `~/.letta/extensions/statusline.tsx`, tell the user to run:
+After editing `~/.letta/mods/statusline.tsx`, tell the user to run:
 
 ```text
 /reload
 ```
 
-The runtime tracks extension loading separately from “no custom statusline,” so a custom statusline should not flash back to the built-in default during reload.
+The runtime tracks mod loading separately from “no custom statusline,” so a custom statusline should not flash back to the built-in default during reload.

package/skills/customizing-statusline/references/examples.md

@@ -1,6 +1,6 @@
 # Statusline Examples
 
-Use these as patterns, not mandatory templates. Keep the final extension focused on the user's request.
+Use these as patterns, not mandatory templates. Keep the final mod focused on the user's request.
 
 ## Agent and model
 

package/skills/customizing-statusline/references/migration.md

@@ -39,7 +39,7 @@ Look for either shape:
 When migrating:
 
 - Preserve old config and referenced files unless the user explicitly asks to delete them.
-- If `command` references a `.sh` file, read it before writing the new extension.
+- If `command` references a `.sh` file, read it before writing the new mod.
 - Translate polling (`refreshIntervalMs`) to `setInterval`.
 - Translate direct command output into cached status plus synchronous rendering.
 - If the command output used `\x1e` to split left/right output, convert it to internal full-row layout with `Box`; do not create a new left/right API.

package/skills/editing-letta-code-desktop-preferences/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: editing-letta-code-desktop-preferences
+description: Edits Letta Code Desktop (LCD) preferences by safely reading and updating ~/.letta/desktop_preferences.json. Use only when the user asks to change current Desktop/LCD settings such as theme, default working directory, remote access preference, or remote environment name via the preferences JSON.
+---
+
+# Editing Letta Code Desktop Preferences
+
+Use this skill only to edit the active Letta Code Desktop preferences JSON file. Do not use it for Desktop product-code changes, Electron IPC work, UI changes, or general Letta Cloud Desktop implementation tasks.
+
+## Preferences file
+
+The Desktop preferences file is:
+
+```text
+~/.letta/desktop_preferences.json
+```
+
+Known preference keys:
+
+- `defaultWorkingDirectory`: default folder for new local sessions.
+- `theme`: `auto`, `light`, or `dark`.
+- `allowRemoteAccess`: boolean for whether remote access should be enabled in preferences.
+- `remoteEnvName`: environment name shown for remote access.
+
+## Workflow
+
+1. Read the existing JSON first.
+2. Preserve unknown keys.
+3. Merge only the requested preference updates.
+4. Write pretty JSON with a trailing newline.
+5. Do not edit token, provider, secret, agent, conversation, memory, or unrelated state files.
+6. Tell the user that the change applies live only if their Desktop build watches preference-file changes; otherwise they should reload/restart Desktop or use Preferences → General.
+
+## Safe edit command
+
+Use a merge-style edit like this, changing only the requested keys:
+
+```bash
+node - <<'NODE'
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const file = path.join(os.homedir(), '.letta', 'desktop_preferences.json');
+fs.mkdirSync(path.dirname(file), { recursive: true });
+
+const current = fs.existsSync(file)
+  ? JSON.parse(fs.readFileSync(file, 'utf8'))
+  : {};
+
+const next = {
+  ...current,
+  // Example update. Replace this with the user's requested setting.
+  theme: 'dark',
+};
+
+fs.writeFileSync(file, JSON.stringify(next, null, 2) + '\n');
+NODE
+```
+
+## Validation
+
+After editing, read the file back or parse it to confirm valid JSON:
+
+```bash
+node -e "JSON.parse(require('fs').readFileSync(require('os').homedir() + '/.letta/desktop_preferences.json', 'utf8')); console.log('desktop_preferences.json is valid')"
+```

package/skills/image-generation/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: image-generation
+description: Generate images from text prompts (and optionally edit/remix input images). Use when the user asks to create, generate, draw, render, or edit an image, illustration, logo, icon, diagram, or photo.
+---
+
+# Image Generation
+
+Generate images via Letta's hosted endpoint `POST /v1/images/generations`. The API
+usually returns base64 image bytes, but some providers return signed image URLs;
+save either form to a local image file before replying.
+
+## Example
+
+Generate the image, save it locally, then show it inline:
+
+```bash
+curl -sS -X POST "https://api.letta.com/v1/images/generations" \
+  -H "Authorization: Bearer $LETTA_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"provider":"gemini","prompt":"a friendly robot mascot waving, flat vector logo, mint green background","n":1}' \
+  > image-response.json
+
+python3 - <<'PY'
+import base64, json, urllib.request
+
+with open("image-response.json") as f:
+    response = json.load(f)
+
+image = response["images"][0]
+if image.get("b64_json"):
+    data = base64.b64decode(image["b64_json"])
+else:
+    data = urllib.request.urlopen(image["url"]).read()
+
+with open("robot-mascot.png", "wb") as f:
+    f.write(data)
+
+print("saved robot-mascot.png; credits:", response["billing"]["credits_charged"])
+PY
+```
+
+In Bash tools launched by Letta Code, the current Letta credential is available
+as `$LETTA_API_KEY`. This works for both Letta auth modes: it may be a normal
+Letta API key, or the OAuth access token from a Letta Cloud OAuth login. Reference
+it directly. If it is missing, the user needs to authenticate with Letta Cloud (or
+provide a Letta API key); do **not** ask for a Flux/OpenAI/Gemini provider key. This
+endpoint also does not use `/connect` BYOK providers — the only `provider` values
+supported here are `flux`, `gemini`, and `openai`.
+
+Then **show the image to the user** by embedding the saved file in your reply:
+
+```markdown
+Here's the mascot:
+
+![a friendly robot mascot waving, flat vector logo](./robot-mascot.png)
+```
+
+The Letta Code UI renders local file paths in markdown image tags, so the image
+appears inline. **Always display generated images this way** — don't just report
+the path, and never paste the raw base64 / a `data:` URI. The markdown path must
+match where you saved the file. For `n > 1`, save each image to its own file and
+embed each on its own line. Also tell the user the `credits_charged`.
+
+## Request body
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `provider` | `"flux"` \| `"gemini"` \| `"openai"` | Required. |
+| `prompt` | string | Required, 1–32000 chars. |
+| `model` | string | Optional; defaults per provider (below). |
+| `n` | int 1–4 | Optional, default 1. Request variations in one call. |
+| `size` | string | Optional, e.g. `"1024x1024"` (OpenAI). |
+| `quality` | `low`\|`medium`\|`high`\|`auto` | Optional (OpenAI; higher = more credits). |
+| `output_format` | `png`\|`jpeg`\|`webp` | Optional (OpenAI). |
+| `input_images` | string[] (max 14) | Optional. Base64 **data URLs** for edit/remix. |
+| `seed` | int | Optional. |
+
+| Provider | Default model | Use for |
+|----------|---------------|---------|
+| `flux` | `flux-2-pro` | Default for normal text-to-image. High-quality general image generation; commonly returns signed URLs. |
+| `gemini` | `gemini-3-pro-image` | Strong prompt adherence, image editing/remix. |
+| `openai` | `gpt-image-2` | Photoreal output, explicit `size`/`quality`/`output_format`. |
+
+Default to `flux` for normal text-to-image requests. Use `gemini` when the user
+provides input images or wants image editing/remix. Use `openai` when the user
+wants photoreal output or a specific size/quality.
+
+## Response
+
+```json
+{
+  "provider": "gemini",
+  "model": "gemini-3-pro-image",
+  "images": [{ "b64_json": "<base64>", "mime_type": "image/png" }],
+  "billing": { "credits_charged": 12, "...": "..." }
+}
+```
+
+Each `images[]` entry has either `b64_json` or `url`, plus `mime_type`. Gemini
+always returns `b64_json`. Flux commonly returns a signed `url`; download it to
+your local image file immediately because signed URLs expire. If OpenAI returns a
+`url`, download that URL instead of base64-decoding.
+
+## Editing / remixing images
+
+Pass source images in `input_images` as base64 **data URLs**
+(`data:<mime>;base64,<data>`) and describe the edit in `prompt`. Gemini handles
+multi-image edits well. To build a data URL from a local file:
+
+```bash
+DATA_URL="data:image/png;base64,$(base64 < input.png | tr -d '\n')"
+```
+
+## Notes
+
+- **Billing**: every success charges credits; don't loop needlessly, and report
+  `credits_charged`.
+- **Errors**: `402` = insufficient credits (`credits_required` in body); `400`/`500`
+  return `{ "message": "..." }` — surface it to the user.
+- Only `flux`, `gemini`, and `openai` are supported here.

package/skills/modifying-the-harness/SKILL.md

@@ -75,6 +75,14 @@ Load the `letta-api-client` skill for richer SDK examples.
 ## 1. Change permissions
 
 Permissions decide which tool calls are allowed, denied, or require approval.
+Use `alwaysAsk` when a rule should request human approval even in
+`unrestricted`/yolo mode.
+
+Settings `ask` rules request approval in normal permission modes, but they do
+not override `unrestricted`/yolo mode. For a mod tool that must pause for human
+approval even in unrestricted mode, set `approvalPolicy: "alwaysAsk"` in the
+tool registration. For broader dynamic policy, use a mod permission overlay or
+a blocking hook.
 
 ### Rule syntax
 
@@ -91,6 +99,15 @@ python3 <skill-dir>/scripts/add_permission.py \
   --scope user
 ```
 
+Force approval even in yolo mode:
+
+```bash
+python3 <skill-dir>/scripts/add_permission.py \
+  --rule "Bash(git push:*)" \
+  --type alwaysAsk \
+  --scope user
+```
+
 ### Edit directly
 
 ```json
@@ -98,7 +115,8 @@ python3 <skill-dir>/scripts/add_permission.py \
   "permissions": {
     "allow": ["Bash(npm:*)", "Read(src/**)"],
     "deny": ["Bash(rm -rf:*)"],
-    "ask": []
+    "ask": [],
+    "alwaysAsk": ["Bash(git push:*)"]
   }
 }
 ```
@@ -215,6 +233,7 @@ Find your own entry by matching `agentId === $LETTA_AGENT_ID`, then edit the fie
 |------|----------------|
 | Auto-approve curl | `add_permission.py --rule "Bash(curl:*)" --type allow --scope user` |
 | Block `rm -rf` | Add `"Bash(rm -rf:*)"` to `permissions.deny`, or add a `PreToolUse` hook |
+| Always ask before git push | `add_permission.py --rule "Bash(git push:*)" --type alwaysAsk --scope user` |
 | Log all Bash calls | `add_hook.py --event PreToolUse --matcher Bash --type command --command '...' --scope user` |
 | Auto-format after edits | `add_hook.py --event PostToolUse --matcher "Edit|Write" --type command --command '...' --scope project` |
 | Gate edits with LLM | `add_hook.py --event PreToolUse --matcher "Edit|Write" --type prompt --prompt '...' --scope user` |
@@ -237,7 +256,7 @@ Find your own entry by matching `agentId === $LETTA_AGENT_ID`, then edit the fie
 
 | Script | Purpose |
 |--------|---------|
-| `scripts/add_permission.py` | Add an allow/deny/ask rule to any scope |
+| `scripts/add_permission.py` | Add an allow/deny/ask/alwaysAsk rule to any scope |
 | `scripts/add_hook.py` | Add a command or prompt hook to any event |
 | `scripts/show_config.py` | Show merged permissions, hooks, and per-agent settings across all scopes |
 

package/skills/modifying-the-harness/scripts/add_permission.py

@@ -5,6 +5,7 @@ Add a permission rule to Letta Code settings.
 Usage:
     python3 add_permission.py --rule "Bash(npm run:*)" --type allow --scope user
     python3 add_permission.py --rule "Read(src/**)" --type allow --scope project
+    python3 add_permission.py --rule "Bash(git push:*)" --type alwaysAsk --scope user
 """
 
 import argparse
@@ -99,7 +100,7 @@ def main():
     parser.add_argument(
         "--type",
         required=True,
-        choices=["allow", "deny", "ask"],
+        choices=["allow", "deny", "ask", "alwaysAsk"],
         help="Type of permission rule",
     )
     parser.add_argument(