ethagent 2.4.0 → 3.0.0

package/src/models/llamacppPreflight.ts

@@ -26,9 +26,6 @@ export type LlamaCppPreflightDeps = {
   timeoutMs?: number
 }
 
-const UNTRACKED_VISION_DETAIL =
-  'A llama-server is already serving this alias but ethagent did not launch it, so we cannot apply the vision projector. Stop the external process and reopen ethagent.'
-
 type ModelsProbe =
   | { up: true; models: string[] }
   | { up: false; models: [] }
@@ -68,19 +65,7 @@ export async function ensureLlamaCppRunnerReady(
       }
     }
     if (!local.mmprojPath) return { ok: true, alreadyRunning: true }
-    const stopped = await (deps.stopServer ?? stopLlamaCppServer)().catch(() => null)
-    if (stopped && stopped.ok && stopped.reason === 'untracked-server') {
-      return withPreflightMessage(
-        {
-          ok: false,
-          code: 'untracked-server',
-          message: UNTRACKED_VISION_DETAIL,
-          detail: UNTRACKED_VISION_DETAIL,
-          servedModels: stopped.servedModels,
-        },
-        local,
-      )
-    }
+    await (deps.stopServer ?? stopLlamaCppServer)().catch(() => null)
   }
 
   const result = await (deps.startServer ?? startLlamaCppServer)({

package/src/models/modelPickerOptions.ts

@@ -61,7 +61,9 @@ const CHILD_INDENT = 4
 export function buildModelPickerOptions(
   data: ModelPickerOptionsData,
   context: ModelPickerOptionsContext,
+  options_: { localOnly?: boolean } = {},
 ): SelectOption<string>[] {
+  const localOnly = options_.localOnly === true
   const options: SelectOption<string>[] = []
 
   options.push(sectionOption('hdr:local', 'Local Models'))
@@ -72,49 +74,53 @@ export function buildModelPickerOptions(
     options.push(utilityOption('local:uninstall', 'Uninstall Downloaded GGUF'))
   }
 
-  options.push(sectionOption('hdr:cloud', 'Cloud'))
-  for (const provider of MODEL_PICKER_CLOUD_PROVIDERS) {
-    options.push(groupOption(`hdr:cloud:${provider}`, cloudProviderDisplayName(provider)))
-    const keySet = data.cloudKeys[provider] === true
-    if (!keySet) {
-      if (provider === 'openai') {
-        options.push(utilityOption('oauth:openai', 'Sign in with ChatGPT', 'Use your ChatGPT subscription'))
+  if (!localOnly) {
+    options.push(sectionOption('hdr:cloud', 'Cloud'))
+    for (const provider of MODEL_PICKER_CLOUD_PROVIDERS) {
+      options.push(groupOption(`hdr:cloud:${provider}`, cloudProviderDisplayName(provider)))
+      const keySet = data.cloudKeys[provider] === true
+      if (!keySet) {
+        if (provider === 'openai') {
+          options.push(utilityOption('oauth:openai', 'Sign in with ChatGPT', 'Use your ChatGPT subscription'))
+        }
+        options.push(utilityOption(`key:set:${provider}`, 'Add API Key'))
+        continue
       }
-      options.push(utilityOption(`key:set:${provider}`, 'Add API Key'))
-      continue
-    }
 
-    const catalog = data.cloudCatalogs[provider]
-    if (catalog?.status === 'fallback') {
-      const reason = catalog.error ? ` · ${catalog.error}` : ''
-      options.push(noticeOption(
-        `hdr:cloud-fallback:${provider}`,
-        `Catalog unavailable${reason} · showing configured model`,
-        CHILD_INDENT,
-      ))
-    }
+      const catalog = data.cloudCatalogs[provider]
+      if (catalog?.status === 'fallback') {
+        const reason = catalog.error ? ` · ${catalog.error}` : ''
+        options.push(noticeOption(
+          `hdr:cloud-fallback:${provider}`,
+          `Catalog unavailable${reason} · showing configured model`,
+          CHILD_INDENT,
+        ))
+      }
 
-    const models = orderModelsForContextFit(provider, cloudPickerModels(provider, catalog, context), context.contextFit)
-    if (models.length === 0) {
-      options.push(noticeOption(`hdr:cloud-empty:${provider}`, 'No selectable models', CHILD_INDENT))
-    }
-    for (const model of models) {
-      const active = context.currentProvider === provider && context.currentModel === model
-      const displayName = formatModelDisplayName(provider, model, { maxLength: 58 })
-      options.push(rowOption(
-        `c:${provider}:${model}`,
-        contextFitLabel(provider, model, `${displayName}${active ? '  *' : ''}`, context.contextFit),
-      ))
+      const models = orderModelsForContextFit(provider, cloudPickerModels(provider, catalog, context), context.contextFit)
+      if (models.length === 0) {
+        options.push(noticeOption(`hdr:cloud-empty:${provider}`, 'No selectable models', CHILD_INDENT))
+      }
+      for (const model of models) {
+        const active = context.currentProvider === provider && context.currentModel === model
+        const displayName = formatModelDisplayName(provider, model, { maxLength: 58 })
+        options.push(rowOption(
+          `c:${provider}:${model}`,
+          contextFitLabel(provider, model, `${displayName}${active ? '  *' : ''}`, context.contextFit),
+        ))
+      }
+      options.push(utilityOption(`catalog:${provider}`, 'Full Catalog'))
+      const manageLabel = provider === 'openai' && data.cloudCredentialKinds?.openai === 'oauth'
+        ? 'Manage ChatGPT Sign-in'
+        : 'Manage API Key'
+      options.push(utilityOption(`key:manage:${provider}`, manageLabel))
     }
-    options.push(utilityOption(`catalog:${provider}`, 'Full Catalog'))
-    const manageLabel = provider === 'openai' && data.cloudCredentialKinds?.openai === 'oauth'
-      ? 'Manage ChatGPT Sign-in'
-      : 'Manage API Key'
-    options.push(utilityOption(`key:manage:${provider}`, manageLabel))
   }
 
-  options.push(sectionOption('hdr:exit', 'Exit'))
-  options.push(utilityOption('cancel', 'Close Model Picker', 'Return to chat without changing model'))
+  if (!localOnly) {
+    options.push(sectionOption('hdr:exit', 'Exit'))
+    options.push(utilityOption('cancel', 'Close Model Picker', 'Return to chat'))
+  }
 
   return options
 }

package/src/providers/contracts.ts

@@ -42,6 +42,7 @@ export type ProviderRetryStreamEvent = { type: 'retry' } & RetryEvent
 export type StreamEvent =
   | { type: 'text'; delta: string }
   | { type: 'thinking'; delta: string }
+  | { type: 'thinking_end' }
   | ProviderRetryStreamEvent
   | { type: 'tool_use_start'; id: string; name: string }
   | { type: 'tool_use_delta'; id: string; delta: string }

package/src/providers/openai-chat.ts

@@ -171,6 +171,7 @@ export class OpenAIChatProvider implements Provider {
     let stopReason: DoneStopReason = 'unknown'
     const toolCalls = new Map<number, StreamingToolCall>()
     const contentThinkingParser = new ContentThinkingParser(this.id)
+    let reasoningPending = false
 
     try {
       for await (const frame of iterSseFrames(response.body, signal, READ_TIMEOUT_MS)) {
@@ -194,18 +195,34 @@ export class OpenAIChatProvider implements Provider {
                 ? delta.thinking
                 : ''
 
-        if (reasoning.length > 0) yield { type: 'thinking', delta: reasoning }
+        if (reasoning.length > 0) {
+          yield { type: 'thinking', delta: reasoning }
+          reasoningPending = true
+        }
         if (text.length > 0) {
+          if (reasoningPending) {
+            yield { type: 'thinking_end' }
+            reasoningPending = false
+          }
           for (const event of contentThinkingParser.push(text)) {
             yield event
           }
         }
 
-        for (const event of applyStreamingToolCallDelta(toolCalls, delta?.tool_calls ?? [])) {
+        const toolCallDeltas = delta?.tool_calls ?? []
+        if (toolCallDeltas.length > 0 && reasoningPending) {
+          yield { type: 'thinking_end' }
+          reasoningPending = false
+        }
+        for (const event of applyStreamingToolCallDelta(toolCalls, toolCallDeltas)) {
           yield event
         }
 
         if (choice?.finish_reason) {
+          if (reasoningPending) {
+            yield { type: 'thinking_end' }
+            reasoningPending = false
+          }
           stopReason = normalizeFinishReason(choice.finish_reason)
         }
         if (parsed.usage) {
@@ -223,6 +240,10 @@ export class OpenAIChatProvider implements Provider {
     for (const event of contentThinkingParser.flush()) {
       yield event
     }
+    if (reasoningPending) {
+      yield { type: 'thinking_end' }
+      reasoningPending = false
+    }
 
     let streamEmittedToolUses = 0
     if (stopReason === 'tool_use' || toolCalls.size > 0) {
@@ -383,17 +404,35 @@ function isToolResultBlock(block: MessageContentBlock): block is Extract<Message
 
 function parseToolArguments(inputJson: string): Record<string, unknown> {
   if (!inputJson.trim()) return {}
+  const direct = tryParseJsonOnce(inputJson)
+  if (direct !== undefined) return coerceToToolArguments(direct)
+  const repaired = repairJsonObject(inputJson)
+  if (!repaired) return {}
+  const parsedRepaired = tryParseJsonOnce(repaired)
+  return parsedRepaired === undefined ? {} : coerceToToolArguments(parsedRepaired)
+}
+
+function tryParseJsonOnce(value: string): unknown {
   try {
-    return JSON.parse(inputJson) as Record<string, unknown>
+    return JSON.parse(value)
   } catch {
-    const repaired = repairJsonObject(inputJson)
-    if (!repaired) return {}
-    try {
-      return JSON.parse(repaired) as Record<string, unknown>
-    } catch {
-      return {}
+    return undefined
+  }
+}
+
+function coerceToToolArguments(value: unknown): Record<string, unknown> {
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+      const inner = tryParseJsonOnce(trimmed)
+      if (inner !== undefined) return coerceToToolArguments(inner)
     }
+    return {}
+  }
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>
   }
+  return {}
 }
 
 function* applyStreamingToolCallDelta(
@@ -486,7 +525,9 @@ class ContentThinkingParser {
           yield { type: this.state === 'thinking' ? 'thinking' : 'text', delta: before }
         }
         this.buffer = this.buffer.slice(tagIndex + tag.length)
+        const wasThinking = this.state === 'thinking'
         this.state = this.state === 'text' ? 'thinking' : 'text'
+        if (wasThinking) yield { type: 'thinking_end' }
         continue
       }
 

package/src/providers/openai-responses.ts

@@ -276,15 +276,30 @@ function parseToolArguments(input: string): Record<string, unknown> {
   const trimmed = input.trim()
   if (!trimmed) return {}
   try {
-    const parsed = JSON.parse(trimmed) as unknown
-    return parsed && typeof parsed === 'object' && !Array.isArray(parsed)
-      ? (parsed as Record<string, unknown>)
-      : {}
+    return coerceToToolArguments(JSON.parse(trimmed))
   } catch {
     return {}
   }
 }
 
+function coerceToToolArguments(value: unknown): Record<string, unknown> {
+  if (typeof value === 'string') {
+    const trimmed = value.trim()
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+      try {
+        return coerceToToolArguments(JSON.parse(trimmed))
+      } catch {
+        return {}
+      }
+    }
+    return {}
+  }
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    return value as Record<string, unknown>
+  }
+  return {}
+}
+
 function networkErrorMessage(baseUrl: string, err: unknown, fallback = 'network error'): string {
   const message = (err as Error).message || fallback
   return `openai request failed at ${baseUrl}: ${message}`

package/src/runtime/toolExecution.ts

@@ -50,8 +50,8 @@ export async function executeToolWithPermissions(
     return {
       result: {
         ok: false,
-        summary: `unknown tool ${options.name}`,
-        content: `tool '${options.name}' is not registered`,
+        summary: `Unknown tool ${options.name}`,
+        content: `Tool '${options.name}' is not registered`,
       },
     }
   }
@@ -98,6 +98,7 @@ export async function executeToolWithPermissions(
     options.permissionMode === 'plan' &&
     request.kind !== 'read' &&
     request.kind !== 'private-continuity-read' &&
+    request.kind !== 'private-skill-read' &&
     !(request.kind === 'mcp' && request.readOnly)
   ) {
     return {
@@ -111,7 +112,7 @@ export async function executeToolWithPermissions(
 
   const matchedRule = matchPermissionRule(options.getPermissionRules(), request)
   const decision: PermissionDecision =
-    modePolicy(options.permissionMode).autoAllowToolKind(request.kind)
+    modePolicy(options.permissionMode).autoAllowToolKind(tool.kind)
       ? 'allow-once'
       : matchedRule
         ? 'allow-once'

package/src/runtime/turn.ts

@@ -10,6 +10,7 @@ import {
 type ProviderTurnEvent =
   | { type: 'text'; delta: string }
   | { type: 'thinking'; delta: string }
+  | { type: 'thinking_end' }
   | ProviderRetryStreamEvent
   | { type: 'tool_use_start'; id: string; name: string }
   | { type: 'tool_use_delta'; id: string; delta: string }
@@ -46,6 +47,7 @@ function normalize(event: StreamEvent): ProviderTurnEvent {
   switch (event.type) {
     case 'text': return { type: 'text', delta: event.delta }
     case 'thinking': return { type: 'thinking', delta: event.delta }
+    case 'thinking_end': return { type: 'thinking_end' }
     case 'retry': return event
     case 'tool_use_start': return event
     case 'tool_use_delta': return event
@@ -67,6 +69,7 @@ export type ContinuationNudgeReason =
   | 'tool_budget'
   | 'private_continuity_tool'
   | 'private_continuity_tool_repair'
+  | 'write_file_repair'
   | 'reasoning_only'
 
 const CONTINUATION_NUDGE_TEXT =
@@ -93,6 +96,9 @@ const PRIVATE_CONTINUITY_NUDGE_TEXT =
 const PRIVATE_CONTINUITY_REPAIR_NUDGE_TEXT =
   'The previous propose_private_continuity_edit call had invalid or missing input. Retry the same native tool now with complete arguments. Do not answer in prose and do not search for markdown files. For memory/preferences use {"file":"MEMORY.md","appendToSection":"Durable User Preferences","appendText":"- User preference or memory note."}. For persona use {"file":"SOUL.md","appendToSection":"Persona","appendText":"- Persona or standing behavior note."}.'
 
+const WRITE_FILE_REPAIR_NUDGE_TEXT =
+  'The previous write_file call was rejected because the arguments were missing or malformed. Retry the same native tool now with a JSON object (not a JSON string) shaped exactly like {"path":"relative/path.ext","content":"...complete file contents..."}. Both fields are required and must be non-empty. Do not answer in prose.'
+
 const REASONING_ONLY_NUDGE_TEXT =
   'You produced private reasoning but no user-visible answer. Answer the user now in visible text. Do not continue only with reasoning.'
 
@@ -100,6 +106,7 @@ export type TurnEvent =
   | { type: 'iteration_start'; index: number }
   | { type: 'text'; delta: string }
   | { type: 'thinking'; delta: string }
+  | { type: 'thinking_end' }
   | ProviderRetryStreamEvent
   | { type: 'tool_use_start'; id: string; name: string }
   | { type: 'tool_use_delta'; id: string; delta: string }
@@ -203,6 +210,8 @@ export async function* runRuntimeTurn(
         } else if (ev.type === 'thinking') {
           thinkingSeen = true
           yield { type: 'thinking', delta: ev.delta }
+        } else if (ev.type === 'thinking_end') {
+          yield { type: 'thinking_end' }
         } else if (ev.type === 'tool_use_start') {
           yield { type: 'tool_use_start', id: ev.id, name: ev.name }
         } else if (ev.type === 'tool_use_delta') {
@@ -279,7 +288,7 @@ export async function* runRuntimeTurn(
       }
       yield {
         type: 'error',
-        message: 'model printed tool names instead of making a tool call',
+        message: 'Model printed tool names instead of making a tool call',
         discardAssistant: true,
       }
       yield doneEvent(false, stopReason)
@@ -302,7 +311,7 @@ export async function* runRuntimeTurn(
       }
       yield {
         type: 'error',
-        message: 'model asked the user to run a tool instead of making a tool call',
+        message: 'Model asked the user to run a tool instead of making a tool call',
         discardAssistant: true,
       }
       yield doneEvent(false, stopReason)
@@ -333,7 +342,7 @@ export async function* runRuntimeTurn(
         }
         yield {
           type: 'error',
-          message: 'model claimed workspace state without matching tool evidence',
+          message: 'Model claimed workspace state without matching tool evidence',
           discardAssistant: true,
         }
         yield doneEvent(false, stopReason)
@@ -342,26 +351,18 @@ export async function* runRuntimeTurn(
     }
 
     if (pendingToolUses.length === 0) {
-      if (!assistantText && thinkingSeen) {
-        if (continuationNudges < maxContinuationNudges) {
-          continuationNudges += 1
-          yield {
-            type: 'continuation_nudge',
-            attempt: continuationNudges,
-            reason: 'reasoning_only',
-          }
-          workingMessages = [
-            ...await rebuildMessages(),
-            { role: 'user', content: REASONING_ONLY_NUDGE_TEXT },
-          ]
-          continue
-        }
+      if (!assistantText && thinkingSeen && continuationNudges < maxContinuationNudges) {
+        continuationNudges += 1
         yield {
-          type: 'error',
-          message: 'model produced reasoning but no visible answer',
+          type: 'continuation_nudge',
+          attempt: continuationNudges,
+          reason: 'reasoning_only',
         }
-        yield doneEvent(false, stopReason)
-        return
+        workingMessages = [
+          ...await rebuildMessages(),
+          { role: 'user', content: REASONING_ONLY_NUDGE_TEXT },
+        ]
+        continue
       }
 
       const nudge = nextNudge(provider, assistantText)
@@ -387,7 +388,7 @@ export async function* runRuntimeTurn(
       if (assistantText && nudge?.reason === 'tool_capability') {
         yield {
           type: 'error',
-          message: 'model refused available tools after corrective nudges',
+          message: 'Model refused available tools after corrective nudges',
         }
         yield doneEvent(false, stopReason)
         return
@@ -456,17 +457,17 @@ export async function* runRuntimeTurn(
         yield {
           type: 'continuation_nudge',
           attempt: continuationNudges,
-          reason: 'private_continuity_tool_repair',
+          reason: repairNudge.reason,
         }
         workingMessages = [
           ...await rebuildMessages(),
-          { role: 'user', content: repairNudge },
+          { role: 'user', content: repairNudge.text },
         ]
         continue
       }
       yield {
         type: 'error',
-        message: 'model called propose_private_continuity_edit with invalid input after corrective nudges',
+        message: repairNudge.failureMessage,
         discardAssistant: true,
       }
       yield doneEvent(false, stopReason)
@@ -485,26 +486,56 @@ function doneEvent(finishedNormally: boolean, stopReason?: TurnStopReason): Extr
   return { type: 'done', finishedNormally }
 }
 
+type RepairNudge = {
+  text: string
+  reason: ContinuationNudgeReason
+  failureMessage: string
+}
+
 function nextToolResultRepairNudge(
   provider: Pick<Provider, 'id' | 'supportsTools'>,
   completedTools: ExecutedToolUse[],
-): string | null {
+): RepairNudge | null {
   if (!provider.supportsTools) return null
   const failedPrivateEdit = completedTools.some(completed =>
     completed.name === 'propose_private_continuity_edit'
     && !completed.result.ok
     && completed.result.summary === 'propose_private_continuity_edit rejected input',
   )
-  if (failedPrivateEdit) return PRIVATE_CONTINUITY_REPAIR_NUDGE_TEXT
+  if (failedPrivateEdit) {
+    return {
+      text: PRIVATE_CONTINUITY_REPAIR_NUDGE_TEXT,
+      reason: 'private_continuity_tool_repair',
+      failureMessage: 'Model called propose_private_continuity_edit with invalid input after corrective nudges',
+    }
+  }
+
+  const failedWriteFile = completedTools.some(completed =>
+    completed.name === 'write_file'
+    && !completed.result.ok
+    && completed.result.summary === 'write_file rejected input',
+  )
+  if (failedWriteFile) {
+    return {
+      text: WRITE_FILE_REPAIR_NUDGE_TEXT,
+      reason: 'write_file_repair',
+      failureMessage: 'Model called write_file with invalid input after corrective nudges',
+    }
+  }
 
   const failedWorkspacePrivateRead = completedTools.some(completed =>
     completed.name === 'read_file'
     && !completed.result.ok
     && /read_private_continuity_file/.test(completed.result.content),
   )
-  return failedWorkspacePrivateRead
-    ? 'The previous read_file call targeted private identity continuity markdown. Retry now with read_private_continuity_file and complete input such as {"file":"MEMORY.md"} or {"file":"SOUL.md"}. Do not search workspace folders.'
-    : null
+  if (failedWorkspacePrivateRead) {
+    return {
+      text: 'The previous read_file call targeted private identity continuity markdown. Retry now with read_private_continuity_file and complete input such as {"file":"MEMORY.md"} or {"file":"SOUL.md"}. Do not search workspace folders.',
+      reason: 'private_continuity_tool_repair',
+      failureMessage: 'Model kept reading private continuity files via read_file after corrective nudges',
+    }
+  }
+  return null
 }
 
 export function parseLocalModelTextToolUse(

package/src/tools/changeDirectoryTool.ts

@@ -32,7 +32,7 @@ export const changeDirectoryTool: Tool<typeof schema> = {
       path: fullPath,
       relativePath: path.relative(context.workspaceRoot, fullPath) || path.basename(fullPath),
       directoryPath: path.dirname(fullPath),
-      title: 'allow directory change?',
+      title: 'Allow directory change?',
       subtitle: fullPath,
     }
   },

package/src/tools/contracts.ts

@@ -48,6 +48,16 @@ export type PermissionRequest =
       file: 'SOUL.md' | 'MEMORY.md'
       range: string
     }
+  | {
+      kind: 'private-skill-read'
+      path: string
+      relativePath: string
+      directoryPath: string
+      title: string
+      subtitle: string
+      skillName: string
+      mode: 'list' | 'read'
+    }
   | {
       kind: 'private-continuity-edit'
       path: string

package/src/tools/deleteFileTool.ts

@@ -32,7 +32,7 @@ export const deleteFileTool: Tool<typeof schema> = {
       path: prepared.fullPath,
       relativePath: prepared.relativePath,
       directoryPath: path.dirname(prepared.fullPath),
-      title: 'allow file delete?',
+      title: 'Allow file delete?',
       subtitle: prepared.fullPath,
       before: preview(prepared.before),
       after: '(deleted)',

package/src/tools/editTool.ts

@@ -41,7 +41,7 @@ export const editTool: Tool<typeof schema> = {
       path: fullPath,
       relativePath,
       directoryPath: path.dirname(fullPath),
-      title: 'allow file edit?',
+      title: 'Allow file edit?',
       subtitle: fullPath,
       before: applied.previewBefore,
       after: applied.previewAfter,

package/src/tools/listDirectoryTool.ts

@@ -31,7 +31,7 @@ export const listDirectoryTool: Tool<typeof schema> = {
       path: fullPath,
       relativePath,
       directoryPath: fullPath,
-      title: 'allow directory listing?',
+      title: 'Allow directory listing?',
       subtitle: fullPath,
     }
   },

package/src/tools/listSkillFilesTool.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod'
+import path from 'node:path'
+import {
+  continuityVaultRef,
+} from '../identity/continuity/storage.js'
+import { listSkillFiles } from '../identity/continuity/skills/loadSkills.js'
+import type { Tool } from './contracts.js'
+
+const schema = z.object({
+  name: z.string().min(1),
+})
+
+export const listSkillFilesTool: Tool<typeof schema> = {
+  name: 'list_private_skill_files',
+  kind: 'private-continuity-read',
+  readOnly: true,
+  description: [
+    'List every file inside a private skill folder for the active identity.',
+    'Returns each file as `- <relativePath> (<bytes>) — <absolutePath>`, including SKILL.md and any supporting files (references, examples, scripts).',
+    'Use this after list_private_skills shows a skill with `(+N supporting files)` to discover what is available, then call read_private_skill with `file` to load text content.',
+    'Pass the absolute path directly to run_bash to execute supporting scripts (e.g. `python "<absolutePath>" <args>`).',
+  ].join(' '),
+  inputSchema: schema,
+  inputSchemaJson: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', description: 'Skill folder name from the private skills index.' },
+    },
+    required: ['name'],
+    additionalProperties: false,
+  },
+  parse(input) {
+    return schema.parse(input)
+  },
+  async buildPermissionRequest(input, context) {
+    const identity = context.config?.identity
+    if (!identity) throw new Error('No active identity; create or load an identity before listing private skill files')
+    const ref = continuityVaultRef(identity)
+    const folder = input.name.replace(/^.*:/, '')
+    const skillDir = path.join(ref.skillsDir, folder)
+    return {
+      kind: 'private-skill-read',
+      path: skillDir,
+      relativePath: `identity-vault/skills/${folder}`,
+      directoryPath: skillDir,
+      title: 'Allow private skill folder list?',
+      subtitle: `List files in ${folder}/`,
+      skillName: input.name,
+      mode: 'list',
+    }
+  },
+  async execute(input, context) {
+    const identity = context.config?.identity
+    if (!identity) {
+      return { ok: false, summary: 'no active identity', content: 'No active identity; cannot list private skill files.' }
+    }
+    try {
+      const folder = input.name.replace(/^.*:/, '')
+      const files = await listSkillFiles(identity, folder)
+      if (files.length === 0) {
+        return { ok: true, summary: `no files in ${folder}`, content: `Skill folder ${folder}/ is empty or does not exist.` }
+      }
+      const lines = files.map(f => `- ${f.relativePath} (${f.sizeBytes} bytes) — ${f.absolutePath}`)
+      return {
+        ok: true,
+        summary: `listed ${files.length} file${files.length === 1 ? '' : 's'} in ${folder}`,
+        content: lines.join('\n'),
+      }
+    } catch (err: unknown) {
+      return {
+        ok: false,
+        summary: 'list failed',
+        content: (err as Error).message,
+      }
+    }
+  },
+}