feat: integrate AHP harness into SDK and core (v1.2.2)

- core: add `hook_executor` field to `SessionOptions` and `with_hook_executor()` builder
- core: `AgentSession` stores `ahp_executor`; `build_agent_loop()` prefers it over built-in `HookEngine`
- sdk/python: add `HarnessServer` class and `harness_server` field on `SessionOptions`; dispatch to `AhpHookExecutor::spawn()` in `build_rust_session_options()`
- sdk/node: add `HarnessServer` class and `harnessServer` field on `SessionOptions`; dispatch to `AhpHookExecutor::spawn()` in `js_session_options_to_rust()`
- both SDKs: depend on `a3s-ahp` crate for `AhpHookExecutor`

Author: RoyLin

core/src/agent_api.rs

@@ -166,6 +166,13 @@ pub struct SessionOptions {
     /// Users can customize role, guidelines, response style, and extra instructions
     /// without losing the core agentic capabilities.
     pub prompt_slots: Option<SystemPromptSlots>,
+    /// Optional external hook executor (e.g. an AHP harness server).
+    ///
+    /// When set, **replaces** the built-in `HookEngine` for this session.
+    /// All 11 lifecycle events are forwarded to the executor instead of being
+    /// dispatched locally. The executor is also propagated to sub-agents via
+    /// the sentinel hook mechanism.
+    pub hook_executor: Option<Arc<dyn crate::hooks::HookExecutor>>,
 }
 
 impl std::fmt::Debug for SessionOptions {
@@ -528,6 +535,19 @@ impl SessionOptions {
         self.prompt_slots = Some(slots);
         self
     }
+
+    /// Replace the built-in hook engine with an external hook executor.
+    ///
+    /// Use this to attach an AHP harness server (or any custom `HookExecutor`)
+    /// to the session. All lifecycle events will be forwarded to the executor
+    /// instead of the in-process `HookEngine`.
+    pub fn with_hook_executor(
+        mut self,
+        executor: Arc<dyn crate::hooks::HookExecutor>,
+    ) -> Self {
+        self.hook_executor = Some(executor);
+        self
+    }
 }
 
 // ============================================================================
