@hassangameryt/freeflow 0.4.0 → 0.6.0

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "Load Freeflow runtime context at session start.",
+  "description": "Load Freeflow runtime context and manage session mode.",
   "hooks": {
     "SessionStart": [
       {
@@ -13,6 +13,31 @@
           }
         ]
       }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT}}/hooks/freeflow-runtime-context.mjs\" UserPromptSubmit",
+            "timeout": 5,
+            "statusMessage": "Checking Freeflow mode"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT}}/hooks/freeflow-runtime-context.mjs\" SessionEnd",
+            "timeout": 3,
+            "statusMessage": "Preserving Freeflow mode"
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/tests/check-runtime-context-hook.sh

@@ -1,10 +1,12 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-ROOT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)"
+ROOT_DIR="$(CDPATH='' cd -- "$(dirname -- "$0")/../.." && pwd)"
 HOOK_PATH="$ROOT_DIR/hooks/freeflow-runtime-context.mjs"
 HOOKS_JSON="$ROOT_DIR/hooks/hooks.json"
-WORKFLOW_SKILL="$ROOT_DIR/skills/workflow/SKILL.md"
+CORE_PROMPT="$ROOT_DIR/runtime/prompts/core.md"
+INTERACTION_PROMPT="$ROOT_DIR/runtime/prompts/interaction-contract.md"
+SKILLS_PROMPT="$ROOT_DIR/runtime/prompts/skills.md"
 
 fail() {
 	echo "runtime-context hook check failed: $*" >&2
@@ -29,18 +31,20 @@ assert_not_contains() {
 
 [[ -f "$HOOK_PATH" ]] || fail "missing hook script"
 [[ -f "$HOOKS_JSON" ]] || fail "missing hooks manifest"
-[[ -f "$WORKFLOW_SKILL" ]] || fail "missing canonical Workflow skill"
-workflow_owner_line="$(grep -m1 '^The active agent owns ' "$WORKFLOW_SKILL" || true)"
-workflow_self_review_line="$(grep -m1 '^Self-review is silent ' "$WORKFLOW_SKILL" || true)"
-[[ -n "$workflow_owner_line" ]] || fail "canonical Workflow owner sentinel missing"
-[[ -n "$workflow_self_review_line" ]] || fail "canonical Workflow self-review sentinel missing"
+for prompt_file in "$CORE_PROMPT" "$INTERACTION_PROMPT" "$SKILLS_PROMPT"; do
+	[[ -f "$prompt_file" ]] || fail "missing runtime prompt fragment: $prompt_file"
+done
 node --check "$HOOK_PATH"
 node -e '
 const fs = require("fs");
 const hooks = JSON.parse(fs.readFileSync(process.argv[1], "utf8")).hooks || {};
 if (!Array.isArray(hooks.SessionStart) || hooks.SessionStart.length === 0) process.exit(1);
 if (hooks.SessionStart[0]?.matcher !== "startup|resume|clear|compact") process.exit(1);
-' "$HOOKS_JSON" || fail "hooks.json does not register the expected SessionStart lifecycle matcher"
+if (!Array.isArray(hooks.UserPromptSubmit) || hooks.UserPromptSubmit.length !== 1) process.exit(1);
+if (hooks.UserPromptSubmit[0]?.matcher != null) process.exit(1);
+if (!Array.isArray(hooks.SessionEnd) || hooks.SessionEnd.length !== 1) process.exit(1);
+if (hooks.SessionEnd[0]?.matcher !== "clear") process.exit(1);
+' "$HOOKS_JSON" || fail "hooks.json does not register the expected non-overlapping runtime events"
 
 tmp_dir="$(mktemp -d)"
 trap 'rm -rf "$tmp_dir"' EXIT
@@ -57,45 +61,207 @@ user_prompt_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$tmp_dir" | node
 [[ -z "$user_prompt_output" ]] || fail "UserPromptSubmit should not duplicate session-start runtime context"
 
 for expected in \
-	"# Freeflow Runtime Context" \
-	'Setup status: configured by `.freeflow/config.json`' \
-	"Runtime delivery: confirmed for this lifecycle-hook invocation." \
+	'"hookEventName":"SessionStart"' \
+	"# Freeflow Stable Guidance" \
+	"## Mode" \
+	"## Shared Terms" \
+	"## Three Nested Loops" \
+	"## Workflow Cue" \
+	"## Action Selection Cue" \
+	"## Supported Exit" \
 	"# Freeflow Interaction Contract" \
-	"Answer questions without inferring action." \
-	"# Freeflow Workflow Bootstrap" \
-	"Use feedback to choose the smallest useful next action." \
-	"$workflow_owner_line" \
-	"$workflow_self_review_line" \
-	'Current Freeflow default mode: `workflow`.' \
+	"Treat questions, criticism, examples, hypotheses, and tentative ideas as" \
+	'Configured default: `workflow` (repository)' \
+	'Effective mode: `workflow` (configured default, active)' \
 	'Interaction Contract: enabled' \
-	'Skills: enabled' \
-	'Output router: disabled'; do
+	'Skills: enabled'; do
 	assert_contains "$codex_output" "$expected" "Codex config-only context"
 done
+assert_not_contains "$codex_output" "Output Router" "Codex host context"
+assert_not_contains "$codex_output" "Output router:" "Codex host context"
+
+# The Pi-only capability key is tolerated by shared host validators but is not
+# injected into Codex or Claude runtime context.
+cognitive_dir="$(mktemp -d)"
+mkdir -p "$cognitive_dir/.freeflow"
+printf '{"defaultMode":"workflow","cognitiveRouting":{"enabled":true,"profiles":{"standard":{"provider":"faux","model":"standard","thinkingLevel":"high"},"reasoning":{"provider":"faux","model":"reasoning","thinkingLevel":"max"}}}}\n' >"$cognitive_dir/.freeflow/config.json"
+cognitive_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$cognitive_dir" | node "$HOOK_PATH" SessionStart)"
+assert_contains "$cognitive_output" "# Freeflow Stable Guidance" "Pi-only capability tolerance"
+assert_not_contains "$cognitive_output" "Cognitive Routing" "non-Pi capability isolation"
+rm -rf "$cognitive_dir"
 for excluded_heading in \
 	"# Freeflow Runtime Kernel" \
 	"## Freeflow Runtime Priority" \
 	"## Loaded Mode Contract Skill" \
 	"## Loaded Workflow Skill" \
 	"## Loaded Decision Gate Skill" \
+	"# Freeflow Workflow Bootstrap" \
 	"## Discovery-light" \
 	"## Loaded Output Router Skill"; do
 	assert_not_contains "$codex_output" "$excluded_heading" "default context"
 done
-workflow_bootstrap_count="$(grep -Fo '# Freeflow Workflow Bootstrap' <<<"$codex_output" | wc -l | tr -d ' ')"
-[[ "$workflow_bootstrap_count" == "1" ]] || fail "Codex SessionStart should load Workflow exactly once"
+skills_prompt_count="$(grep -Fo '## Shared Terms' <<<"$codex_output" | wc -l | tr -d ' ')"
+[[ "$skills_prompt_count" == "1" ]] || fail "Codex SessionStart should load the Skills prompt exactly once"
 assert_not_contains "$codex_output" "## Conversation Mode Boundary" "workflow context"
 assert_not_contains "$codex_output" "## Strict Workflow Overlay" "workflow context"
 
 claude_output="$(printf '{"hook_event_name":"SessionStart","source":"startup","cwd":"%s"}\n' "$tmp_dir" | node "$HOOK_PATH" SessionStart)"
 assert_contains "$claude_output" '"hookEventName":"SessionStart"' "Claude wrapper"
 assert_contains "$claude_output" "# Freeflow Interaction Contract" "Claude config-only context"
-assert_contains "$claude_output" "# Freeflow Workflow Bootstrap" "Claude first-turn context"
-assert_contains "$claude_output" "Answer questions without inferring action." "Claude config-only context"
+assert_contains "$claude_output" "## Shared Terms" "Claude skills context"
+assert_not_contains "$claude_output" "# Freeflow Workflow Bootstrap" "Claude first-turn context"
+assert_contains "$claude_output" "Treat questions, criticism, examples, hypotheses, and tentative ideas as" "Claude config-only context"
+
+# Session mode changes are host-managed state: they apply before the same model request,
+# survive lifecycle restoration, remain isolated by session id, and never edit repo config.
+session_data_dir="$(mktemp -d)"
+session_id="session/with unsafe path characters"
+config_before="$(shasum -a 256 "$tmp_dir/.freeflow/config.json" | awk '{print $1}')"
+mode_change_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"%s","cwd":"%s","prompt":"Switch to conversation mode."}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
+assert_contains "$mode_change_output" '"hookEventName":"UserPromptSubmit"' "same-turn mode change wrapper"
+assert_contains "$mode_change_output" '# Freeflow Runtime State' "same-turn mode change"
+assert_contains "$mode_change_output" 'Session override: `conversation`' "same-turn mode change"
+assert_contains "$mode_change_output" 'Effective mode: `conversation` (session override, active)' "same-turn mode change"
+assert_not_contains "$mode_change_output" "# Freeflow Mode Update" "same-turn mode change"
+assert_not_contains "$mode_change_output" "## Conversation Mode Boundary" "same-turn mode change"
+assert_not_contains "$mode_change_output" "Do not call write, edit, or mutating tools" "same-turn mode change"
+
+restored_mode_output="$(printf '{"hook_event_name":"SessionStart","source":"compact","session_id":"%s","cwd":"%s","model":"gpt-5"}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" SessionStart)"
+assert_contains "$restored_mode_output" 'Configured default: `workflow` (repository)' "restored session mode"
+assert_contains "$restored_mode_output" 'Session override: `conversation`' "restored session mode"
+assert_contains "$restored_mode_output" 'Effective mode: `conversation` (session override, active)' "restored session mode"
+
+other_session_output="$(printf '{"hook_event_name":"SessionStart","source":"resume","session_id":"other-session","cwd":"%s","model":"gpt-5"}\n' "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" SessionStart)"
+assert_contains "$other_session_output" 'Session override: none' "session mode isolation"
+assert_contains "$other_session_output" 'Effective mode: `workflow` (configured default, active)' "session mode isolation"
+
+ordinary_prompt_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"%s","cwd":"%s","prompt":"Please explain this function."}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
+[[ -z "$ordinary_prompt_output" ]] || fail "ordinary prompts should not duplicate runtime context"
+question_prompt_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"%s","cwd":"%s","prompt":"Should we switch to strict-workflow mode?"}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
+[[ -z "$question_prompt_output" ]] || fail "mode questions should not mutate session state"
+hypothetical_prompt_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"%s","cwd":"%s","prompt":"Suppose the mode were workflow."}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
+[[ -z "$hypothetical_prompt_output" ]] || fail "mode hypotheticals should not mutate session state"
+default_prompt_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"%s","cwd":"%s","prompt":"Change the default mode to strict-workflow."}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
+[[ -z "$default_prompt_output" ]] || fail "default-mode requests should remain agent-routed configuration decisions"
+
+native_change_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"%s","cwd":"%s","prompt":"$mode-contract strict-workflow"}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
+assert_contains "$native_change_output" '# Freeflow Runtime State' "Codex native skill mode control"
+assert_contains "$native_change_output" 'Session override: `strict-workflow`' "Codex native skill mode control"
+assert_not_contains "$native_change_output" "# Freeflow Mode Update" "Codex native skill mode control"
+assert_not_contains "$native_change_output" "## Strict Workflow Overlay" "Codex native skill mode control"
+
+claude_data_dir="$(mktemp -d)"
+claude_mode_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"claude-session","cwd":"%s","prompt":"/freeflow:mode-contract conversation"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
+assert_contains "$claude_mode_output" '"hookEventName":"UserPromptSubmit"' "Claude native skill mode control"
+assert_contains "$claude_mode_output" 'Session override: `conversation`' "Claude native skill mode control"
+claude_restored_output="$(printf '{"hook_event_name":"SessionStart","source":"resume","session_id":"claude-session","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" node "$HOOK_PATH" SessionStart)"
+assert_contains "$claude_restored_output" 'Effective mode: `conversation` (session override, active)' "Claude restored session mode"
+
+# Claude /clear ends one session and starts another. SessionEnd transfers only the
+# active override for this host process/workspace, and SessionStart consumes it exactly once.
+claude_clear_end_output="$(printf '{"hook_event_name":"SessionEnd","reason":"clear","session_id":"claude-session","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-a" node "$HOOK_PATH" SessionEnd)"
+[[ -z "$claude_clear_end_output" ]] || fail "SessionEnd clear should not emit model context"
+claude_clear_output="$(printf '{"hook_event_name":"SessionStart","source":"clear","session_id":"claude-session-after-clear","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-a" node "$HOOK_PATH" SessionStart)"
+assert_contains "$claude_clear_output" 'Session override: `conversation`' "Claude clear session transfer"
+assert_contains "$claude_clear_output" 'Effective mode: `conversation` (session override, active)' "Claude clear session transfer"
+claude_unrelated_output="$(printf '{"hook_event_name":"SessionStart","source":"startup","session_id":"claude-unrelated-session","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" node "$HOOK_PATH" SessionStart)"
+assert_contains "$claude_unrelated_output" 'Session override: none' "Claude clear transfer isolation"
+claude_second_clear_output="$(printf '{"hook_event_name":"SessionStart","source":"clear","session_id":"claude-second-clear","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" node "$HOOK_PATH" SessionStart)"
+assert_contains "$claude_second_clear_output" 'Session override: none' "Claude clear transfer one-shot consumption"
+
+# A stale clear handoff is consumed without applying it.
+claude_stale_mode_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"claude-stale-source","cwd":"%s","prompt":"Switch to strict-workflow mode."}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
+assert_contains "$claude_stale_mode_output" 'Session override: `strict-workflow`' "Claude stale clear setup"
+printf '{"hook_event_name":"SessionEnd","reason":"clear","session_id":"claude-stale-source","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-stale" node "$HOOK_PATH" SessionEnd >/dev/null
+clear_transfer_file="$(find "$claude_data_dir/session-modes/claude-clear" -type f -name '*.json' -print -quit)"
+node - "$clear_transfer_file" <<'NODE'
+const fs = require("fs");
+const path = process.argv[2];
+const state = JSON.parse(fs.readFileSync(path, "utf8"));
+state.createdAt = new Date(Date.now() - 120000).toISOString();
+fs.writeFileSync(path, `${JSON.stringify(state)}\n`);
+NODE
+claude_stale_clear_output="$(printf '{"hook_event_name":"SessionStart","source":"clear","session_id":"claude-stale-target","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-stale" node "$HOOK_PATH" SessionStart)"
+assert_contains "$claude_stale_clear_output" 'Session override: none' "Claude stale clear transfer"
+[[ ! -e "$clear_transfer_file" ]] || fail "stale Claude clear transfer should be consumed"
+
+# Malformed plugin-owned transfer content fails closed without suppressing the
+# normal SessionStart context and is consumed rather than retried forever.
+printf '{"hook_event_name":"SessionEnd","reason":"clear","session_id":"claude-stale-source","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-malformed" node "$HOOK_PATH" SessionEnd >/dev/null
+malformed_transfer_file="$(find "$claude_data_dir/session-modes/claude-clear" -type f -name '*.json' -print -quit)"
+printf 'null\n' >"$malformed_transfer_file"
+claude_malformed_clear_output="$(printf '{"hook_event_name":"SessionStart","source":"clear","session_id":"claude-malformed-target","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-malformed" node "$HOOK_PATH" SessionStart)"
+assert_contains "$claude_malformed_clear_output" '# Freeflow Stable Guidance' "Claude malformed clear transfer"
+assert_contains "$claude_malformed_clear_output" 'Session override: none' "Claude malformed clear transfer"
+[[ ! -e "$malformed_transfer_file" ]] || fail "malformed Claude clear transfer should be consumed"
+
+# Overlapping clears in one workspace remain isolated by the host process ID.
+printf '{"hook_event_name":"UserPromptSubmit","session_id":"claude-overlap-a","cwd":"%s","prompt":"Switch to conversation mode."}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" node "$HOOK_PATH" UserPromptSubmit >/dev/null
+printf '{"hook_event_name":"UserPromptSubmit","session_id":"claude-overlap-b","cwd":"%s","prompt":"Switch to strict-workflow mode."}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" node "$HOOK_PATH" UserPromptSubmit >/dev/null
+printf '{"hook_event_name":"SessionEnd","reason":"clear","session_id":"claude-overlap-a","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-overlap-a" node "$HOOK_PATH" SessionEnd >/dev/null
+printf '{"hook_event_name":"SessionEnd","reason":"clear","session_id":"claude-overlap-b","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-overlap-b" node "$HOOK_PATH" SessionEnd >/dev/null
+claude_overlap_b_output="$(printf '{"hook_event_name":"SessionStart","source":"clear","session_id":"claude-overlap-b-new","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-overlap-b" node "$HOOK_PATH" SessionStart)"
+assert_contains "$claude_overlap_b_output" 'Session override: `strict-workflow`' "Claude overlapping clear B"
+claude_overlap_a_output="$(printf '{"hook_event_name":"SessionStart","source":"clear","session_id":"claude-overlap-a-new","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-overlap-a" node "$HOOK_PATH" SessionStart)"
+assert_contains "$claude_overlap_a_output" 'Session override: `conversation`' "Claude overlapping clear A"
+
+# A no-override clear removes any stale transfer for the same process/workspace.
+printf '{"hook_event_name":"SessionEnd","reason":"clear","session_id":"claude-no-override","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-overlap-a" node "$HOOK_PATH" SessionEnd >/dev/null
+claude_no_override_clear_output="$(printf '{"hook_event_name":"SessionStart","source":"clear","session_id":"claude-no-override-new","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-overlap-a" node "$HOOK_PATH" SessionStart)"
+assert_contains "$claude_no_override_clear_output" 'Session override: none' "Claude no-override clear"
+
+# Transfer consumption claims the handoff atomically: two concurrent starts can
+# never both receive the same override.
+printf '{"hook_event_name":"SessionEnd","reason":"clear","session_id":"claude-overlap-b-new","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-race" node "$HOOK_PATH" SessionEnd >/dev/null
+race_output_a="$(mktemp)"
+race_output_b="$(mktemp)"
+printf '{"hook_event_name":"SessionStart","source":"clear","session_id":"claude-race-a","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-race" node "$HOOK_PATH" SessionStart >"$race_output_a" &
+race_pid_a=$!
+printf '{"hook_event_name":"SessionStart","source":"clear","session_id":"claude-race-b","cwd":"%s"}\n' "$tmp_dir" | CLAUDE_PLUGIN_DATA="$claude_data_dir" CLAUDE_PID="claude-process-race" node "$HOOK_PATH" SessionStart >"$race_output_b" &
+race_pid_b=$!
+wait "$race_pid_a" "$race_pid_b"
+race_override_count="$(grep -Fh 'Session override: `strict-workflow`' "$race_output_a" "$race_output_b" | wc -l | tr -d ' ')"
+[[ "$race_override_count" == "1" ]] || fail "Claude clear transfer should have exactly one concurrent consumer"
+rm -f "$race_output_a" "$race_output_b"
+
+# Codex currently reports SessionEnd reason=other, so it must never stage a
+# Claude-style clear handoff.
+codex_clear_data_dir="$(mktemp -d)"
+printf '{"hook_event_name":"UserPromptSubmit","session_id":"codex-source","cwd":"%s","prompt":"Switch to conversation mode."}\n' "$tmp_dir" | PLUGIN_DATA="$codex_clear_data_dir" node "$HOOK_PATH" UserPromptSubmit >/dev/null
+printf '{"hook_event_name":"SessionEnd","reason":"other","session_id":"codex-source","cwd":"%s"}\n' "$tmp_dir" | PLUGIN_DATA="$codex_clear_data_dir" node "$HOOK_PATH" SessionEnd >/dev/null
+if [[ -d "$codex_clear_data_dir/session-modes/claude-clear" ]]; then
+	fail "Codex SessionEnd should not stage Claude clear state"
+fi
+rm -rf "$codex_clear_data_dir" "$claude_data_dir"
+
+reset_output="$(printf '{"hook_event_name":"UserPromptSubmit","session_id":"%s","cwd":"%s","prompt":"Reset the session mode."}\n' "$session_id" "$tmp_dir" | PLUGIN_DATA="$session_data_dir" node "$HOOK_PATH" UserPromptSubmit)"
+assert_contains "$reset_output" 'Session override: cleared' "session mode reset"
+assert_contains "$reset_output" 'Effective mode: `workflow` (configured default, active)' "session mode reset"
+config_after="$(shasum -a 256 "$tmp_dir/.freeflow/config.json" | awk '{print $1}')"
+[[ "$config_before" == "$config_after" ]] || fail "session mode controls modified repository config"
+if find "$session_data_dir" -type f -print | grep -Fq "$session_id"; then
+	fail "raw session id leaked into the session-state path"
+fi
+rm -rf "$session_data_dir"
 
 for source in startup resume clear compact; do
