typeclaw 0.6.0 → 0.8.0

package/src/config/providers.ts

@@ -108,6 +108,112 @@ export const KNOWN_PROVIDERS = {
       },
     },
   },
+  // Anthropic Claude — both the Anthropic Console API (ANTHROPIC_API_KEY)
+  // and Claude Pro/Max/Team/Enterprise subscriptions (OAuth) reach the same
+  // /v1/messages endpoint and share one provider id. Auth path determines
+  // which headers pi-ai's `anthropic-messages` transport injects: API key
+  // sends a plain `x-api-key`; OAuth sends Bearer + Claude Code identity
+  // (anthropic-beta: claude-code-20250219,oauth-2025-04-20 +
+  // user-agent: claude-cli/<version>), which is exactly the surface a
+  // subscriber's `claude setup-token` credential authorizes. The OAuth dance
+  // itself is authorization-code + PKCE against `claude.ai/oauth/authorize`
+  // with a localhost callback server (not device-code); the existing
+  // `typeclaw-claude-code` skill documents the user-side flow for getting
+  // a subscription credential onto the agent when the in-container browser
+  // callback can't reach the user's machine.
+  //
+  // anthropic is the FIRST provider in the registry where both auth modes
+  // coexist on one entry. The runtime in src/agent/auth.ts has a load-bearing
+  // resolution rule: when secrets.json#providers.anthropic carries an OAuth
+  // credential, `ANTHROPIC_API_KEY` in .env is IGNORED (OAuth-on-disk wins
+  // because env-wins only applies to api-key-shaped credentials). For
+  // api-key-only providers this is invisible; for anthropic it surfaces as
+  // "I added the env var but the agent still uses OAuth." The mitigation is
+  // to remove the OAuth credential explicitly (`typeclaw provider remove
+  // anthropic`) before relying on the env-var path. Same rule applies to any
+  // future dual-auth provider — keep the surprise in mind when expanding.
+  //
+  // Model lineup is the current GA tier as of 2026-04-16: Opus 4.7 (top,
+  // released Apr 16 2026), Sonnet 4.6 (mid, Feb 5 2026), Haiku 4.5 (fast,
+  // Oct 1 2025). Anthropic's own model overview lists these three as the
+  // current recommended set and flags earlier Opus/Sonnet variants with
+  // "Consider migrating to current models." Opus 4 / Sonnet 4 are deprecated
+  // (retirement: Jun 15 2026); the 4.5/4.6 alternates remain Active but are
+  // not the recommended path.
+  //
+  // ID semantics differ across the lineup and matter for forward-compat:
+  //   - `claude-haiku-4-5` is a 4.5-generation CONVENIENCE ALIAS that
+  //     resolves to the latest dated snapshot (currently `-20251001`). Per
+  //     Anthropic's model-id docs, pre-4.6 dateless ids are evergreen
+  //     pointers — Anthropic can ship a new dated snapshot under the same
+  //     alias and we pick it up automatically.
+  //   - `claude-sonnet-4-6` and `claude-opus-4-7` are 4.6+-generation PINNED
+  //     SNAPSHOTS, not aliases. Anthropic explicitly says "the dateless ID is
+  //     the canonical model ID for that release. It maps to a single, fixed
+  //     model snapshot." A future Sonnet 4.6.1 (if it ever exists) would ship
+  //     under a new id, NOT silently replace `claude-sonnet-4-6`.
+  // Consequence for refresh discipline: bumping Haiku is a no-op (alias
+  // catches the latest); bumping Sonnet/Opus to a future 4.7+ family is a
+  // real edit here. Don't assume `claude-opus-4-7` will silently advance.
+  //
+  // Opus 4.7 specifics that affect cost accounting:
+  //   - New tokenizer: same input maps to 1.0-1.3x more tokens than prior
+  //     generations depending on content type. Per-token price is unchanged
+  //     vs Opus 4.6, but total cost on identical workloads can rise meaningfully.
+  //   - 1M token context window (vs 200k on Haiku) and 128k max output (vs
+  //     64k on Sonnet/Haiku). 1M context is at standard pricing — no surcharge.
+  //   - New `xhigh` effort level between `high` and `max` (pi-ai 0.67.x may
+  //     not surface this knob yet; check before relying on it).
+  //
+  // Pricing mirrors Anthropic's official table as of 2026-05; cacheWrite is
+  // the 5m-TTL rate (1.25x input). 1h TTL is ~2x input (not modeled here —
+  // pi-ai's `cacheWrite` field captures the default 5m rate only).
+  anthropic: {
+    id: 'anthropic',
+    name: 'Anthropic',
+    baseUrl: 'https://api.anthropic.com',
+    auth: ['api-key', 'oauth'],
+    apiKeyEnv: 'ANTHROPIC_API_KEY',
+    oauthProviderId: 'anthropic',
+    models: {
+      'claude-haiku-4-5': {
+        id: 'claude-haiku-4-5',
+        name: 'Claude Haiku 4.5',
+        api: 'anthropic-messages',
+        provider: 'anthropic',
+        baseUrl: 'https://api.anthropic.com',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+        contextWindow: 200000,
+        maxTokens: 64000,
+      },
+      'claude-sonnet-4-6': {
+        id: 'claude-sonnet-4-6',
+        name: 'Claude Sonnet 4.6',
+        api: 'anthropic-messages',
+        provider: 'anthropic',
+        baseUrl: 'https://api.anthropic.com',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+        contextWindow: 1000000,
+        maxTokens: 64000,
+      },
+      'claude-opus-4-7': {
+        id: 'claude-opus-4-7',
+        name: 'Claude Opus 4.7',
+        api: 'anthropic-messages',
+        provider: 'anthropic',
+        baseUrl: 'https://api.anthropic.com',
+        reasoning: true,
+        input: ['text', 'image'],
+        cost: { input: 5, output: 25, cacheRead: 0.5, cacheWrite: 6.25 },
+        contextWindow: 1000000,
+        maxTokens: 128000,
+      },
+    },
+  },
   // ChatGPT Plus/Pro subscription via the OAuth Codex backend. No API key
   // path here on purpose — the Codex backend is OAuth-only upstream.
   //

