typeclaw 0.12.0 → 0.14.0

package/src/config/mounts-mutation.ts

@@ -0,0 +1,161 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { commitSystemFileSync } from '@/git/system-commit'
+
+import {
+  configSchema,
+  expandMountPath,
+  loadConfigSyncOrDefaults,
+  mountSchema,
+  validateMount,
+  type Mount,
+} from './config'
+
+const CONFIG_FILE = 'typeclaw.json'
+const MOUNT_TARGET_PREFIX = '/agent/mounts'
+
+export type MountListEntry = Mount & {
+  resolvedPath: string
+  targetPath: string
+  status: 'ok' | 'error'
+  statusReason?: string
+}
+
+export type AddMountOptions = {
+  readOnly?: boolean
+  description?: string | undefined
+}
+
+export type AddMountResult = { ok: true; entry: MountListEntry } | { ok: false; reason: string }
+export type RemoveMountResult = { ok: true; removed: MountListEntry } | { ok: false; reason: string }
+
+export function listMounts(cwd: string): MountListEntry[] {
+  const mounts = loadConfigSyncOrDefaults(cwd).mounts
+  return mounts.map((mount) => toListEntry(mount, cwd))
+}
+
+export function addMount(cwd: string, name: string, path: string, options: AddMountOptions = {}): AddMountResult {
+  const mount = buildMount(name, path, options)
+  if (!mount.ok) return mount
+
+  const check = validateMount(mount.value, cwd)
+  if (!check.ok) return check
+
+  const parsed = readConfigRecord(cwd)
+  if (!parsed.ok) return parsed
+
+  const current = readMounts(parsed.value)
+  if (!current.ok) return current
+  if (current.value.some((m) => m.name === mount.value.name)) {
+    return {
+      ok: false,
+      reason: `Mount "${mount.value.name}" already exists. Remove it first with \`typeclaw mount remove ${mount.value.name}\`.`,
+    }
+  }
+
+  const next = { ...parsed.value, mounts: [...current.value, mount.value] }
+  const write = writeMounts(cwd, next, `mount: add ${mount.value.name}`)
+  if (!write.ok) return write
+  return { ok: true, entry: toListEntry(mount.value, cwd) }
+}
+
+export function removeMount(cwd: string, name: string): RemoveMountResult {
+  const trimmed = name.trim()
+  if (trimmed.length === 0) return { ok: false, reason: 'Mount name cannot be empty.' }
+
+  const parsed = readConfigRecord(cwd)
+  if (!parsed.ok) return parsed
+
+  const current = readMounts(parsed.value)
+  if (!current.ok) return current
+
+  const removed = current.value.find((m) => m.name === trimmed)
+  if (removed === undefined) return { ok: false, reason: `Mount "${trimmed}" not found in ${CONFIG_FILE}.` }
+
+  const next = { ...parsed.value, mounts: current.value.filter((m) => m.name !== trimmed) }
+  const write = writeMounts(cwd, next, `mount: remove ${trimmed}`)
+  if (!write.ok) return write
+  return { ok: true, removed: toListEntry(removed, cwd) }
+}
+
+function buildMount(
+  name: string,
+  path: string,
+  options: AddMountOptions,
+): { ok: true; value: Mount } | { ok: false; reason: string } {
+  const description = options.description?.trim()
+  const raw = {
+    name: name.trim(),
+    path,
+    readOnly: options.readOnly ?? false,
+    ...(description !== undefined && description.length > 0 ? { description } : {}),
+  }
+  const parsed = mountSchema.safeParse(raw)
+  if (!parsed.success) {
+    return { ok: false, reason: parsed.error.issues.map(formatIssue).join('; ') }
+  }
+  return { ok: true, value: parsed.data }
+}
+
+function readConfigRecord(cwd: string): { ok: true; value: Record<string, unknown> } | { ok: false; reason: string } {
+  try {
+    const raw = readFileSync(join(cwd, CONFIG_FILE), 'utf8')
+    const parsed = JSON.parse(raw) as unknown
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { ok: false, reason: `${CONFIG_FILE} must contain a JSON object.` }
+    }
+    return { ok: true, value: parsed as Record<string, unknown> }
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return { ok: false, reason: `${CONFIG_FILE} not found at ${cwd}. Run \`typeclaw init\` first.` }
+    }
+    return { ok: false, reason: `Failed to read ${CONFIG_FILE}: ${(error as Error).message}` }
+  }
+}
+
+function readMounts(record: Record<string, unknown>): { ok: true; value: Mount[] } | { ok: false; reason: string } {
+  const parsed = configSchema.safeParse(record)
+  if (!parsed.success) {
+    return { ok: false, reason: `${CONFIG_FILE} is invalid: ${parsed.error.issues.map(formatIssue).join('; ')}` }
+  }
+  return { ok: true, value: parsed.data.mounts }
+}
+
+function writeMounts(
+  cwd: string,
+  record: Record<string, unknown>,
+  commitMessage: string,
+): { ok: true } | { ok: false; reason: string } {
+  const parsed = configSchema.safeParse(record)
+  if (!parsed.success) {
+    return { ok: false, reason: `mounts block would be invalid: ${parsed.error.issues.map(formatIssue).join('; ')}` }
+  }
+
+  try {
+    writeFileSync(join(cwd, CONFIG_FILE), `${JSON.stringify(record, null, 2)}\n`)
+  } catch (error) {
+    return { ok: false, reason: `Failed to write ${CONFIG_FILE}: ${(error as Error).message}` }
+  }
+
+  commitSystemFileSync(cwd, CONFIG_FILE, commitMessage)
+  return { ok: true }
+}
+
+function toListEntry(mount: Mount, cwd: string): MountListEntry {
+  const resolvedPath = expandMountPath(mount.path, cwd)
+  const targetPath = `${MOUNT_TARGET_PREFIX}/${mount.name}`
+  const check = validateMount(mount, cwd)
+  return {
+    ...mount,
+    resolvedPath,
+    targetPath,
+    status: check.ok ? 'ok' : 'error',
+    ...(!check.ok ? { statusReason: check.reason } : {}),
+  }
+}
+
+function formatIssue(issue: { path: PropertyKey[]; message: string }): string {
+  const path = issue.path.length > 0 ? issue.path.map(String).join('.') : '<root>'
+  return `${path}: ${issue.message}`
+}

