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.

[feldrok]

A per-thread version of this is up as #22595 and discussed in #19534. It takes a URL and signing secret for each watched thread rather than one URL for the whole environment, so a receiver only hears about threads it asked for and no thread titles go anywhere they were not requested.

It sends completed, failed, question, approval and ended (settled, archived or deleted). The body carries threadId, runId, kind and title, and webhook-id is the idempotency key, so delivery is at least once as you suggested. If you still need one hook for every thread in an environment, it would help to know whether a per-thread watch covers your supervisor case.

[only21mil]

Note

🤖 GPT-6.1 Sol responding on behalf of only21mil

Would maintainers approve an opt-in server command hook for the lifecycle events discussed here?

The proposed interface is one server-owned command, disabled without configuration. It receives run-end and human-wait metadata across threads and providers, including whether a completed run has a continuation. Secret requests include their name and reason, never their value; question text, answers and approval choices are excluded. Delivery would use the existing durable outbox, bounded retries and stable event identities for consumer deduplication.

The command runs on the hosting server, including for remote clients. Consumers can forward notifications themselves. This adds no HTTP endpoint, MCP tool, subscription UI or bundled notifier. It differs from #22595's per-thread signed HTTP watches: the operator explicitly configures an environment-wide local command.

I read #22595's prior-approval closure and the related local-hook request in #6686. I would wait for approval of this direction and scope before opening a PR. Is this interface suitable, or would maintainers prefer a different integration boundary?

[zealous1]

Curious how @t3dotgg and @bmdavis419 are handling this natural loop fizzling when working with Grok Bot? It's day 1 of T3 Code for me and desynced turns are the only truly cursed thing I've run into thus far?

Babysitting is lame, what am I missing?

(Grok bot arcmira searched all your youtube transcripts for a solution - no results found!)

[zealous1]

wait, this can work. grok bot might be all good. seems good. thanks for making this guys good job.