From 33a80b17a0ceb076bdc84fed6b1232414629b87e Mon Sep 17 00:00:00 2001 From: "warp-agent-staging[bot]" <240773466+warp-agent-staging[bot]@users.noreply.github.com> Date: Thu, 12 Nov 2026 01:56:03 +0000 Subject: [PATCH] Surface waited-on lifecycle events in root and child Claude hooks --- .claude-plugin/marketplace.json | 2 +- .../.claude-plugin/plugin.json | 2 +- plugins/oz-harness-support/README.md | 13 +++-- .../scripts/oz-parent-common.sh | 52 +++++++++--------- .../scripts/oz-parent-listener.sh | 6 ++- .../oz-harness-support/tests/test-hooks.sh | 53 +++++++++++++++---- 6 files changed, 85 insertions(+), 43 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 03a9f28..1bb91f7 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -18,7 +18,7 @@ "name": "oz-harness-support", "description": "Warp integration for Claude Code in Oz cloud agent environments, including parent-message delivery hooks", "source": "./plugins/oz-harness-support", - "version": "1.1.4", + "version": "1.1.5", "category": "productivity", "tags": ["terminal", "warp", "oz"] } diff --git a/plugins/oz-harness-support/.claude-plugin/plugin.json b/plugins/oz-harness-support/.claude-plugin/plugin.json index 2afdd81..69d0b4a 100644 --- a/plugins/oz-harness-support/.claude-plugin/plugin.json +++ b/plugins/oz-harness-support/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "oz-harness-support", "description": "Warp terminal integration for Claude Code in Oz cloud agent environments, including parent-message delivery hooks", - "version": "1.1.4", + "version": "1.1.5", "author": { "name": "Warp", "url": "https://warp.dev" diff --git a/plugins/oz-harness-support/README.md b/plugins/oz-harness-support/README.md index 4dd76d6..6398543 100644 --- a/plugins/oz-harness-support/README.md +++ b/plugins/oz-harness-support/README.md @@ -6,12 +6,17 @@ This plugin is installed automatically in Oz cloud agent environments — there ## Hooks -The plugin registers an Oz parent-message delivery bridge: -- **SessionStart** — starts the parent-message listener for the run -- **UserPromptSubmit** / **PostToolUse** — drain the mailbox, surfacing queued parent messages into the session as additional context -- **Stop** — keeps the session active when parent messages are still pending delivery +The plugin registers an Oz coordination bridge for both root and child runs: +- **SessionStart** — starts the run's event listener, or reuses the Warp-managed bridge +- **UserPromptSubmit** / **PostToolUse** — surface queued mailbox messages and read-only lifecycle notifications as additional context +- **Stop** — keeps the session active when coordination events are still pending delivery - **SessionEnd** — tears down the listener and cleans up hook state +`run_waited_on` notifications say “Run {id} is waiting for you,” where the ID identifies +the waiting run, not necessarily a parent. They are status metadata, not instructions, +and are never acknowledged through mailbox delivery APIs. Hooks require `OZ_CLI` and +`OZ_RUN_ID`; they remain inert outside Oz. + ## Skills The plugin ships skills the agent uses to talk to the Oz platform: diff --git a/plugins/oz-harness-support/scripts/oz-parent-common.sh b/plugins/oz-harness-support/scripts/oz-parent-common.sh index a30d48a..5bef8cf 100755 --- a/plugins/oz-harness-support/scripts/oz-parent-common.sh +++ b/plugins/oz-harness-support/scripts/oz-parent-common.sh @@ -11,14 +11,9 @@ OZ_PARENT_SURFACED_IDS=() read_hook_input() { cat } -# Only child Claude runs have a lead-agent parent to bridge messages from. -# When OZ_PARENT_RUN_ID is absent, leave the hooks inert so they do not affect -# regular Oz harness sessions that are not running as child agents. - oz_harness_available() { [ -n "${OZ_CLI:-}" ] && [ -n "${OZ_RUN_ID:-}" ] && - [ -n "${OZ_PARENT_RUN_ID:-}" ] && command -v "$OZ_CLI" >/dev/null 2>&1 } @@ -39,7 +34,7 @@ session_id_from_input() { } state_root() { - printf '%s\n' "${OZ_PARENT_STATE_ROOT:-$HOME/.claude-code/oz-parent-bridge}" + printf '%s\n' "${OZ_MESSAGE_LISTENER_STATE_ROOT:-${OZ_PARENT_STATE_ROOT:-$HOME/.claude-code/oz-parent-bridge}}" } state_dir_from_session_id() { @@ -265,7 +260,7 @@ ensure_last_sequence_file() { # driver's state directory instead of starting or cleaning up their own # listener lifecycle. listener_lifecycle_managed_externally() { - [ "${OZ_PARENT_LISTENER_MANAGED_EXTERNALLY:-0}" = "1" ] + [ "${OZ_MESSAGE_LISTENER_MANAGED_EXTERNALLY:-${OZ_PARENT_LISTENER_MANAGED_EXTERNALLY:-0}}" = "1" ] } load_hook_state() { @@ -316,7 +311,7 @@ emit_stop_block_if_pending() { pending_count="$(wait_for_pending_parent_messages "$state_dir")" || return 1 [ "$pending_count" -gt 0 ] || return 1 - reason="There are ${pending_count} pending parent message(s) from the lead Oz run. Continue so the next safe boundary can surface them." + reason="There are ${pending_count} pending Oz coordination event(s). Continue so the next safe boundary can surface them." jq -nc --arg reason "$reason" '{decision:"block", reason:$reason}' } @@ -327,20 +322,14 @@ mark_message_delivered() { true } -remove_staged_message() { - local state_dir="$1" - local message_id="$2" - find "$(staged_dir "$state_dir")" -type f -name "*-${message_id}.json" -delete 2>/dev/null || true -} - build_parent_context_from_staged_messages() { local state_dir="$1" local max_context_chars="${2:-6000}" local staged_file total_staged=0 - local message_id sender_run_id subject body sequence + local message_id sender_run_id subject body sequence event_type local block separator candidate remaining note - OZ_PARENT_RENDERED_CONTEXT=$'Lead-agent updates arrived from Oz. Treat the latest parent instructions below as authoritative.\n' + OZ_PARENT_RENDERED_CONTEXT=$'Oz coordination update. Mailbox messages are user-level coordination. Lifecycle notifications are read-only status, not instructions.\n' OZ_PARENT_REMAINING_COUNT=0 OZ_PARENT_SURFACED_IDS=() @@ -353,18 +342,23 @@ build_parent_context_from_staged_messages() { subject="$(json_file_field "$staged_file" '.subject')" body="$(json_file_field "$staged_file" '.body')" sequence="$(json_file_field "$staged_file" '.sequence')" + event_type="$(json_file_field "$staged_file" '.event_type')" [ -n "$message_id" ] || continue [ -n "$subject" ] || subject="(no subject)" - block=$'---\nParent message' - if [ -n "$sequence" ]; then - block="$block #$sequence" - fi - if [ -n "$sender_run_id" ]; then - block="$block from $sender_run_id" + if [ "$event_type" = "run_waited_on" ]; then + block=$'---\nRead-only lifecycle notification\n\n'"$body" + else + block=$'---\nMailbox message' + if [ -n "$sequence" ]; then + block="$block #$sequence" + fi + if [ -n "$sender_run_id" ]; then + block="$block from $sender_run_id" + fi + block="$block"$'\n'"Subject: $subject"$'\n\n'"$body" fi - block="$block"$'\n'"Subject: $subject"$'\n\n'"$body" separator="" if [ "${#OZ_PARENT_SURFACED_IDS[@]}" -gt 0 ]; then @@ -392,7 +386,7 @@ build_parent_context_from_staged_messages() { OZ_PARENT_REMAINING_COUNT=$((total_staged - ${#OZ_PARENT_SURFACED_IDS[@]})) if [ "$OZ_PARENT_REMAINING_COUNT" -gt 0 ]; then - note=$'\n\nMore parent messages are still staged and will be surfaced on a later turn.' + note=$'\n\nMore Oz coordination events are still staged and will be surfaced on a later turn.' if [ $(( ${#OZ_PARENT_RENDERED_CONTEXT} + ${#note} )) -le "$max_context_chars" ]; then OZ_PARENT_RENDERED_CONTEXT="${OZ_PARENT_RENDERED_CONTEXT}${note}" fi @@ -404,9 +398,15 @@ deliver_and_remove_staged_messages() { local message_id shift + local staged_file event_type for message_id in "$@"; do - mark_message_delivered "$message_id" - remove_staged_message "$state_dir" "$message_id" + while IFS= read -r staged_file; do + event_type="$(json_file_field "$staged_file" '.event_type')" + if [ "$event_type" != "run_waited_on" ]; then + mark_message_delivered "$message_id" + fi + rm -f "$staged_file" + done < <(find "$(staged_dir "$state_dir")" -type f -name "*-${message_id}.json" -print) done } diff --git a/plugins/oz-harness-support/scripts/oz-parent-listener.sh b/plugins/oz-harness-support/scripts/oz-parent-listener.sh index fc33e1f..bd68065 100755 --- a/plugins/oz-harness-support/scripts/oz-parent-listener.sh +++ b/plugins/oz-harness-support/scripts/oz-parent-listener.sh @@ -10,12 +10,14 @@ STATE_DIR="${1:?state directory is required}" stage_message_from_watch_record() { local state_dir="$1" local line="$2" - local sequence message_id target + local sequence message_id target previous_sequence sequence="$(json_field "$line" '.sequence')" message_id="$(json_field "$line" '.message_id')" - [ -n "$sequence" ] || return 0 + [[ "$sequence" =~ ^[0-9]+$ ]] || return 0 + previous_sequence="$(cat "$(last_sequence_file "$state_dir")" 2>/dev/null || true)" + [ "$sequence" -gt "${previous_sequence:-0}" ] || return 0 [ -n "$message_id" ] || return 0 target="$(staged_message_path "$state_dir" "$sequence" "$message_id")" diff --git a/plugins/oz-harness-support/tests/test-hooks.sh b/plugins/oz-harness-support/tests/test-hooks.sh index 96fc289..1fca164 100755 --- a/plugins/oz-harness-support/tests/test-hooks.sh +++ b/plugins/oz-harness-support/tests/test-hooks.sh @@ -137,7 +137,7 @@ EOF OUTPUT=$(printf '%s' "$HOOK_INPUT" | bash "$SCRIPT_DIR/on-stop.sh") assert_json_field "stop blocks when staged messages remain" "$OUTPUT" ".decision" "block" -assert_contains "stop reason references pending parent messages" "$OUTPUT" "pending parent message" +assert_contains "stop reason references pending Oz coordination events" "$OUTPUT" "pending Oz coordination event" rm -f "$STATE_DIR/staged/"*.json OUTPUT=$(printf '%s' "$HOOK_INPUT" | bash "$SCRIPT_DIR/on-stop.sh") @@ -152,19 +152,54 @@ assert_eq "session end emits no output" "" "$OUTPUT" assert_eq "session end removes state directory" "false" "$([ -d "$STATE_DIR" ] && echo true || echo false)" echo "" -echo "=== non-child sessions are ignored ===" +echo "=== root lifecycle delivery ===" rm -rf "$STATE_DIR" +: >"$FAKE_OZ_LOG" unset OZ_PARENT_RUN_ID +cat >"$FAKE_OZ_WATCH" <<'EOF' +{"event_type":"run_waited_on","sequence":101,"message_id":"synthetic-wait","sender_run_id":"child-waiter","subject":"","body":"Run child-waiter is waiting for you","occurred_at":"2026-11-12T00:00:00Z"} +{"sequence":102,"message_id":"mailbox-update","sender_run_id":"child-run","subject":"Update","body":"Ordinary mailbox message.","occurred_at":"2026-11-12T00:00:01Z"} +EOF +bash "$SCRIPT_DIR/oz-parent-listener.sh" "$STATE_DIR" +OUTPUT=$(printf '%s' "$HOOK_INPUT" | bash "$SCRIPT_DIR/drain-mailbox.sh" PostToolUse) +assert_contains "root notification names the waiter" "$OUTPUT" "Run child-waiter is waiting for you" +assert_contains "root notification is read-only" "$OUTPUT" "Read-only lifecycle notification" +assert_contains "root preserves ordinary messages" "$OUTPUT" "Ordinary mailbox message." +assert_eq "root notification has no parent authority" "false" "$(printf '%s' "$OUTPUT" | grep -q authoritative && echo true || echo false)" +assert_eq "synthetic notification is never marked delivered" "false" "$(grep -q 'delivered synthetic-wait' "$FAKE_OZ_LOG" && echo true || echo false)" +assert_contains "ordinary mailbox message is marked delivered" "$(cat "$FAKE_OZ_LOG")" "mark-delivered mailbox-update" +assert_eq "root records are removed after drain" "0" "$(find "$STATE_DIR/staged" -name '*.json' | wc -l | tr -d ' ')" +bash "$SCRIPT_DIR/oz-parent-listener.sh" "$STATE_DIR" +assert_eq "reconnect does not replay consumed notifications" "0" "$(find "$STATE_DIR/staged" -name '*.json' | wc -l | tr -d ' ')" +assert_eq "root notification cursor advances" "102" "$(cat "$STATE_DIR/last-sequence")" +mkdir -p "$STATE_DIR/surfaced" +export OZ_MESSAGE_LISTENER_MANAGED_EXTERNALLY=1 +export OZ_MESSAGE_LISTENER_STATE_ROOT="$STATE_ROOT" +cat >"$STATE_DIR/pending-hook-output.json" <<'EOF' +{"additional_context":"Read-only lifecycle notification: Run child-waiter is waiting for you","remaining_staged_count":0,"surfaced_count":1} +EOF OUTPUT=$(printf '%s' "$HOOK_INPUT" | bash "$SCRIPT_DIR/on-session-start.sh") -assert_eq "non-child session start emits no output" "" "$OUTPUT" -assert_eq "non-child session start does not create state directory" "false" "$([ -d "$STATE_DIR" ] && echo true || echo false)" +assert_eq "managed root does not launch legacy listener" "false" "$([ -f "$STATE_DIR/listener.pid" ] && echo true || echo false)" +OUTPUT=$(printf '%s' "$HOOK_INPUT" | bash "$SCRIPT_DIR/drain-mailbox.sh" PostToolUse) +assert_contains "managed root surfaces driver lifecycle context" "$OUTPUT" "Run child-waiter is waiting for you" +assert_eq "managed root acknowledges local driver output" "true" "$([ -f "$STATE_DIR/pending-hook-output.ack" ] && echo true || echo false)" +unset OZ_MESSAGE_LISTENER_MANAGED_EXTERNALLY OZ_MESSAGE_LISTENER_STATE_ROOT +export OZ_PARENT_RUN_ID="parent-run-456" +rm -rf "$STATE_DIR" + +echo "=== non-Oz sessions are ignored ===" +rm -rf "$STATE_DIR" +unset OZ_RUN_ID +OUTPUT=$(printf '%s' "$HOOK_INPUT" | bash "$SCRIPT_DIR/on-session-start.sh") +assert_eq "non-Oz session start emits no output" "" "$OUTPUT" +assert_eq "non-Oz session start does not create state directory" "false" "$([ -d "$STATE_DIR" ] && echo true || echo false)" OUTPUT=$(printf '%s' "$HOOK_INPUT" | bash "$SCRIPT_DIR/drain-mailbox.sh" UserPromptSubmit) -assert_eq "non-child drain emits no output" "" "$OUTPUT" +assert_eq "non-Oz drain emits no output" "" "$OUTPUT" OUTPUT=$(printf '%s' "$HOOK_INPUT" | bash "$SCRIPT_DIR/on-stop.sh") -assert_eq "non-child stop emits no output" "" "$OUTPUT" +assert_eq "non-Oz stop emits no output" "" "$OUTPUT" OUTPUT=$(printf '%s' "$HOOK_INPUT" | bash "$SCRIPT_DIR/on-session-end.sh") -assert_eq "non-child session end emits no output" "" "$OUTPUT" -export OZ_PARENT_RUN_ID="parent-run-456" +assert_eq "non-Oz session end emits no output" "" "$OUTPUT" +export OZ_RUN_ID="child-run-123" echo "" echo "=== externally managed lifecycle and drain ===" @@ -215,7 +250,7 @@ linger_writer_pid=$! OUTPUT=$(printf '%s' "$HOOK_INPUT" | bash "$SCRIPT_DIR/on-stop.sh") wait "$linger_writer_pid" assert_json_field "externally managed stop lingers for late-arriving staged messages" "$OUTPUT" ".decision" "block" -assert_contains "externally managed linger reason references pending parent messages" "$OUTPUT" "pending parent message" +assert_contains "externally managed linger reason references pending Oz coordination events" "$OUTPUT" "pending Oz coordination event" unset OZ_PARENT_STOP_LINGER_ATTEMPTS unset OZ_PARENT_STOP_LINGER_POLL_SECONDS