Show waiting-for-input state in factory visualization

[williamthorsen]

Problem

When an orchestrated run pauses waiting for user input (permission prompts, AskUserQuestion dialogs, wrap-up confirmation), the factory visualization has no way to show this. A user watching the vis just sees stalled activity with no indication the orchestrator is blocked on them.

Proposed solution

Use Claude Code hooks to detect input-waiting states, emit new events to run-log.jsonl, and have the factory vis render the waiting state.

Architecture

Claude Code hooks                    run-log.jsonl                Factory vis
─────────────────                    ─────────────                ──────────
Notification hook  ──> append ──>  waiting_for_input event  ──>  orchestrator shows waiting
UserPromptSubmit   ──> append ──>  input_received event     ──>  orchestrator resumes

Key design decisions

1. Breadcrumb file (.claude/tmp/active-run-dir): The orchestrate skill writes the runDir path here after init_run. Hook scripts read it to discover which run-log.jsonl to append to. tmp/ is already gitignored. Only one orchestration runs per project directory, so cwd is a natural key.

2. Two new event types in run-core: waiting_for_input (with reason: permission_prompt | elicitation_dialog | idle_prompt) and input_received. These fold into a new waitingForInput field on CanonicalRunStatus.

3. Hook scripts (.claude/hooks/): Shell scripts triggered by Claude Code's Notification and UserPromptSubmit hooks. They read the breadcrumb, append JSONL directly (bypassing MCP since hooks run outside MCP context). Atomic single-line appends are safe on POSIX.

4. Visual treatment: Orchestrator sprite switches to concerned animation at 0.6 opacity (between idle 0.35 and active 1.0) when waiting. Clears when input is received. No new sprite assets needed.

5. Backward compatible: Old run-log.jsonl files without these events fold with waitingForInput: undefined. The mapper treats undefined as "not waiting."

Considerations

• Hook scripts must silently no-op when no orchestration is active (breadcrumb guard)
• The UserPromptSubmit hook fires on every user prompt, but the breadcrumb + idempotent folder make this harmless
• The exact JSON field name for the notification type in hook input needs verification during implementation (could be matcher, hook_event_name, or similar)
• JSONL concurrent writes from hooks and MCP are safe under POSIX PIPE_BUF for small lines

Scope

• run-core: 2 new event types, Zod schemas, event folder, exports
• factory: mapper, differ, OrchestratorActor, CatwalkScene, types
• agents: orchestrate skill breadcrumb write/cleanup
• .claude/: hook scripts + settings.json configuration
• Tests for schema parsing and event folding

Acceptance criteria

• waiting_for_input and input_received events parse and validate via Zod schema
• foldEvents() correctly sets/clears waitingForInput on CanonicalRunStatus
• Factory mapper derives orchestrator.waiting from waitingForInput status
• Orchestrator sprite visually changes when waiting (concerned animation, 0.6 opacity)
• Hook scripts silently exit when no orchestration is active
• Hook scripts correctly append JSONL to the active run's log file
• Breadcrumb written after init_run, cleaned up after complete_run
• pnpm run check passes (typecheck, format, lint, tests)
• Manual verification: factory vis shows waiting state during permission prompt

[williamthorsen]

Implementation plan

20260313-1200Z_waiting-for-input-vis_plan.md

Waiting-for-input visibility in factory visualization

Context

When an orchestrated run pauses for user input (permission prompts, AskUserQuestion dialogs, wrap-up confirmation), the factory visualization shows no indication of this. A user watching the vis just sees stalled activity with no way to know the orchestrator is blocked on them.

The solution: use Claude Code hooks to detect input-waiting states, emit new events to run-log.jsonl, and have the factory vis render the waiting state.

Architecture

Claude Code hooks                    run-log.jsonl                Factory vis
─────────────────                    ─────────────                ──────────
Notification hook  ──> append ──>  waiting_for_input event  ──>  orchestrator shows waiting
UserPromptSubmit   ──> append ──>  input_received event     ──>  orchestrator resumes

The hooks discover the active run directory via a breadcrumb file (.claude/tmp/active-run-dir) written by the orchestrate skill at run start.

Step 1: New event types in run-core

1a. Types — packages/run-core/src/types/canonical.ts

Add WaitingForInputReason type (follows existing pattern where canonical.ts owns domain types imported by run-log.ts):

export type WaitingForInputReason = 'permission_prompt' | 'elicitation_dialog' | 'idle_prompt';

Add to CanonicalRunStatus:

waitingForInput: WaitingForInputReason | undefined;

