@letta-ai/letta-code 0.27.4 → 0.27.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.27.4",
+  "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",
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@letta-ai/letta-client": "^1.10.2",
-    "@earendil-works/pi-ai": "^0.77.0",
+    "@earendil-works/pi-ai": "^0.78.1",
     "@pierre/diffs": "1.2.2",
     "glob": "^13.0.0",
     "ink-link": "^5.0.0",

package/skills/acquiring-skills/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: acquiring-skills
-description: Guide for safely discovering and installing skills from external repositories. Use when a user asks for something where a specialized skill likely exists (browser testing, PDF processing, document generation, etc.) and you want to bootstrap your understanding rather than starting from scratch.
+description: Discover and install skills from Hermes, ClawHub, GitHub, and other registries. Load this skill whenever a user asks for a capability you don't already have — image generation, social media, email, calendar, finance, DevOps, search, browser automation, etc.
 ---
 
 # Acquiring New Skills
 
-This skill teaches you how to safely discover and install skills from external sources.
+This skill teaches you how to safely discover and install skills from external sources, including the Hermes Skills Hub, ClawHub (OpenClaw), GitHub repositories, and Letta community repos.
 
 ## SAFETY - READ THIS FIRST
 
@@ -16,19 +16,33 @@ Skills can contain:
 ### Trusted Sources (no user approval needed for download)
 - `https://github.com/letta-ai/skills` - Letta's community skills
 - `https://github.com/anthropics/skills` - Anthropic's official skills
+- `official/*` - Hermes official optional skills (from `NousResearch/hermes-agent`)
 
 ### Untrusted Sources (ALWAYS verify with user)
-For ANY source other than letta-ai or anthropics:
+For ANY source other than the above:
 1. Ask the user before downloading
 2. Explain where the skill comes from
 3. Get explicit approval
 
+This includes ClawHub community skills and arbitrary GitHub repos.
+
 ### Script Safety
 Even for skills from trusted sources, ALWAYS:
 1. Read and inspect any scripts before executing them
 2. Understand what the script does
 3. Be wary of network calls, file operations, or system commands
 
+### Cross-Harness Compatibility
+Skills from Hermes, OpenClaw, and other ecosystems were written for their own harnesses. After installing, **read the full SKILL.md before using it** and watch for:
+
+- **Harness-specific commands** — e.g. `hermes skills config`, `openclaw plugins install`, `/curator`, `/kanban`. These won't exist in Letta. Determine whether the underlying capability can be achieved with Letta tools (Bash, the Skill tool, etc.) or if the skill simply doesn't apply.
+- **Harness-specific paths and state** — e.g. `~/.hermes/skills/`, `~/.openclaw/skills/`, `~/.hermes/config.yaml`. Letta stores skills in the agent's memfs (`<memory-dir>/skills/`). Adapt any path references.
+- **Toolset assumptions** — some skills assume specific tool names or APIs (e.g. Hermes `web` toolset, OpenClaw `browser` tool). Map these to the equivalent Letta tools or note when no equivalent exists.
+- **Platform gating** — skills may declare `platforms: [cli, discord, telegram]` in frontmatter. Ignore platform restrictions that don't apply to Letta.
+- **Environment variables** — skills may require API keys or credentials. Check `requires.env` in frontmatter and note any setup the user needs to do.
+
+If a skill's core knowledge (procedures, API references, best practices) is useful but its commands are harness-specific, adapt the instructions mentally or suggest the user install the relevant CLI tool. If a skill is entirely about harness-specific plumbing with no transferable knowledge, skip it and look for an alternative.
+
 ## When to Use This Skill
 
 **DO use** when:
@@ -45,78 +59,221 @@ Even for skills from trusted sources, ALWAYS:
 
 If you recognize a task that might have an associated skill, **ask the user first**:
 
-> "This sounds like something where a community skill might help (e.g., webapp testing with Playwright). Would you like me to look for available skills in the Letta or Anthropic repositories? This might take a minute, or I can start coding right away if you prefer."
+> "This sounds like something where a community skill might help. Would you like me to search for available skills? I can check the Hermes catalog, ClawHub, or GitHub. Or I can start coding right away if you prefer."
 
 The user may prefer to start immediately rather than wait for skill discovery.
 
 Only proceed with skill acquisition if the user agrees.
 