package/src/doctor/channel-checks.ts

@@ -0,0 +1,328 @@
+import { join } from 'node:path'
+
+import { type AdapterId, type ChannelsConfig } from '@/channels'
+import { loadConfigSync, validateConfig } from '@/config'
+import { readEnvFile } from '@/init'
+import { SecretsBackend } from '@/secrets'
+import { channelFieldDefaultEnv } from '@/secrets/defaults'
+
+import type { CheckContext, CheckResult, DoctorCheck } from './types'
+
+// Host-stage channel adapter health checks. These cannot talk to Slack /
+// Discord / Telegram / KakaoTalk / GitHub APIs — that work belongs to the
+// container-stage `start()` preflight on each adapter (see
+// `src/channels/manager.ts` and individual adapters). What doctor CAN do
+// from the host is verify that the credentials the container will look for
+// are actually present and resolvable, so the operator gets a clear,
+// before-`typeclaw start` signal instead of a silent skip in the runtime
+// logs.
+//
+// Every check is gated on `ctx.hasAgentFolder` (typeclaw.json is required to
+// read the channels config) and additionally on the adapter being declared
+// AND enabled in typeclaw.json. A missing or `enabled: false` adapter
+// reports `skipped` so the operator can see the check ran without it
+// turning into noise on minimal setups.
+
+export function buildChannelChecks(): DoctorCheck[] {
+  return [
+    slackBotCredentials(),
+    discordBotCredentials(),
+    telegramBotCredentials(),
+    kakaotalkCredentials(),
+    githubCredentials(),
+    githubWebhookDelivery(),
+  ]
+}
+
+function slackBotCredentials(): DoctorCheck {
+  return {
+    name: 'channel.slack-bot.credentials',
+    category: 'channels',
+    description: 'slack-bot adapter has SLACK_BOT_TOKEN and SLACK_APP_TOKEN',
+    applies: (ctx) => ctx.hasAgentFolder,
+    run: (ctx) => runTokenAdapterCheck(ctx, 'slack-bot', ['SLACK_BOT_TOKEN', 'SLACK_APP_TOKEN']),
+  }
+}
+
+function discordBotCredentials(): DoctorCheck {
+  return {
+    name: 'channel.discord-bot.credentials',
+    category: 'channels',
+    description: 'discord-bot adapter has DISCORD_BOT_TOKEN',
+    applies: (ctx) => ctx.hasAgentFolder,
+    run: (ctx) => runTokenAdapterCheck(ctx, 'discord-bot', ['DISCORD_BOT_TOKEN']),
+  }
+}
+
+function telegramBotCredentials(): DoctorCheck {
+  return {
+    name: 'channel.telegram-bot.credentials',
+    category: 'channels',
+    description: 'telegram-bot adapter has TELEGRAM_BOT_TOKEN',
+    applies: (ctx) => ctx.hasAgentFolder,
+    run: (ctx) => runTokenAdapterCheck(ctx, 'telegram-bot', ['TELEGRAM_BOT_TOKEN']),
+  }
+}
+
+function kakaotalkCredentials(): DoctorCheck {
+  return {
+    name: 'channel.kakaotalk.credentials',
+    category: 'channels',
+    description: 'kakaotalk adapter has at least one account in secrets.json',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const channels = readDeclaredChannels(ctx)
+      if (channels === null) return configInvalidResult()
+      if (!isAdapterActive(channels, 'kakaotalk')) {
+        return { status: 'skipped', message: 'kakaotalk not configured' }
+      }
+      const block = readChannelsSecrets(ctx)?.kakaotalk
+      const accountCount = block?.accounts ? Object.keys(block.accounts).length : 0
+      if (accountCount === 0) {
+        return {
+          status: 'warning',
+          message: 'kakaotalk has no accounts in secrets.json',
+          details: ['Adapter will start but fail authentication and stay disconnected.'],
+          fix: { description: 'Run `typeclaw channel add kakaotalk` to log in an account.' },
+        }
+      }
+      return { status: 'ok', message: `kakaotalk has ${accountCount} account(s)` }
+    },
+  }
+}
+
+function githubCredentials(): DoctorCheck {
+  return {
+    name: 'channel.github.credentials',
+    category: 'channels',
+    description: 'github adapter has auth and webhookSecret in secrets.json',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const channels = readDeclaredChannels(ctx)
+      if (channels === null) return configInvalidResult()
+      if (!isAdapterActive(channels, 'github')) {
+        return { status: 'skipped', message: 'github not configured' }
+      }
+      const block = readChannelsSecrets(ctx)?.github
+      if (!block) {
+        return {
+          status: 'error',
+          message: 'github secrets missing from secrets.json',
+          details: ['Adapter requires both `auth` and `webhookSecret`.'],
+          fix: { description: 'Run `typeclaw channel set github` to configure GitHub auth.' },
+        }
+      }
+      const dotEnv = safeReadEnvFile(ctx.cwd)
+      const details: string[] = []
+      const webhookSecret = resolveSecretHostStage(block.webhookSecret, dotEnv)
+      if (webhookSecret === undefined || webhookSecret === '') {
+        details.push('webhookSecret is unset (resolves to empty string)')
+      }
+      if (block.auth.type === 'pat') {
+        const token = resolveSecretHostStage(block.auth.token, dotEnv)
+        if (token === undefined || token === '') {
+          details.push('auth.token (PAT) is unset (resolves to empty string)')
+        }
+      } else {
+        const key = resolveSecretHostStage(block.auth.privateKey, dotEnv)
+        if (key === undefined || key === '') {
+          details.push('auth.privateKey (App) is unset (resolves to empty string)')
+        }
+      }
+      if (details.length > 0) {
+        return {
+          status: 'error',
+          message: 'github credentials present but some fields resolve to empty',
+          details,
+          fix: { description: 'Run `typeclaw channel set github` to repopulate the missing fields.' },
+        }
+      }
+      return {
+        status: 'ok',
+        message: `github ${block.auth.type === 'pat' ? 'PAT' : 'App'} auth + webhookSecret resolved`,
+      }
+    },
+  }
+}
+
+function githubWebhookDelivery(): DoctorCheck {
+  return {
+    name: 'channel.github.webhook-delivery',
+    category: 'channels',
+    description: 'github webhook delivery has a public URL (webhookUrl or tunnel)',
+    applies: (ctx) => ctx.hasAgentFolder,
+    async run(ctx) {
+      const cfg = safeLoadConfig(ctx)
+      if (cfg === null) return configInvalidResult()
+      const github = cfg.channels.github
+      if (github === undefined || github.enabled === false) {
+        return { status: 'skipped', message: 'github not configured' }
+      }
+      const hasWebhookUrl = typeof github.webhookUrl === 'string' && github.webhookUrl.length > 0
+      const hasTunnel = cfg.tunnels.some((t) => t.for.kind === 'channel' && t.for.name === 'github')
+      if (hasWebhookUrl || hasTunnel) {
+        const source = hasWebhookUrl ? 'webhookUrl' : 'tunnel'
+        return { status: 'ok', message: `github webhook delivery configured via ${source}` }
+      }
+      if (github.repos.length === 0) {
+        return {
+          status: 'info',
+          message: 'github has no webhookUrl or tunnel, and no repos to register',
+          details: ['Webhooks will not be auto-registered until either webhookUrl or a tunnel binding is set.'],
+        }
+      }
+      return {
+        status: 'warning',
+        message: `github lists ${github.repos.length} repo(s) but has no public URL to deliver webhooks to`,
+        details: [
+          'Either set `channels.github.webhookUrl` in typeclaw.json,',
+          'or add a `tunnels[]` entry with `for: { kind: "channel", name: "github" }`.',
+        ],
+        fix: {
+          description: 'Configure webhookUrl or a github tunnel; see `typeclaw tunnel add` for managed tunnels.',
+        },
+      }
+    },
+  }
+}
+
+async function runTokenAdapterCheck(
+  ctx: CheckContext,
+  adapter: Extract<AdapterId, 'slack-bot' | 'discord-bot' | 'telegram-bot'>,
+  envNames: readonly string[],
+): Promise<CheckResult> {
+  const channels = readDeclaredChannels(ctx)
+  if (channels === null) return configInvalidResult()
+  if (!isAdapterActive(channels, adapter)) {
+    return { status: 'skipped', message: `${adapter} not configured` }
+  }
+  const dotEnv = safeReadEnvFile(ctx.cwd)
+  const channelSecrets = readChannelsSecrets(ctx)
+  const adapterSecrets = (channelSecrets?.[adapter] ?? {}) as Record<string, unknown>
+  const missing: string[] = []
+  for (const envName of envNames) {
+    if (hasTokenForEnv(adapter, envName, dotEnv, adapterSecrets)) continue
+    missing.push(envName)
+  }
+  if (missing.length > 0) {
+    return {
+      status: 'warning',
+      message: `${adapter} missing credentials: ${missing.join(', ')}`,
+      details: [
+        'Adapter will be skipped at start until credentials are present.',
+        'Resolution order: process.env wins over .env file value over secrets.json value.',
+      ],
+      fix: { description: 'Run `typeclaw channel set ' + adapter + '`, or add the env vars to .env.' },
+    }
+  }
+  return { status: 'ok', message: `${adapter} credentials present` }
+}
+
+// hasTokenForEnv resolves a single env-var-style credential the same way the
+// runtime does, plus one host-stage-specific source: process.env > .env file >
+// secrets.json. Empty strings count as unset, matching `src/secrets/resolve.ts`.
+function hasTokenForEnv(
+  adapter: AdapterId,
+  envName: string,
+  dotEnv: Map<string, string>,
+  adapterSecrets: Record<string, unknown>,
+): boolean {
+  const fromProcess = process.env[envName]
+  if (fromProcess !== undefined && fromProcess !== '') return true
+  const fromDotEnv = dotEnv.get(envName)
+  if (fromDotEnv !== undefined && fromDotEnv !== '') return true
+  const fieldName = fieldNameForEnv(adapter, envName)
+  if (fieldName === undefined) return false
+  const secret = adapterSecrets[fieldName]
+  if (!isSecretShape(secret)) return false
+  const resolved = resolveSecretHostStage(secret, dotEnv, envName)
+  return resolved !== undefined && resolved !== ''
+}
+
+// resolveSecretHostStage mirrors `resolveSecret` precedence but adds a .env
+// lookup before falling through to process.env. Doctor runs on the host and
+// never executes the container, so .env values are not in process.env. For
+// Secrets bound to a custom env var (e.g. `{ env: 'MY_TOKEN' }`), the runtime
+// would resolve via process.env.MY_TOKEN inside the container — on the host
+// that yields undefined even when the value is sitting in .env. So look up
+// the custom env name in the parsed .env map first.
+function resolveSecretHostStage(
+  secret: { value?: string; env?: string },
+  dotEnv: Map<string, string>,
+  defaultEnv?: string,
+): string | undefined {
+  const envName = secret.env ?? defaultEnv
+  if (envName !== undefined) {
+    const fromProcess = process.env[envName]
+    if (fromProcess !== undefined && fromProcess !== '') return fromProcess
+    const fromDotEnv = dotEnv.get(envName)
+    if (fromDotEnv !== undefined && fromDotEnv !== '') return fromDotEnv
+  }
+  return secret.value
+}
+
+function fieldNameForEnv(adapter: AdapterId, envName: string): string | undefined {
+  // Reverse-lookup using channelFieldDefaultEnv: scan the small set of known
+  // fields per adapter for the one whose default env matches. The set is
+  // tiny (1-2 entries) so the linear scan is fine.
+  const candidates: Record<string, readonly string[]> = {
+    'slack-bot': ['botToken', 'appToken'],
+    'discord-bot': ['token'],
+    'telegram-bot': ['token'],
+  }
+  const fields = candidates[adapter]
+  if (!fields) return undefined
+  for (const field of fields) {
+    if (channelFieldDefaultEnv(adapter, field) === envName) return field
+  }
+  return undefined
+}
+
+function isSecretShape(value: unknown): value is { value?: string; env?: string } {
+  if (typeof value !== 'object' || value === null) return false
+  const obj = value as Record<string, unknown>
+  const hasValue = typeof obj['value'] === 'string'
+  const hasEnv = typeof obj['env'] === 'string'
+  return hasValue || hasEnv
+}
+
+function readDeclaredChannels(ctx: CheckContext): ChannelsConfig | null {
+  const cfg = safeLoadConfig(ctx)
+  return cfg?.channels ?? null
+}
+
+function safeLoadConfig(ctx: CheckContext): ReturnType<typeof loadConfigSync> | null {
+  const result = validateConfig(ctx.cwd)
+  if (!result.ok) return null
+  try {
+    return loadConfigSync(ctx.cwd)
+  } catch {
+    return null
+  }
+}
+
+function safeReadEnvFile(cwd: string): Map<string, string> {
+  try {
+    return readEnvFile(cwd)
+  } catch {
+    return new Map()
+  }
+}
+
+function readChannelsSecrets(ctx: CheckContext): ReturnType<SecretsBackend['tryReadChannelsSync']> {
+  try {
+    return new SecretsBackend(join(ctx.cwd, 'secrets.json')).tryReadChannelsSync()
+  } catch {
+    return null
+  }
+}
+
+function isAdapterActive(channels: ChannelsConfig, adapter: AdapterId): boolean {
+  const slot = channels[adapter]
+  if (slot === undefined) return false
+  return slot.enabled !== false
+}
+
+function configInvalidResult(): CheckResult {
+  return { status: 'skipped', message: 'config invalid (covered by config.valid)' }
+}

