feat(agent_loop): phase 5 — Janet plugin hook surface for pi-loop hooks

Surface every pi loop hook (prepareNextTurn, shouldStopAfterTurn,
getSteeringMessages, getFollowUpMessages) to Janet plugins via
dedicated slots. Auto-wired into spawn_loop_runner when a plugin
manager is supplied.

**Janet helpers added** (plugin/worker.rs):

  ; prepareNextTurn → next-turn config swap
  (harness/set-next-thinking-level "high")    ; low/medium/high/xhigh/off/minimal
  ; harness/set-next-model already exists — repurposed

  ; shouldStopAfterTurn → graceful exit
  (harness/request-stop-after-turn)

  ; getSteeringMessages → mid-run user injection
  (harness/add-steering "wait, also do X")

  ; getFollowUpMessages → outer-loop continuation
  (harness/add-followup "do this next")

**Rust slot accessors** (plugin/mod.rs):
  - take_pending_next_thinking_level() -> Option<String>
  - take_pending_stop_after_turn()     -> bool
  - drain_steering_messages()          -> Vec<String>
  - drain_followup_messages()          -> Vec<String>

Steering + followup use a newline-blob format (`msg\n`) so a
single eval round-trip drains the queue cleanly.

**Hook factories** (plugin_hooks.rs):
  - prepare_next_turn_from_plugin_manager(pm) -> PrepareNextTurnFn
  - should_stop_after_turn_from_plugin_manager(pm) -> ShouldStopAfterTurnFn
  - get_steering_messages_from_plugin_manager(pm) -> GetSteeringMessagesFn
  - get_followup_messages_from_plugin_manager(pm) -> GetFollowupMessagesFn

Each follows the same lock-then-sync pattern as before/after_tool_call
hooks: acquire mutex, eval slot, release. No `.await` while held.

**Wired into spawn_loop_runner** (integration.rs): when
`cfg.plugin_mgr` is set, all four hooks are installed alongside
the existing before/after_tool_call. Caller-provided
steering_queue still wins if both are set (explicit beats global).

**Tests** (6 new integration tests with real Janet VM):
  - prepare_next_turn_reads_thinking_level
  - prepare_next_turn_returns_none_when_no_slot_set
  - prepare_next_turn_ignores_unknown_thinking_level (typo safety)
  - should_stop_after_turn_drains_slot
  - get_steering_messages_drains_queue (multiple add + drain)
  - get_followup_messages_drains_queue

**Pi reference**: PLAN.md phase 5. Each slot maps 1:1 to a pi
hook from runLoop. Slot mechanism (Janet `var` + `defn` helper +
Rust `take_*` reader) was already established by the pre-existing
harness-next-model / harness-block / harness-mutate-input slots;
phase 5 extends the pattern to the remaining pi hooks.

**Composition with phase 4.6**: prepareNextTurn's thinking_level
field is now actively populated by plugins. The full chain
works:

  plugin sets harness-next-thinking-level "high" in on-tool-end
       ↓
  loop polls prepare_next_turn between turns
       ↓
  TurnUpdate.thinking_level = Some(High)
       ↓
  (currently surfaces tracing warn — code review #3; full
   model-swap apply pending rig API growth, see h-7 deferred)

Gates:
  - cargo build (default)         clean
  - cargo build --features plugin clean
  - cargo build --all-features    clean
  - cargo test (default 846)      green
  - cargo test --features plugin  (985 = 979 pre-existing + 6
                                  new phase 5 tests) green
  - cargo test --ignored          6 h-7 still green (no
                                  regression after Janet
                                  slot additions)
  - cargo fmt                     clean

Phase 6 next: recovery / interjection / abort hardening under
the new loop. Or phase 7 (custom message types). Phase 5 risk
was low as predicted; landed clean.

Author: Yogthos

src/agent/agent_loop/integration.rs

