codex-agent-framework 0.1.20__tar.gz → 0.1.21__tar.gz

{codex_agent_framework-0.1.20 → codex_agent_framework-0.1.21}/CHANGELOG.md

@@ -4,6 +4,29 @@ All notable changes to this project will be documented in this file.
 
 This project loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and uses semantic versioning where practical.
 
+## [0.1.21] - 2026-05-10
+### Added
+- Add the structured `AgentTurn` API: `agent(...)` and `AgentFuture.wait()` now return a turn object with `result`, `completed`, `reason`, `messages`, and `events`.
+- Add resumable non-terminal turns for `auto_proceed=False`; turns that need another model step pause with `reason="requires_next_step"` and continue through `agent.resume_turn(turn)`.
+- Add `agent.set_turn_result(data)` for tools/plugins that need to explicitly finish the current turn with a structured result.
+- Add the built-in `subagents` plugin with profile-based child agents, compact parent results, child-local `set_result`, `SubagentEvent` relay, and a packaged read-only `explorer` profile.
+- Add hierarchical `types` to messages and events while keeping `type` as the concrete computed type.
+- Add configurable `exclude_tools` matching by public or canonical plugin tool names.
+
+### Changed
+- Treat scheduled and post-restart wakeups as internal `DeveloperMessage` entries instead of user-authored messages.
+- Make `AssistantTurnEndEvent` expose a terminal `reason` rather than carrying a raw result payload.
+- Capture turn-local events and messages on `AgentTurn` so embedded callers can inspect what happened without replaying the whole session.
+- Include packaged subagent profile JSON files in distributions.
+- Refresh the packaged default system prompt around agent identity, clarification, durable fixes, and concise final reporting.
+
+### Fixed
+- Preserve coherent turn state across suspended/resumed turns, including stable turn IDs, non-terminal suspension without a turn-end event, and terminal completion on resume.
+
+### Tests
+- Validate the full suite at 483 passing tests.
+- Validate post-restart wakeups after a real server restart and smoke-test `auto_proceed=False` `AgentTurn` suspension/resume behavior.
+
 ## [0.1.20] - 2026-05-09
 ### Added
 - Make runtime plugins the single user-facing extension unit for tools, providers, commands, prompt sections, hooks, and events.