@@ -1229,6 +1249,7 @@ impl Agent {
             session_store,
             auto_save: opts.auto_save,
             hook_engine: Arc::new(crate::hooks::HookEngine::new()),
+            ahp_executor: opts.hook_executor.clone(),
             init_warning,
             command_registry: std::sync::Mutex::new(command_registry),
             model_name: opts
@@ -1277,6 +1298,9 @@ pub struct AgentSession {
     auto_save: bool,
     /// Hook engine for lifecycle event interception.
     hook_engine: Arc<crate::hooks::HookEngine>,
+    /// Optional external hook executor (e.g. AHP harness). When set, replaces
+    /// `hook_engine` as the executor passed to each `AgentLoop`.
+    ahp_executor: Option<Arc<dyn crate::hooks::HookExecutor>>,
     /// Deferred init warning: emitted as PersistenceFailed on first send() if set.
     init_warning: Option<String>,
     /// Slash command registry for `/command` dispatch.
@@ -1314,8 +1338,13 @@ impl AgentSession {
     /// Propagates the lane queue (if configured) for external task handling.
     fn build_agent_loop(&self) -> AgentLoop {
         let mut config = self.config.clone();
-        config.hook_engine =
-            Some(Arc::clone(&self.hook_engine) as Arc<dyn crate::hooks::HookExecutor>);
+        config.hook_engine = Some(
+            if let Some(ref ahp) = self.ahp_executor {
+                ahp.clone()
+            } else {
+                Arc::clone(&self.hook_engine) as Arc<dyn crate::hooks::HookExecutor>
+            },
+        );
         // Always use live tool definitions so tools added via add_mcp_server() are visible
         // to the LLM. The config.tools snapshot taken at session creation misses dynamically
         // added MCP tools.

sdk/node/Cargo.toml

@@ -12,6 +12,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 a3s-code-core = { version = "1.0", path = "../../core" }
+a3s-ahp = { version = "0.1", path = "../../../ahp" }
 napi = { version = "2", features = ["async", "napi6", "serde-json"] }
 napi-derive = "2"
 tokio = { version = "1.35", features = ["full"] }

sdk/node/src/lib.rs

@@ -414,6 +414,40 @@ impl DefaultSecurityProvider {
     }
 }
 
+/// Plain shim for `HarnessServer` — used as the `SessionOptions.harnessServer` field type.
+#[napi(object)]
+#[derive(Clone, Default)]
+pub struct JsHarnessServer {
+    pub program: String,
+    pub args: Vec<String>,
+}
+
+/// External AHP harness server configuration.
+///
+/// Pass to `SessionOptions.harnessServer` to attach an external harness process
+/// that supervises every tool call and prompt in this session via JSON-RPC 2.0.
+///
+/// ```js
+/// agent.session('.', { harnessServer: new HarnessServer('python3', ['harness.py']) });
+/// ```
+#[napi]
+pub struct HarnessServer {
+    pub program: String,
+    pub args: Vec<String>,
+}
+
+#[napi]
+impl HarnessServer {
+    /// Create a harness server config.
+    ///
+    /// @param program - Executable to launch (e.g. "python3")
+    /// @param args    - Arguments passed to the executable (e.g. ["harness.py"])
+    #[napi(constructor)]
+    pub fn new(program: String, args: Vec<String>) -> Self {
+        Self { program, args }
+    }
+}
+
 // ============================================================================
 // SessionOptions
 // ============================================================================
@@ -500,6 +534,15 @@ pub struct SessionOptions {
     pub session_id: Option<String>,
     /// Automatically save the session to the configured store after each turn (default: false).
     pub auto_save: Option<bool>,
+    /// External AHP harness server.
+    ///
+    /// Pass `new HarnessServer("python3", ["harness.py"])` to attach an external
+    /// supervision process. The harness receives every `pre_tool_use` and `pre_prompt`
+    /// event and can return `block`, `skip`, `retry`, or `continue`.
+    /// ```js
+    /// agent.session('.', { harnessServer: new HarnessServer('python3', ['harness.py']) });
+    /// ```
+    pub harness_server: Option<JsHarnessServer>,
 }
 
 /// A single message in conversation history.
@@ -800,6 +843,19 @@ fn js_session_options_to_rust(options: Option<SessionOptions>) -> RustSessionOpt
     if o.auto_save.unwrap_or(false) {
         opts = opts.with_auto_save(true);
     }
+    if let Some(hs) = o.harness_server {
+        match get_runtime().block_on(a3s_ahp::AhpHookExecutor::spawn(
+            &hs.program,
+            hs.args.as_slice(),
+        )) {
+            Ok(executor) => {
+                opts = opts.with_hook_executor(executor);
+            }
+            Err(e) => {
+                eprintln!("a3s-code: AHP harness spawn failed: {e}");
+            }
+        }
+    }
     opts
 }
 

sdk/python/Cargo.toml

@@ -13,6 +13,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 a3s-code-core = { version = "1.0", path = "../../core" }
+a3s-ahp = { version = "0.1", path = "../../../ahp" }
 pyo3 = { version = "0.23", features = ["extension-module"] }
 tokio = { version = "1.35", features = ["full"] }
 serde_json = "1.0"

sdk/python/src/lib.rs

@@ -2795,6 +2795,19 @@ fn build_rust_session_options(so: PySessionOptions) -> RustSessionOptions {
     if so.auto_save {
         o = o.with_auto_save(true);
     }
+    if let Some(hs) = so.harness_server {
+        match get_runtime().block_on(a3s_ahp::AhpHookExecutor::spawn(
+            &hs.program,
+            hs.args.as_slice(),
+        )) {
+            Ok(executor) => {
+                o = o.with_hook_executor(executor);
+            }
+            Err(e) => {
+                eprintln!("a3s-code: AHP harness spawn failed: {e}");
+            }
+        }
+    }
     o
 }
 
@@ -4507,6 +4520,7 @@ fn a3s_code(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_class::<PyFileSessionStore>()?;
     m.add_class::<PyMemorySessionStore>()?;
     m.add_class::<PyDefaultSecurityProvider>()?;
+    m.add_class::<PyHarnessServer>()?;
     m.add_class::<PySessionOptions>()?;
     m.add_class::<PySessionQueueConfig>()?;
     m.add_class::<PySearchConfig>()?;