@@ -384,11 +384,37 @@ pub fn spawn_loop_runner(cfg: LoopSpawnConfig) -> LoopRunner {
     #[cfg(feature = "plugin")]
     {
         if let Some(pm) = cfg.plugin_mgr {
+            // Phase 4.5d: before/after tool call hooks.
             loop_config.before_tool_call = Some(
                 super::plugin_hooks::before_hook_from_plugin_manager(pm.clone()),
             );
-            loop_config.after_tool_call =
-                Some(super::plugin_hooks::after_hook_from_plugin_manager(pm));
+            loop_config.after_tool_call = Some(
+                super::plugin_hooks::after_hook_from_plugin_manager(pm.clone()),
+            );
+            // Phase 5: pi-loop hook surface for plugins.
+            // Each polls a dedicated Janet slot the plugin sets
+            // via harness/* helpers. Hooks fire at the right
+            // loop points (prepareNextTurn between turns;
+            // shouldStopAfterTurn after every turn;
+            // getSteeringMessages per turn boundary;
+            // getFollowUpMessages at outer-loop boundary).
+            loop_config.prepare_next_turn = Some(
+                super::plugin_hooks::prepare_next_turn_from_plugin_manager(pm.clone()),
+            );
+            loop_config.should_stop_after_turn =
+                Some(super::plugin_hooks::should_stop_after_turn_from_plugin_manager(pm.clone()));
+            // Compose with caller-provided steering queue: if
+            // BOTH are present, prefer the plugin one (plugin
+            // hooks compose at runtime; the explicit
+            // steering_queue was for legacy / test usage). Real
+            // production wires one or the other.
+            if loop_config.get_steering_messages.is_none() {
+                loop_config.get_steering_messages = Some(
+                    super::plugin_hooks::get_steering_messages_from_plugin_manager(pm.clone()),
+                );
+            }
+            loop_config.get_followup_messages =
+                Some(super::plugin_hooks::get_followup_messages_from_plugin_manager(pm));
         }
     }
 

src/agent/agent_loop/plugin_hooks.rs

@@ -34,9 +34,12 @@ use crate::plugin::{PluginManager, escape_janet_string};
 
 use super::hooks::{
     AfterToolCallContext, AfterToolCallFn, BeforeToolCallContext, BeforeToolCallFn,
-    BeforeToolCallReturn,
+    BeforeToolCallReturn, GetFollowupMessagesFn, GetSteeringMessagesFn, PrepareNextTurnFn,
+    ShouldStopAfterTurnFn,
 };
+use super::message::{LoopMessage, UserMessage};
 use super::result::{AfterToolCallResult, BeforeToolCallResult};
+use super::types::{ThinkingLevel, TurnUpdate};
 
 /// Build a `BeforeToolCallFn` that dispatches `on-tool-start`
 /// through the shared `PluginManager`.
@@ -224,6 +227,127 @@ fn flatten_text(content: &[serde_json::Value]) -> String {
     out
 }
 
+// ============================================================
+// Phase 5 — pi-loop hook factories
+// ============================================================
+
+/// Build a `PrepareNextTurnFn` that reads the
+/// `harness-next-thinking-level` slot (and `harness-next-model`)
+/// from the plugin manager. Plugins set these slots via
+/// `harness/set-next-thinking-level` / `harness/set-next-model`
+/// inside `on-tool-end` (or any hook firing between turns).
+///
+/// Returns `Some(TurnUpdate)` with the requested fields when any
+/// slot was set; `None` otherwise. Context is never mutated by
+/// this factory — separate hooks compose if a plugin wants to
+/// rewrite the transcript.
+///
+/// Locking pattern matches before/after_hook_from_plugin_manager:
+/// acquire-read-release synchronously per call.
+pub fn prepare_next_turn_from_plugin_manager(pm: Arc<Mutex<PluginManager>>) -> PrepareNextTurnFn {
+    Arc::new(move |_ctx| {
+        let pm = pm.clone();
+        Box::pin(async move {
+            let (thinking, model) = {
+                let mut mgr = pm.lock().unwrap_or_else(|e| e.into_inner());
+                let t = mgr.take_pending_next_thinking_level();
+                let m = mgr.take_pending_next_model();
+                (t, m)
+            };
+            let thinking_level = thinking.and_then(parse_thinking_level);
+            if thinking_level.is_none() && model.is_none() {
+                return None;
+            }
+            Some(TurnUpdate {
+                context: None,
+                model,
+                thinking_level,
+            })
+        })
+    })
+}
+
+/// Build a `ShouldStopAfterTurnFn` that reads the
+/// `harness-stop-after-turn` flag. Plugins call
+/// `harness/request-stop-after-turn` from any per-turn hook
+/// (`on-tool-end`, etc.) to ask the loop to exit gracefully
+/// after the current turn.
+///
+/// Returns `true` once per slot-set; the slot is cleared on
+/// read so subsequent turns see the default (don't stop).
+pub fn should_stop_after_turn_from_plugin_manager(
+    pm: Arc<Mutex<PluginManager>>,
+) -> ShouldStopAfterTurnFn {
+    Arc::new(move |_ctx| {
+        let pm = pm.clone();
+        Box::pin(async move {
+            let mut mgr = pm.lock().unwrap_or_else(|e| e.into_inner());
+            mgr.take_pending_stop_after_turn()
+        })
+    })
+}
+
+/// Build a `GetSteeringMessagesFn` that drains the plugin's
+/// `harness-steering-messages` queue. Plugins call
+/// `harness/add-steering` to inject mid-run user turns.
+///
+/// Returns a (possibly empty) Vec of `LoopMessage::User`s.
+pub fn get_steering_messages_from_plugin_manager(
+    pm: Arc<Mutex<PluginManager>>,
+) -> GetSteeringMessagesFn {
+    Arc::new(move || {
+        let pm = pm.clone();
+        Box::pin(async move {
+            let drained: Vec<String> = {
+                let mut mgr = pm.lock().unwrap_or_else(|e| e.into_inner());
+                mgr.drain_steering_messages()
+            };
+            drained
+                .into_iter()
+                .map(|content| LoopMessage::User(UserMessage { content }))
+                .collect()
+        })
+    })
+}
+
+/// Build a `GetFollowupMessagesFn` that drains the plugin's
+/// `harness-followup-messages` queue. Plugins call
+/// `harness/add-followup` to add post-stop user turns; the
+/// outer loop re-enters with them as the next pending batch.
+pub fn get_followup_messages_from_plugin_manager(
+    pm: Arc<Mutex<PluginManager>>,
+) -> GetFollowupMessagesFn {
+    Arc::new(move || {
+        let pm = pm.clone();
+        Box::pin(async move {
+            let drained: Vec<String> = {
+                let mut mgr = pm.lock().unwrap_or_else(|e| e.into_inner());
+                mgr.drain_followup_messages()
+            };
+            drained
+                .into_iter()
+                .map(|content| LoopMessage::User(UserMessage { content }))
+                .collect()
+        })
+    })
+}
+
+/// Parse a Janet-side level string into `ThinkingLevel`. Pi
+/// values: `"off"`, `"minimal"`, `"low"`, `"medium"`, `"high"`,
+/// `"xhigh"`. Unknown values produce None (plugin's typo is
+/// silently ignored rather than crashing the run).
+fn parse_thinking_level(s: String) -> Option<ThinkingLevel> {
+    match s.as_str() {
+        "off" => Some(ThinkingLevel::Off),
+        "minimal" => Some(ThinkingLevel::Minimal),
+        "low" => Some(ThinkingLevel::Low),
+        "medium" => Some(ThinkingLevel::Medium),
+        "high" => Some(ThinkingLevel::High),
+        "xhigh" => Some(ThinkingLevel::Xhigh),
+        _ => None,
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -450,4 +574,144 @@ mod tests {
         let out = flatten_text(&blocks);
         assert!(out.contains("image"));
     }
+
+    // ============================================================
+    // Phase 5 — pi-loop hook factory tests
+    // ============================================================
+
+    use crate::agent::agent_loop::hooks::TurnHookContext;
+    use crate::agent::agent_loop::message::AssistantMessage as AM;
+
+    fn turn_ctx() -> TurnHookContext {
+        TurnHookContext {
+            message: AM::new(vec![], super::super::message::StopReason::Stop),
+            tool_results: Vec::new(),
+            context: crate::agent::agent_loop::types::Context::default(),
+            new_messages: Vec::new(),
+        }
+    }
+
+    /// prepareNextTurn returns Some(TurnUpdate) with the
+    /// requested thinking_level when a plugin set the slot.
+    #[tokio::test]
+    async fn prepare_next_turn_reads_thinking_level() {
+        let Some(pm) = try_pm() else { return };
+        {
+            let mut mgr = pm.lock().unwrap();
+            mgr.eval(r#"(defn bump [_ctx] (harness/set-next-thinking-level "high"))"#)
+                .unwrap();
+            mgr.register("on-tool-end", "bump");
+            // Fire on-tool-end so the slot gets set.
+            mgr.dispatch_tool_hook("on-tool-end", "@{:tool \"t\" :output \"x\"}")
+                .unwrap();
+        }
+        let hook = prepare_next_turn_from_plugin_manager(pm);
+        let out = hook(turn_ctx()).await;
+        assert!(out.is_some(), "expected TurnUpdate");
+        let upd = out.unwrap();
+        assert_eq!(upd.thinking_level, Some(ThinkingLevel::High));
+        assert!(upd.model.is_none());
+    }
+
+    /// prepareNextTurn returns None when no slot was set.
+    #[tokio::test]
+    async fn prepare_next_turn_returns_none_when_no_slot_set() {
+        let Some(pm) = try_pm() else { return };
+        let hook = prepare_next_turn_from_plugin_manager(pm);
+        assert!(hook(turn_ctx()).await.is_none());
+    }
+
+    /// shouldStopAfterTurn returns true once after a plugin
+    /// calls request-stop-after-turn, then false on subsequent
+    /// reads (slot drained).
+    #[tokio::test]
+    async fn should_stop_after_turn_drains_slot() {
+        let Some(pm) = try_pm() else { return };
+        {
+            let mut mgr = pm.lock().unwrap();
+            mgr.eval(r#"(defn stop [_ctx] (harness/request-stop-after-turn))"#)
+                .unwrap();
+            mgr.register("on-tool-end", "stop");
+            mgr.dispatch_tool_hook("on-tool-end", "@{:tool \"t\" :output \"x\"}")
+                .unwrap();
+        }
+        let hook = should_stop_after_turn_from_plugin_manager(pm);
+        assert!(hook(turn_ctx()).await, "first read should return true");
+        assert!(
+            !hook(turn_ctx()).await,
+            "second read should be false (slot drained)"
+        );
+    }
+
+    /// getSteeringMessages drains the slot — each
+    /// harness/add-steering call appears as a LoopMessage::User
+    /// once; subsequent polls see only newly-added messages.
+    #[tokio::test]
+    async fn get_steering_messages_drains_queue() {
+        let Some(pm) = try_pm() else { return };
+        {
+            let mut mgr = pm.lock().unwrap();
+            mgr.eval(
+                r#"(defn add [_ctx] (harness/add-steering "first") (harness/add-steering "second"))"#,
+            )
+            .unwrap();
+            mgr.register("on-tool-end", "add");
+            mgr.dispatch_tool_hook("on-tool-end", "@{:tool \"t\" :output \"x\"}")
+                .unwrap();
+        }
+        let hook = get_steering_messages_from_plugin_manager(pm.clone());
+        let messages = hook().await;
+        assert_eq!(messages.len(), 2);
+        let texts: Vec<String> = messages
+            .iter()
+            .filter_map(|m| match m {
+                LoopMessage::User(u) => Some(u.content.clone()),
+                _ => None,
+            })
+            .collect();
+        assert_eq!(texts, vec!["first", "second"]);
+        // Second poll: empty (drained).
+        assert!(hook().await.is_empty());
+    }
+
+    /// getFollowupMessages mirrors steering but reads its own
+    /// independent slot.
+    #[tokio::test]
+    async fn get_followup_messages_drains_queue() {
+        let Some(pm) = try_pm() else { return };
+        {
+            let mut mgr = pm.lock().unwrap();
+            mgr.eval(r#"(defn add [_ctx] (harness/add-followup "next turn"))"#)
+                .unwrap();
+            mgr.register("on-tool-end", "add");
+            mgr.dispatch_tool_hook("on-tool-end", "@{:tool \"t\" :output \"x\"}")
+                .unwrap();
+        }
+        let hook = get_followup_messages_from_plugin_manager(pm);
+        let messages = hook().await;
+        assert_eq!(messages.len(), 1);
+        match &messages[0] {
+            LoopMessage::User(u) => assert_eq!(u.content, "next turn"),
+            _ => panic!("expected User"),
+        }
+    }
+
+    /// Unknown thinking-level strings get filtered out — a
+    /// plugin typo doesn't crash the run.
+    #[tokio::test]
+    async fn prepare_next_turn_ignores_unknown_thinking_level() {
+        let Some(pm) = try_pm() else { return };
+        {
+            let mut mgr = pm.lock().unwrap();
+            mgr.eval(r#"(defn bad [_ctx] (harness/set-next-thinking-level "supercritical"))"#)
+                .unwrap();
+            mgr.register("on-tool-end", "bad");
+            mgr.dispatch_tool_hook("on-tool-end", "@{:tool \"t\" :output \"x\"}")
+                .unwrap();
+        }
+        let hook = prepare_next_turn_from_plugin_manager(pm);
+        // "supercritical" doesn't parse → thinking_level None
+        // → no model set either → None overall.
+        assert!(hook(turn_ctx()).await.is_none());
+    }
 }

src/plugin/mod.rs

@@ -2010,6 +2010,71 @@ impl PluginManager {
         self.take_string_slot("harness-next-model")
     }
 
+    // ============================================================
+    // Phase 5 — pi-loop hook slots
+    // ============================================================
+
+    /// Read and clear the `harness-next-thinking-level` slot.
+    /// Set by plugins via `harness/set-next-thinking-level` to
+    /// request a reasoning-level change for the next turn. The
+    /// new agent_loop path consults this from its
+    /// `prepareNextTurn` hook.
+    ///
+    /// Returns the raw string ("low" | "medium" | "high" |
+    /// "xhigh" | "off" | "minimal"); the caller maps it to
+    /// `ThinkingLevel`.
+    pub fn take_pending_next_thinking_level(&mut self) -> Option<String> {
+        self.take_string_slot("harness-next-thinking-level")
+    }
+
+    /// Read and clear the `harness-stop-after-turn` flag. Set
+    /// by plugins via `harness/request-stop-after-turn` to ask
+    /// the loop to exit gracefully after the current turn.
+    /// Polled by the agent_loop `shouldStopAfterTurn` hook.
+    pub fn take_pending_stop_after_turn(&mut self) -> bool {
+        // The slot is `nil` initially and `true` once set. Eval
+        // returns "true" or "false" as text.
+        let was_set = self
+            .worker
+            .eval("(if harness-stop-after-turn true false)")
+            .map(|s| s == "true")
+            .unwrap_or(false);
+        if was_set {
+            let _ = self.worker.eval("(set harness-stop-after-turn nil)");
+        }
+        was_set
+    }
+
+    /// Drain the `harness-steering-messages` blob — a newline-
+    /// separated list of strings each plugins added via
+    /// `harness/add-steering`. Returns one entry per message;
+    /// empty Vec if no plugin added any.
+    pub fn drain_steering_messages(&mut self) -> Vec<String> {
+        self.drain_newline_blob("harness-steering-messages")
+    }
+
+    /// Drain the `harness-followup-messages` blob. Same shape
+    /// as steering; read at the outer-loop boundary by the new
+    /// loop's `getFollowUpMessages` hook.
+    pub fn drain_followup_messages(&mut self) -> Vec<String> {
+        self.drain_newline_blob("harness-followup-messages")
+    }
+
+    /// Shared body for `drain_*_messages` — read the slot's
+    /// string contents, split on newline, filter empty entries,
+    /// clear the slot to `""`.
+    fn drain_newline_blob(&mut self, var: &str) -> Vec<String> {
+        let raw = self
+            .worker
+            .eval(&format!("(if (string? {var}) {var} \"\")"))
+            .unwrap_or_default();
+        let _ = self.worker.eval(&format!("(set {var} \"\")"));
+        raw.lines()
+            .map(|s| s.to_string())
+            .filter(|s| !s.is_empty())
+            .collect()
+    }
+
     /// Read and clear the `harness-prompt-replace` slot. Set by plugins
     /// from `on-prompt` to rewrite the user turn before the agent runs.
     /// Distinct from `take_pending_prompt`, which carries the