Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.
Python agentsai-hackingai-penetration-testingai-pentestingai-securityartificial-intelligencebug-bountycode-qualityctf-toolscybersecuritycybersecurity-toolsethical-hackinghackingllm-securityoffensive-securitypenetration-testingpentesting-toolsred-teamingsecuritysecurity-automation
feat(orchestration): full parity with legacy harness — 8 gaps closed via SDK natives
0xallamf4834cd6f7a4
diff --git a/strix/agents/factory.py b/strix/agents/factory.pyindex 3f374833..12139fac 100644--- a/strix/agents/factory.py+++ b/strix/agents/factory.py@@ -32,6 +32,7 @@ from strix.tools.agents_graph.tools import (agent_status,create_agent,send_message_to_agent,+ stop_agent,view_agent_graph,wait_for_message,)@@ -104,6 +105,7 @@ _BASE_TOOLS: tuple[Tool, ...] = (send_message_to_agent,wait_for_message,create_agent,+ stop_agent,)diff --git a/strix/entry.py b/strix/entry.pyindex 1bfe8c85..4f336ade 100644--- a/strix/entry.py+++ b/strix/entry.py@@ -36,7 +36,7 @@ from strix.runtime import session_managerif TYPE_CHECKING:- from agents.result import RunResult+ from agents.result import RunResultBaselogger = logging.getLogger(__name__)@@ -163,7 +163,7 @@ async def run_strix_scan(max_turns: int = STRIX_DEFAULT_MAX_TURNS,model: str | None = None,cleanup_on_exit: bool = True,-) -> RunResult:+) -> RunResultBase:"""Run one Strix scan end-to-end against a freshly-prepared sandbox.Args:diff --git a/strix/interface/tui.py b/strix/interface/tui.pyindex d0d22e55..8c5882bf 100644--- a/strix/interface/tui.py+++ b/strix/interface/tui.py@@ -1727,15 +1727,24 @@ class StrixTUIApp(App): # type: ignore[misc]# Route to the agent's bus inbox. The scan loop runs on a# worker thread; ``run_coroutine_threadsafe`` submits the# coroutine onto that loop and returns immediately so the TUI- # stays responsive.+ # stays responsive. After enqueuing the message, request a+ # graceful interrupt of the agent's current turn so the user+ # input is processed without waiting for the active LLM/tool+ # call to finish — the SDK saves the in-flight turn cleanly+ # before honoring ``cancel(mode="after_turn")``.if self._scan_loop is not None and not self._scan_loop.is_closed():+ target_agent_id = self.selected_agent_idasyncio.run_coroutine_threadsafe(self.bus.send(- self.selected_agent_id,+ target_agent_id,{"from": "user", "content": message, "type": "instruction"},),self._scan_loop,)+ asyncio.run_coroutine_threadsafe(+ self.bus.request_interrupt(target_agent_id, mode="after_turn"),+ self._scan_loop,+ )self._displayed_events.clear()self._update_chat_view()diff --git a/strix/orchestration/bus.py b/strix/orchestration/bus.pyindex 135fc554..6a27dfb7 100644--- a/strix/orchestration/bus.py+++ b/strix/orchestration/bus.py@@ -8,8 +8,15 @@ Strix scan.from __future__ import annotationsimport asyncio+import contextlibfrom dataclasses import dataclass, field-from typing import Any+from typing import TYPE_CHECKING, Any+++if TYPE_CHECKING:+ from collections.abc import AsyncIterator++ from agents.result import RunResultStreaming@dataclass@@ -23,21 +30,30 @@ class AgentMessageBus:``inject_messages_filter`` at the top of each LLM turn).- ``tasks``: per-agent ``asyncio.Task`` handle so the parent (or signalhandler) can cancel descendants.+ - ``streams``: per-agent ``RunResultStreaming`` handle so callers can+ request graceful ``cancel(mode="after_turn")`` mid-stream — the SDK+ saves the current turn to session before honoring the cancel.- ``statuses``: per-agent lifecycle state — ``running | waiting |- completed | crashed | stopped``.+ completed | crashed | stopped | llm_failed``.- ``parent_of``: tree edges; root agents have ``None``.- ``names``: human-readable per-agent names.- ``stats_live`` / ``stats_completed``: token + call counters that hooks- keep up to date for live and finalized agents respectively.+ keep up to date for live and finalized agents respectively. Also+ carries per-agent-lifetime warning flags (``warned_85``,+ ``warned_final``).+ - ``stopping``: agent ids whose interactive outer-loop should exit on+ next iteration instead of waiting for more messages."""inboxes: dict[str, list[dict[str, Any]]] = field(default_factory=dict)tasks: dict[str, asyncio.Task[Any]] = field(default_factory=dict)+ streams: dict[str, RunResultStreaming] = field(default_factory=dict)statuses: dict[str, str] = field(default_factory=dict)parent_of: dict[str, str | None] = field(default_factory=dict)names: dict[str, str] = field(default_factory=dict)stats_live: dict[str, dict[str, Any]] = field(default_factory=dict)stats_completed: dict[str, dict[str, Any]] = field(default_factory=dict)+ stopping: set[str] = field(default_factory=set)_events: dict[str, asyncio.Event] = field(default_factory=dict)_lock: asyncio.Lock = field(default_factory=asyncio.Lock)@@ -59,6 +75,8 @@ class AgentMessageBus:"cached": 0,"cost": 0.0,"calls": 0,+ "warned_85": False,+ "warned_final": False,}async def send(self, target: str, msg: dict[str, Any]) -> None:@@ -91,6 +109,23 @@ class AgentMessageBus:event.clear()await event.wait()+ async def wait_for_user_message(self, agent_id: str) -> None:+ """Block until ``agent_id``'s inbox has a message with ``from='user'``.++ Used by the ``llm_failed`` recovery path: after a hard model failure,+ only direct user input should resume the agent — peer messages can't+ unstick a stuck model. Re-checks the inbox after each event in case+ only peer messages arrived.+ """+ while True:+ async with self._lock:+ for msg in self.inboxes.get(agent_id, []):+ if msg.get("from") == "user":+ return+ event = self._events.setdefault(agent_id, asyncio.Event())+ event.clear()+ await event.wait()+async def drain(self, agent_id: str) -> list[dict[str, Any]]:"""Atomically read and clear ``agent_id``'s pending messages.@@ -108,20 +143,30 @@ class AgentMessageBus:"""Accumulate per-call usage from RunHooks.on_llm_end.Tolerates ``usage=None`` (some providers omit usage on streaming).+ Increments ``calls`` unconditionally so it doubles as a per-agent+ lifetime turn counter (legacy ``state.iteration`` parity)."""- if usage is None:- returnasync with self._lock:stats = self.stats_live.setdefault(agent_id,- {"in": 0, "out": 0, "cached": 0, "cost": 0.0, "calls": 0},+ {+ "in": 0,+ "out": 0,+ "cached": 0,+ "cost": 0.0,+ "calls": 0,+ "warned_85": False,+ "warned_final": False,+ },)+ stats["calls"] += 1+ if usage is None:+ returnstats["in"] += getattr(usage, "input_tokens", 0) or 0stats["out"] += getattr(usage, "output_tokens", 0) or 0details = getattr(usage, "input_tokens_details", None)if details is not None:stats["cached"] += getattr(details, "cached_tokens", 0) or 0- stats["calls"] += 1async def finalize(self, agent_id: str, status: str) -> None:"""Move an agent from live to completed; clean up routing state.@@ -135,6 +180,8 @@ class AgentMessageBus:self.inboxes.pop(agent_id, None)self.parent_of.pop(agent_id, None)self.names.pop(agent_id, None)+ self.streams.pop(agent_id, None)+ self.stopping.discard(agent_id)self._events.pop(agent_id, None)async def park(self, agent_id: str) -> None:@@ -150,13 +197,62 @@ class AgentMessageBus:if agent_id in self.statuses:self.statuses[agent_id] = "waiting"+ async def mark_llm_failed(self, agent_id: str) -> None:+ """Mark an agent as ``llm_failed`` after retries exhausted.++ Mirrors legacy ``state.llm_failed`` semantics: only direct user+ input can resume the agent (see :meth:`wait_for_user_message`).+ Status survives until the next ``Runner.run`` cycle starts and+ ``on_agent_start`` mirrors it back to ``running``, or finalize+ clears it.+ """+ async with self._lock:+ if agent_id in self.statuses:+ self.statuses[agent_id] = "llm_failed"++ @contextlib.asynccontextmanager+ async def attach_stream(+ self,+ agent_id: str,+ streamed: RunResultStreaming,+ ) -> AsyncIterator[None]:+ """Register ``streamed`` so ``request_interrupt`` can find it; clean up after."""+ async with self._lock:+ self.streams[agent_id] = streamed+ try:+ yield+ finally:+ async with self._lock:+ if self.streams.get(agent_id) is streamed:+ self.streams.pop(agent_id, None)++ async def request_interrupt(+ self,+ agent_id: str,+ mode: str = "after_turn",+ ) -> bool:+ """Ask the agent's active streaming run to cancel gracefully.++ Returns True if a streaming run was attached (so a cancel request+ was issued), False otherwise. ``mode='after_turn'`` lets the SDK+ finish the current turn — including saving items to session — so+ cancellation never leaves orphan tool outputs or truncated+ assistant messages. ``mode='immediate'`` is the hard variant.+ """+ async with self._lock:+ streamed = self.streams.get(agent_id)+ if streamed is None:+ return False+ streamed.cancel(mode=mode) # type: ignore[arg-type] # mode is a Literal+ return True+async def total_stats(self) -> dict[str, Any]:- """Snapshot of live + completed stats."""+ """Snapshot of live + completed stats. Excludes warning flags."""async with self._lock:agg = {"in": 0, "out": 0, "cached": 0, "cost": 0.0, "calls": 0}for stats in (*self.stats_live.values(), *self.stats_completed.values()):- for key, value in stats.items():- agg[key] = agg.get(key, 0) + value+ for key in agg:+ agg[key] += stats.get(key, 0)return aggasync def cancel_descendants(self, root_agent_id: str) -> None:@@ -165,6 +261,10 @@ class AgentMessageBus:Wired into the CLI Ctrl+C handler and TUI stop button —the SDK's ``result.cancel`` doesn't cascade to children spawnedvia ``asyncio.create_task``, so we walk the tree ourselves.++ This is the **hard** path: ``task.cancel()`` raises ``CancelledError``+ immediately, which may truncate a turn mid-stream. For graceful+ cascading stops use :meth:`cancel_descendants_graceful`."""async with self._lock:queue = [root_agent_id]@@ -182,3 +282,26 @@ class AgentMessageBus:*(t for t in tasks_to_cancel if not t.done()),return_exceptions=True,)++ async def cancel_descendants_graceful(self, root_agent_id: str) -> None:+ """Graceful cascade: ``request_interrupt`` per node, leaves-first.++ Each node's current turn finishes (and is saved to session) before+ the run loop honors the cancel. The interactive outer loop sees+ the agent in ``stopping`` and returns instead of awaiting more+ messages, so finalize fires with status="stopped".+ """+ async with self._lock:+ queue = [root_agent_id]+ order: list[str] = []+ while queue:+ aid = queue.pop()+ order.append(aid)+ queue.extend(child for child, parent in self.parent_of.items() if parent == aid)+ for aid in order:+ self.stopping.add(aid)+ streams_to_cancel = [+ (aid, self.streams[aid]) for aid in reversed(order) if aid in self.streams+ ]+ for _aid, streamed in streams_to_cancel:+ streamed.cancel(mode="after_turn")diff --git a/strix/orchestration/filter.py b/strix/orchestration/filter.pyindex c7ddde4a..09ee8a0e 100644--- a/strix/orchestration/filter.py+++ b/strix/orchestration/filter.py@@ -8,12 +8,15 @@ retries — so a single drain per turn doesn't lose messages on retry.from __future__ import annotationsimport logging+from datetime import UTC, datetimefrom typing import TYPE_CHECKINGfrom agents.run_config import CallModelData, ModelInputDataif TYPE_CHECKING:+ from typing import Any+from strix.orchestration.bus import AgentMessageBus@@ -23,9 +26,11 @@ logger = logging.getLogger(__name__)async def inject_messages_filter(data: CallModelData) -> ModelInputData:"""Drain bus inbox and append messages as user-role items before the LLM call.- Messages from peer agents are formatted with a labeled header so the- receiving model can attribute them. Messages from the literal sender- ``"user"`` (a real human via TUI) are added as plain user messages.+ Peer-agent messages are wrapped in the legacy ``<inter_agent_message>``+ XML envelope (sender / metadata / content / delivery_info) so the+ receiving model gets the same prompt-shape as pre-migration — including+ the explicit "DO NOT echo back" instruction. Direct user messages+ (``from="user"``) are passed plain.Any exception inside the filter — malformed message dict, bug in``bus.drain``, etc. — is caught and the original ``data.model_data``@@ -49,14 +54,11 @@ async def inject_messages_filter(data: CallModelData) -> ModelInputData:if sender == "user":new_input.append({"role": "user", "content": content})else:- msg_type = msg.get("type", "info")- priority = msg.get("priority", "normal")- header = f"[Message from agent {sender} | type={msg_type} | priority={priority}]"new_input.append({"role": "user",- "content": f"{header}\n{content}",- }+ "content": _format_inter_agent_message(bus, msg),+ },)return ModelInputData(input=new_input,@@ -67,3 +69,34 @@ async def inject_messages_filter(data: CallModelData) -> ModelInputData:"inject_messages_filter failed; proceeding with unmodified input",)return data.model_data+++def _format_inter_agent_message(bus: AgentMessageBus, msg: dict[str, Any]) -> str:+ """Render a peer-agent message in the legacy XML envelope.++ The wrapper carries an explicit "do not echo back" instruction that+ the legacy harness used to keep models from quoting the entire+ received message dict in their own next turn.+ """+ sender_id = str(msg.get("from", "unknown"))+ sender_name = bus.names.get(sender_id, sender_id)+ msg_type = msg.get("type", "information")+ priority = msg.get("priority", "normal")+ timestamp = msg.get("timestamp") or datetime.now(UTC).isoformat()+ content = str(msg.get("content", ""))+ return (+ "<inter_agent_message>\n"+ " <delivery_notice><important>You have received a message from another "+ "agent. Acknowledge and respond to the sender if needed; DO NOT echo "+ "back this entire message block.</important></delivery_notice>\n"+ f" <sender><agent_name>{sender_name}</agent_name>"+ f"<agent_id>{sender_id}</agent_id></sender>\n"+ f" <message_metadata><type>{msg_type}</type>"+ f"<priority>{priority}</priority>"+ f"<timestamp>{timestamp}</timestamp></message_metadata>\n"+ f" <content>{content}</content>\n"+ " <delivery_info><note>This message was delivered during your task "+ "execution. Please acknowledge and respond if needed.</note>"+ "</delivery_info>\n"+ "</inter_agent_message>"+ )diff --git a/strix/orchestration/hooks.py b/strix/orchestration/hooks.pyindex fb08f819..c785a6cb 100644--- a/strix/orchestration/hooks.py+++ b/strix/orchestration/hooks.py@@ -36,15 +36,28 @@ class StrixOrchestrationHooks(RunHooks[Any]):system_prompt: str | None,input_items: list[Any],) -> None:+ del agent, system_prompttry:- # Type contract guarantees ``input_items`` is list[TResponseInputItem];- # we trust SDK here. The try/except below catches any surprise.ctx = context.contextif not isinstance(ctx, dict):return+ bus = ctx.get("bus")+ agent_id = ctx.get("agent_id")+ if bus is None or agent_id is None:+ return+ stats = bus.stats_live.get(agent_id)+ if stats is None:+ returnmax_turns = int(ctx.get("max_turns", 300))- cur = int(ctx.get("turn_count", 0))- if max_turns >= 4 and cur == int(max_turns * 0.85):+ cur = int(stats.get("calls", 0))+ if max_turns < 4:+ return+ # Once-flags live alongside ``calls`` on ``bus.stats_live`` so the+ # warnings fire exactly once per agent lifetime — surviving+ # ``run_with_continuation`` cycles, mirroring legacy+ # ``state.max_iterations_warning_sent``.+ if cur >= int(max_turns * 0.85) and not stats.get("warned_85"):+ stats["warned_85"] = Trueinput_items.append({"role": "user",@@ -52,9 +65,10 @@ class StrixOrchestrationHooks(RunHooks[Any]):"[System warning] You are at 85% of your iteration ""budget. Begin consolidating findings."),- }+ },)- elif max_turns >= 4 and cur == max_turns - 3:+ if cur >= max_turns - 3 and not stats.get("warned_final"):+ stats["warned_final"] = Trueinput_items.append({"role": "user",@@ -62,7 +76,7 @@ class StrixOrchestrationHooks(RunHooks[Any]):"[System warning] You have 3 iterations left. Your ""next tool call MUST be the finish tool."),- }+ },)except Exception:logger.exception("on_llm_start failed")@@ -94,7 +108,6 @@ class StrixOrchestrationHooks(RunHooks[Any]):output_tokens=int(getattr(usage, "output_tokens", 0) or 0),cached_tokens=cached,)- ctx["turn_count"] = int(ctx.get("turn_count", 0)) + 1except Exception:logger.exception("on_llm_end failed")@@ -178,11 +191,10 @@ class StrixOrchestrationHooks(RunHooks[Any]):if stays_alive:await bus.park(me)- # Reset per-cycle flags so the next ``Runner.run`` invocation- # can detect a fresh finish-tool call and re-trigger budget- # warnings against its own iteration count.+ # Reset the finish flag so the next cycle can detect its own+ # finish-tool call. The lifetime turn counter and warning+ # flags live on ``bus.stats_live`` and persist across cycles.ctx["agent_finish_called"] = False- ctx["turn_count"] = 0else:await bus.finalize(me, final_status)except Exception:diff --git a/strix/orchestration/run_loop.py b/strix/orchestration/run_loop.pyindex 811a7bd8..7c062629 100644--- a/strix/orchestration/run_loop.py+++ b/strix/orchestration/run_loop.py@@ -1,21 +1,25 @@-"""``run_with_continuation`` — interactive-mode demo-loop wrapper around ``Runner.run``.+"""``run_with_continuation`` — interactive-mode demo-loop wrapper around ``Runner.run_streamed``.Pre-migration ``BaseAgent.agent_loop`` ran forever in interactive mode,re-entering a "waiting state" after each finish-tool call so the agentcould pick up follow-up messages from its parent (or from the user, in-the root's case). Post-migration ``Runner.run`` returns on-``StopAtTools(...)`` and the agent is gone.--This helper restores the legacy semantics using the SDK's canonical-demo-loop pattern (``agents/repl.py:run_demo_loop``): after each-``Runner.run`` cycle, ``await bus.wait_for_message(agent_id)``, drain-new messages, and re-invoke ``Runner.run`` with them as the next turn's-input. The session (if provided) preserves prior conversation across-cycles.--Used by both the root scan loop in ``entry.run_strix_scan`` and the-child-agent loop in ``tools.agents_graph.tools.create_agent`` so every-interactive agent on the bus stays alive.+the root's case). Post-migration this helper restores the legacy+semantics using the SDK's streaming Runner + ``RunResultStreaming.cancel``+so the user can interrupt mid-turn without truncating session state.++Behaviors restored from legacy:++- **Mid-stream interrupt** via ``streamed.cancel(mode="after_turn")``:+ TUI signals through ``bus.request_interrupt``; the SDK saves the+ current turn cleanly before honoring the cancel.+- **LLM failure resume** (legacy ``state.llm_failed``): hard model+ failures after retries exhausted park the agent in ``llm_failed``+ status; only direct user input can resume.+- **Waiting timeout** auto-resume (legacy ``waiting_timeout``):+ interactive subagents auto-resume after 300s with a "Waiting timeout+ reached" message. Interactive root waits forever.+- **Graceful stop** (legacy ``stop_agent``): ``bus.stopping`` set+ causes the outer loop to return instead of awaiting more messages."""from __future__ import annotations@@ -25,12 +29,14 @@ import loggingfrom typing import TYPE_CHECKING, Anyfrom agents import Runner+from agents.exceptions import AgentsException, MaxTurnsExceeded, UserError+from openai import APIErrorif TYPE_CHECKING:from agents.lifecycle import RunHooksfrom agents.memory import Session- from agents.result import RunResult+ from agents.result import RunResultBasefrom agents.run_config import RunConfigfrom strix.orchestration.bus import AgentMessageBus@@ -39,6 +45,13 @@ if TYPE_CHECKING:logger = logging.getLogger(__name__)+#: Auto-resume timeout for interactive *subagents* (legacy parity).+#: Interactive root agents wait forever; non-interactive runs don't loop.+_WAITING_TIMEOUT_SUBAGENT = 300.0++_TIMEOUT_RESUME_MESSAGE = "Waiting timeout reached. Resuming execution."++async def run_with_continuation(*,agent: Any,@@ -51,19 +64,8 @@ async def run_with_continuation(agent_id: str,interactive: bool,session: Session | None = None,-) -> RunResult:- """Run an agent once (non-interactive) or in a continuation loop (interactive).-- For non-interactive runs this is a thin wrapper around- ``Runner.run`` and returns its result.-- For interactive runs the function loops: after each ``Runner.run``- returns, it awaits ``bus.wait_for_message(agent_id)``, drains any- accumulated messages from the inbox, formats them as the next- turn's user input, and invokes ``Runner.run`` again. The loop ends- when the wait gets cancelled (e.g. parent ``cancel_descendants`` or- user-issued KeyboardInterrupt).- """+) -> RunResultBase:+ """Run an agent once (non-interactive) or in a continuation loop (interactive)."""kwargs: dict[str, Any] = {"input": initial_input,"run_config": run_config,@@ -74,16 +76,38 @@ async def run_with_continuation(if session is not None:kwargs["session"] = session- result: RunResult = await Runner.run(agent, **kwargs)+ # Interactive subagents auto-resume after a timeout to mirror legacy+ # ``waiting_timeout``. Roots wait forever (legacy ``waiting_timeout=0``).+ waiting_timeout: float | None = None+ if interactive:+ async with bus._lock:+ parent_id = bus.parent_of.get(agent_id)+ if parent_id is not None:+ waiting_timeout = _WAITING_TIMEOUT_SUBAGENT++ result = await _run_streamed(agent, bus, agent_id, **kwargs)if not interactive:return resultwhile True:+ if agent_id in bus.stopping:+ return result+try:- await bus.wait_for_message(agent_id)+ if waiting_timeout is None:+ await bus.wait_for_message(agent_id)+ else:+ await asyncio.wait_for(+ bus.wait_for_message(agent_id),+ timeout=waiting_timeout,+ )except asyncio.CancelledError:return result+ except TimeoutError:+ kwargs["input"] = _TIMEOUT_RESUME_MESSAGE+ result = await _run_streamed(agent, bus, agent_id, **kwargs)+ continuepending = await bus.drain(agent_id)if not pending:@@ -95,4 +119,48 @@ async def run_with_continuation(continuekwargs["input"] = next_input- result = await Runner.run(agent, **kwargs)+ result = await _run_streamed(agent, bus, agent_id, **kwargs)+++async def _run_streamed(+ agent: Any,+ bus: AgentMessageBus,+ agent_id: str,+ **kwargs: Any,+) -> RunResultBase:+ """Drive one ``Runner.run_streamed`` cycle to completion.++ Catches hard model failures (after SDK retries are exhausted) and+ parks the agent in ``llm_failed`` until a user message arrives,+ matching legacy ``state.llm_failed`` semantics. Programmer errors+ (``UserError``), max-turn breaches, and explicit cancellation+ propagate to the caller.+ """+ interactive = bool(kwargs.get("context", {}).get("interactive", False))+ while True:+ streamed = Runner.run_streamed(agent, **kwargs)+ try:+ async with bus.attach_stream(agent_id, streamed):+ async for _event in streamed.stream_events():+ pass+ except (UserError, MaxTurnsExceeded, asyncio.CancelledError):+ raise+ except (AgentsException, APIError):+ if not interactive:+ raise+ logger.exception(+ "LLM hard failure for agent %s; awaiting user resume",+ agent_id,+ )+ await bus.mark_llm_failed(agent_id)+ await bus.wait_for_user_message(agent_id)+ pending = await bus.drain(agent_id)+ next_input = "\n\n".join(+ str(msg.get("content", "")).strip() for msg in pending if msg.get("content")+ )+ if not next_input:+ continue+ kwargs["input"] = next_input+ continue+ else:+ return streameddiff --git a/strix/run_config_factory.py b/strix/run_config_factory.pyindex 11463302..88af371a 100644--- a/strix/run_config_factory.py+++ b/strix/run_config_factory.py@@ -150,7 +150,6 @@ def make_agent_context("model": model,"model_settings": model_settings,"max_turns": max_turns,- "turn_count": 0,"agent_finish_called": False,"is_whitebox": is_whitebox,"interactive": interactive,diff --git a/strix/tools/agents_graph/tools.py b/strix/tools/agents_graph/tools.pyindex 8b6ee426..9642dd29 100644--- a/strix/tools/agents_graph/tools.py+++ b/strix/tools/agents_graph/tools.py@@ -42,6 +42,38 @@ def _ctx(ctx: RunContextWrapper) -> dict[str, Any]:return ctx.context if isinstance(ctx.context, dict) else {}+def _render_completion_report(+ *,+ agent_name: str,+ agent_id: str,+ task: str,+ success: bool,+ result_summary: str,+ findings: list[str],+ recommendations: list[str],+) -> str:+ """Render an ``<agent_completion_report>`` XML payload (legacy parity)."""+ from datetime import UTC, datetime+ from html import escape++ status = "SUCCESS" if success else "FAILED"+ completion_time = datetime.now(UTC).isoformat()+ findings_xml = "".join(f"<finding>{escape(f)}</finding>" for f in findings)+ recs_xml = "".join(f"<recommendation>{escape(r)}</recommendation>" for r in recommendations)+ return (+ "<agent_completion_report>\n"+ f" <agent_info><agent_name>{escape(agent_name)}</agent_name>"+ f"<agent_id>{escape(agent_id)}</agent_id>"+ f"<task>{escape(task)}</task>"+ f"<status>{status}</status>"+ f"<completion_time>{completion_time}</completion_time></agent_info>\n"+ f" <results><summary>{escape(result_summary)}</summary>"+ f"<findings>{findings_xml}</findings>"+ f"<recommendations>{recs_xml}</recommendations></results>\n"+ "</agent_completion_report>"+ )++@function_tool(timeout=30)async def view_agent_graph(ctx: RunContextWrapper) -> str:"""Print the multi-agent tree — every agent, its parent, its status.@@ -411,21 +443,26 @@ async def create_agent(await bus.register(child_id, name, parent_id)- parent_history = inner.get("parent_input_items") if inherit_context else None+ # ``ctx.turn_input`` carries the parent's full conversation up to and+ # including the call that's currently invoking ``create_agent``+ # (populated by SDK at ``run_internal/turn_resolution.py:806``).+ # Wrap as a single read-only block so the child sees the parent's+ # reasoning as background but doesn't try to continue parent's turns.+ parent_history = list(ctx.turn_input) if inherit_context and ctx.turn_input else []initial_input: list[TResponseInputItem] = []if parent_history:+ rendered = json.dumps(parent_history, ensure_ascii=False, default=str)initial_input.append({"role": "user",- "content": "[Inherited context from parent — read-only history]",- }- )- initial_input.extend(parent_history)- initial_input.append(- {- "role": "user",- "content": "[End of inherited context]",- }+ "content": (+ "<inherited_context_from_parent>\n"+ f"{rendered}\n"+ "</inherited_context_from_parent>\n"+ "Use the above as background only; do not continue the "+ "parent's work. Your task follows."+ ),+ },)initial_input.append({@@ -456,6 +493,9 @@ async def create_agent(run_id=inner.get("run_id"),agent_factory=factory,)+ # Stash the task string for ``agent_finish`` to echo back in its+ # XML completion report.+ child_ctx["task"] = taskchild_run_config = make_run_config(sandbox_session=inner.get("sandbox_session"),@@ -569,17 +609,14 @@ async def agent_finish(if report_to_parent:async with bus._lock:agent_name = bus.names.get(me, me)- report = json.dumps(- {- "kind": "agent_completion_report",- "from": agent_name,- "agent_id": me,- "success": success,- "summary": result_summary,- "findings": list(findings or []),- "recommendations": list(final_recommendations or []),- },- ensure_ascii=False,+ report = _render_completion_report(+ agent_name=agent_name,+ agent_id=me,+ task=str(inner.get("task", "")),+ success=success,+ result_summary=result_summary,+ findings=list(findings or []),+ recommendations=list(final_recommendations or []),)await bus.send(parent_id,@@ -606,3 +643,94 @@ async def agent_finish(ensure_ascii=False,default=str,)+++@function_tool(timeout=30)+async def stop_agent(+ ctx: RunContextWrapper,+ target_agent_id: str,+ cascade: bool = True,+ reason: str = "",+) -> str:+ """Gracefully stop a running agent (and optionally its descendants).++ Uses the SDK's ``RunResultStreaming.cancel(mode="after_turn")`` so the+ target's current turn finishes — including saving items to its+ session — before the run loop honors the cancel. The agent's+ interactive outer loop sees ``stopping`` and exits without awaiting+ more messages, so ``on_agent_end`` finalizes with status="stopped".++ Use sparingly. Prefer ``send_message_to_agent`` (asking the agent+ to wrap up) for soft-stop scenarios. Reach for ``stop_agent`` when+ a child has gone off-track and won't self-correct.++ Args:+ target_agent_id: The 8-char id from ``view_agent_graph`` /+ ``create_agent``. Cannot stop yourself.+ cascade: If ``True`` (default), also stop every descendant of+ ``target_agent_id`` leaves-first. ``False`` stops only the+ target.+ reason: Optional human-readable reason for the stop, surfaced+ in logs and telemetry.+ """+ inner = _ctx(ctx)+ bus = inner.get("bus")+ me = inner.get("agent_id")+ if bus is None or me is None:+ return json.dumps(+ {"success": False, "error": "Bus or agent_id missing in context."},+ ensure_ascii=False,+ default=str,+ )+ if target_agent_id == me:+ return json.dumps(+ {+ "success": False,+ "error": "Cannot stop yourself; call agent_finish or finish_scan instead.",+ },+ ensure_ascii=False,+ default=str,+ )+ async with bus._lock:+ if target_agent_id not in bus.statuses:+ return json.dumps(+ {"success": False, "error": f"Unknown agent_id: {target_agent_id}"},+ ensure_ascii=False,+ default=str,+ )+ target_status = bus.statuses.get(target_agent_id)++ if target_status in ("completed", "crashed", "stopped"):+ return json.dumps(+ {+ "success": False,+ "error": f"Target agent '{target_agent_id}' is already {target_status}.",+ },+ ensure_ascii=False,+ default=str,+ )++ if cascade:+ await bus.cancel_descendants_graceful(target_agent_id)+ else:+ async with bus._lock:+ bus.stopping.add(target_agent_id)+ await bus.request_interrupt(target_agent_id, mode="after_turn")++ logger.info(+ "stop_agent: target=%s cascade=%s reason=%r",+ target_agent_id,+ cascade,+ reason,+ )+ return json.dumps(+ {+ "success": True,+ "target_agent_id": target_agent_id,+ "cascade": cascade,+ "reason": reason,+ "note": "Cancellation is graceful — current turn completes first.",+ },+ ensure_ascii=False,+ default=str,+ )