package/src/doctor/checks.ts

@@ -21,6 +21,7 @@ import { buildDockerfile, DOCKERFILE } from '@/init/dockerfile'
 import { detectMissingDeps } from '@/init/ensure-deps'
 import { buildGitignore, GITIGNORE_FILE } from '@/init/gitignore'
 
+import { buildChannelChecks } from './channel-checks'
 import type { DoctorCheck } from './types'
 
 export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): DoctorCheck[] {
@@ -40,6 +41,7 @@ export function buildStaticChecks(opts: { dockerExec?: DockerExec } = {}): Docto
     hostdRegistration(),
     containerState(dockerExec),
     containerHostPort(),
+    ...buildChannelChecks(),
   ]
 }
 

package/src/init/dockerfile.ts

@@ -1,4 +1,9 @@
 import type { DockerfileConfig, DockerfileFeatureToggle } from '@/config/config'
+import {
+  CLAUDE_CREDENTIALS_FILE_NAME,
+  CLAUDE_CREDENTIALS_RELATIVE_PATH,
+  CLAUDE_DEFAULT_CONFIG_DIR_NAME,
+} from '@/secrets/export-claude-credentials-file'
 
 import { GHCR_BASE_IMAGE_REPO } from './cli-version'
 
@@ -283,13 +288,19 @@ set -eu
 #                           no inbound exposure anyway.
 # link_persistent_home_files symlinks credential files that tools write
 # to $HOME into a bind-mounted location so they survive container
