Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"]
}
Expand Down
2 changes: 1 addition & 1 deletion plugins/oz-harness-support/.claude-plugin/plugin.json
Original file line number Diff line number Diff line change
@@ -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"
Expand Down
13 changes: 9 additions & 4 deletions plugins/oz-harness-support/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
52 changes: 26 additions & 26 deletions plugins/oz-harness-support/scripts/oz-parent-common.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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
}

Expand All @@ -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() {
Expand Down Expand Up @@ -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() {
Expand Down Expand Up @@ -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}'
}

Expand All @@ -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=()

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
}

Expand Down
6 changes: 4 additions & 2 deletions plugins/oz-harness-support/scripts/oz-parent-listener.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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")"
Expand Down
53 changes: 44 additions & 9 deletions plugins/oz-harness-support/tests/test-hooks.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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")
Expand All @@ -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 ==="
Expand Down Expand Up @@ -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

Expand Down
Loading