-	event_output="$(printf '{"hook_event_name":"SessionStart","source":"%s","cwd":"%s","model":"gpt-5"}\n' "$source" "$tmp_dir" | node "$HOOK_PATH" SessionStart)"
-	assert_contains "$event_output" "# Freeflow Interaction Contract" "$source SessionStart context"
+	codex_event_output="$(printf '{"hook_event_name":"SessionStart","source":"%s","cwd":"%s","model":"gpt-5"}\n' "$source" "$tmp_dir" | node "$HOOK_PATH" SessionStart)"
+	claude_event_output="$(printf '{"hook_event_name":"SessionStart","source":"%s","cwd":"%s"}\n' "$source" "$tmp_dir" | node "$HOOK_PATH" SessionStart)"
+	for host in codex claude; do
+		if [[ "$host" == "codex" ]]; then
+			event_output="$codex_event_output"
+		else
+			event_output="$claude_event_output"
+			assert_contains "$event_output" '"hookEventName":"SessionStart"' "Claude $source wrapper"
+		fi
+		assert_contains "$event_output" "# Freeflow Interaction Contract" "$host $source SessionStart context"
+		assert_contains "$event_output" "## Shared Terms" "$host $source SessionStart context"
+		contract_count="$(grep -Fo '# Freeflow Interaction Contract' <<<"$event_output" | wc -l | tr -d ' ')"
+		skills_count="$(grep -Fo '## Shared Terms' <<<"$event_output" | wc -l | tr -d ' ')"
+		[[ "$contract_count" == "1" ]] || fail "$host $source SessionStart should load the Interaction Contract exactly once"
+		[[ "$skills_count" == "1" ]] || fail "$host $source SessionStart should load the Skills prompt exactly once"
+		assert_not_contains "$event_output" "# Freeflow Workflow Bootstrap" "$host $source SessionStart context"
+	done
 done
 
 # Repo-owned host instructions are neither required for activation nor modified by the read-only hook.
