@hassangameryt/freeflow 0.4.0 → 0.5.0

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

@@ -1,7 +1,7 @@
 #!/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"
@@ -40,7 +40,11 @@ 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,21 +61,23 @@ 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 \
+	'"hookEventName":"SessionStart"' \
 	"# Freeflow Runtime Context" \
-	'Setup status: configured by `.freeflow/config.json`' \
-	"Runtime delivery: confirmed for this lifecycle-hook invocation." \
+	'Runtime delivery: confirmed for this lifecycle-hook invocation.' \
+	'Configured default: `workflow` (repository)' \
+	'Effective mode: `workflow` (configured default, active)' \
 	"# 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`.' \
 	'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"
 for excluded_heading in \
 	"# Freeflow Runtime Kernel" \
 	"## Freeflow Runtime Priority" \
@@ -93,9 +99,150 @@ assert_contains "$claude_output" "# Freeflow Interaction Contract" "Claude confi
 assert_contains "$claude_output" "# Freeflow Workflow Bootstrap" "Claude first-turn context"
 assert_contains "$claude_output" "Answer questions without inferring action." "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" 'Session override: `conversation`' "same-turn mode change"
+assert_contains "$mode_change_output" 'Effective mode: `conversation` (session override, active)' "same-turn mode change"
+assert_contains "$mode_change_output" "## Conversation Mode Boundary" "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" 'Session override: `strict-workflow`' "Codex native skill mode control"
+assert_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 Runtime Context' "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" "# Freeflow Workflow Bootstrap" "$host $source SessionStart context"
+		contract_count="$(grep -Fo '# Freeflow Interaction Contract' <<<"$event_output" | wc -l | tr -d ' ')"
+		bootstrap_count="$(grep -Fo '# Freeflow Workflow Bootstrap' <<<"$event_output" | wc -l | tr -d ' ')"
+		[[ "$contract_count" == "1" ]] || fail "$host $source SessionStart should load the Interaction Contract exactly once"
+		[[ "$bootstrap_count" == "1" ]] || fail "$host $source SessionStart should load Workflow exactly once"
+	done
 done
 
 # Repo-owned host instructions are neither required for activation nor modified by the read-only hook.
@@ -124,8 +271,8 @@ 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" 'Configured default: `strict-workflow` (personal)' "local default override"
+assert_contains "$local_output" 'Effective mode: `strict-workflow` (configured default, active)' "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" "# Freeflow Interaction Contract" "local default override"
@@ -134,8 +281,8 @@ 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"
@@ -148,7 +295,7 @@ 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"
@@ -169,7 +316,7 @@ printf '{"enabled":true,"defaultMode":"workflow"}\n' >"$local_disabled_dir/.free
 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_contains "$local_disabled_output" 'Configured but inactive: `enabled` is false (personal).' "local master source"
 assert_not_contains "$local_disabled_output" "# Freeflow Interaction Contract" "local master override"
 rm -rf "$local_disabled_dir"
 
@@ -185,19 +332,22 @@ 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" "# Freeflow Interaction Contract" "Codex strict context"
+assert_contains "$all_output" "# Freeflow Workflow Bootstrap" "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_contains "$all_output" "## Strict Workflow Overlay" "all-capabilities strict overlay"
 rm -rf "$all_dir"
 
@@ -205,8 +355,8 @@ 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" 'Configured default: `conversation` (repository)' "conversation context"
+assert_contains "$conversation_output" 'Effective mode: `conversation` (configured default, active)' "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"
@@ -216,8 +366,10 @@ 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" "# Freeflow Workflow Bootstrap" "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.5.0",
   "description": "Feedback-based control system for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -66,6 +66,7 @@
     "LICENSE",
     "README.md",
     "assets/**",
+    "capabilities/**",
     "command-surface.json",
     "hooks/**",
     "pi-extension/**",

package/pi-extension/dist/output-router/native-safety-net.js

@@ -153,7 +153,7 @@ function appendSafetyNetWarning(event, message) {
   ];
 }
 // Keep post-tool native transformations aligned with
