typeclaw 0.13.0 → 0.15.0

package/src/sandbox/policy.ts

@@ -0,0 +1,47 @@
+export type SandboxMount =
+  | { type: 'ro-bind'; source: string; dest: string }
+  | { type: 'bind'; source: string; dest: string }
+  | { type: 'tmpfs'; dest: string }
+  | { type: 'dev'; dest: string }
+
+export type SandboxNetwork = 'none' | 'inherit'
+
+export type SandboxProcStrategy = 'tmpfs' | 'none'
+
+export type SandboxEnvPolicy = {
+  set?: Record<string, string>
+  passthrough?: string[]
+}
+
+export type SandboxCommandFilter = {
+  allowPrefixes?: string[]
+  rejectShellMetacharacters?: boolean
+}
+
+export type SandboxProcessPolicy = {
+  newSession?: boolean
+  dieWithParent?: boolean
+}
+
+export type SandboxPolicy = {
+  bwrapPath?: string
+  cwd?: string
+  mounts?: SandboxMount[]
+  network?: SandboxNetwork
+  env?: SandboxEnvPolicy
+  commandFilter?: SandboxCommandFilter
+  process?: SandboxProcessPolicy
+  proc?: SandboxProcStrategy
+}
+
+// The env the sandbox always re-introduces after `--clearenv`. Anything not
+// listed here (or explicitly named in `env.set` / `env.passthrough` by the
+// consumer) is invisible inside the sandbox. This is the load-bearing leak
+// guard: the container env holds FIREWORKS_API_KEY and GH_TOKEN, and env
+// inheritance is the single highest-risk exfil path for prompt-injected bash.
+// HOME points at /tmp because the sandbox mounts /tmp as a fresh tmpfs.
+export const DEFAULT_SANDBOX_ENV: Record<string, string> = {
+  PATH: '/usr/local/bin:/usr/bin:/bin',
+  HOME: '/tmp',
+  LANG: 'C.UTF-8',
+}

package/src/sandbox/quote.ts

@@ -0,0 +1,18 @@
+// POSIX shell quoting for rendering a bwrap argv array into a single
+// `bash -c`-safe string. Today's bash tool accepts a string `command` slot
+// (`mutableArgs.command`), so the sandbox primitive renders its canonical
+// argv into a quoted string the agent runtime can drop in unchanged.
+//
+// This is a local copy of the same helper in `src/update/index.ts`. It is
+// deliberately not promoted to a shared module yet: two call sites do not
+// justify the coupling, and this primitive is meant to stand alone with zero
+// imports from the rest of the tree. Promote to `src/shared/shell.ts` only
+// when a third independent consumer appears.
+export function shellQuote(arg: string): string {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg)) return arg
+  return `'${arg.replaceAll("'", "'\\''")}'`
+}
+
+export function formatCommand(argv: readonly string[]): string {
+  return argv.map(shellQuote).join(' ')
+}

package/src/secrets/claude-credentials-json.ts