-## Skill Repositories
+## Skill Sources
+
+### 1. Hermes Skills Hub (NousResearch)
+
+Hermes has a full Skills Hub with 88k+ skills across multiple registries. It includes official optional skills shipped with the project, plus community skills from skills.sh, well-known endpoints, GitHub repos, ClawHub, LobeHub, and browse.sh.
+
+**Searching Hermes skills:**
+
+The Hermes CLI has built-in search and browse:
+
+```bash
+hermes skills browse                              # Browse all hub skills (official first)
+hermes skills browse --source official            # Browse only official optional skills
+hermes skills search kubernetes                   # Search all sources
+hermes skills search react --source skills-sh     # Search the skills.sh directory
+hermes skills search https://mintlify.com/docs --source well-known
+hermes skills inspect openai/skills/k8s           # Preview before installing
+```
+
+The web catalog is at https://hermes-agent.nousresearch.com/docs/skills.
+
+Hermes hub sources:
+
+| Source | Example identifier | Notes |
+|--------|--------------------|-------|
+| `official` | `official/security/1password` | Optional skills shipped with Hermes |
+| `skills-sh` | `skills-sh/vercel-labs/agent-skills/vercel-react-best-practices` | skills.sh directory |
+| `well-known` | `well-known:https://mintlify.com/docs/.well-known/skills/mintlify` | Skills hosted at `/.well-known/skills/` |
+| `url` | `https://sharethis.chat/SKILL.md` | Direct URL to a single SKILL.md |
+| `github` | `openai/skills/k8s` | GitHub repo/path |
+| `clawhub` | ClawHub registry skills | ClawHub marketplace |
+| `lobehub` | LobeHub registry skills | LobeHub marketplace |
+| `browse-sh` | `browse-sh/airbnb.com/search-listings-ddgioa` | browse.sh crawled skills |
+
+If Hermes is not installed, you can browse the official optional skills directly:
+
+```bash
+# Browse the catalog on GitHub
+# https://github.com/NousResearch/hermes-agent/tree/main/optional-skills
+# Categories: autonomous-ai-agents, blockchain, creative, devops, finance,
+#             health, mcp, mlops, productivity, research, security, ...
+
+# Or clone and browse locally
+git clone --depth 1 https://github.com/NousResearch/hermes-agent.git /tmp/hermes-browse
+ls /tmp/hermes-browse/optional-skills/
+ls /tmp/hermes-browse/optional-skills/finance/
+rm -rf /tmp/hermes-browse
+```
+
+**Installing Hermes skills** into Letta uses the `official/` prefix (for official optional skills):
+
+```bash
+letta skills install official/finance/stocks
+letta skills install official/blockchain/solana
+letta skills install official/research/duckduckgo-search
+letta skills install official/mlops/flash-attention
+letta skills install official/creative/meme-generation
+```
+
+The `official/<category>/<skill>` form clones `NousResearch/hermes-agent` and copies from `optional-skills/<category>/<skill>`.
+
+For non-official Hermes hub skills, use the GitHub URL or shorthand form to install into Letta (e.g., `letta skills install openai/skills/k8s`).
+
+### 2. ClawHub (OpenClaw)
+
+ClawHub (https://clawhub.ai) is the public registry for OpenClaw skills and plugins. It hosts community-contributed skills with versioning, security scans, and search.
+
+**Searching ClawHub skills:**
+
+```bash
+# Browse the web registry
+# https://clawhub.ai
+
+# Or use the clawhub CLI if installed
+clawhub search "calendar"
+clawhub search "screenshot"
+clawhub explore
+
+# Or search via the API directly
+curl -s "https://clawhub.ai/api/v1/skills?q=calendar" | jq '.items[].slug'
+```
+
+**Installing ClawHub skills** uses the `clawhub/` or `clawhub:` prefix:
+
+```bash
+letta skills install clawhub/nano-banana-pro
+letta skills install clawhub:nano-banana-pro
+letta skills install clawhub:nano-banana-pro@1.0.1      # pin a version
+letta skills install https://clawhub.ai/skills/my-skill  # URL form also works
+```
+
+**Note:** A bare slug like `letta skills install nano-banana-pro` will NOT resolve through ClawHub — you must include the `clawhub/` or `clawhub:` prefix.
+
+### 3. GitHub Repositories
+
+Any GitHub repository containing a `SKILL.md` can be installed directly.
+
+```bash
+# Full repo (installs from repo root)
+letta skills install https://github.com/owner/repo
+
+# Subdirectory (tree URL)
+letta skills install https://github.com/owner/repo/tree/main/path/to/skill
+
+# SKILL.md blob URL (installs parent directory)
+letta skills install https://github.com/owner/repo/blob/main/path/to/skill/SKILL.md
+
+# Shorthand: owner/repo/path
+letta skills install owner/repo/path/to/skill
+```
+
+### 4. Letta & Anthropic Community Repos
 
 | Repository | Description |
 |------------|-------------|
 | https://github.com/letta-ai/skills | Community skills for Letta agents |
 | https://github.com/anthropics/skills | Anthropic's official Agent Skills |
 
-Browse these repositories to discover available skills. Check the README for skill listings.
+These can be installed via the GitHub URL forms above, or manually cloned and copied.
+
+## The `letta skills install` Command
+
+The CLI handles downloading, placing the skill in the agent's memory, and committing the change:
+
+```bash
+letta skills install <source> --agent $AGENT_ID [--force]
+```
+
+Your agent ID is always available as `$AGENT_ID` in the environment. Pass it explicitly with `--agent` to install into your own memfs:
+
+```bash
+letta skills install official/finance/stocks --agent $AGENT_ID
+letta skills install clawhub/nano-banana-pro --agent $AGENT_ID
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--agent <id>` | Install into a specific agent's memfs (use `$AGENT_ID` for yourself) |
+| `-n <name>` | Resolve agent by name instead of id |
+| `--force` | Replace an existing skill with the same name |
+
+Also available as a top-level alias: `letta install <source> --agent $AGENT_ID`.
+
+**Managing installed skills:**
+
+```bash
+letta skills list --agent $AGENT_ID
+letta skills delete <skill-name> --agent $AGENT_ID
+```
 
 ## Installation Locations
 
+When using `letta skills install`, skills are placed in the agent's memfs at `<memory-dir>/skills/<skill-name>/`.
+
+For manual installation:
+
 | Location | Path | When to Use |
 |----------|------|-------------|
-| **Agent-scoped** | `~/.letta/agents/<agent-id>/memory/skills/<skill>/` | Skills for a single agent (default for agent-specific capabilities) |
+| **Agent-scoped** | `~/.letta/agents/<agent-id>/memory/skills/<skill>/` | Skills for a single agent (default) |
 | **Global** | `~/.letta/skills/<skill>/` | General-purpose skills useful across projects |
 | **Project** | `.skills/<skill>/` | Project-specific skills |
 
-**Rule**: Default to **agent-scoped** for changes that should apply only to the current agent. Use **project** for repo-specific skills. Use **global** only if all agents should inherit the skill.
+**Rule**: Default to **agent-scoped**. Use **project** for repo-specific skills. Use **global** only if all agents should inherit the skill.
 
-## How to Download Skills
+## Manual Download (When CLI Install Isn't Available)
 
 Skills are directories containing SKILL.md and optionally scripts/, references/, examples/.
 
-### Method: Clone to /tmp, then copy
-
 ```bash
-# 1. Clone the repo (shallow)
+# Clone, copy, cleanup
 git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
-
-# 2. Copy the skill to your skills directory
-# For agent-scoped (recommended default):
 cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/agents/<agent-id>/memory/skills/
-# For global:
-# cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/skills/
-# For project:
-# cp -r /tmp/skills-temp/skills/webapp-testing .skills/
-
-# 3. Cleanup
 rm -rf /tmp/skills-temp
 ```
 
-### Alternative: rsync (preserves permissions)
+## Registering New Skills
 
-```bash
-git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
-rsync -av /tmp/skills-temp/skills/webapp-testing/ ~/.letta/agents/<agent-id>/memory/skills/webapp-testing/
-rm -rf /tmp/skills-temp
-```
+After installing (via CLI or manual copy), skills are automatically discovered on the next message. Skills are discovered from `~/.letta/skills/`, `.skills/`, and agent-scoped `~/.letta/agents/<agent-id>/memory/skills/` directories.
 
-## Registering New Skills
+## Search Strategy
+
+When looking for a skill to solve a user's problem:
 
-After downloading a skill, it will be automatically discovered on the next message. Skills are discovered from `~/.letta/skills/`, `.skills/`, and agent-scoped `~/.letta/agents/<agent-id>/memory/skills/` directories.
+1. **Search Hermes Skills Hub first** — `hermes skills search <query>` searches 88k+ skills across all registries. If Hermes CLI isn't available, browse the official optional-skills on GitHub (finance, mlops, blockchain, devops, research, creative, security, etc.).
+2. **Search ClawHub** — community registry with versioning. Use `clawhub search` or the web UI.
+3. **Search GitHub** — look for repos with `SKILL.md` files. Try `github.com/letta-ai/skills` and `github.com/anthropics/skills` first.
+4. **Ask the user** — they may know of a specific skill repo or have preferences about sources.
 
 ## Complete Example
 
-User asks: "Can you help me test my React app's UI?"
+User asks: "Can you help me track stock prices?"
+
+1. **Recognize opportunity**: Stock/finance data — Hermes has a stocks skill
+2. **Ask user**: "Hermes has an official stocks skill that covers quotes, history, search, and crypto via Yahoo. Want me to install it?"
+3. **If user agrees, install**:
+   ```bash
+   letta skills install official/finance/stocks --agent $AGENT_ID
+   ```
+4. **Review for compatibility**: Read the installed SKILL.md. Check for harness-specific commands, paths, or tools that need adaptation (see Cross-Harness Compatibility above). Confirm the skill's instructions make sense in Letta before using it.
+5. **Invoke**: `Skill(skill: "stocks")`
+6. **Use**: Follow the skill's instructions, adapting any harness-specific details as needed
+
+User asks: "Can you generate images with Nano Banana Pro?"
 
-1. **Recognize opportunity**: Browser/webapp testing - likely has a skill
-2. **Ask user**: "Would you like me to look for webapp testing skills, or start coding right away?"
-3. **If user agrees, find skill**: Check anthropics/skills for webapp-testing
-4. **Download** (trusted source):
+1. **Recognize opportunity**: Image generation skill on ClawHub
+2. **Ask user**: "There's a nano-banana-pro skill on ClawHub. Want me to install it?"
+3. **Install**:
    ```bash
-   git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
-   cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/agents/<agent-id>/memory/skills/
-   rm -rf /tmp/skills-temp
+   letta skills install clawhub/nano-banana-pro --agent $AGENT_ID
    ```
-5. **Inspect scripts**: Read any .py or .ts files before using them
-6. **Invoke**: `Skill(skill: "webapp-testing")`
-7. **Use**: Follow the skill's instructions for the user's task
+4. **Review for compatibility**: Read the SKILL.md, check for any OpenClaw-specific commands or setup, adapt as needed.
+5. **Invoke**: `Skill(skill: "nano-banana-pro")`

package/skills/creating-extensions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: creating-extensions
-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.
+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.
 ---
 
 # Creating Extensions
@@ -13,6 +13,8 @@ Use this skill to create or update trusted global Letta Code extensions in:
 
 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`.
 
+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.
+
 ## Choose the right capability
 
 | User wants | Build |
@@ -24,6 +26,8 @@ Extensions are trusted local apps for Letta Code. They add small composable capa
 | 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 |
 
 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.
@@ -32,17 +36,17 @@ Default to a **tool** when the model should decide when to use the capability. D
 
 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:
-   - 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:
+3. Choose the extension shape and load only the needed recipe:
    - tools: `references/tools.md`
    - 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 commands/tools/events, timers, subscriptions, and panels that should close on reload.
+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`.
 
@@ -74,6 +78,8 @@ 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
 letta.capabilities.ui.customStatuslineRenderer
@@ -89,9 +95,21 @@ letta.capabilities.ui.customStatuslineRenderer
 - 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.
 
+## 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.
+
+Agents can inspect local extension diagnostics at:
+
+```text
+~/.letta/extensions/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.
 - 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.
@@ -110,6 +128,7 @@ Before finishing, verify:
 - 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.
 - 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.
@@ -118,9 +137,13 @@ Before finishing, verify:
 
 ## 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
+| Reference | Load when |
+| --- | --- |
+| `references/tools.md` | The model should autonomously call a local capability |
+| `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/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/architecture.md

@@ -2,6 +2,16 @@
 
 Use this reference for non-trivial extensions: multiple capabilities, local state, timers, background model work, or UI.
 
+## Contents
+
+- Mental model
+- Capability composition patterns
+- Local state
+- Timers and subscriptions
+- Scoped conversation handles
+- Error handling
+- Final review checklist
+
 ## 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:
@@ -13,6 +23,8 @@ An extension is trusted local code that registers capabilities during activation
 
 Do not import Letta Code internals. If the extension 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.
+
 ## Capability composition patterns
 
 ### Tool + command

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

@@ -4,6 +4,15 @@ 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`.
 
+## Contents
+
+- Decide command vs skill vs tool
+- Command IDs
+- Prompt command
+- Output-only command
+- Panel command
+- Busy-safe conversation command
+
 ## Decide command vs skill vs tool
 
 | Need | Use |
@@ -116,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

@@ -2,6 +2,16 @@
 
 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`.
 
+## Contents
+
+- Capabilities
+- Supported events
+- Tool argument transforms
+- Turn input transforms
+- Event handler context
+- 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.
 
 ## Capabilities
@@ -34,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) => {
@@ -105,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:
 
@@ -128,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`.