package/src/init/dockerfile.ts

@@ -394,14 +394,101 @@ RUN echo "${encoded}" | base64 -d > ${TYPECLAW_ENTRYPOINT_PATH} \\
 // `~/.local/bin/claude` shim, which itself dereferences to the versioned
 // binary under `~/.local/share/claude/versions/<ver>/`, so upgrades via
 // `claude update` keep working without re-running this layer.
+// `~/.claude.json` is Claude Code's internal state file (NOT
+// `~/.claude/settings.json`, which is user-facing). On first run with an
+// empty or missing file, `claude` enters a TTY-only theme picker:
+// "Welcome to Claude Code … Choose the text style that looks best with
+// your terminal" with 7 options. The picker is unskippable via CLI
+// flags or env vars (no `--skip-onboarding`, no `--theme=dark`;
+// `IS_DEMO=1` exists but has documented side effects). The single
+// official escape hatch is writing `{"hasCompletedOnboarding": true,
+// "theme": "dark"}` to `~/.claude.json` before the first launch —
+// confirmed by Anthropic in multiple GitHub issues
+// (anthropics/claude-code#4714, #8938, #13827) and the empirical
+// answer used by metabase/metabase's `bin/claude-dangerous`, the
+// `claudeCodeAlDevContainer` feature, and dozens of other Docker
+// integrations.
+//
+// Without the pre-seed, the very first agent-driven `tmux new-session …
+// claude` invocation hangs on the theme picker: the agent's
+// `send-keys "<prompt>" Enter` arrives at the picker, gets interpreted
+// as picker input, and never reaches claude's actual prompt. The
+// `typeclaw-claude-code` skill is structured around a `Stop`-hook
+// sentinel, which never fires while the picker is up, so the polling
+// loop only learns of the hang at the 10-minute wall-clock budget.
+// Pre-seeding here costs ~85 bytes on disk and zero runtime overhead.
+//
+// SCOPE: this seed is NECESSARY but not SUFFICIENT for a fully
+// no-questions-asked first launch. Claude Code also shows two
+// post-seed modal dialogs that this file deliberately does NOT
+// pre-clear:
+//   1. "Detected a custom API key from environment. Do you want to use
+//      this API key?" — fires when ANTHROPIC_API_KEY is set. Options
+//      `[No (recommended), Yes]`, focus on No, picker does NOT wrap.
+//   2. Workspace trust ("Do you trust the files in this folder?") —
+//      fires on every new cwd. Options `[Yes, proceed, No, exit]`,
+//      focus on Yes.
+// Both are kept as runtime decisions handled by the
+// `typeclaw-claude-code` skill (see its "Driving the session" section,
+// "Clear startup dialogs" step, which uses dialog-specific keystrokes
+// because the picker doesn't wrap). Pre-seeding
+// `hasTrustDialogAccepted` or `customApiKeyResponses.approved` here
+// would silently widen the trust surface in ways the operator hasn't
+// consented to — the seed's job is strictly cosmetic-wizard removal,
+// not trust/permission preemption.
+//
+// `theme: "dark"` matches typeclaw's default TUI theme so the visual
+// transition between the typeclaw TUI and a tmux-attached claude pane
+// is consistent. Users on light terminals can override by editing
+// `~/.claude.json` (which persists across container restarts only if
+// they mount it; in the default container-ephemeral state it resets
+// to this default on every rebuild, which is fine — `claude` reads
+// the file at startup and the theme has no behavioral impact).
+//
+// `lastOnboardingVersion` is INTENTIONALLY OMITTED. ii-agent and a
+// few other templates ship `lastOnboardingVersion: "1.0.30"`, but
+// that value is version-coupled and goes stale on every Claude Code
+// release. Empirically against Claude Code 2.1.146, the current
+// `hasCompletedOnboarding: true` alone is honored without a version
+// pin. If a future Claude version starts re-triggering the picker
+// when the field is missing, capture `claude --version` output at
+// build time and inject it then — don't hardcode a stale value.
+//
+// `installMethod: "native"` and `numStartups: 1` match the shape
+// Claude Code itself writes after a clean first launch; keeping them
+// makes our seed indistinguishable from a real post-onboarding state,
+// which minimizes the chance of a future "if the file looks like
+// agent-pre-seed, redo onboarding" detection heuristic landing on us.
+//
+// Built via `JSON.stringify` rather than a hand-written string
+// literal so quote/escape bugs surface as TS errors at compile time,
+// not as a corrupt `~/.claude.json` discovered only when the build
+// runs. The `printf '%s\\n' '<JSON>'` shell pattern relies on the
+// JSON containing no single quotes (true by construction — JSON.
+// stringify only emits double quotes); a regression test parses the
+// emitted JSON back to confirm.
+const CLAUDE_CODE_ONBOARDING_SEED = JSON.stringify({
+  hasCompletedOnboarding: true,
+  theme: 'dark',
+  installMethod: 'native',
+  numStartups: 1,
+})
+
 function renderClaudeCodeInstallLayer(enabled: boolean): string {
   if (!enabled) return ''
   return `# Layer 5.6 (toggle): install Anthropic's Claude Code CLI. Opt-in via
 # typeclaw.json#docker.file.claudeCode. The skill \`typeclaw-claude-code\`
-# documents the auth + usage flow.
+# documents the auth + usage flow. Pre-seed ~/.claude.json so the first
+# launch skips the TTY-only theme picker; see CLAUDE_CODE_ONBOARDING_SEED
+# above for the rationale and what the seed deliberately does NOT cover.
+# The seed write runs LAST in the chain so the final layer state is
+# exactly the seeded config — independent of whether any earlier command
+# (or a future Claude version's \`--version\` smoke test) writes a
+# default \`~/.claude.json\` partway through the layer.
 RUN curl -fsSL https://claude.ai/install.sh | bash \\
  && ln -sf "$HOME/.local/bin/claude" /usr/local/bin/claude \\
- && claude --version > /dev/null`
+ && claude --version > /dev/null \\
+ && printf '%s\\n' '${CLAUDE_CODE_ONBOARDING_SEED}' > "$HOME/.claude.json"`
 }
 
 // Shared-library runtime deps Chrome for Testing needs to launch on amd64

package/src/init/models-dev.ts

@@ -13,6 +13,7 @@ const PROVIDER_TO_MODELS_DEV: Record<KnownProviderId, string> = {
   // (Codex is a backend, not a separate provider in their taxonomy). Curated
   // entries are surfaced regardless of upstream membership.
   'openai-codex': 'openai',
+  anthropic: 'anthropic',
   fireworks: 'fireworks-ai',
   zai: 'zai',
   // zai-coding (GLM Coding Plan) is a billing surface, not a separate model

package/src/shared/index.ts

@@ -21,4 +21,4 @@ export {
   type TunnelSnapshot,
 } from './protocol'
 
-export { formatLocalDate, formatLocalDateTime } from './local-time'
+export { formatLocalDate, formatLocalDateTime, resolveLocalTimezoneName } from './local-time'

package/src/shared/local-time.ts

@@ -19,3 +19,20 @@ function formatTimezoneOffset(date: Date): string {
   const abs = Math.abs(offsetMinutes)
   return `${sign}${pad2(Math.floor(abs / 60))}:${pad2(abs % 60)}`
 }
+
+// IANA timezone name of the process (e.g. `Asia/Seoul`). Reads the resolved
+// zone from Intl, falling back to `UTC` if the runtime cannot resolve one —
+// this should never happen on Bun + tzdata-equipped containers, but the
+// fallback keeps the prompt renderable rather than throwing during session
+// creation. The returned name is what the agent shows the user when asked
+// "what time is it" — pairing the wall clock with a recognizable zone name
+// is what disambiguates "15:31 +09:00" from "15:31 KST" for a non-technical
+// reader.
+export function resolveLocalTimezoneName(): string {
+  try {
+    const zone = Intl.DateTimeFormat().resolvedOptions().timeZone
+    return zone && zone.length > 0 ? zone : 'UTC'
+  } catch {
+    return 'UTC'
+  }
+}

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

@@ -9,6 +9,12 @@ You can delegate work to Claude Code, Anthropic's official coding agent. The age
 
 This skill is for the case where Claude Code is the right tool: hard architecture work, multi-file refactors, deep code analysis, a second-opinion read on something you wrote. It is **not** for trivial edits — the round-trip cost (worktree setup + process spawn + auth check + TUI init + at least one full Claude turn) is 15–45 seconds and several thousand tokens of someone else's context window. Do trivial edits yourself.
 
+## Run the delegation inside `operator`, not inline
+
+Once you've decided Claude Code is the right tool, spawn the bundled `operator` subagent to do the actual driving — don't run the worktree setup, the tmux session, the polling loop, the multi-turn decision loop, and the cleanup inline in your own context. The whole loop typically takes several minutes and produces large amounts of intermediate output (TUI buffer captures, Stop sentinels per turn, JSONL transcript references); running it inline blocks the user from talking to you and burns through your context window before you ever get to the synthesis step. `operator` is write-capable and runs the same loop, then returns a clean final report (what claude produced, what `git diff main..cc-<id>` shows, what you should review). You ship the worktree, the prompt, and the safety constraints to operator; operator ships you back the diff and the summary.
+
+Exception: a quick sanity ping (`claude --version` to check the binary exists, `env | grep ANTHROPIC` to check auth). Those are single fast bash calls — do them inline. The "spawn through operator" rule applies to anything that runs `claude` itself as an interactive TUI.
+
 ## When to delegate to Claude Code
 
 Use Claude Code for:
@@ -79,6 +85,7 @@ Before you spawn `claude` for any real work:
 - **`docker.file.claudeCode: true`** in `typeclaw.json`. Verify with `which claude`; if missing, the toggle isn't on. Tell the user to enable it and `typeclaw start --build`.
 - **`docker.file.tmux: true`** (default `true`, but check). Verify with `which tmux`.
 - **Auth set up** — see above. Verify with `env | grep -E '^(ANTHROPIC_API_KEY|CLAUDE_CODE_OAUTH_TOKEN)='`.
+- **Onboarding pre-seeded.** The Dockerfile layer writes `~/.claude.json` with `hasCompletedOnboarding: true` and `theme: "dark"` so the first `claude` invocation skips the TTY-only theme picker / welcome wizard. **This is necessary but not sufficient** — even with the seed, Claude Code can still land on two other pre-prompt modals: the "Detected a custom API key from environment. Do you want to use this API key?" confirmation (when `ANTHROPIC_API_KEY` is set in env — default focus is **No**, so `Down Enter` is needed to accept) and the workspace trust dialog ("Do you trust the files in this folder?", default focus already on **Yes**, so a bare `Enter` accepts). The "Driving the session" section below clears them as a loop. If `~/.claude.json` is empty or missing entirely (custom mount, manual `rm`, a `CLAUDE_CONFIG_DIR` pointing at a fresh directory), the theme picker also reappears. Self-heal: `printf '%s\n' '{"hasCompletedOnboarding":true,"theme":"dark","installMethod":"native","numStartups":1}' > "$HOME/.claude.json"` before spawning, then retry.
 - **Agent folder is a git repo.** Verify with `git -C /agent rev-parse --is-inside-work-tree`. The worktree model below requires it. If the user's agent folder somehow isn't a repo (rare — `typeclaw init` scaffolds one), tell them to `git init && git add -A && git commit -m "initial"` first.
 - **No uncommitted changes that you care about.** `git -C /agent status --porcelain` should be clean, or you should be willing to set the working tree aside before delegating. The worktree is a separate checkout, so claude can't see your uncommitted changes — meaning claude operates on the last committed state. If the user wants claude to work with in-progress edits, commit them first (even on a WIP branch).
 
@@ -165,11 +172,29 @@ The minimum protocol — translate to your actual tool calls:
 1. Create the worktree, write the hook config (above).
 2. `tmux new-session -d -s cc-<id> -c /tmp/cc-<id> claude`.
 3. Wait ~3 seconds for the TUI to initialize.
-4. `tmux send-keys -t cc-<id> "<your prompt>" Enter`.
-5. **Poll** for `/tmp/cc-<id>/.done` in a 500ms-cadence loop with a wall-clock budget (default 10 minutes). On every iteration, also check `tmux has-session -t cc-<id>` — if the session died, claude crashed or auth failed.
-6. When `.done` exists: `rm .done`, read `sentinel.json`, examine `last_assistant_message`.
-7. Decide using the multi-turn loop below.
-8. When done: `tmux send-keys -t cc-<id> "/exit" Enter && sleep 1 && tmux kill-session -t cc-<id>`.
+4. **Clear startup dialogs (BEFORE sending the task prompt).** Even with `~/.claude.json` pre-seeded, claude can land on one or both pre-prompt modals. Run this as a **loop**, not a one-shot: clearing one dialog can immediately reveal the next, and you must keep polling until claude's actual input prompt is visible (it renders a bottom-of-pane input box with a `╭` / `╰` border).
+
+   The two known modals, with the exact keystrokes for each (Claude Code's select widget does NOT wrap — pressing `Up` from the first option is a no-op, so the direction must match the dialog's option order):
+   - **Custom API key confirmation** — "Detected a custom API key from environment. Do you want to use this API key?" Fires when `ANTHROPIC_API_KEY` is set (exactly typeclaw's auth path). Options are `[No (recommended), Yes]` with focus initialized on **No**. Resolution: `tmux send-keys -t cc-<id> Down Enter` to advance to **Yes** and submit. Sending `Up Enter` would submit the **No** answer, which can persist as a rejection in `customApiKeyResponses.rejected` and break subsequent launches — never do that here.
+
+   - **Workspace trust** — "Do you trust the files in this folder?" Fires on first launch in any new cwd, so every fresh `/tmp/cc-<id>/` worktree triggers it. Options are `[Yes, proceed, No, exit]` with focus on the first option (**Yes**) by default. Resolution: bare `tmux send-keys -t cc-<id> Enter` — no arrow key needed. Always verify the pane text matches the trust dialog before pressing Enter; a misidentified modal would submit a different default.
+
+   Loop shape (translate to your tool calls):
+   1. Capture the last ~15 lines: `tmux capture-pane -t cc-<id> -p -S -15`.
+   2. If the capture contains the API key dialog text → `send-keys Down Enter`, sleep 500ms, goto 1.
+   3. If the capture contains the trust dialog text → `send-keys Enter`, sleep 500ms, goto 1.
+   4. If the capture shows the input box (`╭` border on a bottom line, no dialog text above it) → ready; exit the loop.
+   5. Otherwise sleep 500ms, goto 1. Apply a wall-clock budget of ~10 seconds; if the loop hasn't reached step 4 by then, abort with `/exit` and surface to the user — claude is in a state this skill doesn't model.
+
+   Do not use a fixed 2-second wait then send the prompt — cold-start and slow-disk cases can deliver a dialog at 2.5s+, and sending the task prompt into a modal corrupts the session.
+
+   **Safety note**: accepting workspace trust on a fresh `/tmp/cc-<id>/` worktree is the right call **only when its `HEAD` is the intended clean state** — typically the agent folder's last good commit on a branch the user controls. If the user just merged a third-party PR, pulled a remote branch, or checked out an untrusted ref, the worktree carries that content too and "trusting" it gives claude tool access on potentially hostile code. Before auto-accepting trust, sanity-check: if the user hasn't said something equivalent to "delegate this to Claude Code", or if you're not confident the current `HEAD` is one the user authored or reviewed, surface the trust dialog to them instead. Do NOT extend even a legitimate trust acceptance to in-session permission prompts (Bash, Edit, etc.) — those still need per-turn judgment per the multi-turn decision loop below.
+
+5. `tmux send-keys -t cc-<id> "<your prompt>" Enter`.
+6. **Poll** for `/tmp/cc-<id>/.done` in a 500ms-cadence loop with a wall-clock budget (default 10 minutes). On every iteration, also check `tmux has-session -t cc-<id>` — if the session died, claude crashed or auth failed.
+7. When `.done` exists: `rm .done`, read `sentinel.json`, examine `last_assistant_message`.
+8. Decide using the multi-turn loop below.
+9. When done: `tmux send-keys -t cc-<id> "/exit" Enter && sleep 1 && tmux kill-session -t cc-<id>`.
 
 The full polling implementation, the ANSI-handling rules for `capture-pane` fallbacks, and the "tmux session died unexpectedly" recovery path are in `references/tmux-driving.md`.
 

package/src/skills/typeclaw-config/SKILL.md

@@ -342,17 +342,17 @@ The `docker.file` block has two layers of customization:
 
 ### Fields
 
-| Field         | Required | Type              | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `tmux`        | no       | boolean \| string | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`).                                                                                                                                                                                                                                                                                                              |
-| `gh`          | no       | boolean \| string | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version.                                                                                                                                                                                                                                                                    |
-| `python`      | no       | boolean           | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin.                                                                                                                                                               |
-| `ffmpeg`      | no       | boolean \| string | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version.                                                                                                                                                                                                                                                                                                                                                        |
-| `cjkFonts`    | no       | boolean           | Default `true`. Installs `fonts-noto-cjk` (~56 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes). Boolean-only: the package is a metapackage tracking upstream Noto, no useful apt pin.                           |
-| `cloudflared` | no       | boolean           | Default `true`. Downloads the pinned `cloudflared` GitHub release (~35 MB) into the image so `cloudflare-quick` tunnels work on the next `start` without a separate Dockerfile edit. `false` skips the layer entirely on agents that don't use tunnels. Boolean-only — pinning is owned by the typeclaw release.                                                                                                                                |
-| `xvfb`        | no       | boolean           | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin. |
-| `claudeCode`  | no       | boolean           | Default `false`. `true` runs Anthropic's official `curl -fsSL https://claude.ai/install.sh \| bash` in a dedicated layer (between agent-browser and the entrypoint shim). Not apt: no version-pin variant; the upstream installer manages channels via env vars. Pairs with the `typeclaw-claude-code` skill, which documents the auth + tmux-driven usage flow.                                                                                |
-| `append`      | no       | array of strings  | Each entry is a single Dockerfile line — schema **rejects** entries containing `\n` or `\r`. Defaults to `[]`. Splice happens just before `ENTRYPOINT`, after `ENV NODE_ENV=production`.                                                                                                                                                                                                                                                        |
+| Field         | Required | Type              | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------- | -------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tmux`        | no       | boolean \| string | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`).                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `gh`          | no       | boolean \| string | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `python`      | no       | boolean           | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin.                                                                                                                                                                                                                                                                                                   |
+| `ffmpeg`      | no       | boolean \| string | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `cjkFonts`    | no       | boolean           | Default `true`. Installs `fonts-noto-cjk` (~56 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes). Boolean-only: the package is a metapackage tracking upstream Noto, no useful apt pin.                                                                                                                                                               |
+| `cloudflared` | no       | boolean           | Default `true`. Downloads the pinned `cloudflared` GitHub release (~35 MB) into the image so `cloudflare-quick` tunnels work on the next `start` without a separate Dockerfile edit. `false` skips the layer entirely on agents that don't use tunnels. Boolean-only — pinning is owned by the typeclaw release.                                                                                                                                                                                                                                                                    |
+| `xvfb`        | no       | boolean           | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin.                                                                                                                                     |
+| `claudeCode`  | no       | boolean           | Default `false`. `true` runs Anthropic's official `curl -fsSL https://claude.ai/install.sh \| bash` in a dedicated layer (between agent-browser and the entrypoint shim) and pre-seeds `~/.claude.json` to skip the TTY-only theme picker on first launch (without it the agent's `tmux send-keys` would be eaten by the picker). Not apt: no version-pin variant; the upstream installer manages channels via env vars. Pairs with the `typeclaw-claude-code` skill, which documents the auth + tmux-driven usage flow including how to clear the post-seed API-key/trust dialogs. |
+| `append`      | no       | array of strings  | Each entry is a single Dockerfile line — schema **rejects** entries containing `\n` or `\r`. Defaults to `[]`. Splice happens just before `ENTRYPOINT`, after `ENV NODE_ENV=production`.                                                                                                                                                                                                                                                                                                                                                                                            |
 
 Toggle version strings reject whitespace and `=` (apt-injection guard) — pass just the version, not `pkg=ver`.
 