-// skills/output-router/references/safety-policy.md.
+// capabilities/output-router/references/safety-policy.md.
 export async function handleNativeToolSafetyNet(event, ctx) {
   const routerConfigResult = await readOutputRouterConfig(ctx.cwd);
   notifyRouterConfigWarnings(ctx, routerConfigResult);

package/pi-extension/dist/runtime/runtime-context.js

@@ -81,7 +81,7 @@ async function loadRuntimeContext(capabilityState = undefined) {
       ? readFile(new URL("../../../skills/workflow/SKILL.md", import.meta.url), "utf8")
       : Promise.resolve(null),
     outputRouterEnabled
-      ? readFile(new URL("../../../skills/output-router/SKILL.md", import.meta.url), "utf8")
+      ? readFile(new URL("../../../capabilities/output-router/SKILL.md", import.meta.url), "utf8")
       : Promise.resolve(null),
   ]);
   return { interactionContract, workflowSkill, outputRouterSkill };

package/pi-extension/src/output-router/native-safety-net.ts

@@ -180,7 +180,7 @@ function appendSafetyNetWarning(event, message) {
 }
 
 // Keep post-tool native transformations aligned with
-// skills/output-router/references/safety-policy.md.
+// capabilities/output-router/references/safety-policy.md.
 export async function handleNativeToolSafetyNet(event, ctx) {
   const routerConfigResult = await readOutputRouterConfig(ctx.cwd);
   notifyRouterConfigWarnings(ctx, routerConfigResult);

package/pi-extension/src/runtime/runtime-context.ts

@@ -94,7 +94,7 @@ async function loadRuntimeContext(capabilityState = undefined) {
       ? readFile(new URL("../../../skills/workflow/SKILL.md", import.meta.url), "utf8")
       : Promise.resolve(null),
     outputRouterEnabled
-      ? readFile(new URL("../../../skills/output-router/SKILL.md", import.meta.url), "utf8")
+      ? readFile(new URL("../../../capabilities/output-router/SKILL.md", import.meta.url), "utf8")
       : Promise.resolve(null),
   ]);
 

package/pi-extension/tests/integration/pi-extension.test.js

@@ -209,9 +209,11 @@ test("Pi exposes canonical model skills and maps published command aliases", asy
       assert.ok(match, `unexpected skill path: ${path}`);
       return match[1];
     });
+    assert.equal(skillNames.length, 25);
     for (const skill of ["discuss", "execute-work", "track-work"]) {
       assert.ok(skillNames.includes(skill));
     }
+    assert.ok(!skillNames.includes("output-router"));
     assert.ok(!skillNames.includes("discover"));
     assert.ok(!skillNames.includes("execute-plan"));
     await Promise.all(resources.skillPaths.map((path) => readFile(path, "utf8")));

package/router/dist/config/config.d.ts

@@ -6,7 +6,7 @@ import type {
   ScriptTransformConfig,
   VaultRetentionPolicy,
 } from "./types.js";
-export declare const OUTPUT_ROUTER_SKILL_PATH = "skills/output-router/SKILL.md";
+export declare const OUTPUT_ROUTER_SKILL_PATH = "capabilities/output-router/SKILL.md";
 export declare const DEFAULT_VAULT_ROOT = "~/.cache/freeflow-router/vault";
 export declare const DEFAULT_POST_TOOL_ROUTING = "off";
 export declare const DEFAULT_OUTPUT_ROUTER_ENABLED = false;

package/router/dist/config/config.js

@@ -6,7 +6,7 @@ import {
   RESERVED_OBSERVED_ROUTING_PERSISTENCE_MODES,
   STORAGE_POLICY_MODES,
 } from "./types.js";
-export const OUTPUT_ROUTER_SKILL_PATH = "skills/output-router/SKILL.md";
+export const OUTPUT_ROUTER_SKILL_PATH = "capabilities/output-router/SKILL.md";
 export const DEFAULT_VAULT_ROOT = "~/.cache/freeflow-router/vault";
 export const DEFAULT_POST_TOOL_ROUTING = "off";
 export const DEFAULT_OUTPUT_ROUTER_ENABLED = false;