-# restarts. The canonical case is Codex CLI's ~/.codex/auth.json: codex
-# rewrites the file in place to rotate OAuth tokens, and the official
-# CI/CD guidance is to persist auth.json so refresh-token state
-# compounds across runs. The container's $HOME (/root by default) lives
-# on Docker's writable overlay and is wiped on every \`stop\`+\`start\`
-# cycle, so without this symlink the operator would have to re-paste
-# auth.json after every restart.
+# restarts. The container's $HOME (/root by default) lives on Docker's
+# writable overlay and is wiped on every \`stop\`+\`start\` cycle, so
+# without this symlink the operator would have to re-paste credentials
+# after every restart.
+#
+# Two files are linked today, both following the same contract:
+#   - ~/.codex/auth.json — Codex CLI rotates OAuth tokens in place by
+#     rewriting auth.json with refreshed credentials.
+#   - $CLAUDE_CONFIG_DIR/.credentials.json, or ~/.claude/.credentials.json
+#     by default — Claude Code rotates OAuth tokens in place by rewriting
+#     .credentials.json on every successful refresh (anthropics/claude-code
+#     #53063). Linux/Windows path; macOS uses the Keychain entry "Claude
+#     Code-credentials" with the same JSON shape.
 #
 # The persist root lives under /agent/.typeclaw/home/ (bind-mounted
 # from the agent folder via the -v <cwd>:/agent flag in start.ts).