@@ -124,23 +290,23 @@ mkdir -p "$local_dir/.freeflow"
 printf '{"defaultMode":"workflow"}\n' >"$local_dir/.freeflow/config.json"
 printf '{"defaultMode":"strict-workflow"}\n' >"$local_dir/.freeflow/local.json"
 local_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$local_dir" | node "$HOOK_PATH" SessionStart)"
-assert_contains "$local_output" 'Current Freeflow default mode: `strict-workflow`.' "local default override"
-assert_contains "$local_output" 'defaultMode `strict-workflow` from local' "local default source"
-assert_contains "$local_output" "## Strict Workflow Overlay" "local strict overlay"
-assert_contains "$local_output" "security, privacy, billing, data loss, migrations, public interfaces" "local strict overlay"
+assert_contains "$local_output" 'Configured default: `strict-workflow` (personal)' "local default override"
+assert_contains "$local_output" 'Effective mode: `strict-workflow` (configured default, active)' "local default source"
+assert_not_contains "$local_output" "## Strict Workflow Overlay" "local strict overlay"
+assert_not_contains "$local_output" "security, privacy, billing, data loss, migrations, public interfaces" "local strict overlay"
 assert_contains "$local_output" "# Freeflow Interaction Contract" "local default override"
-assert_contains "$local_output" "# Freeflow Workflow Bootstrap" "local default override"
+assert_contains "$local_output" "## Shared Terms" "local default override"
 rm -rf "$local_dir"
 
 local_interaction_dir="$(mktemp -d)"
 mkdir -p "$local_interaction_dir/.freeflow"
