feat: Extension — one plug-in contract for the agent lifecycle (#241 PR 1)

[yuanhao]

PR 1 of #241: the Extension contract and its loop wiring. It builds on #242 (hook-order pin test), #244 (loop fixes) and #245 (AgentLoopConfig::new), all merged.

The contract (src/extension.rs, yoagent::extension)

Extension, the factory, one per installation. It has name, mode (Advisory/Required), filters_tool_output, rechecks_modified_calls, start_run(&RunContext) -> Box<dyn RunHooks>, and a sync on_event(&self, run_id, event).

RunHooks, fresh per run, &mut self, no-op defaults. It has tools, on_input, before_model, before_tool, after_tool, on_stop and finish.

Types:

• RunContext: run_id, the host's label, prompts, depth, cancel.
• Contexts InputContext, StopContext; decisions InputDecision, TurnDecision, StopDecision; RunOutcome, ExtensionError. All the context, decision and outcome types are #[non_exhaustive].
• Stateless::new(name, hooks) clones the hooks per run.
• Constants EXTENSION_FAILED_PREFIX, EXTENSION_MESSAGE_PREFIX (in is_loop_injected) and DEFAULT_MAX_STOP_CONTINUES.

API

• Agent and SubAgentTool: with_extension, with_tree_extension, with_max_stop_continues.
• Agent::with_run_label.
• AgentLoopConfig gains extensions, tree_extensions, max_stop_continues and run_label (non-breaking since feat!: AgentLoopConfig::new + #[non_exhaustive] (#228, for #241) #245).
• ToolContext gains tree_extensions() and delegation_depth() for custom delegation tools.

Semantics, as revised in #241

• Failures follow the mode table.

  • The single-call guards fail closed in both modes: on_input rejects, before_tool denies, after_tool withholds the result.
  • A required failure ends the run with an assistant Error message prefixed [Extension failed: <name>], calls on_error, and keeps TurnStart/TurnEnd paired.
  • Failures inside after_tool and on_event are checked at the next boundary.

• before_model runs once per turn, before the retry loop.

  • Notes go on the latest user turn and are never stored.
  • Stop behaves like a limit (a stop marker).
  • The model is never called on Stop or Fail.

• before_tool runs after the ToolMiddleware chain. A rechecks_modified_calls policy judges the final arguments again when a later extension rewrote them (the gap raised on Design: Extension — one plug-in contract for the agent lifecycle #241).

• after_tool sees the result before truncation, the output sink and ToolExecutionEnd. While an extension filters_tool_output, ToolExecutionUpdate/ProgressMessage are withheld.

• on_stop applies when the last message is an assistant Stop and no follow-ups are queued. Continue appends [Extension <name>] … as a loop-injected user turn, capped. Exceeding the cap fails a required extension and only warns for an advisory one.

• Tree extensions:

  • they are prepended in child runs at any depth, passed through ToolContext, which SubAgentTool reads;
  • their tools are not offered to children;
  • state for one run is fresh per run, and aggregate state lives on the Extension.

  This closes the existing bypass where a parent's middleware did not gate a sub-agent's own calls.

Deviations from the issue text (reasoned)

• on_event is on Extension (&self), not RunHooks (&mut self). If it locked the run's hooks, an event would wait behind an in-flight async hook. For example, an approval before_tool waiting on a UI that waits on the event would stall. Events are delivered in order through a forwarder task that exists only when extensions do, and is drained before the run returns.
• finish(&mut self) instead of self: Box<Self>.
• The older hooks are not re-routed through adapters. They keep their exact code paths and run first at each point, so tests/hook_order_test.rs passes unmodified. That is the compatibility guarantee. before_model notes land before TurnHook notes, because turn hooks run inside the provider call, once per attempt.

Tests

tests/extension_test.rs (23 cases) covers every hook and the mode table:

• panics contained per mode, start failures, notes, Stop, the rechecking policy;
• redaction with partial output withheld (and sent when no extension filters it);
• the on_stop cap, advisory and required;
• on_event seeing every event in consumer order;
• per-run isolation across two concurrent agents sharing an extension, with finish once per run;
• continue_loop running no on_input;
• RunContext contents;
• tree extensions: a deny at depth 0, 1 and 2 while an ordinary extension stays with the parent, the tree's tools not offered to children, and a tree-wide budget stopping a child.

tests/hook_order_test.rs is unchanged.

Checks

• cargo test --all-features: 57 test binaries.
• clippy with --all-features and --no-default-features.
• wasm32 clippy (CLIPPY_CONF_DIR=.github/clippy-wasm32, --features decision).
• cargo doc -Dwarnings, fmt.

Docs:

• a new docs/concepts/extensions.md, in SUMMARY;
• CHANGELOG Unreleased → Added;
• a CLAUDE.md architecture note.

PR 2 (dogfooding ToolGate / InputGuard / Advisor / Budget / yoagent-rutis) follows.

🤖 Generated with Claude Code

https://claude.ai/code/session_01T7iq5hpndSiHQcnAsywKuG