1b. Types — packages/run-core/src/types/run-log.ts

Import WaitingForInputReason from ./canonical.js (same pattern as Criticality, RunStatus, etc.).

Add two event interfaces:

export interface WaitingForInputEvent {
  t: string;
  event: 'waiting_for_input';
  reason: WaitingForInputReason;
}

export interface InputReceivedEvent {
  t: string;
  event: 'input_received';
}

Add both to the RunEvent union. Update doc comment from 13 to 15.

1c. Schemas — packages/run-core/src/schemas/run-log-schema.ts

Add Zod schemas:

const waitingForInputReasonSchema = z.enum(['permission_prompt', 'elicitation_dialog', 'idle_prompt']);

const waitingForInputSchema = z.object({
  t: z.string(),
  event: z.literal('waiting_for_input'),
  reason: waitingForInputReasonSchema,
});

const inputReceivedSchema = z.object({
  t: z.string(),
  event: z.literal('input_received'),
});

Add both to the z.discriminatedUnion('event', [...]) array. Update doc comment.

1d. Event folder — packages/run-core/src/event-folder.ts

Initialize waitingForInput: undefined in foldEvents().

Add cases to applyEvent():

case 'waiting_for_input':
  state.waitingForInput = event.reason;
  break;

case 'input_received':
  state.waitingForInput = undefined;
  break;

1e. Exports — packages/run-core/src/index.ts

Export WaitingForInputEvent, InputReceivedEvent, and WaitingForInputReason.

1f. Factory re-export — packages/factory/src/shared/types/canonical.ts

Add WaitingForInputReason to the re-export list.

Step 2: Tests for new events

2a. Schema tests — packages/run-core/src/schemas/__tests__/run-log-schema.test.ts

Follow existing pattern (parse valid line, check fields):

• it('parses a waiting_for_input event with reason')
• it('parses an input_received event')
• it('throws when waiting_for_input has invalid reason')

2b. Event folder tests — packages/run-core/src/__tests__/event-folder.test.ts

Follow existing pattern (fold events, check state):

• it('initializes waitingForInput as undefined with no events')
• it('sets waitingForInput on waiting_for_input event')
• it('clears waitingForInput on input_received event')

Step 3: Factory visualization updates

3a. Types — packages/factory/src/client/visualizations/catwalk/types.ts

Add waiting: boolean to OrchestratorConfig.

Add waitingChanged: { from: boolean; to: boolean } | null to OrchestratorDiff.

3b. Mapper — packages/factory/src/client/visualizations/catwalk/mappers/run-to-catwalk.ts

In buildOrchestrator():

const waiting = status.waitingForInput !== undefined && status.status === 'in_progress';
const effectiveWorking = waiting ? false : working;

return { stationIndex, working: effectiveWorking, celebrating, waiting, carriedArtifacts, codeBadge };

3c. Differ — packages/factory/src/client/visualizations/catwalk/state/catwalk-differ.ts

In diffOrchestrator(), add:

const waitingChanged = prev.waiting === next.waiting ? null : { from: prev.waiting, to: next.waiting };

Return it in the diff. Add orchestrator.waitingChanged !== null to hasChanges.

3d. OrchestratorActor — packages/factory/src/client/visualizations/catwalk/actors/OrchestratorActor.ts

Add waiting: boolean to OrchestratorActorConfig.

Add setWaiting(waiting: boolean) method:

• When true: switch to concerned animation at moderate opacity (0.6 — distinct from idle 0.35 and active 1.0)
• When false: restore to idle animation at ORCH_IDLE_OPACITY

3e. CatwalkScene — packages/factory/src/client/visualizations/catwalk/scene/CatwalkScene.ts

In applyDiff(), after working/celebrating logic:

if (diff.orchestrator.waitingChanged !== null && this.orchestratorRef !== undefined) {
  this.orchestratorRef.setWaiting(diff.orchestrator.waitingChanged.to);
}

In addOrchestrator(), handle initial waiting state:

if (config.orchestrator.waiting) {
  orchestratorActor.setWaiting(true);
}

Pass waiting in the OrchestratorActorConfig constructor call.

Step 4: Breadcrumb file in orchestrate skill

4a. Write breadcrumb — packages/agents/content/skills/orchestrate/SKILL.md

After init_run success, add instruction to write the breadcrumb:

mkdir -p .claude/tmp && echo "{run-dir}" > .claude/tmp/active-run-dir

4b. Clean up breadcrumb — same file

After complete_run (success or failure), add:

rm -f .claude/tmp/active-run-dir

Step 5: Hook scripts