-printf '{"defaultMode":"workflow"}\n' > "$local_interaction_dir/.freeflow/config.json"
-printf '{"interactionContract":false}\n' > "$local_interaction_dir/.freeflow/local.json"
+printf '{"defaultMode":"workflow"}\n' >"$local_interaction_dir/.freeflow/config.json"
+printf '{"interactionContract":false}\n' >"$local_interaction_dir/.freeflow/local.json"
 local_interaction_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$local_interaction_dir" | node "$HOOK_PATH" SessionStart)"
 assert_contains "$local_interaction_output" 'Interaction Contract: disabled' "independent local interaction override"
 assert_contains "$local_interaction_output" 'Skills: enabled' "independent local interaction override"
 assert_not_contains "$local_interaction_output" "# Freeflow Interaction Contract" "independent local interaction override"
-assert_contains "$local_interaction_output" "# Freeflow Workflow Bootstrap" "independent local interaction override"
+assert_contains "$local_interaction_output" "## Shared Terms" "independent local interaction override"
 rm -rf "$local_interaction_dir"
 
 local_skills_dir="$(mktemp -d)"
@@ -148,10 +314,11 @@ mkdir -p "$local_skills_dir/.freeflow"
 printf '{"defaultMode":"workflow"}\n' >"$local_skills_dir/.freeflow/config.json"
 printf '{"defaultMode":"conversation","interactionContract":false,"skills":{"enabled":false}}\n' >"$local_skills_dir/.freeflow/local.json"
 local_skills_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$local_skills_dir" | node "$HOOK_PATH" SessionStart)"
