# State Mapping [Back to README](../../README.md) Most lifecycle events from agents (Claude Code hooks, Codex JSONL, Copilot hooks) map to the same animation states. Local interactive Claude Code main sessions can additionally show `executing` ("Handling tools"). A fresh, identified `PreToolUse` for a recognized tool supplies this hint; it describes the tool-call phase, which starts before permission checks, not confirmed OS process execution. Question/plan-review tools, child sessions, remote/WSL/headless sources and ambiguous identities keep their existing behavior. The table's working visuals also serve as the default executing visuals; themes may supply an optional `states.executing` animation. Mini mode reuses `mini-working`. An ordinary tool result returns to `working`, even when another parallel call has no result yet; only an accepted `PostToolBatch` proves the transition back to `thinking`. Failures retain the existing error/interrupted behavior. A denied or undecided local main-session approval returned through Clawd's normal resolution flow invalidates the hint and suppresses late tool-start callbacks until a distinct prompt or accepted batch; allow does not upgrade a working session. If the result arrives after the prior prompt closes, suppression covers the next adopted prompt too, because a queued prompt may not have sent its first hook yet. Subagent work keeps `juggling` priority and never restores an old execution hint. Hooks and persisted recovery/history still use `working`; the runtime derives `executing` internally. Other agents are unchanged. This hint deliberately favors uncertainty: a duplicate Pre can return to `working`, and cleanup of an approval already answered in the native terminal can temporarily suppress it. Hiding approval bubbles through DND or Settings does not itself run the normal resolution callback or invalidate the hint. Without a per-tool identity in the approval result, an accepted older batch can still release suppression before another denied call's late Pre arrives; this remains an event-ordering limitation. Subagent events still map to the logical `juggling` state, but Clawd now chooses a tiered asset by live subagent count: 1 subagent uses `clawd-headphones-groove.svg`, while 2+ subagents use `clawd-working-juggling.svg`. The old Clawd conducting asset is retired; Calico and Cloudling still use their conducting animations for their 2+ subagent tier. The default theme also uses headphones for two ordinary working/thinking sessions. After the last child finishes, the parent can correctly return to `working` while the pet keeps the same headphones asset for other active conversations. Use the parent's HUD state and `activeSubagentCount` to distinguish this from a child that is still active; the asset alone does not prove a stuck subagent. Local Codex JSONL monitoring also uses this tier for active delegated children with an explicit `session_meta.source.subagent.thread_spawn.parent_thread_id`. Only direct children of an existing visible local parent count. Internal guardian threads, unknown relationships, completed historical turns and grandchildren do not add to the parent's tier. A child's accepted turn starts/finishes independently of the parent; parent completion can leave the busy tier visible until the final child finishes. Its completion cue then plays once when the final child truly finishes or the parent session ends. The parent's real phase, plan and completion history remain unchanged; snapshots expose `effectiveState` and `activeSubagentCount` separately for presentation. Child progress expires after 20 minutes without a real lifecycle/tool/model event; metadata and token-count refreshes do not extend it. Remote/WSL monitoring and Codex permission handling are unchanged. Forked logs can include their parent's header and history after the child's own header. A header for another thread cannot replace the child's identity or classification. With a valid identified child birth timestamp, records older than that birth are excluded from both child counting and its turn/question/plan/title bookkeeping. Missing-ID/time legacy records keep their existing recovery behavior; future events cannot advance the child turn fence before being rejected. On Windows, an open append handle can leave a rollout's modification time unchanged. Within the existing directory discovery range, a bounded in-memory identity/size ledger detects actual growth and admits proven delegated files through bounded head/tail recovery. First observation alone does not revive a session; root and guardian files are excluded from this extra path, and token-only appends cannot revive a completed child. Temporary read errors retain the growth trigger for a bounded retry. Old directories outside normal discovery and cold files without subsequent growth keep the existing recovery limits. Known pending local Codex approvals and native questions expose a separate `pendingAttention` presentation fact. Waiting, error/interruption and foreground compaction cues take precedence over the child busy tier; waiting remains visible until its pending entry is removed, including after the last child finishes. Snapshot/HUD refreshes observe permission add/remove/resolve without making a decision or rewriting the parent's lifecycle, and the active-child count stays zero for a waiting parent with no children. The idle rows below describe the theme's stock behavior. Settings → Animation & Sound → Animations can instead choose any idle visual declared by the active theme as its persistent resting look. This changes only the visual shown while the logical state is `idle`: task, permission, completion, sleep, reaction, and roam states still take precedence and return to the selected look afterward. The choice is stored per theme and falls back to the theme default if the file disappears. Non-default idle visuals intentionally do not use cursor eye tracking or spin-to-dizzy. Clawd also has a conditional Outlaw idle easter egg: while both the Western cowboy hat and cigarette are selected, an eligible ordinary idle roll has a 50% chance to play `clawd-outlaw-bender.svg`, with a 30-minute cooldown. Hidden, low-power, mini, roaming, dragging, menu-open, and non-idle periods do not consume the roll or cooldown. The animation embeds its own hat and cigarette, so the two external accessory layers are hidden only for that file. | Agent Event | State | Animation | Clawd | Calico | Cloudling | |---|---|---|---|---|---| | Idle (no activity) | idle | Eye-tracking follow | | | | | Idle (random) | idle | Reading / patrol | | | | | UserPromptSubmit | thinking | Thought bubble + spark | | | | | PreToolUse / PostToolUse (1 session) | working (typing) | Typing | | | | | PreToolUse / PostToolUse (2 sessions) | working (2-session tier) | Headphones groove | | | | | PreToolUse (3+ sessions) | working (building) | Building | | | | | SubagentStart (1 live subagent) | juggling | Headphones groove | | | | | SubagentStart (2+ live subagents) | juggling (2+ tier) | Three-ball juggling | | | | | PostToolUseFailure | error | Error | | | | | Stop / PostCompact | attention | Happy | | | | | PermissionRequest | notification | Alert | | | | | Codex `request_user_input` | notification | Alert + read-only question card | | | | | PreCompact | sweeping | Sweeping | | | | | WorktreeCreate | carrying | Carrying | | | | | 60s mouse idle | sleeping | Sleep | | | | | SessionEnd | remove session; idle if no live sessions | No sleep transition | | | | In the Clawd theme, a direct Claude Code `/design` command selects the painting visual through `UserPromptExpansion`. The accepted main-session `Stop` selects heart eyes; this marks a completed turn, not successful publication. Temporary tool failures, notifications and automatic compaction keep the design hint for resumed work, while terminal failures, session end and the next ordinary prompt clear it. Both poses retain the selected head accessory and temporarily hide the mouth accessory, which returns on supported ordinary poses. Other themes use their normal state visuals. Claude Code 2.1.280+ additionally registers `PostToolBatch`. An accepted main-session batch returns to `thinking` before the next model request, without marking the turn complete. It requires the current `prompt_id` and exact bounded tool identities; early batches wait for ordinary correlated evidence for every named tool. Missing/ambiguous identity, pending approvals, child batches, headless sessions and delayed old callbacks do not produce this phase change. Prompt identity is turn correlation, not message deduplication: additional same-id messages still run normal handling, queued turns can start from identified tools after the prior turn closes without another Submit, and fresh tools after a vetoed Stop can continue that turn. An unseen id while a turn is open disables phase inference without retiring the open prompt. SessionEnd is authoritative regardless of prompt id. Settled success tails preserve thinking while retaining metadata, permission cleanup and the AskUserQuestion transcript completion fallback; a current failure plays its error cue and resumes the established model phase afterward. Live subagent cues retain their priority. Older/unknown Claude versions do not register the new batch hook. The phase event does not change persisted recovery leases or session history. The 2.1.280 gate is a conservative verified baseline, not a claim about the first release supporting the event. See [Claude's hook contract](https://code.claude.com/docs/en/hooks#posttoolbatch). ## Kimi Code CLI (Kimi-CLI) Hook Events Kimi Code CLI (Kimi-CLI) now uses hook-only integration (`~/.kimi/config.toml`), and maps these 13 hook events to shared Clawd states: | Kimi Hook Event | State | |---|---| | SessionStart | idle | | SessionEnd | remove session; idle if no live sessions | | UserPromptSubmit | thinking | | PreToolUse | working by default. Explicit payload approval signals (`permission_required` / `requires_approval` / `waiting_for_approval` / `is_permission_request`) always flip the permission animation immediately. Beyond that, the persistent mode decides how permission-gated tools are treated: **`suspect` (installer default)** arms a deferred heuristic — if no `PostToolUse` lands within the suspect window, Kimi is assumed blocked on its approval TUI and the cue fires; `explicit` reacts to explicit signals only (which current kimi-cli never emits — effectively no cues). The installer (`npm run install:kimi-hooks` and the auto-sync at startup) persists the mode as a `--permission-mode=` flag on the `command` field of `~/.kimi/config.toml`, preserving a previously chosen mode across re-syncs. Runtime env vars override the persisted flag: `CLAWD_KIMI_PERMISSION_MODE=explicit\|suspect` (beats the persisted argv flag; `CLAWD_KIMI_DISABLE_PRETOOL_PERMISSION` and `CLAWD_KIMI_PERMISSION_IMMEDIATE` are checked before it), `CLAWD_KIMI_PERMISSION_IMMEDIATE=1` forces immediate remap for gated tools, `CLAWD_KIMI_PERMISSION_SUSPECT=1` (legacy alias) enables suspect for the current process, `CLAWD_KIMI_PERMISSION_SUSPECT_MS=` tunes the suspect window, `CLAWD_KIMI_DISABLE_PRETOOL_PERMISSION=1` keeps explicit-only behavior regardless of other switches. Queued gated calls are tracked in a per-session gate ledger: each answered approval re-arms the cue for the next pending one. | | PostToolUse | working | | PostToolUseFailure | error | | Stop | attention | | StopFailure | error | | SubagentStart | juggling | | SubagentStop | working | | PreCompact | sweeping | | PostCompact | attention | | Notification | notification | ## Gemini CLI Hook Notes Gemini CLI stays on hook-only integration, but two Gemini-native events are intentionally not forced into the shared Claude/Codex semantics: | Gemini Hook Event | Clawd behavior | |---|---| | AfterAgent | Recorded as `AfterAgent` and the session returns to `idle`. It does not remap to shared `Stop`, so Gemini turns no longer auto-show the `attention` / done animation. | | PreCompress | Recorded as `PreCompress` in session history, but does not switch the pet to `sweeping`. The current visible state (usually `thinking` or `working`) stays in place. | ## ZCode Hook Events ZCode uses config-file hooks under `~/.zcode/cli/config.json`: | ZCode Hook Event | State | |---|---| | SessionStart | idle | | UserPromptSubmit | thinking | | PreToolUse | working | | PostToolUse | working | | PostToolUseFailure | error | | Stop | attention | | PermissionRequest | notification (fail-closed path, no-capability drops) | `PermissionRequest` is a blocking permission approval since Phase 2: the hook waits on Clawd's local bubble or remote approval and answers a manual allow/deny via `hookSpecificOutput` on stdout. Permission automation deliberately defers for ZCode until its tool surface and session identity are audited. The `notification` mapping above fires on the fail-closed path (missing/unknown tool name), when Clawd is not running, and — since #1264 — server-side whenever Clawd drops a request it may not decide (no-capability interactions such as ZCode's real ExitPlanMode, or an AskUserQuestion whose shape has no answerable surface): the pet flashes the transient notification (~5s auto-return, no HUD row) instead of staying silent while ZCode waits on its native prompt. A shown bubble or remote card keeps posting `/state` as before. ZCode does not provide a `SessionEnd` hook in this integration, so completion relies on `Stop` plus Clawd's normal process-liveness and stale-session cleanup. When Clawd yields no decision (timeout, disconnect, DND, bubbles off), the hook prints `{}` and ZCode's own permission flow takes over. ## Grok Build Hook Events Grok Build uses config-file hooks under `/hooks/clawd-on-desk.json`: | Grok Hook Event | State | Notes | |---|---|---| | SessionStart | idle | | | UserPromptSubmit | thinking | records the newest turn in the turn fence | | PreToolUse / PostToolUse | working | | | PostToolUseFailure / StopFailure | error | | | Stop (`reason="end_turn"`, no live background tasks/crons, inactive stop hook) | attention | only a genuine unblocked end of turn | | Stop (continuation signal) | working with `event=null` | adapter-local; never latches a terminal | | Stop (`channel_closed` / `shutdown` / missing / unknown reason) | dropped | never synthesizes Done; the real `SessionEnd` or `idle_prompt` settles | | StopCancelled | idle | settles without Done; corrects a same-turn Stop tail | | Notification (`notificationType="idle_prompt"`) | notification | plays the one-shot, then stores the session idle; fence settles the turn | | Other Notification | notification | presentation only; does not settle the active turn | | PreCompact | sweeping | | | PostCompact (manual) | idle | never a completion | | PostCompact (auto) | thinking | never a completion | | PermissionDenied | notification (passive) | no decision; Grok owns permissions | | SessionEnd | remove session; idle if no live sessions | clears the turn fence record | Grok never registers `/permission`; the adapter always emits `{}`. Subagent events (`subagentType`) and `SubagentStart` / `SubagentStop` are out of scope in Phase 1. ## Pi Extension Events Pi uses a global extension (`~/.pi/agent/extensions/clawd-on-desk`) and maps interactive-session lifecycle events to shared Clawd states: | Pi Extension Event | Clawd Event | State | |---|---|---| | session_start | SessionStart | idle | | before_agent_start | UserPromptSubmit | thinking | | tool_call | PreToolUse | working | | tool_result (ok) | PostToolUse | working | | tool_result (isError) | PostToolUseFailure | error | | agent_end | Stop | attention | | session_before_compact | PreCompact | sweeping | | session_compact | PostCompact | attention | | session_shutdown | SessionEnd | remove session; idle if no live sessions | Pi is state-only in Clawd: Clawd does not intercept permissions or add confirmation prompts, so Pi keeps its default YOLO execution behavior. ## OMP Extension Events OMP (oh-my-pi) uses a per-agent extension directory — `~/.omp/agent/extensions/clawd-on-desk` for the default environment — and maps interactive-session lifecycle events to shared Clawd states: | OMP Extension Event | Clawd Event | State | |---|---|---| | session_start | SessionStart | idle | | session_switch / session_branch | SessionStart | idle | | before_agent_start | UserPromptSubmit | thinking | | tool_call | PreToolUse | working | | tool_result (ok) | PostToolUse | working | | tool_result (isError) | PostToolUseFailure | error | | session_stop candidate + following agent_end (`willContinue !== true`) | Stop | attention | | session_before_compact | PreCompact | sweeping | | session_compact | PostCompact | attention | | session_shutdown | SessionEnd | remove session; idle if no live sessions | Three behaviours differ from the Pi extension deliberately: - **Completion is committed across `session_stop` and the following `agent_end`.** `session_stop` is a pre-settle aggregation hook: another extension can still request a hidden continuation after Clawd's handler runs. Clawd records a main-session candidate there, then commits it only when OMP's following `agent_end` does not carry `willContinue: true`. Scheduling pauses, built-in retries and extension continuations therefore do not play the finish chime. - **`session_switch` / `session_branch` are reported, and the session being left is retired** with a synthetic `SessionEnd`. OMP can move an interactive terminal to another conversation with no shutdown for the old one, which would otherwise leave a live HUD row for a session nothing reports on again. - **A `session_title` is always sent.** Several interactive OMP sessions legitimately share one working directory, and the folder-name fallback would render every row — and every jump target — identically. OMP is state-only in Clawd: Clawd does not intercept permissions or add confirmation prompts, so OMP keeps its own execution behavior. ## Mini Mode Drag to the right screen edge (or right-click → "Mini Mode") to enter mini mode — half-body visible at screen edge, peeking out on hover. | Trigger | Mini Reaction | Clawd | Calico | Cloudling | |---|---|---|---|---| | Default | Breathing + blinking + eye tracking | | | | | Hover | Peek out + wave | | | | | Notification | Alert pop | | | | | Task complete | Happy celebration | | | | ## Click Reactions Easter eggs — try double-clicking, rapid 4-clicks, or poking Clawd repeatedly to discover hidden reactions. ## Hash Sage (optional official theme) Hash Sage (哈希仙人) is **not** bundled with Clawd. It is an optional official theme downloaded on demand from the independent `rullerzhou-afk/clawd-themes` repository (Settings → Theme → Official themes). Once installed it runs as an external APNG theme with the same logical states, the approved SVG effects baked into each APNG, and no cursor eye tracking: | State | Hash Sage animation | |---|---| | idle | 空手待机 — standing breath (approved sample; the full idle set is not final yet) | | idle random pool (after 20 s without mouse movement) | 小云捉迷藏 — a little cloud flies in, circles her with a gold trail, plays on her fingertip and flies off; starts and ends on the idle pose | | thinking | 掐诀推演 — palm compass turns, code glyphs rise | | working (1 session) | 执笔制符 — writes the verification talisman | | working (2 sessions) / juggling (1 subagent) | 御剑 · 哈希符文 — twin swords with hash runes | | working (3+ sessions) / juggling (2+ subagents) | 忙碌协作 — two paper spirits help out | | attention | 完成收功 — unrolls the seal scroll | | notification | 小铃轻唤 — rings the small bell | | error | 怎么又炸了 — the talisman backfires | | sweeping / carrying | 拂尘引纸 / 牵云运匣 | | yawning → dozing → collapsing → sleeping → waking | 哈欠入盹 → 托腮轻盹 → 云来安睡 → 云上代码梦 → 伸懒腰醒来 | | DND sleep transition | 直接安睡 | | roam, mini crab-walk | 乘云而行 (drawn heading right, mirrored when heading left) | | drag / double-click / annoyed, 4-click | 张手轻摆 / 小小吃惊 / 有点嫌弃 | | mini idle / enter / hover peek | 贴边探头 / 从右侧走入 / 探出与呼吸 | | mini alert / task complete / working | 摇铃 / 竖卷收功 / 挥符 | | mini enter-sleep / sleep (DND) | 闭眼入场 / 贴墙睡眠呼吸 | Re-downloading after an uninstall is a lossy upgrade: it clears this theme's customizations and Clawd-managed sound overrides. ## Whale-chan (optional official theme) Whale-chan (鲸鱼娘) is **not** bundled with Clawd either. It is an optional official theme downloaded on demand from the same `rullerzhou-afk/clawd-themes` repository (Settings → Theme → Official themes) and requires Clawd 1.2.0. Once installed it runs as an external animated-image theme (animated WebP since theme 1.0.1) with the same logical states, effects baked into each animation, and no cursor eye tracking: | State | Whale-chan animation | |---|---| | idle | 陪你发一会儿呆 — standing breath | | idle random pool (after 20 s without mouse movement) | 大家一起来合奏 — conducts, the music ring fades in and out, then crossfades back to idle | | Default idle visual choice (Settings → Default idle visual) | 泡在泳池里偷个懒 — offered through `idleVisualOptions`, never picked at random | | thinking | 认真想一想 | | working (1 session) | 今天也在努力呀 | | working (2 sessions) / juggling (subagents) | 发现电饭煲啦 — the magic rice cooker | | working (3+ sessions) | 撑着小伞去踩水 — umbrella in the rain | | attention | 任务完成啦! | | notification | 有件事要你确认哦 | | error | 报错也要被接住 | | sweeping / carrying | 把尾巴擦得亮晶晶 / 泡在泳池里偷个懒 | | yawning → dozing → collapsing → sleeping → waking | 慢慢钻进纸箱里 → 在纸箱里轻轻呼吸 → 从纸箱飘进云朵 → 睡在软绵绵的云上 → 睡饱啦,回来陪你 | | DND sleep transition | 乘着云朵进入深睡 | | roam, mini crab-walk | 搭上鲸鱼巴士去兜风 (drawn heading right, mirrored when heading left) | | drag / click reactions | 被拎起来也要晃一晃 / 戳我干嘛,哼! | | mini enter / idle | 从屏幕边探出头来 / 趴在屏幕边陪着你 | | mini hover peek | 撑起身子看看你, then holds the pose while the pointer stays (`mini-peek-hold`) | | mini working / alert / task complete | 认真干饭中 / 叮!有事找你 / 砰!做完啦 | | mini enter-sleep / sleep (DND) / hover while asleep | 闭着眼也来陪你 / 趴在屏幕边睡着了 / 睡着也撑起身子 (`mini-sleep-peek`) |