@@ -0,0 +1,129 @@
+import type { ProviderCredential } from './schema'
+
+// Emit the on-disk shape Claude Code consumes at ~/.claude/.credentials.json
+// (Linux/Windows; macOS keeps this same JSON inside the Keychain entry
+// "Claude Code-credentials"). The single required top-level key is
+// `claudeAiOauth`. Field names use camelCase, not snake_case — diverging
+// from Codex CLI's `tokens.access_token` shape but matching every
+// third-party Claude Code integration we surveyed (ATLAS_OS, OmniRoute,
+// jcode, paperclip, opencode-claude-auth).
+//
+// `expiresAt` is MILLISECONDS since epoch, not seconds and not ISO. The
+// CLI carries no top-level expiry field outside `claudeAiOauth` — token
+// expiry is recorded both as `expiresAt` here and embedded in the JWT
+// `exp` claim of `accessToken`. The runtime exporter (export-claude-
+// credentials-file.ts) uses the JWT exp for its newer-wins compare,
+// mirroring the Codex CLI exporter's approach, because `expiresAt` is
+// the field Claude Code itself rewrites on in-place refresh.
+//
+// `mcpOAuth` (MCP server OAuth state) may coexist alongside
+// `claudeAiOauth` in the same file. This emitter accepts an optional
+// `preserveMcpOAuth` block so callers that read-merge-write the file
+// don't drop unrelated state. Codex CLI's file is fully owned by the
+// OAuth credential and has no equivalent; this is the one extra
+// complication versus emitCodexAuthJson.
+export type ClaudeAiOauthBlock = {
+  accessToken: string
+  refreshToken: string
+  expiresAt: number
+  scopes?: string[]
+  subscriptionType?: string
+}
+
+export type EmitClaudeCredentialsJsonOptions = {
+  preserveMcpOAuth?: unknown
+}
+
+export function emitClaudeCredentialsJson(
+  credential: ProviderCredential,
+  options: EmitClaudeCredentialsJsonOptions = {},
+): string {
+  if (credential.type !== 'oauth') {
+    throw new Error('emitClaudeCredentialsJson only accepts oauth-typed credentials')
+  }
+  const fields = credential as ProviderCredential & {
+    access?: unknown
+    refresh?: unknown
+    expires?: unknown
+    scopes?: unknown
+    subscriptionType?: unknown
+  }
+  const access = fields.access
+  const refresh = fields.refresh
+  if (typeof access !== 'string' || access.length === 0) {
+    throw new Error('credential is missing a non-empty `access` field')
+  }
+  if (typeof refresh !== 'string' || refresh.length === 0) {
+    throw new Error('credential is missing a non-empty `refresh` field')
+  }
+
+  // Resolution order for `expiresAt`:
+  //   1. `expires` on the credential (pi-ai writes absolute ms epoch here).
+  //   2. JWT `exp` claim decoded from `access`.
+  //   3. 0 — Claude Code treats a missing/zero expiry as "expired" and
+  //      triggers an immediate refresh on next use, which is the safe
+  //      fallback when neither source is available.
+  const expiresAt = readExpiryMs(fields, access)
+
+  const claudeAiOauth: ClaudeAiOauthBlock = {
+    accessToken: access,
+    refreshToken: refresh,
+    expiresAt,
+  }
+  if (Array.isArray(fields.scopes) && fields.scopes.every((s): s is string => typeof s === 'string')) {
+    claudeAiOauth.scopes = fields.scopes
+  }
+  if (typeof fields.subscriptionType === 'string' && fields.subscriptionType.length > 0) {
+    claudeAiOauth.subscriptionType = fields.subscriptionType
+  }
+
+  // Read-merge-write: preserve any existing `mcpOAuth` block the caller
+  // supplied. The emitter doesn't read disk itself (that's the exporter's
+  // job); the caller passes whatever it found at the existing file path.
+  const out: Record<string, unknown> = { claudeAiOauth }
+  if (options.preserveMcpOAuth !== undefined) {
+    out['mcpOAuth'] = options.preserveMcpOAuth
+  }
+  return `${JSON.stringify(out, null, 2)}\n`
+}
+
+// Extracts the JWT `exp` claim (seconds since epoch) and converts to ms.
+// Used by the runtime exporter's newer-wins compare and by emit's
+// `expiresAt` fallback. Returns null on any decode failure; the caller
+// treats that as "unknown freshness". Logic mirrors
+// decodeCodexAccessTokenExpiryMs verbatim — Claude Code OAuth access
+// tokens are standard JWTs with the same base64url-encoded payload
+// shape Codex uses.
+export function decodeClaudeAccessTokenExpiryMs(accessToken: string): number | null {
+  const parts = accessToken.split('.')
+  if (parts.length !== 3) return null
+  const middle = parts[1] ?? ''
+  if (middle === '') return null
+  const normalized = middle.replace(/-/g, '+').replace(/_/g, '/')
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4)
+  let payload: Record<string, unknown>
+  try {
+    const decoded = typeof atob === 'function' ? atob(padded) : Buffer.from(padded, 'base64').toString('utf8')
+    const parsed: unknown = JSON.parse(decoded)
+    if (!isPlainObject(parsed)) return null
+    payload = parsed
+  } catch {
+    return null
+  }
+  const exp = payload['exp']
+  if (typeof exp !== 'number' || !Number.isFinite(exp)) return null
+  return Math.floor(exp * 1000)
+}
+
+function readExpiryMs(fields: { expires?: unknown }, accessToken: string): number {
+  if (typeof fields.expires === 'number' && Number.isFinite(fields.expires)) {
+    return fields.expires
+  }
+  const fromJwt = decodeClaudeAccessTokenExpiryMs(accessToken)
+  if (fromJwt !== null) return fromJwt
+  return 0
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/src/secrets/export-claude-credentials-file.ts

@@ -0,0 +1,279 @@
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  readlinkSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, isAbsolute, join, resolve } from 'node:path'
+
+import { decodeClaudeAccessTokenExpiryMs, emitClaudeCredentialsJson } from './claude-credentials-json'
+import type { ProviderCredential, Providers } from './schema'
+import { SecretsBackend } from './storage'
+
+const FILE_MODE = 0o600
+const DIR_MODE = 0o700
+export const CLAUDE_CREDENTIALS_FILE_NAME = '.credentials.json'
+export const CLAUDE_DEFAULT_CONFIG_DIR_NAME = '.claude'
+export const CLAUDE_CREDENTIALS_RELATIVE_PATH = join(CLAUDE_DEFAULT_CONFIG_DIR_NAME, CLAUDE_CREDENTIALS_FILE_NAME)
+
+export type ExportClaudeCredentialsFileResult =
+  | { action: 'skipped'; reason: SkipReason }
+  | { action: 'wrote'; path: string }
+  | { action: 'failed'; reason: string }
+
+export type SkipReason =
+  | 'claude-code-disabled'
+  | 'no-anthropic-credential'
+  | 'credential-not-oauth'
+  | 'on-disk-is-fresher'
+
+export type ExportClaudeCredentialsFileOptions = {
+  claudeCodeEnabled: boolean
+  providers: Providers
+  homeDir?: string
+  configDir?: string
+  now?: () => number
+  log?: (message: string) => void
+}
+
+// Writes typeclaw's anthropic OAuth credential to
+// $CLAUDE_CONFIG_DIR/.credentials.json (or $HOME/.claude/.credentials.json
+// by default) when it's safe to do so. The Dockerfile entrypoint shim
+// symlinks the same resolved credentials path to
+// /agent/.typeclaw/home/.claude/.credentials.json on every boot, so the
+// write follows the symlink and lands on the persistent host-side path —
+// same contract as exportCodexAuthFile.
+//
+// Three guards, cheapest first. The first two return without ever touching
+// the filesystem, which keeps the 90% case (users who don't enable
+// Claude Code) at zero overhead on every container start.
+export function exportClaudeCredentialsFileIfApplicable(
+  options: ExportClaudeCredentialsFileOptions,
+): ExportClaudeCredentialsFileResult {
+  if (!options.claudeCodeEnabled) return { action: 'skipped', reason: 'claude-code-disabled' }
+
+  const credential = options.providers['anthropic']
+  if (credential === undefined) return { action: 'skipped', reason: 'no-anthropic-credential' }
+  if (credential.type !== 'oauth') return { action: 'skipped', reason: 'credential-not-oauth' }
+
+  const targetPath = resolveClaudeCredentialsPath({
+    ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+    ...(options.configDir !== undefined ? { configDir: options.configDir } : {}),
+  })
+
+  try {
+    const existing = readExisting(targetPath)
+    if (!shouldOverwrite(existing, credential, options.now ?? Date.now)) {
+      return { action: 'skipped', reason: 'on-disk-is-fresher' }
+    }
+    const mcpOAuthOpt = existing?.mcpOAuth !== undefined ? { preserveMcpOAuth: existing.mcpOAuth } : {}
+    const contents = emitClaudeCredentialsJson(credential, mcpOAuthOpt)
+    writeAtomic(targetPath, contents)
+    return { action: 'wrote', path: targetPath }
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    options.log?.(`exportClaudeCredentialsFile: ${reason}`)
+    return { action: 'failed', reason }
+  }
+}
+
+type ExistingFile = {
+  onDiskAccessToken: string | null
+  onDiskExpiresAt: number | null
+  mcpOAuth: unknown
+}
+
+// Read once, parse once. Returns null when the file is missing OR
+// unparseable. Returning null short-circuits both branches of the
+// overwrite decision (the no-disk-file recovery path) AND drops any
+// non-recoverable mcpOAuth state — but if the file is unparseable
+// there's nothing to recover anyway. When parsing succeeds, we hand
+// back the access token (for the newer-wins compare) and the raw
+// mcpOAuth block (for read-merge-write preservation).
+function readExisting(targetPath: string): ExistingFile | null {
+  let raw: string
+  try {
+    raw = readFileSync(targetPath, 'utf8')
+  } catch {
+    return null
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  if (typeof parsed !== 'object' || parsed === null) return null
+  const obj = parsed as Record<string, unknown>
+  const claudeBlock = obj['claudeAiOauth']
+  let onDiskAccessToken: string | null = null
+  let onDiskExpiresAt: number | null = null
+  if (typeof claudeBlock === 'object' && claudeBlock !== null) {
+    const claudeObj = claudeBlock as Record<string, unknown>
+    const access = claudeObj['accessToken']
+    if (typeof access === 'string' && access.length > 0) onDiskAccessToken = access
+    const expiresAt = claudeObj['expiresAt']
+    if (typeof expiresAt === 'number' && Number.isFinite(expiresAt) && expiresAt > 0) {
+      onDiskExpiresAt = expiresAt
+    }
+  }
+  return { onDiskAccessToken, onDiskExpiresAt, mcpOAuth: obj['mcpOAuth'] }
+}
+
+// Newer-wins: skip the write unless typeclaw's stored credential is
+// strictly fresher than the on-disk expiry. Claude Code rotates tokens
+// in-place (issue #53063 in anthropics/claude-code confirms it rewrites
+// .credentials.json with a fresher accessToken/refreshToken/expiresAt
+// on every successful refresh), so on a restart the file may legitimately
+// be ahead of secrets.json. We must not clobber that.
+//
+// Ties skip: when expiries match there's nothing to gain from a write,
+// and avoiding the I/O keeps the steady state at zero churn.
+//
+// existing === null OR existing.onDiskAccessToken === null OR expiry
+// undecodable from both expiresAt and JWT → return true. That's the "we
+// have a valid credential, the file is unusable, replace it" recovery case.
+function shouldOverwrite(
+  existing: ExistingFile | null,
+  credential: ProviderCredential & { expires?: unknown; access?: unknown },
+  now: () => number,
+): boolean {
+  if (existing === null) return true
+  if (existing.onDiskAccessToken === null) return true
+  const onDiskExpiry = readOnDiskExpiry(existing)
+  if (onDiskExpiry === null) return true
+  const credentialExpiry = readCredentialExpiry(credential, now)
+  return credentialExpiry > onDiskExpiry
+}
+
+function readOnDiskExpiry(existing: ExistingFile): number | null {
+  if (existing.onDiskExpiresAt !== null) return existing.onDiskExpiresAt
+  if (existing.onDiskAccessToken === null) return null
+  return decodeClaudeAccessTokenExpiryMs(existing.onDiskAccessToken)
+}
+
+// Resolution order for the credential's expiry:
+//   1. The `expires` field pi-ai writes (absolute ms epoch).
+//   2. The JWT `exp` claim decoded from `access`.
+//   3. Now — guarantees we still write on first boot when the credential
+//      lacks both, rather than silently skipping forever.
+function readCredentialExpiry(credential: { expires?: unknown; access?: unknown }, now: () => number): number {
+  if (typeof credential.expires === 'number' && Number.isFinite(credential.expires)) {
+    return credential.expires
+  }
+  if (typeof credential.access === 'string') {
+    const fromJwt = decodeClaudeAccessTokenExpiryMs(credential.access)
+    if (fromJwt !== null) return fromJwt
+  }
+  return now()
+}
+
+export function resolveClaudeCredentialsPath(options: { homeDir?: string; configDir?: string } = {}): string {
+  const configDir = resolveClaudeConfigDir(options.configDir)
+  if (configDir !== null) return join(configDir, CLAUDE_CREDENTIALS_FILE_NAME)
+  return join(options.homeDir ?? homedir(), CLAUDE_CREDENTIALS_RELATIVE_PATH)
+}
+
+function resolveClaudeConfigDir(configDir: string | undefined): string | null {
+  const raw = configDir ?? process.env['CLAUDE_CONFIG_DIR']
+  const trimmed = raw?.trim()
+  return trimmed === undefined || trimmed.length === 0 ? null : trimmed
+}
+
+// Atomic temp-then-rename, mirroring export-codex-auth-file.ts's
+// writeAtomic. The directory is created with 0700 and the file with 0600
+// because the credential carries a long-lived refresh token — leaking it
+// via lax permissions defeats the whole point. The 0600 chmod after
+// rename is belt-and-suspenders: writeFileSync's `mode` is applied at
+// create time, but umask can mask it down on some filesystems.
+//
+// Symlink preservation: the entrypoint shim will install
+// $HOME/.claude/.credentials.json as a symlink to
+// /agent/.typeclaw/home/.claude/.credentials.json. POSIX rename(2)
+// replaces the directory entry at the destination atomically and does
+// NOT follow symlinks, so a naive renameSync against the symlink path
+// would replace the symlink with a regular file, leaving the persistent
+// path empty and Claude Code's in-place token refresh silently lost on
+// every restart. Resolve the symlink target with readlinkSync and rename
+// against the real path so the symlink itself is preserved. The temp
+// file MUST live alongside the real target (same filesystem) because
+// renameSync across filesystems fails with EXDEV.
+function writeAtomic(targetPath: string, contents: string): void {
+  const realTarget = resolveSymlinkTarget(targetPath)
+  const dir = dirname(realTarget)
+  mkdirSync(dir, { recursive: true, mode: DIR_MODE })
+  const tmp = `${realTarget}.${process.pid}.${Date.now()}.tmp`
+  writeFileSync(tmp, contents, { encoding: 'utf8', mode: FILE_MODE })
+  try {
+    renameSync(tmp, realTarget)
+  } catch (err) {
+    try {
+      unlinkSync(tmp)
+    } catch {
+      // best-effort cleanup of the temp file when rename fails
+    }
+    throw err
+  }
+  try {
+    statSync(realTarget)
+    chmodSync(realTarget, FILE_MODE)
+  } catch {
+    // ignore — file vanished between rename and chmod is benign
+  }
+}
+
+// Returns the absolute path renameSync should target. When `path` is a
+// symlink (production: $HOME/.claude/.credentials.json -> /agent/...),
+// returns the resolved absolute target so we write through the link
+// instead of replacing it. Otherwise (tests, or first boot before the
+// shim installs the symlink), returns the path unchanged. readlinkSync
+// throws EINVAL when the path exists but isn't a symlink and ENOENT
+// when nothing is there — both cases fall through to the original path.
+function resolveSymlinkTarget(path: string): string {
+  let link: string
+  try {
+    link = readlinkSync(path)
+  } catch {
+    return path
+  }
+  return isAbsolute(link) ? link : resolve(dirname(path), link)
+}
+
+export type ExportClaudeCredentialsFileForAgentOptions = {
+  agentDir: string
+  claudeCodeEnabled: boolean
+  homeDir?: string
+  configDir?: string
+  log?: (message: string) => void
+}
+
+// Boot-time convenience wrapper for src/run/index.ts. Mirrors
+// exportCodexAuthFileForAgent: takes agentDir, never throws, returns a
+// result the caller can ignore. Secrets-file read failures are caught
+// and surfaced as 'failed' so the agent boot is never blocked by a
+// missing or malformed secrets.json.
+export function exportClaudeCredentialsFileForAgent(
+  options: ExportClaudeCredentialsFileForAgentOptions,
+): ExportClaudeCredentialsFileResult {
+  if (!options.claudeCodeEnabled) return { action: 'skipped', reason: 'claude-code-disabled' }
+  let providers: Providers
+  try {
+    providers = new SecretsBackend(join(options.agentDir, 'secrets.json')).tryReadProvidersSync()
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+    options.log?.(`exportClaudeCredentialsFile: ${reason}`)
+    return { action: 'failed', reason }
+  }
+  return exportClaudeCredentialsFileIfApplicable({
+    claudeCodeEnabled: options.claudeCodeEnabled,
+    providers,
+    ...(options.homeDir !== undefined ? { homeDir: options.homeDir } : {}),
+    ...(options.configDir !== undefined ? { configDir: options.configDir } : {}),
+    ...(options.log !== undefined ? { log: options.log } : {}),
+  })
+}

package/src/secrets/index.ts

@@ -13,3 +13,13 @@ export {
   exportCodexAuthFileForAgent,
   exportCodexAuthFileIfApplicable,
 } from './export-codex-auth-file'
+
+export {
+  CLAUDE_CREDENTIALS_FILE_NAME,
+  CLAUDE_CREDENTIALS_RELATIVE_PATH,
+  CLAUDE_DEFAULT_CONFIG_DIR_NAME,
+  type ExportClaudeCredentialsFileResult,
+  exportClaudeCredentialsFileForAgent,
+  exportClaudeCredentialsFileIfApplicable,
+  resolveClaudeCredentialsPath,
+} from './export-claude-credentials-file'

package/src/skills/typeclaw-channel-kakaotalk/SKILL.md

@@ -11,14 +11,16 @@ This means **you are messaging as a person, not as a bot.** Other participants s
 
 ## What KakaoTalk does NOT support
 
-If you produce any of the following, KakaoTalk will render it literally and the recipient will see the raw markup:
-
-- **Bold / italic / strikethrough** — `**bold**` shows as `**bold**`. Drop the asterisks; emphasize with word choice or capitalization (sparingly).
-- **Headings** — `# H1`, `## H2`, `### H3` all render as raw `#` characters.
-- **Tables** — pipe-delimited tables become a wall of `|` characters. Use bullet lists or short prose paragraphs instead.
-- **Code fences** — ``` blocks render as raw backticks. For short snippets, paste the code inline. For long snippets, summarize and offer to send it via another channel.
-- **Inline code** — `` `foo` `` renders as `` `foo` ``. Just write `foo`.
-- **Links with display text** — `[label](url)` becomes the literal string. Send the bare URL on its own; the KakaoTalk client will auto-link it.
+KakaoTalk renders messages as plain text — it has no rich-text formatting. **Write plain text from the start.** The adapter strips common markdown as a safety net before sending (so an accidental `**bold**` won't leak literal asterisks), but treat that as a last-resort guard, not a license to write markdown: the strip removes _markers_, it cannot make formatting-dependent layouts like tables readable. Compose for a plain-text surface and you control the result; lean on the stripper and you get whatever falls out.
+
+Specifically, do not rely on any of the following — write the plain-text equivalent yourself:
+
+- **Bold / italic / strikethrough** — emphasize with word choice or capitalization (sparingly), not `**asterisks**`.
+- **Headings** — `# H1`, `## H2`, `### H3` carry no visual weight here. Use a short label line or just lead with the point.
+- **Tables** — the stripper cannot rescue a pipe-delimited table; it would collapse into an unreadable line. Use bullet lists or short prose paragraphs instead.
+- **Code fences** — for short snippets, paste the code inline as plain text. For long snippets, summarize and offer to send it via another channel.
+- **Inline code** — just write `foo`, no backticks.
+- **Links with display text** — send the bare URL on its own line; the KakaoTalk client auto-links it. (A `[label](url)` that slips through is reduced to `label (url)`, but a bare URL reads cleaner.)
 - **Mentions** — there is no `@user` syntax that the protocol surfaces. Address people by name in the message body.
 - **Threads / replies-with-quote** — every message is a top-level chat post. There is no per-message reply UI.
 - **Outbound stickers / emoticons** — the KakaoTalk sticker store requires desktop-app purchase flows that the SDK does not replicate. Inbound stickers ARE surfaced (see below), but you cannot send one. If the user asks for a sticker, acknowledge the limit and offer text.
@@ -106,4 +108,4 @@ The adapter drops every inbound where `event.author_id` equals the logged-in acc
 
 ## When you cannot answer in KakaoTalk
 
-If the user asks you to do something the adapter cannot do (render markdown, post in a thread, send a sticker), say so plainly. Files are fine — those go through `attachments[]` as described above — but markdown rendering, threading, and stickers are real limits. Acknowledge the limit instead of silently dropping the request.
+If the user asks you to do something the adapter cannot do (post in a thread, send a sticker, render a real table), say so plainly. Files are fine — those go through `attachments[]` as described above — but threading, stickers, and rich formatting are real limits. Markdown markers you emit get stripped to plain text automatically, so a stray `**` won't leak; the limit is that nothing renders as formatting, not that it crashes. Acknowledge the limit instead of silently dropping the request.

package/src/skills/typeclaw-claude-code/SKILL.md

@@ -36,10 +36,11 @@ If `claude` is installed but no credential is set up, you have to broker the aut
 
 **Decision rule, top to bottom:**
 
-1. **Already authenticated?** Run `env | grep -E '^(ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)='` — if either is present, skip auth entirely.
-2. **User has an Anthropic Console workspace** (API billing, no subscription) → API key path.
-3. **User has a Claude Pro/Max/Team/Enterprise subscription** → OAuth token path.
-4. **User is unsure** → ask which kind of Claude account they have. Both paths are now equally low-friction (one user action each — paste an API key, or run one command on their machine and paste the result), so the old "prefer API key when unsure" bias is gone. Pick by account shape, not by flow complexity.
+1. **`~/.claude/.credentials.json` already populated?** When typeclaw is configured with an `anthropic` OAuth credential (via `typeclaw provider add anthropic` or the init wizard) AND `docker.file.claudeCode: true`, the agent boot auto-emits the credential to `~/.claude/.credentials.json`. Check with `test -s ~/.claude/.credentials.json && jq -e '.claudeAiOauth.accessToken' ~/.claude/.credentials.json` — if it returns a string, Claude Code reads it on its own with no env var needed. Skip auth entirely.
+2. **Already authenticated via env?** Run `env | grep -E '^(ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)='` — if either is present, skip auth entirely.
+3. **User has an Anthropic Console workspace** (API billing, no subscription) → API key path.
+4. **User has a Claude Pro/Max/Team/Enterprise subscription** → OAuth token path.
+5. **User is unsure** → ask which kind of Claude account they have. Both paths are now equally low-friction (one user action each — paste an API key, or run one command on their machine and paste the result), so the old "prefer API key when unsure" bias is gone. Pick by account shape, not by flow complexity.
 
 Both paths converge on the same final steps: read `.env`, merge one new `KEY=value` line, write back with the `nonWorkspaceWrite` guard ack, verify, and prompt the user to restart the container. Only the credential differs.
 

package/src/skills/typeclaw-claude-code/references/auth-flow.md

@@ -4,6 +4,41 @@ Deep dive for the auth paths. Read it when `SKILL.md`'s "First-time auth (intera
 
 The two paths are intentionally symmetric: in both, the user produces one string on their side, pastes it to you, you validate it, you do read-modify-write on `.env`, you offer a restart. Only the credential differs.
 
+## Path 0 — auto-export from typeclaw's anthropic OAuth credential
+
+If the user has already configured an `anthropic` OAuth credential in typeclaw (via `typeclaw provider add anthropic` or the init wizard) AND `docker.file.claudeCode: true`, the agent boot in `src/run/index.ts` auto-emits the credential to `~/.claude/.credentials.json` before `claude` ever runs. The destination matches Claude Code's documented Linux/Windows credential path; macOS uses the Keychain entry `"Claude Code-credentials"` with the same JSON shape, which typeclaw does not target (typeclaw runs Claude Code inside a Linux container).
+
+The on-disk shape:
+
+```json
+{
+  "claudeAiOauth": {
+    "accessToken": "sk-ant-oat01-...",
+    "refreshToken": "sk-ant-ort01-...",
+    "expiresAt": 1730000000000,
+    "scopes": ["user:inference", "user:profile", "user:sessions:claude_code", "user:mcp_servers"],
+    "subscriptionType": "max"
+  }
+}
+```
+
+Field names are camelCase and `expiresAt` is **milliseconds** since epoch (not seconds, not ISO).
+
+### Newer-wins on every boot
+
+The exporter compares typeclaw's stored `expires` against the JWT `exp` claim embedded in the on-disk `accessToken`. Strictly fresher wins; ties skip. Claude Code rotates tokens in place by rewriting `.credentials.json` on every successful refresh (anthropics/claude-code#53063), so on a restart the on-disk file may legitimately be ahead of `secrets.json` and must not be clobbered. The persistent-`$HOME` symlink the entrypoint shim installs (`~/.claude/.credentials.json` → `/agent/.typeclaw/home/.claude/.credentials.json`) is what makes the in-place refresh survive `stop`+`start`.
+
+If `.credentials.json` already carries an `mcpOAuth` block (MCP server OAuth state), the exporter preserves it on overwrite. Only the `claudeAiOauth` block is rewritten.
+
+### When Path 0 does NOT fire
+
+- `docker.file.claudeCode: false` — the install layer is off, no point exporting.
+- `secrets.json#providers.anthropic` is absent — nothing to export.
+- The stored credential is api-key shape — Claude Code reads API keys from `ANTHROPIC_API_KEY` env, not from `.credentials.json`. Fall back to Path A.
+- The on-disk JWT `exp` is already fresher — Claude Code refreshed in-place, skip.
+
+In each of those cases the agent boots without touching the file and Path A or Path B applies. The exporter is failure-tolerant: any error (read, write, fs guard) is logged via `console.warn` and the boot continues — Claude Code will then surface the missing credential on first invocation, which is the existing fallback.
+
 ## Path A — API key (recap)
 
 The API key path lives entirely in `SKILL.md` because there's nothing to elaborate. Summary:

package/typeclaw.schema.json

@@ -32,6 +32,7 @@
               "anthropic/claude-haiku-4-5",
               "anthropic/claude-sonnet-4-6",
               "anthropic/claude-opus-4-7",
+              "anthropic/claude-opus-4-8",
               "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
               "zai/glm-4.5-air",
               "zai/glm-4.6",
@@ -59,6 +60,7 @@
                 "anthropic/claude-haiku-4-5",
                 "anthropic/claude-sonnet-4-6",
                 "anthropic/claude-opus-4-7",
+                "anthropic/claude-opus-4-8",
                 "fireworks/accounts/fireworks/routers/kimi-k2p6-turbo",
                 "zai/glm-4.5-air",
                 "zai/glm-4.6",