-assert_contains "$local_skills_output" 'Resolved default mode: `conversation` (dormant because Skills are disabled).' "local dormant mode"
+assert_contains "$local_skills_output" 'Resolved mode: `conversation` (dormant because Skills are disabled)' "local dormant mode"
 assert_contains "$local_skills_output" 'Interaction Contract: disabled' "local interaction override"
 assert_contains "$local_skills_output" 'Skills: disabled' "local skills override"
 assert_not_contains "$local_skills_output" "# Freeflow Interaction Contract" "local interaction override"
+assert_not_contains "$local_skills_output" "# Freeflow Mode Update" "local skills override"
 assert_not_contains "$local_skills_output" "# Freeflow Workflow Bootstrap" "local skills override"
 rm -rf "$local_skills_dir"
 
@@ -168,56 +335,58 @@ mkdir -p "$local_disabled_dir/.freeflow"
 printf '{"enabled":true,"defaultMode":"workflow"}\n' >"$local_disabled_dir/.freeflow/config.json"
 printf '{"enabled":false,"processing":{"unsafeUnsandboxed":{"enabled":true}}}\n' >"$local_disabled_dir/.freeflow/local.json"
 local_disabled_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$local_disabled_dir" | node "$HOOK_PATH" SessionStart)"
-assert_contains "$local_disabled_output" "# Freeflow Disabled" "local master override"
-assert_contains "$local_disabled_output" "effective \`enabled\` is false from local" "local master source"
-assert_not_contains "$local_disabled_output" "# Freeflow Interaction Contract" "local master override"
+[[ -z "$local_disabled_output" ]] || fail "local master override should suppress hook prompt delivery"
 rm -rf "$local_disabled_dir"
 
 disabled_dir="$(mktemp -d)"
 mkdir -p "$disabled_dir/.freeflow"
 printf '{"enabled":false,"defaultMode":"workflow"}\n' >"$disabled_dir/.freeflow/config.json"
 disabled_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$disabled_dir" | node "$HOOK_PATH" SessionStart)"