@@ -427,7 +427,7 @@ The toggle-driven apt install benefits from BuildKit `--mount=type=cache` on `/v
 
 ## Gitignore
 
-`typeclaw start` rewrites the agent folder's `.gitignore` from a template baked into the typeclaw CLI on **every** invocation, then auto-commits it when the agent folder is a git repo and the file changed. The template protects two categories: truly-ignored paths (`.env`, `node_modules/`, `workspace/`, `mounts/`, `Dockerfile`, `.DS_Store`) and system-managed runtime state (`sessions/`, `memory/`, `channels/`) that TypeClaw, not the agent, commits on its own schedule. Editing `.gitignore` by hand is temporary; the next `typeclaw start` overwrites it.
+`typeclaw start` rewrites the agent folder's `.gitignore` from a template baked into the typeclaw CLI on **every** invocation, then auto-commits it when the agent folder is a git repo and the file changed. The template protects two categories: truly-ignored paths (`secrets.json`, `.env`, `.env.local`, `auth.json`, `node_modules/`, `workspace/`, `mounts/`, `Dockerfile`, `.DS_Store`) and system-managed runtime state (`sessions/`, `memory/`, `channels/`) that TypeClaw, not the agent, commits on its own schedule. Editing `.gitignore` by hand is temporary; the next `typeclaw start` overwrites it.
 
 The `git.ignore.append` field (introduced when the legacy top-level `gitignore` key was nested under the `git` namespace for future extensibility — see **Legacy migration**) is the supported escape hatch for additional local ignore patterns. It is an array of strings, each treated as a single `.gitignore` line. The CLI splices them into the autogenerated `.gitignore` before TypeClaw's protected rules, prefixed with a `# Custom entries from typeclaw.json#git.ignore.append.` comment.
 