{codex_agent_framework-0.1.20/codex_agent_framework.egg-info → codex_agent_framework-0.1.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-agent-framework
-Version: 0.1.20
+Version: 0.1.21
 Summary: A lightweight event-driven Codex agent runtime.
 Author: Baptiste
 License-Expression: MIT
@@ -286,10 +286,17 @@ agent = Agent(
     voice_enabled=False,
 )
 
-answer = agent("Summarize this repository in three practical bullet points.")
-print(answer)
+turn = agent("Summarize this repository in three practical bullet points.")
+
+print("Completed:", turn.completed)
+print("Reason:", turn.reason)
+print("Result:", turn.result)
+for message in turn.messages:
+    print(message.as_string())
 ```
 
+`agent(...)` returns an `AgentTurn`, not a raw string. `turn.result` is the useful final result, while `turn.messages` and `turn.events` contain the messages and events produced by that command. If `auto_proceed=False`, a tool-using turn can pause with `completed=False` and `reason="requires_next_step"`; call `agent.resume_turn(turn)` to continue the same turn object until it reaches a terminal reason such as `completed`, `result_set`, `interrupted`, or `error`.
+
 Resume the latest session interactively:
 
 ```python
@@ -398,7 +405,7 @@ def repo():
 
 agent = Agent(session="latest", voice_enabled=False)
 agent.add_command(repo)
-print(agent("/repo"))
+print(agent("/repo").result)
 ```
 
 ### Add stateful plugins
@@ -593,8 +600,11 @@ The default agent exposes local tools and plugin tools to the model. Plugin tool
 | Scheduler plugin | `scheduler_schedule`, `scheduler_cancel`, `scheduler_list`, `scheduler_restart_and_wakeup` | Future turns, periodic wakeups, post-restart continuation. |
 | Browser plugin | `browser_open`, `browser_goto`, `browser_click`, `browser_fill`, `browser_press`, ... | Persistent Playwright/Chromium automation with active-tab context. |
 | Desktop plugin | `desktop_start_session`, `desktop_run_commands`, `desktop_stop_session` | Screenshot-backed Linux desktop automation. |
+| Subagents plugin | `subagents_run` | Run an ephemeral child agent from a predefined profile and return a compact structured result. |
 
-Built-ins are intentionally packaged as plugins. Current built-in plugin modules include `files`, `content`, `bash`, `python`, `interface`, `environment`, `memory`, `planner`, `scheduler`, `browser`, and `desktop`.
+Built-ins are intentionally packaged as plugins. Current built-in plugin modules include `files`, `content`, `bash`, `python`, `interface`, `environment`, `memory`, `planner`, `scheduler`, `browser`, `desktop`, and `subagents`.
+
+The `subagents` plugin ships profile JSON files inside the package, starting with `explorer`, a read-only codebase inspection agent. Parent agents choose an existing profile and task; child agents receive their own config, tools, prompt, and temporary session instead of inheriting the parent's runtime implicitly.
 
 Built-in plugins are configurable. `None` means load all plugins, an empty list means load none, and an explicit list selects specific plugin module names:
 
@@ -703,8 +713,11 @@ Useful exported events include:
 - `ToolCallStartEvent` / `ToolCallDoneEvent`
 - `SessionLoadedEvent` / `SessionDeletedEvent`
 - `AssistantInterruptedEvent`
+- `SubagentEvent`
 - `AudioPlaybackEvent`
 
+Messages and events expose hierarchical `types` as well as the final computed `type`, so listeners can subscribe to broad classes such as all events or to precise concrete event types.
+
 Plugins can also register event and hook handlers with decorators:
 
 ```python
@@ -833,13 +846,13 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 The current tree validates at:
 
 ```text
-456 passed
+483 passed
 ```
 
-The published `0.1.20` release was validated at:
+The published `0.1.21` release was validated at:
 
 ```text
-456 passed
+483 passed
 ```
 
 ## Packaging
@@ -857,6 +870,7 @@ The distribution includes prompt text files, `codex_agent/get_text/default_gitig
 
 ## Recent changes
 
+- `0.1.21`: add structured `AgentTurn` returns with messages/events, resumable non-terminal turns for `auto_proceed=False`, profile-based subagents, hierarchical message/event types, and internal wakeups as developer messages.
 - `0.1.20`: make runtime plugins the single user-facing extension unit for tools/providers/commands, remove legacy direct runtime tool/provider loading, split tool/provider managers, and keep system-prompt templating on an explicit minimal namespace.
 - `0.1.19`: prune compacted raw session history after compaction, keep only the latest compaction anchor plus the new compaction and any unfinished remainder, and drop older redundant compaction summaries from active session files.
 - `0.1.18`: make `start server/tray` detach by default, move durable memory fully into the memory plugin, keep wakeups as a core runtime primitive, expose RAG memory timestamps/sources, and move browser/desktop backend controllers into core modules with plugins as facades.

{codex_agent_framework-0.1.20 → codex_agent_framework-0.1.21}/README.md

@@ -237,10 +237,17 @@ agent = Agent(
     voice_enabled=False,
 )
 
-answer = agent("Summarize this repository in three practical bullet points.")
-print(answer)
+turn = agent("Summarize this repository in three practical bullet points.")
+
+print("Completed:", turn.completed)
+print("Reason:", turn.reason)
+print("Result:", turn.result)
+for message in turn.messages:
+    print(message.as_string())
 ```
 
+`agent(...)` returns an `AgentTurn`, not a raw string. `turn.result` is the useful final result, while `turn.messages` and `turn.events` contain the messages and events produced by that command. If `auto_proceed=False`, a tool-using turn can pause with `completed=False` and `reason="requires_next_step"`; call `agent.resume_turn(turn)` to continue the same turn object until it reaches a terminal reason such as `completed`, `result_set`, `interrupted`, or `error`.
+
 Resume the latest session interactively:
 
 ```python
@@ -349,7 +356,7 @@ def repo():
 
 agent = Agent(session="latest", voice_enabled=False)
 agent.add_command(repo)
-print(agent("/repo"))
+print(agent("/repo").result)
 ```
 
 ### Add stateful plugins
@@ -544,8 +551,11 @@ The default agent exposes local tools and plugin tools to the model. Plugin tool
 | Scheduler plugin | `scheduler_schedule`, `scheduler_cancel`, `scheduler_list`, `scheduler_restart_and_wakeup` | Future turns, periodic wakeups, post-restart continuation. |
 | Browser plugin | `browser_open`, `browser_goto`, `browser_click`, `browser_fill`, `browser_press`, ... | Persistent Playwright/Chromium automation with active-tab context. |
 | Desktop plugin | `desktop_start_session`, `desktop_run_commands`, `desktop_stop_session` | Screenshot-backed Linux desktop automation. |
+| Subagents plugin | `subagents_run` | Run an ephemeral child agent from a predefined profile and return a compact structured result. |
 
-Built-ins are intentionally packaged as plugins. Current built-in plugin modules include `files`, `content`, `bash`, `python`, `interface`, `environment`, `memory`, `planner`, `scheduler`, `browser`, and `desktop`.
+Built-ins are intentionally packaged as plugins. Current built-in plugin modules include `files`, `content`, `bash`, `python`, `interface`, `environment`, `memory`, `planner`, `scheduler`, `browser`, `desktop`, and `subagents`.
+
+The `subagents` plugin ships profile JSON files inside the package, starting with `explorer`, a read-only codebase inspection agent. Parent agents choose an existing profile and task; child agents receive their own config, tools, prompt, and temporary session instead of inheriting the parent's runtime implicitly.
 
 Built-in plugins are configurable. `None` means load all plugins, an empty list means load none, and an explicit list selects specific plugin module names:
 
@@ -654,8 +664,11 @@ Useful exported events include:
 - `ToolCallStartEvent` / `ToolCallDoneEvent`
 - `SessionLoadedEvent` / `SessionDeletedEvent`
 - `AssistantInterruptedEvent`
+- `SubagentEvent`
 - `AudioPlaybackEvent`
 
+Messages and events expose hierarchical `types` as well as the final computed `type`, so listeners can subscribe to broad classes such as all events or to precise concrete event types.
+
 Plugins can also register event and hook handlers with decorators:
 
 ```python
@@ -784,13 +797,13 @@ The tests isolate `AGENT_RUNTIME_DIR` automatically, so they should not create o
 The current tree validates at:
 
 ```text
-456 passed
+483 passed
 ```
 
-The published `0.1.20` release was validated at:
+The published `0.1.21` release was validated at:
 
 ```text
-456 passed
+483 passed
 ```
 
 ## Packaging
@@ -808,6 +821,7 @@ The distribution includes prompt text files, `codex_agent/get_text/default_gitig
 
 ## Recent changes
 
+- `0.1.21`: add structured `AgentTurn` returns with messages/events, resumable non-terminal turns for `auto_proceed=False`, profile-based subagents, hierarchical message/event types, and internal wakeups as developer messages.
 - `0.1.20`: make runtime plugins the single user-facing extension unit for tools/providers/commands, remove legacy direct runtime tool/provider loading, split tool/provider managers, and keep system-prompt templating on an explicit minimal namespace.
 - `0.1.19`: prune compacted raw session history after compaction, keep only the latest compaction anchor plus the new compaction and any unfinished remainder, and drop older redundant compaction summaries from active session files.
 - `0.1.18`: make `start server/tray` detach by default, move durable memory fully into the memory plugin, keep wakeups as a core runtime primitive, expose RAG memory timestamps/sources, and move browser/desktop backend controllers into core modules with plugins as facades.

{codex_agent_framework-0.1.20 → codex_agent_framework-0.1.21}/codex_agent/__init__.py

@@ -27,6 +27,7 @@ from .event import (
     ResponseToolCallsDeltaEvent,
     ServerToolCallEvent,
     SessionDeletedEvent,
+    SubagentEvent,
     SessionLoadedEvent,
     ToolCallDoneEvent,
     ToolCallStartEvent,
@@ -48,7 +49,7 @@ from .message import (
 from .image import ImageMessage
 from .mainloop import MainLoopManager
 from .plugin import Plugin, PluginsManager, event_handler, hook_handler
-from .command import AgentCommand, AgentFuture, CommandManager, command
+from .command import AgentCommand, AgentFuture, AgentTurn, CommandManager, command
 from .provider import ProvidersManager, provider
 from .runtime import RuntimeManager
 from .sessions import AgentSession, SessionsManager
@@ -87,6 +88,7 @@ __all__ = [
     "ResponseToolCallsDeltaEvent",
     "ServerToolCallEvent",
     "SessionDeletedEvent",
+    "SubagentEvent",
     "SessionLoadedEvent",
     "ToolCallDoneEvent",
     "ToolCallStartEvent",
@@ -111,6 +113,7 @@ __all__ = [
     "ProvidersManager",
     "AgentCommand",
     "AgentFuture",
+    "AgentTurn",
     "CommandManager",
     "command",
     "provider",

{codex_agent_framework-0.1.20 → codex_agent_framework-0.1.21}/codex_agent/agent.py

@@ -14,7 +14,7 @@ from .scheduler import AgentScheduler
 from .sessions import SessionsManager
 from .status import StatusManager
 from .tool import ImageGenerationTool, ToolsManager, reset_current_agent, set_current_agent
-from .ai import AIBadRequestError, AIClient
+from .ai import AIClient
 from .voice import VoiceProcessor
 from .latex import LaTeXProcessor
 from .event import AssistantInterruptRequestedEvent, AssistantInterrupted, AssistantInterruptedEvent, AudioPlaybackEvent, EventBus
@@ -71,6 +71,7 @@ class Agent:
         self.plugins_manager.init_runtime()
         self.command_manager.init_runtime()
         self.tools_manager.init_server_tools()
+        self.tools_manager.apply_config_exclusions()
         self.start_new_session() if session == "new" else self.load_session(session)
 
     def on(self, event_type, handler=None):
@@ -82,7 +83,11 @@ class Agent:
         return self.events.on(event_type, handler)
 
     def emit(self, event_type, **data):
-        return self.events.emit(event_type, **data)
+        event = self.events.emit(event_type, **data)
+        mainloop_manager = getattr(self, "mainloop_manager", None)
+        if mainloop_manager is not None:
+            mainloop_manager.record_event(event)
+        return event
 
     @property
     def busy(self):
@@ -104,28 +109,35 @@ class Agent:
     def start_turn(self):
         return self.mainloop_manager.start_turn()
 
+    def resume_turn(self, turn):
+        future = self.mainloop_manager.resume_turn(turn)
+        return None if future is None else future.wait()
+
     def submit_command(self, prompt):
         return self.command_manager.submit(prompt)
 
     def submit_message(self, message):
         return self.mainloop_manager.submit_message(message)
 
+    def set_turn_result(self, data):
+        return self.mainloop_manager.set_turn_result(data)
+
     def list_wakeups(self, include_done=True):
         return self.scheduler.list(include_done=include_done)
 
     def schedule_wakeup(self, **kwargs):
         if self.mainloop_manager.should_queue_state_command():
-            return self.submit("schedule_wakeup", **kwargs).wait()
+            return self.submit("schedule_wakeup", **kwargs).wait().result
         return self.scheduler.schedule(**kwargs)
 
     def cancel_wakeup(self, job_id):
         if self.mainloop_manager.should_queue_state_command():
-            return self.submit("cancel_wakeup", job_id=job_id).wait()
+            return self.submit("cancel_wakeup", job_id=job_id).wait().result
         return self.scheduler.cancel(job_id)
 
     def delete_wakeup(self, job_id):
         if self.mainloop_manager.should_queue_state_command():
-            return self.submit("delete_wakeup", job_id=job_id).wait()
+            return self.submit("delete_wakeup", job_id=job_id).wait().result
         return self.scheduler.delete(job_id)
 
     def interrupt(self, reason="user"):
@@ -256,7 +268,7 @@ class Agent:
             return decorator
 
         if hasattr(self, "mainloop_manager") and self.mainloop_manager.should_queue_state_command():
-            return self.submit("add_hook", key=key, func=func).wait()
+            return self.submit("add_hook", key=key, func=func).wait().result
 
         return self.hooks.add(key, func)
 
@@ -327,6 +339,10 @@ class Agent:
         Returns:
             Message: The aggregated assistant message with content and/or tool calls.
         """
+        if self.session and not self.session.is_sane():
+            repair = self.session.repair()
+            if repair.repaired:
+                self.status_manager.invalidate_context_cache()
         messages = self.context_manager.get_context()
         if self.context_manager.should_auto_compact(messages):
             self.compact_session(
@@ -335,21 +351,16 @@ class Agent:
             )
             messages = self.context_manager.get_context()
 
-        try:
-            message=self.ai.run(
-                messages=messages,
-                tools=self.tools_manager.get_response_tools(),
-                prompt_cache_key=self.current_session_id,
-                **self.config.extract('model','reasoning_effort','verbosity','parallel_tool_calls')
-            )
-        except AIBadRequestError:
-            self.sessions_manager.restore_api_success_backup()
-            raise
+        message=self.ai.run(
+            messages=messages,
+            tools=self.tools_manager.get_response_tools(),
+            prompt_cache_key=self.current_session_id,
+            **self.config.extract('model','reasoning_effort','verbosity','parallel_tool_calls')
+        )
         self.sessions_manager.append_message(message)
         for item in message.output_items:
             if self.tools_manager.server_tool_for_item(item):
                 self.sessions_manager.append_message(ServerToolResponseMessage(item=item))
-        self.sessions_manager.save_api_success_backup()
         return message
 
     def speak(self,text,**kwargs):
@@ -431,7 +442,7 @@ class Agent:
 
         return dest_path
 
-    def __call__(self,prompt=None)->bool:
+    def __call__(self, prompt=None):
         return self.mainloop_manager.call(prompt=prompt)
 
     def interact(self):

{codex_agent_framework-0.1.20 → codex_agent_framework-0.1.21}/codex_agent/agent_runtime.py

@@ -429,7 +429,7 @@ class ProcessAgentRuntime(AgentRuntime):
         payload = dict(values or {})
         payload.update(kwargs)
         result = self.call("update_config", {"values": payload, "save": save}, timeout=self.command_timeout)
-        self.cache.config = result
+        self.cache["config"] = result
         return result
 
     def session(self):

{codex_agent_framework-0.1.20 → codex_agent_framework-0.1.21}/codex_agent/builtin_plugins/memory/__init__.py

@@ -370,6 +370,7 @@ You can manage memory explicitly with the memory tools:
 Use your memory tools judiciously and proactively to create durable records of important information that should persist beyond the current session.
 Do not over-memorize routine exchanges, transient implementation details, or information that is only useful within the current turn. 
 Prefer durable facts, preferences, decisions, and important outcomes.
+Memory entries should be rather short (one paragraph) and semantically well scoped for more efficient retrieval.
 Keep your memory tidy and up to date by editing or deleting outdated or irrelevant entries.
 When automatic memory archiving is enabled, completed turns are summarized into memory in the background when they contain something worth remembering.
 """
@@ -469,7 +470,7 @@ When automatic memory archiving is enabled, completed turns are summarized into
 
     @event_handler(AssistantTurnEndEvent)
     def archive_completed_turn(self, event):
-        if event.get("result") is not True:
+        if event.get("reason") != "completed":
             return None
         if not self.config.auto_archive:
             return None

codex_agent_framework-0.1.21/codex_agent/builtin_plugins/subagents/__init__.py

@@ -0,0 +1,220 @@
+"""Subagents plugin: delegate focused tasks to ephemeral child agents."""
+
+import json
+import os
+from pathlib import Path
+
+from modict import modict
+
+from ...event import SubagentEvent
+from ...plugin import Plugin
+from ...tool import tool
+
+
+class SubagentResult(modict):
+    _config = modict.config(require_all="never")
+
+    type = "subagent_result"
+    profile = ""
+    name = ""
+    task = ""
+    status = ""
+    result = None
+    error = None
+
+
+class SubagentsPlugin(Plugin):
+    name = "subagents"
+    description = "Delegate focused tasks to ephemeral child agents with their own config and plugins."
+    profiles_dir = Path(__file__).parent / "profiles"
+    system_prompt = """
+# Subagents
+
+Use `subagents_run` to delegate a focused task to a subagent profile with its own predefined config, tools and plugins.
+Choose one of the available profiles and provide a focused task. The child agent receives its own `set_result` tool to provide a structured result. The parent receives that result and should report it back clearly.
+"""
+    child_system_prompt = """
+You are a focused subagent running inside a parent agent.
+
+Fundamentals:
+- Work only on the delegated task.
+- Use your available tools autonomously when useful.
+- You may perform multiple reasoning/tool steps before finishing.
+- Keep your work scoped to your role and available capabilities.
+- When the task is complete, call the local `set_result` tool with the structured result to return to the parent agent.
+- Do not ask the user for follow-up; report uncertainty or missing inputs in the structured result instead.
+"""
+
+    def __init__(self, agent):
+        super().__init__(agent)
+        self.profiles = modict()
+        self.load_profiles()
+
+    def load_profiles(self):
+        profiles_dir = Path(self.profiles_dir)
+        if not profiles_dir.is_dir():
+            return self.profiles
+        for path in sorted(profiles_dir.glob("*.json")):
+            self.load_profile_file(path)
+        return self.profiles
+
+    def load_profile_file(self, path):
+        with open(path, encoding="utf-8") as f:
+            profile = json.load(f)
+        if not isinstance(profile, dict):
+            raise ValueError(f"Invalid subagent profile {path}: expected JSON object")
+        profile_name = profile.pop("id", None) or path.stem
+        self.register_profile(profile_name, **profile)
+        return profile_name
+
+    def register_profile(self, profile_name, **profile):
+        self.profiles[profile_name] = modict(profile)
+        return self.profiles[profile_name]
+
+    def get_system_prompt_sections(self):
+        if not self.profiles:
+            return [self.system_prompt.strip() + "\n\nNo subagent profiles are currently available."]
+        lines = [self.system_prompt.strip(), "", "Available subagent profiles:"]
+        for name, profile in self.profiles.items():
+            description = profile.get("description", "No description provided.")
+            lines.append(f"- `{name}`: {description}")
+        return ["\n".join(lines)]
+
+    def profile(self, name):
+        if not name:
+            raise ValueError("A subagent profile is required")
+        if name not in self.profiles:
+            raise ValueError(f"Unknown subagent profile: {name}")
+        return modict(self.profiles[name])
+
+    def profile_system_prompt(self, profile):
+        sections = [self.child_system_prompt.strip()]
+        structured = []
+        for key, title in (
+            ("role", "Role"),
+            ("goal", "Goal"),
+            ("means", "Means"),
+            ("objective", "Objective"),
+        ):
+            value = profile.get(key)
+            if value:
+                structured.append(f"## {title}\n{value}")
+        if structured:
+            sections.append("\n\n".join(structured))
+        if profile.get("system_prompt"):
+            sections.append(str(profile.system_prompt).strip())
+        return "\n\n".join(section for section in sections if section)
+
+    def child_config(self, profile):
+        data = modict(profile)
+        config = modict(data.pop("config", {}) or {})
+
+        for key in ("name", "builtin_plugins", "custom_plugins", "exclude_tools", "model", "reasoning_effort", "verbosity"):
+            if key in data:
+                config[key] = data[key]
+
+        config.system = self.profile_system_prompt(data)
+        config.setdefault("name", data.get("name") or f"{self.agent.config.name} subagent")
+        config.setdefault("username", self.agent.config.get("username"))
+        config.setdefault("userage", self.agent.config.get("userage"))
+        config.setdefault("openai_api_key", self.agent.config.get("openai_api_key"))
+        config.setdefault("voice_enabled", False)
+        config.setdefault("builtin_plugins", [])
+        config.setdefault("custom_plugins", [])
+        config.setdefault("exclude_tools", [])
+        return config
+
+    def relay_child_event(self, subagent, child, event):
+        wrapped = SubagentEvent(
+            subagent=subagent,
+            event=event,
+            session_id=getattr(child, "current_session_id", ""),
+        )
+        self.agent.events.emit(wrapped)
+        mainloop_manager = getattr(self.agent, "mainloop_manager", None)
+        if mainloop_manager is not None:
+            mainloop_manager.record_event(wrapped)
+        return event
+
+    def install_child_tools(self, child):
+        def set_result(data):
+            """
+            description: |
+                Set some data as this turn's result and finish the turn after the current step.
+                The result will be accessible by the caller (user or other Agent) as `AgentTurn.result`
+                Use this when your task is complete and you need to return structured data to the caller.
+            parameters:
+                data:
+                    description: Structured result data to return for the current subagent turn.
+            required:
+                - data
+            """
+            child.set_turn_result(data)
+            return "Subagent result set."
+
+        child.add_tool(set_result, name="set_result")
+        return child
+
+    def cleanup_session(self, child):
+        session = getattr(child, "session", None)
+        if session is None:
+            return
+        for path in (session.session_file, session.api_success_backup_file):
+            if path and os.path.exists(path):
+                os.remove(path)
+
+    def run_subagent(self, profile, task):
+        from ...agent import Agent
+
+        child = None
+        profile_data = None
+        try:
+            profile_data = self.profile(profile)
+            child = Agent(session="new", **self.child_config(profile_data))
+            child.on("*", lambda event: self.relay_child_event(profile, child, event))
+            self.install_child_tools(child)
+            prompt = (
+                f"{task}\n\n"
+                "When the delegated task is complete, call the `set_result` tool with the structured result to return to the parent agent."
+            )
+            turn = child(prompt)
+            return SubagentResult(
+                profile=profile,
+                name=child.config.name,
+                task=task,
+                status=turn.status,
+                result=turn.result,
+            )
+        except Exception as exc:
+            return SubagentResult(
+                profile=profile,
+                name=(profile_data or {}).get("name", profile),
+                task=task,
+                status="error",
+                error=str(exc),
+            )
+        finally:
+            if child is not None:
+                child.stop(timeout=1.0)
+                if not (profile_data or {}).get("keep_session", False):
+                    self.cleanup_session(child)
+
+    @tool(name="run")
+    def run(self, profile: str, task: str):
+        """
+        description: |
+            Run a focused task in an ephemeral child agent selected from predefined profiles.
+            The calling agent must only choose an existing profile and provide the specific task.
+            The child agent receives a local `set_result` tool to return structured data to the parent.
+        parameters:
+            profile:
+                description: Registered subagent profile to use.
+                type: string
+            task:
+                description: Specific task prompt to give to the selected subagent profile.
+                type: string
+        required:
+            - profile
+            - task
+        """
+        return self.run_subagent(profile=profile, task=task)

codex_agent_framework-0.1.21/codex_agent/builtin_plugins/subagents/profiles/explorer.json

@@ -0,0 +1,12 @@
+{
+  "id": "explorer",
+  "name": "Codebase explorer",
+  "description": "Read-only project/codebase exploration subagent for mapping structure, inspecting files, and reporting findings.",
+  "role": "You are a read-only project and codebase exploration subagent.",
+  "goal": "Understand the relevant structure, files, code paths, and implementation details needed for the delegated task, then return a clear structured report.",
+  "means": "Use read-only inspection tools such as file reading and content extraction. Do not modify files, run destructive actions, or change project state.",
+  "objective": "Call `set_result` with a structured exploration report including key findings, relevant files/symbols, confidence, and any remaining uncertainties.",
+  "builtin_plugins": ["files", "content", "environment"],
+  "exclude_tools": ["files.write", "files.edit"],
+  "voice_enabled": false
+}

{codex_agent_framework-0.1.20 → codex_agent_framework-0.1.21}/codex_agent/client.py

@@ -45,8 +45,22 @@ class AgentClient:
     def emit_local(self, event):
         event = modict(event)
         event_type = event.get("type")
-        handlers = list(self._event_handlers.get(event_type, ()))
-        handlers.extend(self._event_handlers.get("*", ()))
+        event_types = list(event.get("types") or [event_type])
+        if event_type and event_type not in event_types:
+            event_types.append(event_type)
+        handlers = []
+        seen = set()
+        for current_type in event_types:
+            for handler in self._event_handlers.get(current_type, ()):
+                if handler in seen:
+                    continue
+                seen.add(handler)
+                handlers.append(handler)
+        for handler in self._event_handlers.get("*", ()):
+            if handler in seen:
+                continue
+            seen.add(handler)
+            handlers.append(handler)
         for handler in handlers:
             try:
                 handler(event)