-assert_contains "$disabled_output" "# Freeflow Disabled" "disabled context"
-assert_not_contains "$disabled_output" "# Freeflow Runtime Kernel" "disabled context"
+[[ -z "$disabled_output" ]] || fail "disabled Freeflow should suppress hook prompt delivery"
 rm -rf "$disabled_dir"
 
 router_dir="$(mktemp -d)"
 mkdir -p "$router_dir/.freeflow"
 printf '{"defaultMode":"workflow","skills":{"enabled":false},"outputRouter":{"enabled":true}}\n' >"$router_dir/.freeflow/config.json"
 router_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$router_dir" | node "$HOOK_PATH" SessionStart)"
-assert_contains "$router_output" "Skills: disabled" "router-only context"
-assert_contains "$router_output" "## Loaded Output Router Skill" "router-only context"
-assert_contains "$router_output" "# Freeflow Interaction Contract" "router-only context"
-assert_not_contains "$router_output" "# Freeflow Workflow Bootstrap" "router-only context"
+assert_contains "$router_output" "Skills: disabled" "Codex context with legacy router config"
+assert_contains "$router_output" "# Freeflow Interaction Contract" "Codex context with legacy router config"
+assert_not_contains "$router_output" "# Freeflow Workflow Bootstrap" "Codex context with disabled skills"
+assert_not_contains "$router_output" "Output Router" "Codex context with legacy router config"
+assert_not_contains "$router_output" "Output router:" "Codex context with legacy router config"
 rm -rf "$router_dir"
 
 all_dir="$(mktemp -d)"
 mkdir -p "$all_dir/.freeflow"
 printf '{"defaultMode":"strict-workflow","outputRouter":{"enabled":true}}\n' >"$all_dir/.freeflow/config.json"
 all_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$all_dir" | node "$HOOK_PATH" SessionStart)"