5a. Notification hook — .claude/hooks/on-waiting-for-input.sh

#!/usr/bin/env bash
set -euo pipefail

BREADCRUMB=".claude/tmp/active-run-dir"
[ -f "$BREADCRUMB" ] || exit 0

RUN_DIR=$(cat "$BREADCRUMB")
LOG_FILE="$RUN_DIR/run-log.jsonl"
[ -f "$LOG_FILE" ] || exit 0

INPUT=$(cat)
REASON=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('matcher',''))" 2>/dev/null || echo "")

case "$REASON" in
  permission_prompt|elicitation_dialog|idle_prompt) ;;
  *) exit 0 ;;
esac

TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "{\"t\":\"$TIMESTAMP\",\"event\":\"waiting_for_input\",\"reason\":\"$REASON\"}" >> "$LOG_FILE"

5b. Input received hook — .claude/hooks/on-input-received.sh

#!/usr/bin/env bash
set -euo pipefail

BREADCRUMB=".claude/tmp/active-run-dir"
[ -f "$BREADCRUMB" ] || exit 0

RUN_DIR=$(cat "$BREADCRUMB")
LOG_FILE="$RUN_DIR/run-log.jsonl"
[ -f "$LOG_FILE" ] || exit 0

TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
echo "{\"t\":\"$TIMESTAMP\",\"event\":\"input_received\"}" >> "$LOG_FILE"

Note: These scripts write JSONL directly (not via MCP) because hooks run outside the MCP context. Atomic single-line appends are safe on POSIX (well under PIPE_BUF).

Step 6: Hook configuration

.claude/settings.json

Add hooks key alongside existing enabledPlugins and mcpServers:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "idle_prompt|permission_prompt|elicitation_dialog",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/on-waiting-for-input.sh"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/on-input-received.sh"
          }
        ]
      }
    ]
  }
}

Verification

1. Unit tests: pnpm run check — validates typecheck, format, lint, and tests across all packages
2. Manual integration test:
   • Start factory dev server (cd packages/factory && pnpm run dev)
   • Start an orchestrated run
   • When a permission prompt appears, verify the orchestrator sprite switches to the concerned animation with moderate opacity
   • When the user responds, verify the orchestrator returns to working/idle
3. Hook isolation test: Run Claude Code without an active orchestration — verify hooks are silent (no errors, no file writes)

Files to modify

File	Change
packages/run-core/src/types/canonical.ts	Add WaitingForInputReason, add field to CanonicalRunStatus
packages/run-core/src/types/run-log.ts	Add WaitingForInputEvent, InputReceivedEvent, extend RunEvent union
packages/run-core/src/schemas/run-log-schema.ts	Add Zod schemas, extend discriminated union
packages/run-core/src/event-folder.ts	Add two cases to applyEvent(), init field
packages/run-core/src/index.ts	Export new types
packages/run-core/src/schemas/__tests__/run-log-schema.test.ts	Schema parse tests
packages/run-core/src/__tests__/event-folder.test.ts	Folder state tests
packages/factory/src/shared/types/canonical.ts	Re-export WaitingForInputReason
packages/factory/src/client/visualizations/catwalk/types.ts	Add waiting to configs/diffs
packages/factory/src/client/visualizations/catwalk/mappers/run-to-catwalk.ts	Derive waiting from status
packages/factory/src/client/visualizations/catwalk/state/catwalk-differ.ts	Diff waiting field
packages/factory/src/client/visualizations/catwalk/actors/OrchestratorActor.ts	Add setWaiting() method
packages/factory/src/client/visualizations/catwalk/scene/CatwalkScene.ts	Apply waiting diff
packages/agents/content/skills/orchestrate/SKILL.md	Breadcrumb write/cleanup
.claude/hooks/on-waiting-for-input.sh	New file
.claude/hooks/on-input-received.sh	New file
.claude/settings.json	Hook configuration

[williamthorsen]

Insight: _waiting guard pattern for priority-based animation override

The _waiting guard pattern — where the actor tracks its own waiting state and defers visual working updates while waiting — cleanly prevents choreographer-driven state changes from clobbering higher-priority visual states.

When waitingChanged and workingChanged arrive in the same diff, the choreographer calls setWorking() after setWaiting() has already been applied. Without the guard, the working animation overwrites the concerned animation. The _waiting flag in OrchestratorActor causes setWorking() to update only the stored _working value (for later restoration) while skipping the visual change.

This pattern generalizes to any future priority-based animation override (e.g., error states, celebration priority over working).

Source: #290 orchestrated run 20260313-105404Z