Feature: configurable outbound completion webhook for turn/thread terminal events

[mferraznw]

Summary

T3 Code already has strong in-product completion signals (turn.completed, thread settled lifecycle, WebSocket push to connected clients) and a polished mobile outbound path (Agent Awareness → T3 Connect Relay → APNs / Live Activities when publishAgentActivity is enabled).

What is missing is a user-configurable HTTP completion webhook (or equivalent generic outbound callback) that third-party supervisors, CI, or multi-agent harnesses can subscribe to when a turn or thread becomes terminal.

Problem

Multi-agent setups (Claude / Codex / Grok Build / remote workers) often need:

1. A cheap parent process (or shell) to be woken when a T3 worker finishes a turn
2. A structured payload (thread id, turn id, state, optional last assistant text / checkpoint)
3. Delivery without holding a long-lived WebSocket client or polling ~/.t3/userdata/state.sqlite

Today the practical workarounds are:

• Poll the local SQLite projection DB
• Stay connected on the orchestration WebSocket and filter events
• Rely on mobile Agent Awareness (human UX, not agent-to-agent)

None of those is a clean “POST my URL when this thread’s turn completes” contract.

Proposal (minimal v1)

Opt-in environment or settings config, for example:

completionWebhookUrl: https://…
completionWebhookEvents: [turn.completed, turn.failed, thread.settled]
completionWebhookSecret: …   # optional HMAC header

On matching terminal events, POST JSON roughly:

{
  "event": "turn.completed",
  "environmentId": "…",
  "threadId": "…",
  "turnId": "…",
  "state": "completed",
  "sessionStatus": "ready",
  "projectId": "…",
  "title": "…",
  "completedAt": "…",
  "checkpointRef": "…",
  "deepLink": "/threads/{env}/{thread}"
}

Non-goals for v1

• Full chat transcript in the payload (optional later / signed URL)
• Replacing Agent Awareness / APNs
• Guaranteed exactly-once delivery across process restarts (at-least-once + idempotency key is enough)

Nice-to-have later

• Per-thread override via orchestration API
• Retry / dead-letter visibility in Settings
• Filter by project or provider

Why this fits existing architecture

From current main plumbing:

• Runtime already emits turn.completed (ProviderRuntimeIngestion / adapters)
• CheckpointReactor already reacts to turn completion for git capture
• AgentAwarenessRelay already projects terminal phases and publishes outbound activity to the relay
• Relay already has delivery attempt tracking for mobile

A local (or optional relay-mediated) webhook fan-out is a small sibling of Agent Awareness, aimed at machines rather than lock-screen humans.

Alternatives considered

Approach	Gap
Mobile Agent Awareness only	Human notifications; no arbitrary URL; no agent resume payload
Client WebSocket only	Requires always-on subscriber process with auth
SQLite poll by external tool	Works today; duplicates product logic; races on projection lag
OS notifications (desktop)	Local human UX only

Related

• Agent Awareness + publishAgentActivity (mobile completion delivery)
• Issue discussions around OS notifications for completed/failed turns
• Subagent parentThreadId (links children; does not notify external parents)

Context

We're currently bridging this with a local delegate subscribe --t3 watcher against state.sqlite + optional DELEGATE_WEBHOOK_URL. A first-party webhook would remove the poller and give a supported contract for agent harnesses.

One final note for your consideration. We are using T3 cross-host for run visibility, so thinking the above would also help us use our inggest workflows for the same, hence the external supervison mention.

I'm happy to raise a PR for this, if invited to do so.

Thanks for considering.