-assert_contains "$all_output" "# Freeflow Interaction Contract" "all-capabilities context"
-assert_contains "$all_output" "## Loaded Output Router Skill" "all-capabilities context"
-assert_contains "$all_output" 'Current Freeflow default mode: `strict-workflow`.' "all-capabilities context"
-assert_contains "$all_output" "## Strict Workflow Overlay" "all-capabilities strict overlay"
+assert_contains "$all_output" "# Freeflow Interaction Contract" "Codex strict context"
+assert_contains "$all_output" "## Shared Terms" "Codex strict context"
+assert_not_contains "$all_output" "Output Router" "Codex strict context"
+assert_not_contains "$all_output" "Output router:" "Codex strict context"
+assert_contains "$all_output" 'Effective mode: `strict-workflow` (configured default, active)' "Codex strict context"
+assert_not_contains "$all_output" "## Strict Workflow Overlay" "all-capabilities strict overlay"
 rm -rf "$all_dir"
 
 conversation_dir="$(mktemp -d)"
 mkdir -p "$conversation_dir/.freeflow"
 printf '{"defaultMode":"conversation"}\n' >"$conversation_dir/.freeflow/config.json"
 conversation_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$conversation_dir" | node "$HOOK_PATH" SessionStart)"
-assert_contains "$conversation_output" 'Current Freeflow default mode: `conversation`.' "conversation context"
-assert_contains "$conversation_output" '`conversation`: answer, discuss, critique, and inspect read-only' "conversation context"
-assert_contains "$conversation_output" "## Conversation Mode Boundary" "conversation overlay"
-assert_contains "$conversation_output" "Do not call write, edit, or mutating tools" "conversation overlay"
-assert_contains "$conversation_output" "an execution skill does not override this boundary" "conversation overlay"
+assert_contains "$conversation_output" 'Configured default: `conversation` (repository)' "conversation context"
+assert_contains "$conversation_output" 'Effective mode: `conversation` (configured default, active)' "conversation context"
+assert_not_contains "$conversation_output" "## Conversation Mode Boundary" "conversation overlay"
+assert_not_contains "$conversation_output" "Do not call write, edit, or mutating tools" "conversation overlay"
+assert_not_contains "$conversation_output" "an execution skill does not override this boundary" "conversation overlay"
 rm -rf "$conversation_dir"
 
 observed_dir="$(mktemp -d)"
 mkdir -p "$observed_dir/.freeflow"
 printf '{"defaultMode":"workflow","outputRouter":{"enabled":true,"observedRouting":{"enabled":true}},"scriptTransform":{"enabled":false}}\n' >"$observed_dir/.freeflow/config.json"
 observed_output="$(printf '{"cwd":"%s","model":"gpt-5"}\n' "$observed_dir" | node "$HOOK_PATH" SessionStart)"
