Skip to content
Merged
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
17 changes: 16 additions & 1 deletion gateway/hooks.py
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,22 @@
message -- inbound message text (truncated to 500 chars)

``agent:end`` adds:
response -- agent response text (truncated to 500 chars)
response -- agent response text (truncated to 500 chars; kept for
backward compatibility)
response_full -- the entire agent response text, untruncated, so a decision
hook can inspect the whole reply (a violation buried past
char 500 is invisible in ``response``)

``agent:end`` is dispatched via :meth:`emit_collect`, so a handler MAY return a
decision dict to control delivery (mirroring the ``command:*`` protocol):
{"decision": "deny", "message": "..."} -- suppress the reply; the message
is surfaced back into the loop so
the agent must revise.
{"decision": "rewrite", "response": "..."} -- substitute the reply text.
None / anything else -- no-op (record-only handlers keep
working exactly as before).
A handler that raises, times out, or returns garbage falls through to sending
the reply unchanged β€” a broken predicate can never silence the agent.

Handlers posting a follow-up into the same Telegram forum-topic should
include ``message_thread_id=int(thread_id)`` when ``chat_type == "forum"``
Expand Down
108 changes: 103 additions & 5 deletions gateway/run.py
Original file line number Diff line number Diff line change
Expand Up @@ -560,6 +560,79 @@ def _sanitize_gateway_final_response(platform: Any, text: str) -> str:
return redacted


# Cap for the ``response`` field in the agent:end hook context. The truncated
# form is kept for backward compatibility (other consumers may rely on it);
# the untruncated reply is exposed separately as ``response_full`` so a
# decision hook can inspect the whole reply, not just the first 500 chars.
_AGENT_END_RESPONSE_CAP = 500


def _agent_end_hook_context(base_ctx: Dict[str, Any], response: Optional[str]) -> Dict[str, Any]:
"""Build the ``agent:end`` hook context.

``response`` stays capped at :data:`_AGENT_END_RESPONSE_CAP` chars (the
historical field other consumers may depend on). ``response_full`` carries
the entire reply so a decision hook can catch a violation anywhere in a long
reply β€” not only one that happens to fall in the last 500 chars.
"""
full = response or ""
return {
**base_ctx,
"response": full[:_AGENT_END_RESPONSE_CAP],
"response_full": full,
}


def _apply_agent_end_hook_decisions(
response_full: str,
hook_results: List[Any],
) -> "tuple[str, Optional[str]]":
"""Resolve ``agent:end`` handler return values into a delivery decision.

Mirrors the proven ``command:*`` decision protocol. Each element of
``hook_results`` is a handler return value; only ``dict``s with a
recognized ``decision`` act, and the FIRST actionable decision wins:

* ``deny`` -> the original reply is suppressed; the handler's
``message`` is surfaced back into the loop so the agent
must revise. A deny with no usable message falls back to
a generic block notice (never an empty reply).
* ``rewrite`` -> the handler's ``response`` is substituted. A rewrite with
no usable replacement text is a no-op (must never blank
the reply).
* anything else / ``allow`` / missing ``decision`` / non-dict -> no-op.

Returns ``(final_response, decision)`` where ``decision`` is ``"deny"``,
``"rewrite"``, or ``None`` (pass the original reply through unchanged).

Wedge-safety: this function never raises for a bad handler payload and never
returns an empty ``final_response`` for a no-op. A broken predicate must not
be able to silence the agent β€” the caller wraps the whole hook dispatch in
try/except as a second layer.
"""
for hook_result in hook_results or []:
if not isinstance(hook_result, dict):
continue
decision = str(hook_result.get("decision", "")).strip().lower()
if not decision or decision == "allow":
continue
if decision == "deny":
message = hook_result.get("message")
if isinstance(message, str) and message.strip():
return message, "deny"
return (
"That reply was blocked by a policy hook. Revise it and try again.",

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On deny with no handler message, this fallback string is delivered to the recipient as the reply (and stored as the assistant turn), since the call site substitutes it into response. That matches the command:* deny path this mirrors, so it is fine here β€” just flagging that when the live handler is armed, a real deny should carry a message written for a human, since the deny text is what gets shown, not a prompt fed back to the model.

"deny",
)
if decision == "rewrite":
new_response = hook_result.get("response")
if isinstance(new_response, str) and new_response.strip():
return new_response, "rewrite"
# No usable replacement β€” do not blank the reply; keep looking.
continue
return response_full, None


def _prepare_gateway_status_message(platform: Any, event_type: str, message: str) -> Optional[str]:
"""Filter/sanitize agent status callbacks before platform delivery.

Expand Down Expand Up @@ -14186,11 +14259,36 @@ async def _handle_message_with_agent(self, event, source, _quick_key: str, run_g
if _footer_line and response and not agent_result.get("already_sent") and not _intentional_silence:
response = f"{response}\n\n{_footer_line}"

# Emit agent:end hook
await self.hooks.emit("agent:end", {
**hook_ctx,
"response": (response or "")[:500],
})
# Emit agent:end hook. Unlike the fire-and-forget emit() this used
# to be, this uses emit_collect() so a handler can BLOCK or REWRITE
# the reply β€” mirroring the command:* decision protocol. The full
# (untruncated) reply is exposed as response_full so a violation
# anywhere in a long reply is visible, not only in the first 500
# chars. The entire dispatch is wrapped so a broken/raising handler
# can never wedge the turn: on any failure we fall through to
# sending the reply unchanged.
try:
_agent_end_ctx = _agent_end_hook_context(hook_ctx, response)
_agent_end_results = await self.hooks.emit_collect(
"agent:end", _agent_end_ctx
)
_final_resp, _agent_end_decision = _apply_agent_end_hook_decisions(
_agent_end_ctx["response_full"], _agent_end_results
)
if _agent_end_decision in ("deny", "rewrite"):
logger.info(
"agent:end hook %s the reply for session %s",
_agent_end_decision,
session_entry.session_id if session_entry else "?",
)
response = _final_resp
except Exception as _agent_end_err:
# A decision hook must never be able to silence the agent.
logger.debug(
"agent:end hook dispatch failed (non-fatal), sending reply "
"unchanged: %s",
_agent_end_err,
)

# Check for pending process watchers (check_interval on background processes)
try:
Expand Down
Loading
Loading