fix(claude): union-merged hook registration, session-boundary starts, and ask classification

json-upsert gains arrays="union" (exact-equality array union, default
stays replace) so the generated hook registration joins user-declared
hooks instead of clobbering them each materialization; SessionStart marks
the writer's session boundary; PermissionRequest classifies its ask kind
from tool_name (AskUserQuestion -> question, else permission); the
catalog resolves CATALOG-first in claude-observe.sh.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: schickling

examples/native/agent-claude.kdl

@@ -18,7 +18,7 @@ agent "<identity>" {
     copy "assets/bus.st2.md" ".st2/bus.md"
     ensure-line ".claude/rules/st2.md" "@../../.st2/PERSONA.md"
     ensure-line ".claude/rules/st2.md" "@../../.st2/bus.md"
-    json-upsert ".claude/settings.local.json" #"""
+    json-upsert ".claude/settings.local.json" arrays="union" #"""
 {
   "$schema": "https://json.schemastore.org/claude-code-settings.json",
   "hooks": {

src/catalog_transaction.rs

@@ -922,6 +922,7 @@ fn normalize_agent(spec: &agent_spec::AgentSpec) -> Result<BTreeMap<String, Sema
             RenderOp::JsonUpsert {
                 destination,
                 content,
+                arrays,
             } => {
                 insert_value(
                     &mut fields,
@@ -945,6 +946,14 @@ fn normalize_agent(spec: &agent_spec::AgentSpec) -> Result<BTreeMap<String, Sema
                     SemanticType::String,
                     &normalized,
                 );
+                if *arrays == crate::materialize::ArrayMerge::Union {
+                    insert_value(
+                        &mut fields,
+                        &format!("{root}/arrays"),
+                        SemanticType::String,
+                        "union",
+                    );
+                }
             }
             RenderOp::EnsureLine { destination, line } => {
                 insert_value(

src/claude_session.rs

@@ -15,7 +15,7 @@ use std::path::Path;
 
 use anyhow::{Context as _, Result};
 
-use crate::harness_state::{Activity, BlockedOn, InputBuffer, Observation};
+use crate::harness_state::{Activity, Ask, BlockedOn, InputBuffer, Observation};
 use crate::provider_session::{
     PROVIDER_POLL, STOP, SessionObserver, install_signal_handler, run_provider,
 };
@@ -75,8 +75,13 @@ pub fn run_observe(
         return Ok(());
     };
     let pty_session = runtime_id.unwrap_or(identity).to_string();
-    harness_state::Writer::new(&agent_dir, identity, "claude", Some(pty_session))
-        .observe(observation)
+    let mut writer = harness_state::Writer::new(&agent_dir, identity, "claude", Some(pty_session));
+    if event == "SessionStart" {
+        // The one event that names a session boundary: even if the new session's first state
+        // matches a fresh predecessor record, continuity must not be claimed across the restart.
+        writer.interrupt();
+    }
+    writer.observe(observation)
 }
 
 /// Map one Claude hook event to an observation, or `None` when the event says nothing about
@@ -117,10 +122,23 @@ pub fn observe_hook_event(event: &str, payload: &serde_json::Value) -> Option<Ob
             BlockedOn::None,
             InputBuffer::Unknown,
         )),
-        "PermissionRequest" => Some(
-            Observation::new(Activity::Active, BlockedOn::Human, InputBuffer::Unknown)
-                .with_reason("permissionRequest"),
-        ),
+        "PermissionRequest" => {
+            // Driver-side classification (#162): the payload's tool_name distinguishes Claude's
+            // question form from an ordinary permission prompt — the DQ-H1 captures show
+            // AskUserQuestion arriving as a PermissionRequest like any other tool.
+            let ask = if payload.get("tool_name").and_then(serde_json::Value::as_str)
+                == Some("AskUserQuestion")
+            {
+                Ask::Question
+            } else {
+                Ask::Permission
+            };
+            Some(
+                Observation::new(Activity::Active, BlockedOn::Human, InputBuffer::Unknown)
+                    .with_ask(ask)
+                    .with_reason("permissionRequest"),
+            )
+        }
         _ => None,
     }
 }