-assert_contains "$observed_output" "# Freeflow Interaction Contract" "observed-routing config"
-assert_contains "$observed_output" "## Loaded Output Router Skill" "observed-routing config"
+assert_contains "$observed_output" "# Freeflow Interaction Contract" "Codex context with observed-routing config"
+assert_contains "$observed_output" "## Shared Terms" "Codex context with observed-routing config"
+assert_not_contains "$observed_output" "Output Router" "Codex context with observed-routing config"
+assert_not_contains "$observed_output" "Output router:" "Codex context with observed-routing config"
 rm -rf "$observed_dir"
 
 echo "runtime-context hook checks passed"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hassangameryt/freeflow",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Feedback-based control system for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -18,24 +18,33 @@
   "scripts": {
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "format:router-dist": "prettier --write router/dist",
     "format:pi-extension-dist": "prettier --write pi-extension/dist",
-    "build:router": "tsc -p router/tsconfig.json && npm run format:router-dist",
     "build:pi-extension": "tsc -p pi-extension/tsconfig.json && npm run format:pi-extension-dist",
-    "build": "npm run build:router && npm run build:pi-extension",
+    "build": "npm run build:pi-extension",
+    "typecheck": "tsc -p pi-extension/tsconfig.json --noEmit",
+    "check": "npm run typecheck && npm run check:source && npm run check:changelog && npm run check:release-workflow && npm run check:docs && npm run format:check && npm run check:release-version && npm run check:commands && npm run check:activation && npm run check:runtime && npm run check:package",
+    "check:source": "node scripts/validation/check-source-files.mjs",
+    "check:changelog": "node scripts/validation/check-changelog.mjs --structure",
+    "check:release-workflow": "node scripts/validation/check-release-workflow.mjs",
+    "check:docs": "node scripts/validation/check-docs.mjs",
+    "check:release-version": "node scripts/validation/check-release-version.mjs",
+    "check:commands": "scripts/validation/audit-command-surface.sh",
+    "check:activation": "scripts/validation/check-activation-contract.sh",
+    "check:runtime": "hooks/tests/check-runtime-context-hook.sh",
+    "check:package": "node scripts/validation/check-package.mjs",
+    "check:release-metadata": "scripts/validation/validate-release-metadata.sh --mode prepublish",
     "test:pi-extension": "npm run build && node --test $(find pi-extension/tests -name '*.test.js' | sort)",
-    "test:router": "npm run build:router && node --test $(find router/tests -name '*.test.js' | sort)",
     "test:skill-author": "node --test $(find .skill-eval/write-skill/tests -name '*.test.mjs' | sort)",
     "test:skill-eval": "node --test $(find .skill-eval/evaluate-skill/tests -name '*.test.mjs' | sort)",
-    "bench:router": "npm run build:router && node router/dist/benchmarks/benchmarks.js",
-    "bench:router:commands": "npm run build:router && node router/dist/benchmarks/command-benchmarks.js",
-    "bench:router:context-saving-baseline": "npm run build:router && node router/dist/benchmarks/context-saving-baseline.js",
-    "bench:router:context-mode-normalized": "npm run build:router && node router/dist/benchmarks/context-mode-normalized-benchmarks.js",
-    "bench:router:context-mode-real-deep": "npm run build:router && node router/dist/benchmarks/context-mode-real-deep-benchmark.js",
-    "bench:router:storage-policy": "npm run build:router && node router/dist/benchmarks/storage-policy-benchmarks.js",
-    "bench:router:index": "npm run build:router && node router/dist/benchmarks/index-benchmarks.js",
-    "bench:router:vault-index": "npm run build:router && node router/dist/benchmarks/vault-index-benchmarks.js",
-    "bench:router:codex-qa": "npm run build:router && node router/dist/benchmarks/codex-qa-benchmarks.js"
+    "test:track-work": "node --test .skill-eval/track-work/tests/*.test.mjs",
+    "test:freeflow-snapshot": "node --test scripts/freeflow-snapshot.test.mjs",
+    "test:release-utils": "node --test scripts/release-utils.test.mjs",
+    "test:changelog": "node --test scripts/validation/check-changelog.test.mjs",
+    "test:release-workflow": "node --test scripts/validation/check-release-workflow.test.mjs",
+    "test:docs": "node --test scripts/validation/check-docs.test.mjs",
+    "release:prepare": "node scripts/release.mjs",
+    "release:notes": "node scripts/release-notes.mjs",
+    "snapshot:refresh": "node scripts/freeflow-snapshot.mjs"
   },
   "keywords": [
     "pi-package",
@@ -66,11 +75,11 @@
     "LICENSE",
     "README.md",
     "assets/**",
+    "capabilities/**",
+    "runtime/**",
     "command-surface.json",
     "hooks/**",
     "pi-extension/**",
-    "router/dist/**",
-    "runtime/**",
     "skills/**"
   ],
   "peerDependencies": {