@@ -329,6 +340,12 @@ link_persistent_home_files() {
   persist_root="\${TYPECLAW_PERSIST_HOME_ROOT:-/agent/.typeclaw/home}"
   mkdir -p "$persist_root/.codex" "$HOME/.codex"
   ln -sfn "$persist_root/.codex/auth.json" "$HOME/.codex/auth.json"
+  claude_config_dir="\${CLAUDE_CONFIG_DIR:-}"
+  if [ -z "$claude_config_dir" ]; then
+    claude_config_dir="$HOME/${CLAUDE_DEFAULT_CONFIG_DIR_NAME}"
+  fi
+  mkdir -p "$persist_root/${CLAUDE_DEFAULT_CONFIG_DIR_NAME}" "$claude_config_dir"
+  ln -sfn "$persist_root/${CLAUDE_CREDENTIALS_RELATIVE_PATH}" "$claude_config_dir/${CLAUDE_CREDENTIALS_FILE_NAME}"
 }
 
 start_xvfb() {

package/src/init/hatching.ts

@@ -38,7 +38,7 @@ Routing answers:
    1. \`write\` your name into \`IDENTITY.md\` (a first-person one-liner is fine: "I am <name>.").
    2. ${q1AliasStep} The agent folder's directory name is already an implicit alias — only add the answered name explicitly when it differs from the dir name (different casing, a different word, or extra forms like "<name>" plus a Latin transliteration). This wires plain-text addressing in channels: when a user writes your name in chat without an @-mention, the engagement layer will recognize it. \`alias\` is live-reloadable.
 2. **Q2 — the user's name.** Ask what to call them. After the answer: \`write\` it to both \`IDENTITY.md\` and \`USER.md\`.
-3. **Q3 — tone/personality.** Ask how they want you to show up (tone, language, formality). After the answer: \`write\` it into \`SOUL.md\`. If they shrug or don't care: **default to warm, friendly, and easygoing** — a kind colleague who genuinely likes the person they work with, uses contractions, makes small jokes, never stiff. Write that as the default into \`SOUL.md\`.
+3. **Q3 — tone/personality.** Ask how they want you to show up (tone, language, formality). After the answer: \`write\` it into \`SOUL.md\`. If they shrug or don't care: **default to warm, friendly, and easygoing** — a kind colleague who genuinely likes the person they work with, uses contractions, makes small jokes, never stiff. Write that as the default into \`SOUL.md\`. **Kaomoji affinity** — if their answer leans cute, adorable, warm, playful, soft, cozy, or is in Korean asking for 친근/귀엽/다정한 tone, append a line to \`SOUL.md\` like: \`I lean on kaomojis like (◕‿◕✿) and (｡･ω･｡) to carry warmth — emojis still welcome when they actually mean something, but kaomojis lead.\` This makes the bundled \`typeclaw-kaomoji\` skill auto-load later when you need it. Do not force this line if the user asked for a neutral, professional, or terse tone.
 
 **Do not ask what they want you to do, what project you'll work on, or why they installed you.** That reveals itself when they give you a real task. Probing here makes the tool feel heavy for someone just trying it out.
 

package/src/plugin/index.ts

@@ -75,6 +75,12 @@ export type { PermissionService } from '@/permissions'
 export type { LoadPluginEntryFn, ResolvedPlugin } from './loader'
 export { loadPluginEntry, derivePluginNameFromPackage } from './loader'
 export { materializeSkills, type MaterializedSkills, type SkillEntry } from './skills'
+export {
+  createLoadSkillTool,
+  type CreateLoadSkillToolOptions,
+  type LoadableSkill,
+  type LoadSkillArgs,
+} from './load-skill'
 export {
   buildPluginCronGlobalId,
   RESERVED_COMMAND_NAMES,

package/src/plugin/load-skill.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod'
+
+import { defineTool } from './define'
+import type { Tool } from './types'
+
+// One unit of curated skill content a subagent can load on demand. The
+// `name` becomes a value in the tool's `name` enum; `description` is what
+// the model sees in the tool description block so it can decide which
+// skill to load WITHOUT having to load it first; `content` is the body
+// returned by the tool when the model picks this skill.
+export type LoadableSkill = {
+  name: string
+  description: string
+  content: string
+}
+
+export type CreateLoadSkillToolOptions = {
+  skills: readonly LoadableSkill[]
+  // Override the tool's top-level description. Defaults to a generic
+  // explanation of how the tool works followed by the per-skill menu.
+  // Plugins can pass a more specific framing (e.g. "Load a review skill
+  // …") so the subagent's instructions line up with the tool name.
+  description?: string
+}
+
+export type LoadSkillArgs = { name: string }
+
+// Build a typed `load_skill` tool a subagent can call to fetch the body
+// of a curated skill on demand. The factory closes over the `skills`
+// list so:
+//   - the `name` parameter is a Zod enum narrowed to exactly the skill
+//     names the caller supplied (typo-resistant; the model sees the
+//     allowed values in the tool's JSON Schema),
+//   - the tool's `description` lists every skill's name + description so
+//     the model can choose the right one BEFORE calling the tool, paying
+//     only one tool-call's worth of context for the body it actually
+//     needs,
+//   - unknown names are rejected by parameter validation, not by the
+//     handler — the runtime returns the validation error before
+//     `execute` runs.
+//
+// This is the runtime-loaded counterpart to TypeClaw's startup-time
+// skill discovery (`additionalSkillPaths` in `src/agent/index.ts`).
+// Subagents bypass the file-based resource loader, so the startup path
+// is unavailable to them; this factory gives plugin authors a typed way
+// to expose curated skills to their subagents via `customTools`.
+export function createLoadSkillTool(options: CreateLoadSkillToolOptions): Tool<LoadSkillArgs> {
+  const { skills } = options
+
+  if (skills.length === 0) {
+    throw new Error('createLoadSkillTool: `skills` must contain at least one entry')
+  }
+
+  const seen = new Set<string>()
+  for (const skill of skills) {
+    if (skill.name.length === 0) {
+      throw new Error('createLoadSkillTool: skill name must be non-empty')
+    }
+    if (seen.has(skill.name)) {
+      throw new Error(`createLoadSkillTool: duplicate skill name ${JSON.stringify(skill.name)}`)
+    }
+    seen.add(skill.name)
+  }
+
+  // z.enum requires a `[string, ...string[]]` tuple. Build it from the
+  // skill list so the JSON Schema surfaced to the model lists exactly
+  // the allowed values.
+  const names = skills.map((s) => s.name) as [string, ...string[]]
+
+  const description = options.description ?? buildDefaultDescription(skills)
+
+  return defineTool<LoadSkillArgs>({
+    description,
+    parameters: z.object({
+      name: z.enum(names).describe('The name of the skill to load. Must match one of the available skills.'),
+    }),
+    async execute(args) {
+      const skill = skills.find((s) => s.name === args.name)
+      if (skill === undefined) {
+        // Defensive: Zod enum validation should have rejected this
+        // before reaching the handler. Surface a clear message anyway.
+        const available = names.join(', ')
+        throw new Error(`Unknown skill ${JSON.stringify(args.name)}. Available skills: ${available}.`)
+      }
+      return {
+        content: [{ type: 'text' as const, text: skill.content }],
+        details: { name: skill.name, contentBytes: skill.content.length },
+      }
+    },
+  })
+}
+
+function buildDefaultDescription(skills: readonly LoadableSkill[]): string {
+  const menu = skills.map((s) => `- \`${s.name}\` — ${s.description}`).join('\n')
+  return `Load a curated skill by name. Returns the full skill body as text so you can apply it to the current task. Call this when you have identified which skill matches the task; do NOT load multiple skills speculatively.
+
+Available skills:
+${menu}`
+}