@@ -269,9 +287,14 @@ mod tests {
         let observer = SessionObserver::new(tmp.path(), "hetz.worker", "claude", "hetz.worker");
 
         // A hook process wrote a blocked observation between wrapper ticks.
-        harness_state::Writer::new(tmp.path(), "hetz.worker", "claude", None)
-            .observe(observe_hook_event("PermissionRequest", &serde_json::Value::Null).unwrap())
-            .unwrap();
+        harness_state::Writer::new(
+            tmp.path(),
+            "hetz.worker",
+            "claude",
+            Some("hetz.worker".to_string()),
+        )
+        .observe(observe_hook_event("PermissionRequest", &serde_json::Value::Null).unwrap())
+        .unwrap();
         let before = fs::read(&record).unwrap();
 
         std::thread::sleep(Duration::from_millis(2));
@@ -293,9 +316,14 @@ mod tests {
         let stop = AtomicBool::new(false);
 
         // A turn is in flight when the provider dies by signal.
-        harness_state::Writer::new(tmp.path(), "hetz.worker", "claude", None)
-            .observe(observe_hook_event("UserPromptSubmit", &serde_json::Value::Null).unwrap())
-            .unwrap();
+        harness_state::Writer::new(
+            tmp.path(),
+            "hetz.worker",
+            "claude",
+            Some("hetz.worker".to_string()),
+        )
+        .observe(observe_hook_event("UserPromptSubmit", &serde_json::Value::Null).unwrap())
+        .unwrap();
 
         let result = run_provider(
             "Claude",
@@ -337,4 +365,26 @@ mod tests {
         assert_eq!(observed.state, Activity::Ended);
         assert_eq!(observed.exit.as_deref(), Some("exit 0"));
     }
+
+    #[test]
+    fn permission_requests_classify_their_ask_kind_from_the_tool_name() {
+        use crate::harness_state::Ask;
+        let permission = observe_hook_event(
+            "PermissionRequest",
+            &serde_json::json!({ "tool_name": "Bash", "tool_input": {} }),
+        )
+        .unwrap();
+        assert_eq!(permission.ask, Ask::Permission);
+
+        let question = observe_hook_event(
+            "PermissionRequest",
+            &serde_json::json!({ "tool_name": "AskUserQuestion", "tool_input": {} }),
+        )
+        .unwrap();
+        assert_eq!(question.ask, Ask::Question);
+
+        // Non-blocking events carry no ask.
+        let idle = observe_hook_event("Stop", &serde_json::json!({})).unwrap();
+        assert_eq!(idle.ask, Ask::None);
+    }
 }

src/driver.rs

@@ -125,10 +125,18 @@ fn expand_claude(driver: &ClaudeDriver, bus_id: &str) -> Result<KdlDocument> {
     let mut render = KdlNode::new("render");
     render.set_children(document([
         node("json-upsert", vec![".mcp.json".to_string(), mcp]),
-        node(
-            "json-upsert",
-            vec![".claude/settings.local.json".to_string(), settings],
-        ),
+        {
+            // Hook arrays join whatever the workspace already declares: replacement would clobber
+            // user-registered hooks on every materialization, and union is idempotent.
+            let mut upsert = node(
+                "json-upsert",
+                vec![".claude/settings.local.json".to_string(), settings],
+            );
+            upsert
+                .entries_mut()
+                .push(KdlEntry::new_prop("arrays", "union"));
+            upsert
+        },
     ]));
 
     let mut provider = vec!["claude".to_string()];

src/hooks.rs

@@ -582,6 +582,9 @@ mod tests {
                 let mut entries = node
                     .entries()
                     .iter()
+                    // Positional arguments only: properties (e.g. `arrays="union"`) are merge
+                    // strategy, not payload.
+                    .filter(|entry| entry.name().is_none())
                     .filter_map(|entry| match entry.value() {
                         kdl::KdlValue::String(value) => Some(value.as_str()),
                         _ => None,

src/materialize.rs

@@ -26,6 +26,7 @@ pub enum RenderOp {
     JsonUpsert {
         destination: String,
         content: String,
+        arrays: ArrayMerge,
     },
     EnsureLine {
         destination: String,
@@ -36,6 +37,17 @@ pub enum RenderOp {
     },
 }
 
+/// How a json-upsert treats an array both sides declare. `Replace` is the default and the
+/// original contract; `union` appends patch elements the target lacks (exact-equality dedupe), so
+/// registrations can join arrays other owners also write — user-declared entries survive and
+/// re-materialization is idempotent.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum ArrayMerge {
+    #[default]
+    Replace,
+    Union,
+}
+
 #[derive(Debug, Clone, PartialEq, Eq, Default)]
 pub struct RenderPlan {
     pub ops: Vec<RenderOp>,
@@ -68,6 +80,7 @@ impl RenderOp {
             | Self::JsonUpsert {
                 destination,
                 content,
+                ..
             } => {
                 references_variable(destination, variable) || references_variable(content, variable)
             }
@@ -162,9 +175,22 @@ fn parse_render_node(node: &KdlNode, agent: &str) -> Result<RenderPlan> {
                 serde_json::from_str::<serde_json::Value>(&content).with_context(|| {
                     format!("agent '{agent}': json-upsert content is not valid JSON")
                 })?;
+                let arrays = match directive
+                    .entries()
+                    .iter()
+                    .find(|entry| entry.name().is_some_and(|name| name.value() == "arrays"))
+                    .and_then(|entry| entry.value().as_string())
+                {
+                    None | Some("replace") => ArrayMerge::Replace,
+                    Some("union") => ArrayMerge::Union,
+                    Some(other) => anyhow::bail!(
+                        "agent '{agent}': json-upsert arrays=\"{other}\" (expected replace|union)"
+                    ),
+                };
                 plan.ops.push(RenderOp::JsonUpsert {
                     destination: destination.clone(),
                     content,
+                    arrays,
                 });
             }
             "ensure-line" => {
@@ -267,6 +293,7 @@ fn resolve_driver_render_executable(plan: &mut RenderPlan, agent: &str) -> Resul
         let RenderOp::JsonUpsert {
             destination,
             content,
+            ..
         } = operation
         else {
             continue;
@@ -312,6 +339,7 @@ fn effective_plan(root: &Path, spec: &AgentSpec, this_host: &str) -> Result<Rend
         plan.ops.push(RenderOp::JsonUpsert {
             destination: ".mcp.json".into(),
             content,
+            arrays: ArrayMerge::Replace,
         });
     }
     Ok(plan)
@@ -466,18 +494,27 @@ fn ensure_line(path: &Path, line: &str) -> Result<bool> {
     Ok(true)
 }
 
-fn deep_merge(target: &mut serde_json::Value, patch: serde_json::Value) {
+fn deep_merge(target: &mut serde_json::Value, patch: serde_json::Value, arrays: ArrayMerge) {
     match (target, patch) {
         (serde_json::Value::Object(target), serde_json::Value::Object(patch)) => {
             for (key, value) in patch {
                 match target.get_mut(&key) {
-                    Some(existing) => deep_merge(existing, value),
+                    Some(existing) => deep_merge(existing, value, arrays),
                     None => {
                         target.insert(key, value);
                     }
                 }
             }
         }
+        (serde_json::Value::Array(target), serde_json::Value::Array(patch))
+            if arrays == ArrayMerge::Union =>
+        {
+            for element in patch {
+                if !target.contains(&element) {
+                    target.push(element);
+                }
+            }
+        }
         (target, patch) => *target = patch,
     }
 }
@@ -563,7 +600,7 @@ enum PreparedOp {
 #[derive(Debug, Clone, PartialEq)]
 enum RenderClaim {
     Replace(Vec<u8>),
-    JsonUpsert(serde_json::Value),
+    JsonUpsert(serde_json::Value, ArrayMerge),
     EnsureLine(String),
 }
 
@@ -627,6 +664,7 @@ fn claims_for_agent(
             RenderOp::JsonUpsert {
                 destination: raw_destination,
                 content,
+                arrays,
             } => {
                 let patch = serde_json::from_str(&expand(&content, &env)).with_context(|| {
                     format!(
@@ -636,7 +674,7 @@ fn claims_for_agent(
                 })?;
                 (
                     destination(&workspace, &raw_destination, &env)?,
-                    RenderClaim::JsonUpsert(patch),
+                    RenderClaim::JsonUpsert(patch, arrays),
                 )
             }
             RenderOp::EnsureLine {
@@ -784,6 +822,7 @@ pub fn materialize_agent(root: &Path, spec: &AgentSpec, this_host: &str) -> Resu
             RenderOp::JsonUpsert {
                 destination: raw_destination,
                 content,
+                arrays,
             } => {
                 let destination = destination(&workspace, &raw_destination, &env)?;
                 let current = virtual_files
@@ -804,7 +843,7 @@ pub fn materialize_agent(root: &Path, spec: &AgentSpec, this_host: &str) -> Resu
                             spec.identity
                         )
                     })?;
-                deep_merge(&mut target, patch);
+                deep_merge(&mut target, patch, arrays);
                 let mut bytes = serde_json::to_vec_pretty(&target)?;
                 bytes.push(b'\n');
                 let note = format!("{}: upserted {}", spec.identity, raw_destination);
@@ -1056,6 +1095,7 @@ mod tests {
                 "nested": {"right": 2, "replace": "new"},
                 "array": [2]
             }),
+            ArrayMerge::Replace,
         );
         assert_eq!(
             target,
@@ -1066,4 +1106,27 @@ mod tests {
             })
         );
     }
+
+    /// Union mode joins arrays idempotently: foreign entries survive and repeating the same
+    /// patch adds nothing — the contract the generated hook registration relies on.
+    #[test]
+    fn deep_merge_union_preserves_foreign_array_entries_and_is_idempotent() {
+        let mut target = serde_json::json!({
+            "hooks": {"Stop": [{"hooks": [{"type": "command", "command": "user-audit.sh"}]}]}
+        });
+        let ours = serde_json::json!({
+            "hooks": {"Stop": [{"hooks": [{"type": "command", "command": "$ST_HOOKS/claude-observe.sh Stop"}]}]}
+        });
+        deep_merge(&mut target, ours.clone(), ArrayMerge::Union);
+        deep_merge(&mut target, ours, ArrayMerge::Union);
+        assert_eq!(
+            target,
+            serde_json::json!({
+                "hooks": {"Stop": [
+                    {"hooks": [{"type": "command", "command": "user-audit.sh"}]},
+                    {"hooks": [{"type": "command", "command": "$ST_HOOKS/claude-observe.sh Stop"}]}
+                ]}
+            })
+        );
+    }
 }

tests/fixtures/driver/claude.out.kdl

@@ -1,5 +1,5 @@
 render {
     json-upsert .mcp.json "{\n  \"mcpServers\": {\n    \"st2\": {\n      \"args\": [\n        \"--catalog\",\n        \"$CATALOG\",\n        \"driver\",\n        \"claude-mcp\",\n        \"--identity\",\n        \"Silber.fabric\"\n      ],\n      \"command\": \"st2\",\n      \"type\": \"stdio\"\n    }\n  }\n}"
-    json-upsert ".claude/settings.local.json" "{\n  \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n  \"hooks\": {\n    \"PermissionRequest\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh PermissionRequest\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"PostToolUse\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh PostToolUse\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"PreCompact\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-pre-compact.sh\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"PreToolUse\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh PreToolUse\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"async\": true,\n            \"asyncRewake\": true,\n            \"command\": \"$ST_HOOKS/claude-session-start.sh\",\n            \"type\": \"command\"\n          },\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh SessionStart\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"Stop\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh Stop\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"StopFailure\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-stop-failure.sh\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh UserPromptSubmit\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ]\n  }\n}"
+    json-upsert ".claude/settings.local.json" "{\n  \"$schema\": \"https://json.schemastore.org/claude-code-settings.json\",\n  \"hooks\": {\n    \"PermissionRequest\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh PermissionRequest\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"PostToolUse\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh PostToolUse\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"PreCompact\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-pre-compact.sh\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"PreToolUse\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh PreToolUse\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"SessionStart\": [\n      {\n        \"hooks\": [\n          {\n            \"async\": true,\n            \"asyncRewake\": true,\n            \"command\": \"$ST_HOOKS/claude-session-start.sh\",\n            \"type\": \"command\"\n          },\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh SessionStart\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"Stop\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh Stop\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"StopFailure\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-stop-failure.sh\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ],\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [\n          {\n            \"command\": \"$ST_HOOKS/claude-observe.sh UserPromptSubmit\",\n            \"type\": \"command\"\n          }\n        ]\n      }\n    ]\n  }\n}" arrays=union
 }
 argv st2 --catalog $CATALOG driver claude-session --identity Silber.fabric --runtime-id Silber.fabric -- claude --model opus --effort xhigh "--dangerously-load-development-channels=server:st2" --permission-mode bypassPermissions --model override "Start the assigned work."