@@ -439,7 +439,7 @@ The `git.ignore.append` field (introduced when the legacy top-level `gitignore`
 
 ### Ordering and protected paths
 
-`.gitignore` is order-sensitive: later `!` negation rules can unignore earlier ignore rules. TypeClaw therefore renders `git.ignore.append` **before** its own truly-ignored and system-managed entries, so even a custom `!sessions/` or `!.env` cannot override TypeClaw's protections. Custom ordinary ignore patterns still work because they add additional ignores; they just do not get the final word over TypeClaw-owned paths.
+`.gitignore` is order-sensitive: later `!` negation rules can unignore earlier ignore rules. TypeClaw therefore renders `git.ignore.append` **before** its own truly-ignored and system-managed entries, so even a custom `!sessions/`, `!secrets.json`, or `!.env` cannot override TypeClaw's protections. Custom ordinary ignore patterns still work because they add additional ignores; they just do not get the final word over TypeClaw-owned paths.
 
 Materialized shape when `append` is non-empty:
 
@@ -449,6 +449,7 @@ scratch/
 *.local.log
 
 # Truly ignored: ...
+secrets.json
 .env
 Dockerfile
 
@@ -514,16 +515,16 @@ Do **not** invent plugin blocks; their existence is determined by the plugins li
 
 The model registry currently has these entries:
 
-| `model` value                                          | Display name    | Provider     | Auth                | Notes                                                                                    |
-| ------------------------------------------------------ | --------------- | ------------ | ------------------- | ---------------------------------------------------------------------------------------- |
-| `openai/gpt-5.4-nano`                                  | GPT-5.4 nano    | OpenAI       | API key             | Default. Requires `OPENAI_API_KEY` in `.env`. Reasoning model, 400K context.             |
-| `openai/gpt-5.4-mini`                                  | GPT-5.4 mini    | OpenAI       | API key             | Requires `OPENAI_API_KEY` in `.env`. Reasoning model, 400K context.                      |
-| `openai/gpt-5.4`                                       | GPT-5.4         | OpenAI       | API key             | Requires `OPENAI_API_KEY` in `.env`. Reasoning model, 1.05M context.                     |
-| `openai/gpt-5.5`                                       | GPT-5.5         | OpenAI       | API key             | Flagship. Requires `OPENAI_API_KEY` in `.env`. Reasoning model, 1.05M context.           |
-| `openai-codex/gpt-5.4-mini`                            | GPT-5.4 mini    | OpenAI Codex | OAuth (ChatGPT P/P) | Cheaper Codex tier. Requires OAuth login at init. Persisted to `secrets.json`. 272K ctx. |
-| `openai-codex/gpt-5.4`                                 | GPT-5.4         | OpenAI Codex | OAuth (ChatGPT P/P) | Codex mid-tier. Requires OAuth login at init. Persisted to `secrets.json`. 272K context. |
-| `openai-codex/gpt-5.5`                                 | GPT-5.5         | OpenAI Codex | OAuth (ChatGPT P/P) | Flagship Codex. Requires OAuth login at init. Persisted to `secrets.json`. 272K context. |
-| `fireworks/accounts/fireworks/routers/kimi-k2p6-turbo` | Kimi K2.6 Turbo | Fireworks    | API key             | Requires `FIREWORKS_API_KEY` in `.env`. Reasoning model, 256K context.                   |
+| `model` value                                          | Display name    | Provider     | Auth                | Notes                                                                                                                              |
+| ------------------------------------------------------ | --------------- | ------------ | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `openai/gpt-5.4-nano`                                  | GPT-5.4 nano    | OpenAI       | API key             | Default. API key in `secrets.json#providers.openai.key.value` (or `OPENAI_API_KEY` env override). Reasoning model, 400K context.   |
+| `openai/gpt-5.4-mini`                                  | GPT-5.4 mini    | OpenAI       | API key             | API key in `secrets.json#providers.openai.key.value` (or `OPENAI_API_KEY` env override). Reasoning model, 400K context.            |
+| `openai/gpt-5.4`                                       | GPT-5.4         | OpenAI       | API key             | API key in `secrets.json#providers.openai.key.value` (or `OPENAI_API_KEY` env override). Reasoning model, 1.05M context.           |
+| `openai/gpt-5.5`                                       | GPT-5.5         | OpenAI       | API key             | Flagship. API key in `secrets.json#providers.openai.key.value` (or `OPENAI_API_KEY` env override). Reasoning model, 1.05M context. |
+| `openai-codex/gpt-5.4-mini`                            | GPT-5.4 mini    | OpenAI Codex | OAuth (ChatGPT P/P) | Cheaper Codex tier. Requires OAuth login at init. Persisted to `secrets.json`. 272K ctx.                                           |
+| `openai-codex/gpt-5.4`                                 | GPT-5.4         | OpenAI Codex | OAuth (ChatGPT P/P) | Codex mid-tier. Requires OAuth login at init. Persisted to `secrets.json`. 272K context.                                           |
+| `openai-codex/gpt-5.5`                                 | GPT-5.5         | OpenAI Codex | OAuth (ChatGPT P/P) | Flagship Codex. Requires OAuth login at init. Persisted to `secrets.json`. 272K context.                                           |
+| `fireworks/accounts/fireworks/routers/kimi-k2p6-turbo` | Kimi K2.6 Turbo | Fireworks    | API key             | API key in `secrets.json#providers.fireworks.key.value` (or `FIREWORKS_API_KEY` env override). Reasoning model, 256K context.      |
 
 **Do not write any other value into `model`.** The schema enum will reject the file at load, and the runtime will refuse to boot the agent process. If the user names a model that isn't in this table — "use Claude", "switch to o3" — be honest:
 
@@ -533,12 +534,9 @@ Do **not** edit `typeclaw.json` to a model the registry doesn't know, even if th
 
 ## Provider credentials
 
-`typeclaw.json` does **not** hold API keys or OAuth tokens. Credentials live in two gitignored files:
+`typeclaw.json` does **not** hold API keys or OAuth tokens. Credentials live in two gitignored files, with `secrets.json` as the canonical store and `.env` retained for env-var overrides and parity with non-typeclaw tooling that reads from the environment:
 
-- **`./.env`** (any environment variable, including API keys): plain `KEY=value` lines, loaded by Docker via `--env-file` at container start. The canonical env-var names per provider:
-  - `OPENAI_API_KEY` — for any `openai/...` model.
-  - `FIREWORKS_API_KEY` — for any `fireworks/...` model.
-- **`./secrets.json`** (structured store): a `v2` envelope managed by `SecretsBackend` (wraps `pi-coding-agent`'s `AuthStorage`). Two top-level slices:
+- **`./secrets.json`** (canonical structured store): a `v2` envelope managed by `SecretsBackend` (wraps `pi-coding-agent`'s `AuthStorage`). Written by `typeclaw init`, the OAuth refresh path, and explicit user-driven rotation. Two top-level slices:
   - `providers.*` — per-provider credentials. API-key providers store `{ type: 'api_key', key: <Secret> }`. OAuth providers store the `pi-coding-agent` token blob `{ type: 'oauth', access_token, refresh_token, expires_at, ... }`. The container auto-refreshes OAuth tokens with file locking; api-key writes only happen on explicit user-driven rotation.
   - `channels.*` — per-adapter credentials, with named fields per adapter:
     - `discord-bot: { token: <Secret> }`
@@ -547,6 +545,13 @@ Do **not** edit `typeclaw.json` to a model the registry doesn't know, even if th
 
   (Pre-v2 agent folders carry the older `llm` slice and channel-env-var-keyed shape; they are upgraded transparently on first read. Pre-rename folders may even carry the file as `auth.json`; it is renamed to `secrets.json` on the next boot.)
 
+- **`./.env`** (env-var overrides): plain `KEY=value` lines, loaded by Docker via `--env-file` at container start. When set, an env var **wins** over the file value (see resolution rules below). Useful for CI, transient rotations, or any tooling outside typeclaw that reads from the environment. The canonical env-var names per provider:
+  - `OPENAI_API_KEY` — for any `openai/...` model.
+  - `FIREWORKS_API_KEY` — for any `fireworks/...` model.
+  - `ANTHROPIC_API_KEY` — for any `anthropic/...` model when using API-key auth.
+
+  New typeclaw secrets should land in `secrets.json` (via `typeclaw init` or a structured edit) — `.env` is no longer the default home.
+
 ### The `Secret` shape and env-wins resolution
 
 Every secret-bearing field in `secrets.json` is a **`Secret`**: either a plain string or an object `{ value?, env? }`.
@@ -580,11 +585,11 @@ Every secret-bearing field in `secrets.json` is a **`Secret`**: either a plain s
 
 ### Switching credentials
 
-If a user wants to switch from API key to OAuth (or vice versa) for a provider that supports both, the easiest path is to delete the relevant entry from `.env` / `secrets.json#providers` and re-run `typeclaw init` from inside the agent folder — it'll prompt for the auth method again.
+If a user wants to switch from API key to OAuth (or vice versa) for a provider that supports both, the easiest path is to delete the relevant entry from `secrets.json#providers` (and any matching env-var override in `.env`) and re-run `typeclaw init` from inside the agent folder — it'll prompt for the auth method again.
 
-If the user wants to rotate an api-key, edit either `.env` (env-wins picks it up immediately) or `secrets.json#providers.<provider>.key` (rewrite the `value` field, or remove the entry if the env var should take over). After either, `typeclaw restart` on the host stage.
+If the user wants to rotate an api-key, edit `secrets.json#providers.<provider>.key` — rewrite the `value` field (preserving any `env` binding), or remove the entry entirely if an env-var override is taking over. `.env` is a secondary path that still works (env-wins picks it up immediately), but `secrets.json` is the durable home. After either, `typeclaw restart` on the host stage.
 
-Never echo, log, or commit values from `.env` or `secrets.json`. Both are gitignored by default — keep them that way.
+Never echo, log, or commit values from `secrets.json` or `.env`. Both are gitignored by default — keep them that way.
 
 ## Editing `typeclaw.json` safely
 
@@ -627,7 +632,7 @@ Never echo, log, or commit values from `.env` or `secrets.json`. Both are gitign
 ## Things you must not do
 
 - **Do not invent fields the schema doesn't support** (no `provider`, `apiKey`, `temperature`, `maxTokens`, `systemPrompt`, `tools`, `timeout`, `retry`, etc.). They will be silently dropped or, worse, mistaken for a plugin config block. Lying to the user that "I added a temperature field" when the runtime ignores it is a worse failure than refusing.
-- **Do not move secrets into `typeclaw.json`.** It is committed to git. API keys belong in `.env`.
+- **Do not move secrets into `typeclaw.json`.** It is committed to git. API keys and channel tokens belong in `secrets.json` (or, for env-override use cases, `.env`).
 - **Do not change `port` casually.** The host-stage `typeclaw start` launcher publishes a port mapping it learned at `start` time. Changing the port in `typeclaw.json` without re-running `typeclaw start` (which re-reads it) means the TUI will connect to the wrong port and silently fail. If you change `port`, tell the user explicitly that the next `typeclaw start` will pick the new mapping.
 - **Do not change `model` to something not in the registry.** The schema enum will reject the file at load, and the runtime will refuse to boot the agent process. If the user wants a model that isn't there, this is a typeclaw-side change, not a config edit.
 - **Do not edit `typeclaw.json` from inside an `exec` cron job's `command`.** That mutates the file behind the runtime's back. Live-reloadable fields still won't update until something triggers a `reload`, and restart-required fields are guaranteed wrong.

package/src/skills/typeclaw-git/SKILL.md

@@ -9,7 +9,7 @@ Your agent folder is a git repo. Almost every file in it (`typeclaw.json`, `cron
 
 The contents of `.gitignore` split into two distinct categories — the distinction matters for this skill:
 
-- **Truly ignored** (`.env`, `node_modules/`, `workspace/`, `mounts/`, `Dockerfile`, `.DS_Store`) — never in history, ever. Secrets, runtime junk, your free-write zone, and regenerated-on-start system files.
+- **Truly ignored** (`secrets.json`, `.env`, `node_modules/`, `workspace/`, `mounts/`, `Dockerfile`, `.DS_Store`) — never in history, ever. Secrets, runtime junk, your free-write zone, and regenerated-on-start system files.
 - **System-managed** (`sessions/`, `memory/`, `channels/`) — gitignored so _you_ don't stage them, but TypeClaw force-commits them on its own schedule. `sessions/` is auto-backed up by the runtime; `memory/` is committed by the dreaming subagent; `channels/` is runtime-owned channel state. Treat them as runtime-owned: do not `git add` them, do not write commit messages about them, and do not be alarmed when they appear in `git log`.
 
 Everything not in either bucket is yours to commit.
@@ -80,7 +80,7 @@ If you discover an unrelated dirty file from a previous turn, commit it separate
 - **Do not skip the commit** "because the change is small." Small changes are exactly the ones that get lost. Toggling `enabled: false` on a cron job is a decision; commit it.
 - **Do not write empty or generic messages** ("update", "fix", "change config"). The history exists to be read.
 - **Do not amend or force-push** to clean up later. Sloppy history with real commits beats clean history that lies about when decisions happened.
-- **Do not commit `.env` or anything truly-ignored.** If `git status` shows a truly-ignored file as staged, something is wrong with `.gitignore` — fix that first, don't commit the secret.
+- **Do not commit `secrets.json`, `.env`, or anything truly-ignored.** If `git status` shows a truly-ignored file as staged, something is wrong with `.gitignore` — fix that first, don't commit the secret.
 - **Do not commit `sessions/` or `memory/` either, even though `git log` shows them.** They're system-managed: TypeClaw's auto-backup and dreaming subagent own those commits. If you find one of them staged in your working tree, unstage it (`git restore --staged sessions/ memory/`) — your edit got mixed up with the runtime's domain.
 - **Do not bundle unrelated changes.** One commit, one decision.
 

package/src/skills/typeclaw-plugins/SKILL.md

@@ -718,7 +718,7 @@ Plugin `ToolContext` is `{ signal, sessionId, agentDir, logger }`. There is no `
   - `session.prompt`: `src/agent/index.ts` `createResourceLoader` (after default prompt assembly)
   - `session.idle`: `src/server/index.ts` `drain()` — fires immediately after every `session.prompt()` resolves (success or error)
   - `session.start`/`session.end`: `src/server/index.ts` ws open/close
-  - `tool.before`/`tool.after`: `src/agent/plugin-tools.ts` `wrapPluginTool`, `wrapSystemTool`, and `wrapSystemAgentTool`
+  - `tool.before`/`tool.after`: `src/agent/plugin-tools.ts` `wrapPluginTool`, `wrapSystemTool`, `wrapSystemAgentTool`, and `wrapAgentToolAsCustomToolDefinition`. The last one is the load-bearing path for pi's builtin coding tools (`read`/`bash`/`edit`/`write`/`grep`/`find`/`ls`): pi-coding-agent 0.67.3 treats `createAgentSession({ tools })` as a name filter only, so the wrapping has to ride in `customTools` to actually override the builtin implementations. See the top-of-file contract block in `plugin-tools.ts` for the full reasoning.
 - **Schema additions**: `src/config/config.ts` (`plugins` array, `.catchall(z.unknown())` for per-plugin blocks, `extractPluginConfigs`)
 
 ### Audit log on boot

package/typeclaw.schema.json

@@ -26,6 +26,9 @@
               "openai/gpt-5.4-mini",
               "openai/gpt-5.4",
               "openai/gpt-5.5",
+              "anthropic/claude-haiku-4-5",
+              "anthropic/claude-sonnet-4-6",
+              "anthropic/claude-opus-4-7",
               "openai-codex/gpt-5.4-mini",
               "openai-codex/gpt-5.4",
               "openai-codex/gpt-5.5",
@@ -50,6 +53,9 @@
                 "openai/gpt-5.4-mini",
                 "openai/gpt-5.4",
                 "openai/gpt-5.5",
+                "anthropic/claude-haiku-4-5",
+                "anthropic/claude-sonnet-4-6",
+                "anthropic/claude-opus-4-7",
                 "openai-codex/gpt-5.4-mini",
                 "openai-codex/gpt-5.4",
                 "openai-codex/gpt-5.5",