package/router/dist/tools/run.js

@@ -833,7 +833,7 @@ function commandRoutingFailureResult(options) {
   };
 }
 // Keep exactness-sensitive command routing aligned with
-// skills/output-router/references/safety-policy.md.
+// capabilities/output-router/references/safety-policy.md.
 function routeCommandOutput(options) {
   const outputBytes = byteLength(options.combined);
   const outputLines = countLines(options.combined);

package/skills/mode-contract/SKILL.md

@@ -55,27 +55,49 @@ The user owns mode changes. Recommend `strict-workflow` when risk warrants it, b
 
 A task type, risk classification, direct skill call, or workflow route does not switch mode. Invoking an execution skill during Conversation still does not authorize mutation.
 
-Use host-native mode control when available. In Pi:
+Use host-managed session control so the change takes effect before the model acts. A clear natural-language instruction may use the same control. Questions, examples, hypotheses, and tentative language do not change mode.
 
 ```text
-/freeflow mode
+Switch to conversation mode.                 -> session override
+Use strict-workflow for this session.         -> session override
+Should we switch to strict-workflow?          -> answer or discuss; no override
+Suppose the mode were conversation.           -> discussion; no override
+```
+
+Host-native controls are:
+
+```text
+Pi:
 /freeflow mode conversation
 /freeflow mode workflow
 /freeflow mode strict-workflow
 /freeflow mode reset
+
+Claude:
+/freeflow:mode-contract <conversation|workflow|strict-workflow|reset>
+
+Codex:
+$mode-contract <conversation|workflow|strict-workflow|reset>
 ```
 
-Pi handles these commands before the model runs. The three setting commands create a session override; `reset` clears it and returns to the configured default, including a personal override when present. `/freeflow mode` inspects or selects mode according to host UI support.
+Claude and Codex persist their override in plugin-owned session state keyed by the host session identifier. Pi persists it in branch-aware Pi session state. The override survives ordinary turns and supported resume, clear, and compact boundaries for that session; `reset` clears it and returns to the configured default. A new session starts from configured state.
 
-For a natural-language request to change Pi session mode, direct the user to the native command. Do not claim runtime state changed until the host reports the new effective mode.
+Treat only runtime-reported effective state as proof that the control succeeded. If the host reports missing session identity, unavailable writable plugin state, disabled Skills, or another failure, say that mode did not change. Do not compensate by editing a configured default.
 
 Mention mode only when the user asks, configuration is being discussed, or it changes the next action.
 
 ## Change Defaults Separately
 
-A persistent default change is not a session-mode change. An unqualified personal default request targets `.freeflow/local.json`; changing the shared repository default requires explicit repository, team, or shared-default wording.
+A persistent default change is not a session-mode change. Determine which configured layer the user means before editing:
+
+- explicit **personal** or **local** default targets `.freeflow/local.json`;
+- explicit **shared**, **repository**, or **team** default targets `.freeflow/config.json`;
+- an unqualified “change the default mode” request leaves that scope user-owned—ask one direct local-versus-repository question and wait;
+- “global” is not a defined Freeflow layer—ask whether the user means this checkout's personal default or the shared repository default.
+
+Do not infer the target from which file already exists or from the current mode. Preserve unrelated settings in the selected layer.
 
-In Pi, use `/freeflow mode` or `/freeflow settings session` for a temporary mode override, `/freeflow settings` for personal overrides, and `/freeflow settings repo` for shared defaults. In another host, use its native settings when available or update only the explicitly selected valid layer while preserving unrelated settings.
+In Pi, `/freeflow settings` edits personal overrides and `/freeflow settings repo` edits shared defaults. In another host, an agent may update only the explicitly selected valid configuration layer. Session controls never modify either file.
 
 For agent-performed config edits, obey the effective mode when one exists. Conversation remains read-only. When no mode is effective because Freeflow is unconfigured, inactive, blocked by invalid config, or Skills are dormant, an explicit configuration or [Setup Freeflow](../setup-freeflow/SKILL.md) request governs the selected change; any dormant resolved mode is neither authority nor prohibition. User-operated host controls change their own state before the model continues.
 

package/skills/setup-freeflow/SKILL.md

@@ -13,7 +13,7 @@ Create or repair the smallest valid layered setup. Keep repository activation, p
 
 Answer setup questions and delivery checks read-only. An explicit action request authorizes the smallest selected setup change under the state rules below. When repository config is missing, first activation authorizes minimal shared config; it does not authorize personal overrides, optional capabilities, replacement of invalid config, or edits to repo-owned host instructions.
 
-Read [the activation contract](references/activation-contract.md) before changing setup state. Read [host setup](references/host-setup.md) when runtime delivery, lifecycle, or host trust matters. Read [Output Router setup](references/output-router-setup.md) only when the user explicitly requests it during setup or repair; later tuning belongs to [Output Router](../output-router/SKILL.md).
+Read [the activation contract](references/activation-contract.md) before changing setup state. Read [host setup](references/host-setup.md) when runtime delivery, lifecycle, or host trust matters.
 
 ## Establish Mutation Authority
 
@@ -64,17 +64,12 @@ Before writing local config in a Git checkout, verify it is untracked and ignore
 
 If local config is invalid, report that it blocks effective runtime. Repair or remove it only with authorization; never discard it and fall back silently.
 
-## Keep Optional Setup Explicit
-
-Do not ask an automatic capabilities question. Configure Output Router only when explicitly requested, using [Output Router setup](references/output-router-setup.md). Preserve valid existing capability config during idempotent setup.
-
 ## Establish Same-Turn Context
 
 After successful verification, apply newly effective context directly for the remainder of the setup turn:
 
 - read the [Interaction Contract](../../runtime/interaction-contract.md) when it is effective;
-- read [Workflow](../workflow/SKILL.md) and [Mode Contract](../mode-contract/SKILL.md) when Skills are effective;
-- read an explicitly configured capability skill only when runtime state says it is effective.
+- read [Workflow](../workflow/SKILL.md) and [Mode Contract](../mode-contract/SKILL.md) when Skills are effective.
 
 This direct read establishes same-turn guidance; it does not prove that a lifecycle adapter ran. After first activation, use [host setup](references/host-setup.md) to name the exact host-native lifecycle action for automatic delivery and resource refresh, state what applies before that boundary, and keep delivery confirmed, unavailable, or unconfirmed from evidence.
 
@@ -86,13 +81,12 @@ Verify:
 - local config is missing or valid, personal, untracked, and ignored when applicable;
 - effective `enabled`, Interaction Contract, Skills, and configured default values have the expected sources;
 - Skills-disabled mode remains resolved but dormant;
-- optional capability config changed only when requested;
 - no repo-owned host instructions or unrelated files changed.
 
 Report separately:
 
 1. shared repository activation;
 2. personal override state and effective sources;
-3. effective capability state;
+3. effective Interaction Contract, Skills, and mode state;
 4. same-turn direct context reads;
 5. automatic runtime delivery as **confirmed**, **unavailable**, or **unconfirmed**.

package/skills/setup-freeflow/references/activation-contract.md

@@ -19,8 +19,6 @@ Supported defaults are `conversation`, `workflow`, and `strict-workflow`. Missin
 - `skills.enabled: true`
 - `defaultMode: workflow`
 
-Repository config may also contain documented Output Router settings. Add optional settings only after an explicit request and preserve valid existing settings during idempotent setup.
-
 Do not add current mode, task state, phase, file inventories, plans, version metadata, activation paths, empty optional sections, host instruction copies, or generated workflow text.
 
 Missing or invalid repository config means repository activation is absent. A valid config with effective `enabled: false` remains configured but inactive.
@@ -44,8 +42,6 @@ It may override these core values:
 
 Every field is optional. Omission inherits the repository value, then the built-in default. Local core precedence is property-level, not whole-file replacement.
 
-The local file may also contain documented local-only `processing` config. It must not contain repository-owned Output Router config.
-
 Keep local config untracked and ignored. In a Git checkout, prefer `.git/info/exclude` or an existing ignore rule over an unsolicited shared `.gitignore` edit. Refuse to write personal overrides to a tracked local file.
 
 A missing local file means full inheritance. An invalid existing local file blocks effective Freeflow and must not silently fall back to repository settings. Repair or removal requires authorization.
@@ -58,7 +54,7 @@ Resolve core values in this order:
 host session override -> personal override -> repository value -> built-in default
 ```
 
-Host session overrides, where supported, may temporarily change Freeflow master enablement, Interaction Contract, Skills, and mode. They are host session state, not config, and cannot bypass missing or invalid repository activation.
+Host session overrides are host state, not config, and cannot bypass missing or invalid repository activation. Pi may temporarily override Freeflow master enablement, Interaction Contract, Skills, and mode. Claude and Codex support mode-only overrides in plugin-owned session state.
 
 Effective Freeflow requires:
 
@@ -68,8 +64,6 @@ Effective Freeflow requires:
 
 The Interaction Contract and Skills are independent resolved switches. When Skills are disabled, the configured mode remains visible as resolved state but no Freeflow mode is effective.
 
-Repository-owned Output Router settings remain independent capability config and take effect only while top-level Freeflow is enabled.
-
 ## Mutation Authority By State
 
 Mode constrains agent-performed setup only when a mode is effective:
@@ -88,8 +82,9 @@ When effective, host adapters may deliver:
 
 - `runtime/interaction-contract.md` when the Interaction Contract switch is enabled;
 - one full `skills/workflow/SKILL.md` bootstrap when Skills are enabled;
-- compact active or dormant mode and capability state;
-- explicitly enabled capability context owned by that capability.
+- compact active or dormant mode state.
+
+Pi may additionally deliver explicitly enabled Pi capability context through its extension. Codex and Claude `SessionStart` hooks deliver only the core Interaction Contract, Workflow bootstrap, and mode state; their `UserPromptSubmit` hook delivers only an explicit session-mode change or failure delta.
 
 The full Mode Contract and other workflow skills remain on demand. Adapters load context only; they do not enforce policy, block tools, grant permissions, or replace repo instructions.
 

package/skills/setup-freeflow/references/host-setup.md

@@ -45,9 +45,9 @@ Confirm automatic delivery through current extension status or runtime evidence
 
 ## Codex And Claude
 
-The packaged lifecycle hook reads the same repository and local layers at supported session start, resume, clear, and compact boundaries.
+The packaged runtime hook reads the same repository and local layers plus plugin-owned session mode state. At supported session start, resume, clear, and compact boundaries, `SessionStart` restores the complete enabled context. On submitted prompts, `UserPromptSubmit` changes mode only for an explicit native or conservative natural-language session control and otherwise emits nothing.
 
-When top-level Freeflow is effective, the hook loads the Interaction Contract if enabled and the full Workflow bootstrap if Skills are enabled. It reports layered value sources and active or dormant mode state. Optional capabilities remain independently gated by valid repository config and top-level Freeflow.
+When top-level Freeflow is effective, the hook loads the Interaction Contract if enabled and the full Workflow bootstrap if Skills are enabled. It reports configured, session, resolved, and effective mode state without treating a configured default as the current session mode.
 
 After first-time setup, tell the user to trigger the least disruptive supported host-native lifecycle boundary: resume, clear, compact, or a new session/startup as available. Name the exact control supported by the current host; do not prescribe Pi's `/reload`. Until that boundary runs, use same-turn direct reads without claiming automatic delivery.
 
@@ -61,10 +61,6 @@ Installed and trusted registration can establish availability for the next lifec
 
 Do not compensate for unavailable or unconfirmed delivery by copying Freeflow text into repository instructions.
 
-## Optional Capabilities
-
-Do not ask a generic capability question during normal setup. If Output Router is explicitly requested, use `output-router-setup.md` and keep its config in the shared repository layer unless the documented setting is specifically local-only.
-
 Do not install repo-local hooks, CLI commands, lint rules, global standards, documentation inventories, or state files during setup.
 
 ## Conflicts