openclaw - 💡(How to fix) Fix [Feature]: Add an optional result-return mode for /hooks/agent [1 participants]

Summary

Add an opt-in, machine-friendly result-return mode for POST /hooks/agent, so external automations can submit work and receive a deterministic result without relying on sessions_history polling or reopening sessions_send over HTTP.

Problem to solve

OpenClaw currently has two nearby primitives, but neither is a clean fit for callback / handoff workflows:

• /hooks/agent is good for authenticated external triggers, but it is async-oriented and posts a summary into the main session.
• sessions_send is good for agent-to-agent messaging, but it is intentionally blocked from HTTP /tools/invoke by default, and its semantics are broader than a narrow machine callback.

This leaves a gap for workflows like:

• runner completion callbacks
• long-running bot-task completion callbacks
• protocol-style continuation handoff (run_handoff -> run_handoff_result)

Today the best official workaround is:

1. send work via POST /hooks/agent
2. later recover the result with sessions_history

That works for simple experiments, but it is awkward as a product surface:

• requires stitching together two APIs
• encourages polling/readback flows
• is not a first-class machine callback primitive

Proposed solution

Extend POST /hooks/agent with an optional wait/result mode.

Example request:

{
  "message": "Run this protocol task",
  "agentId": "bridge-protocol",
  "sessionKey": "hook:bridge:run-123",
  "deliver": false,
  "waitForResult": true,
  "timeoutSeconds": 30,
  "resultMode": "assistant_text",
  "announceToMain": false
}

Example response:

{
  "ok": true,
  "status": "completed",
  "runId": "run_123",
  "sessionKey": "agent:bridge-protocol:hook:bridge:run-123",
  "result": "{\"type\":\"run_handoff_result\",\"status\":\"ok\"}"
}

Suggested behavior:

• waitForResult=false → keep current async behavior
• waitForResult=true → wait for completion and return a narrow machine-readable result
• announceToMain=false → suppress the current summary-to-main behavior for machine-callback use cases

This request is not asking to default-enable sessions_send over HTTP.

Alternatives considered

1. /hooks/agent + sessions_history

   • works, but awkward and polling-oriented

2. Re-enable sessions_send over HTTP

   • possible locally, but works against the current security posture
   • also exposes broader semantics than needed

3. Custom plugin / local fork

   • possible, but this seems generic enough to deserve a first-class API

Impact

Affected users:

• automation-heavy deployments
• external runner integrations
• orchestration / callback workflows

Severity:

• medium to high for these use cases

Consequence:

• extra glue code
• noisy main-session summaries for machine-only flows
• pressure to use stitched-together polling or local security exceptions

Evidence/examples

Relevant current behavior:

• /hooks/agent already provides authenticated isolated agent ingress
• /tools/invoke intentionally blocks sessions_send by default
• simple protocol-style responses can already be recovered via sessions_history
• what is missing is a first-class machine result path

Related, but not identical:

• #18237
• #43454

Additional information

A minimal solution would be to add this as an opt-in extension to /hooks/agent, while keeping the existing hook security model unchanged:

• hooks.token
• hooks.allowedAgentIds
• hooks.defaultSessionKey
• hooks.allowedSessionKeyPrefixes

I’d be happy to help test or refine the API shape if this direction makes sense.