arkaos 2.20.0 → 2.20.1

package/VERSION

@@ -1 +1 @@
-2.20.0
+2.20.1

package/config/hooks/_lib/workflow-classifier.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS v2 — Shared Workflow Classifier
+#
+# Decides whether a user prompt triggers the mandatory 13-phase flow.
+# Used by: user-prompt-submit.sh, pre-tool-use.sh, stop.sh.
+#
+# Contract:
+#   arka_wf_classify "<prompt text>"  → echoes "true" or "false", exits 0.
+#   arka_wf_mark_required "<session_id>"  → writes marker file.
+#   arka_wf_is_required "<session_id>"  → exits 0 if required, 1 otherwise.
+#   arka_wf_clear_required "<session_id>"  → removes marker file.
+#
+# Markers live under /tmp/arkaos-wf-required/<session_id>.
+# Python path for mark/clear: delegates to flow_enforcer.py when available,
+# otherwise falls back to touching the marker file directly.
+# ============================================================================
+
+ARKA_WF_REQUIRED_DIR="${ARKA_WF_REQUIRED_DIR:-/tmp/arkaos-wf-required}"
+
+# Reject any session_id outside [A-Za-z0-9._-]{1,128}. Protects the marker
+# directory from path-traversal writes (CWE-22). Must stay in sync with
+# core/workflow/flow_enforcer.py::_safe_session_id.
+arka_wf_safe_session_id() {
+  local session_id="${1:-}"
+  [ -z "$session_id" ] && return 1
+  [ ${#session_id} -gt 128 ] && return 1
+  case "$session_id" in
+    *[!A-Za-z0-9._-]*) return 1 ;;
+  esac
+  return 0
+}
+
+# Verb + noun patterns shared with the original inline classifier in
+# user-prompt-submit.sh. Keep in sync when adding new intent verbs.
+ARKA_WF_VERB_PATTERN='(criar?|crie[ms]?|cria[mr]?|adicionar?|adiciona[mr]?|implementar?|implementa[mr]?|desenvolver?|desenvolve[mr]?|construir?|constru[ií]a?[mr]?|fazer?|faz[ae][mr]?|refactor(izar?)?|corrigir?|corrige[mr]?|consertar?|conserta[mr]?|create[sd]?|creating|build(s|ing)?|add(s|ed|ing)?|implement(s|ed|ing)?|develop(s|ed|ing)?|fix(es|ed|ing)?|refactor(s|ed|ing)?|make[sd]?|making)'
+
+# Classify: returns "true" if the prompt looks like a creation/
+# implementation/modification request, "false" otherwise.
+# Skips: explicit slash commands (already routed) and bang shells.
+arka_wf_classify() {
+  local text="${1:-}"
+  [ -z "$text" ] && { echo "false"; return 0; }
+
+  local first_char
+  first_char=$(printf '%s' "$text" | head -c 1)
+  if [ "$first_char" = "/" ] || [ "$first_char" = "!" ]; then
+    echo "false"
+    return 0
+  fi
+
+  if echo "$text" | grep -qiE "\b${ARKA_WF_VERB_PATTERN}\b"; then
+    echo "true"
+  else
+    echo "false"
+  fi
+}
+
+# Mark that the flow is required for this session. Safe no-op if session_id
+# is empty or fails the allowlist check.
+arka_wf_mark_required() {
+  local session_id="${1:-}"
+  arka_wf_safe_session_id "$session_id" || return 0
+  mkdir -p "$ARKA_WF_REQUIRED_DIR" 2>/dev/null
+  date -u +"%Y-%m-%dT%H:%M:%SZ" > "$ARKA_WF_REQUIRED_DIR/$session_id" 2>/dev/null
+}
+
+# Test whether flow is required. Exit code 0 = required, 1 = not required.
+arka_wf_is_required() {
+  local session_id="${1:-}"
+  arka_wf_safe_session_id "$session_id" || return 1
+  [ -f "$ARKA_WF_REQUIRED_DIR/$session_id" ]
+}
+
+# Clear the requirement marker. Safe no-op if absent or unsafe.
+arka_wf_clear_required() {
+  local session_id="${1:-}"
+  arka_wf_safe_session_id "$session_id" || return 0
+  rm -f "$ARKA_WF_REQUIRED_DIR/$session_id" 2>/dev/null
+  return 0
+}
+
+# When invoked directly (not sourced), expose a simple CLI for ad-hoc use.
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  case "${1:-}" in
+    classify)   arka_wf_classify "${2:-}" ;;
+    mark)       arka_wf_mark_required "${2:-}" ;;
+    is-required) arka_wf_is_required "${2:-}" && echo "true" || echo "false" ;;
+    clear)      arka_wf_clear_required "${2:-}" ;;
+    *)
+      echo "Usage: $0 {classify <text>|mark <session_id>|is-required <session_id>|clear <session_id>}" >&2
+      exit 64
+      ;;
+  esac
+fi

package/config/hooks/pre-tool-use.ps1

@@ -0,0 +1,117 @@
+# ============================================================================
+# ArkaOS v2 — PreToolUse Hook (Windows PowerShell)
+#
+# Parity with config/hooks/pre-tool-use.sh. Blocks Write/Edit/MultiEdit when
+# the mandatory 13-phase flow is required for the session AND the assistant
+# has not emitted a flow marker in its last 3 messages of the transcript.
+#
+# Delegates the decision to core/workflow/flow_enforcer.py.
+#
+# Exit 0 = allow (silent). Exit 2 = deny + structured hookSpecificOutput JSON.
+# ============================================================================
+
+$ErrorActionPreference = "SilentlyContinue"
+
+# --- Read stdin JSON ---
+$inputJson = [Console]::In.ReadToEnd()
+if ([string]::IsNullOrWhiteSpace($inputJson)) { exit 0 }
+
+try {
+    $inp = $inputJson | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+$toolName = [string]$inp.tool_name
+$transcriptPath = [string]$inp.transcript_path
+$sessionId = [string]$inp.session_id
+$cwd = [string]$inp.cwd
+
+# --- Fast allow: not a gated tool ---
+if ($toolName -ne "Write" -and $toolName -ne "Edit" -and $toolName -ne "MultiEdit") {
+    exit 0
+}
+
+# --- Resolve ARKAOS_ROOT ---
+if ([string]::IsNullOrWhiteSpace($env:ARKAOS_ROOT)) {
+    $repoPathFile = Join-Path $HOME ".arkaos/.repo-path"
+    if (Test-Path $repoPathFile) {
+        $env:ARKAOS_ROOT = (Get-Content $repoPathFile -Raw).Trim()
+    } elseif (Test-Path (Join-Path $HOME ".arkaos")) {
+        $env:ARKAOS_ROOT = (Join-Path $HOME ".arkaos")
+    } else {
+        $env:ARKAOS_ROOT = if ($env:ARKA_OS) { $env:ARKA_OS } else { Join-Path $HOME ".claude/skills/arkaos" }
+    }
+}
+
+$enforcerPy = Join-Path $env:ARKAOS_ROOT "core/workflow/flow_enforcer.py"
+if (-not (Test-Path $enforcerPy)) { exit 0 }
+
+$python = Get-Command python3 -ErrorAction SilentlyContinue
+if (-not $python) { $python = Get-Command python -ErrorAction SilentlyContinue }
+if (-not $python) { exit 0 }
+
+# --- Delegate to Python enforcer ---
+$env:TOOL_NAME = $toolName
+$env:TRANSCRIPT_PATH = $transcriptPath
+$env:SESSION_ID = $sessionId
+$env:CWD = $cwd
+
+$pyScript = @'
+import json
+import os
+import sys
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.workflow.flow_enforcer import evaluate, record_telemetry
+except Exception:
+    print(json.dumps({"allow": True, "reason": "enforcer-import-failed"}))
+    sys.exit(0)
+
+decision = evaluate(
+    tool_name=os.environ.get("TOOL_NAME", ""),
+    transcript_path=os.environ.get("TRANSCRIPT_PATH", ""),
+    session_id=os.environ.get("SESSION_ID", ""),
+    cwd=os.environ.get("CWD", ""),
+)
+try:
+    record_telemetry(
+        session_id=os.environ.get("SESSION_ID", ""),
+        tool=os.environ.get("TOOL_NAME", ""),
+        decision=decision,
+        cwd=os.environ.get("CWD", ""),
+    )
+except Exception:
+    pass
+print(json.dumps({
+    "allow": decision.allow,
+    "reason": decision.reason,
+    "stderr_msg": decision.to_stderr_message(),
+}))
+'@
+
+$decisionJson = $pyScript | & $python.Source -
+if ([string]::IsNullOrWhiteSpace($decisionJson)) { exit 0 }
+
+try {
+    $decision = $decisionJson | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+if ($decision.allow) { exit 0 }
+
+# --- Deny path ---
+[Console]::Error.WriteLine($decision.stderr_msg)
+
+$denyOut = @{
+    hookSpecificOutput = @{
+        hookEventName = "PreToolUse"
+        permissionDecision = "deny"
+        permissionDecisionReason = $decision.stderr_msg
+    }
+} | ConvertTo-Json -Compress -Depth 5
+
+Write-Output $denyOut
+exit 2

package/config/hooks/pre-tool-use.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS v2 — PreToolUse Hook (Flow Enforcement Gate)
+#
+# Blocks Write/Edit/MultiEdit when the mandatory 13-phase flow is required
+# for the session AND the assistant has not emitted a flow marker
+# (`[arka:routing]`, `[arka:trivial]`, or `[arka:phase:`) in its last
+# 3 messages of the transcript.
+#
+# Delegates the decision to core/workflow/flow_enforcer.py (single source
+# of truth, pytest-covered). This shell script is a thin wrapper — anti
+# pattern `duplicated-security-logic` compliance.
+#
+# Timeout: 10s.
+# Allow semantics: no stdout, exit 0.
+# Deny semantics: hookSpecificOutput.permissionDecision=deny JSON on stdout,
+# `[ARKA:ENFORCEMENT] ...` on stderr, exit 2.
+# ============================================================================
+
+input=$(cat)
+
+# ─── Extract fields (docs: session_id, transcript_path, cwd, tool_name)
+TOOL_NAME=""
+TRANSCRIPT_PATH=""
+SESSION_ID=""
+CWD=""
+if command -v jq &>/dev/null; then
+  TOOL_NAME=$(echo "$input" | jq -r '.tool_name // ""' 2>/dev/null)
+  TRANSCRIPT_PATH=$(echo "$input" | jq -r '.transcript_path // ""' 2>/dev/null)
+  SESSION_ID=$(echo "$input" | jq -r '.session_id // ""' 2>/dev/null)
+  CWD=$(echo "$input" | jq -r '.cwd // ""' 2>/dev/null)
+fi
+
+# ─── Fast allow: not a gated tool
+case "$TOOL_NAME" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# ─── Resolve ARKAOS_ROOT (same rules as user-prompt-submit.sh) ──────────
+if [ -z "${ARKAOS_ROOT:-}" ]; then
+  if [ -f "$HOME/.arkaos/.repo-path" ]; then
+    ARKAOS_ROOT=$(cat "$HOME/.arkaos/.repo-path")
+  elif [ -d "$HOME/.arkaos" ]; then
+    ARKAOS_ROOT="$HOME/.arkaos"
+  else
+    ARKAOS_ROOT="${ARKA_OS:-$HOME/.claude/skills/arkaos}"
+  fi
+fi
+
+# ─── Degrade gracefully if Python or module is unavailable ──────────────
+if ! command -v python3 &>/dev/null; then
+  exit 0
+fi
+if [ ! -f "$ARKAOS_ROOT/core/workflow/flow_enforcer.py" ]; then
+  exit 0
+fi
+
+# ─── Delegate to Python enforcer ────────────────────────────────────────
+DECISION_JSON=$(TOOL_NAME="$TOOL_NAME" \
+                TRANSCRIPT_PATH="$TRANSCRIPT_PATH" \
+                SESSION_ID="$SESSION_ID" \
+                CWD="$CWD" \
+                ARKAOS_ROOT="$ARKAOS_ROOT" \
+                python3 - <<'PY' 2>/dev/null
+import json
+import os
+import sys
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.workflow.flow_enforcer import evaluate, record_telemetry
+except Exception:
+    print(json.dumps({"allow": True, "reason": "enforcer-import-failed"}))
+    sys.exit(0)
+
+decision = evaluate(
+    tool_name=os.environ.get("TOOL_NAME", ""),
+    transcript_path=os.environ.get("TRANSCRIPT_PATH", ""),
+    session_id=os.environ.get("SESSION_ID", ""),
+    cwd=os.environ.get("CWD", ""),
+)
+try:
+    record_telemetry(
+        session_id=os.environ.get("SESSION_ID", ""),
+        tool=os.environ.get("TOOL_NAME", ""),
+        decision=decision,
+        cwd=os.environ.get("CWD", ""),
+    )
+except Exception:
+    pass
+print(json.dumps({
+    "allow": decision.allow,
+    "reason": decision.reason,
+    "stderr_msg": decision.to_stderr_message(),
+}))
+PY
+)
+
+if [ -z "$DECISION_JSON" ]; then
+  exit 0
+fi
+
+ALLOW=$(echo "$DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('allow', True))" 2>/dev/null)
+
+if [ "$ALLOW" = "True" ] || [ "$ALLOW" = "true" ]; then
+  exit 0
+fi
+
+# ─── Deny path: structured hookSpecificOutput + stderr fallback ─────────
+REASON=$(echo "$DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('reason',''))" 2>/dev/null)
+STDERR_MSG=$(echo "$DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('stderr_msg',''))" 2>/dev/null)
+
+# Emit stderr (visible to the model per Claude Code hook spec) ─────────
+echo "$STDERR_MSG" >&2
+
+# Emit structured deny JSON (preferred path when runtime understands it).
+# STDERR_MSG is passed via env var and read inside a single-quoted heredoc
+# so no shell interpolation occurs inside the Python source — this closes
+# the command-injection surface flagged by Francisca's tech review.
+STDERR_MSG="$STDERR_MSG" python3 - <<'PY'
+import json
+import os
+
+out = {
+    "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "deny",
+        "permissionDecisionReason": os.environ.get("STDERR_MSG", ""),
+    }
+}
+print(json.dumps(out))
+PY
+
+exit 2

package/config/hooks/stop.ps1

@@ -0,0 +1,112 @@
+# ============================================================================
+# ArkaOS v2 — Stop Hook (Windows PowerShell, WARN mode v1)
+#
+# Parity with config/hooks/stop.sh. Observes whether a flow-required session
+# closed with [arka:phase:13] or [arka:trivial]. Logs to telemetry; never
+# blocks in v1.
+# ============================================================================
+
+$ErrorActionPreference = "SilentlyContinue"
+
+$inputJson = [Console]::In.ReadToEnd()
+if ([string]::IsNullOrWhiteSpace($inputJson)) { exit 0 }
+
+try {
+    $inp = $inputJson | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+$sessionId = [string]$inp.session_id
+$transcriptPath = [string]$inp.transcript_path
+$stopHookActive = [string]$inp.stop_hook_active
+$cwd = [string]$inp.cwd
+
+if ($stopHookActive -eq "true") { exit 0 }
+
+$wfMarker = Join-Path "/tmp/arkaos-wf-required" $sessionId
+if ([string]::IsNullOrWhiteSpace($sessionId) -or -not (Test-Path $wfMarker)) {
+    exit 0
+}
+
+if ([string]::IsNullOrWhiteSpace($env:ARKAOS_ROOT)) {
+    $repoPathFile = Join-Path $HOME ".arkaos/.repo-path"
+    if (Test-Path $repoPathFile) {
+        $env:ARKAOS_ROOT = (Get-Content $repoPathFile -Raw).Trim()
+    } elseif (Test-Path (Join-Path $HOME ".arkaos")) {
+        $env:ARKAOS_ROOT = (Join-Path $HOME ".arkaos")
+    } else {
+        $env:ARKAOS_ROOT = if ($env:ARKA_OS) { $env:ARKA_OS } else { Join-Path $HOME ".claude/skills/arkaos" }
+    }
+}
+
+$enforcerPy = Join-Path $env:ARKAOS_ROOT "core/workflow/flow_enforcer.py"
+if (-not (Test-Path $enforcerPy)) { exit 0 }
+
+$python = Get-Command python3 -ErrorAction SilentlyContinue
+if (-not $python) { $python = Get-Command python -ErrorAction SilentlyContinue }
+if (-not $python) { exit 0 }
+
+$env:SESSION_ID_VAL = $sessionId
+$env:TRANSCRIPT_PATH_VAL = $transcriptPath
+$env:CWD_VAL = $cwd
+
+$pyScript = @'
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.workflow.flow_enforcer import (
+        _load_last_assistant_messages,
+        TELEMETRY_PATH,
+        clear_flow_required,
+    )
+except Exception:
+    sys.exit(0)
+
+session_id = os.environ.get("SESSION_ID_VAL", "")
+transcript_path = os.environ.get("TRANSCRIPT_PATH_VAL", "")
+cwd = os.environ.get("CWD_VAL", "")
+
+messages = _load_last_assistant_messages(transcript_path, n=1)
+last = messages[-1] if messages else ""
+
+phase13 = bool(re.search(r"\[arka:phase:13\]", last, re.IGNORECASE))
+trivial = bool(re.search(r"\[arka:trivial\]", last, re.IGNORECASE))
+
+entry = {
+    "ts": datetime.now(timezone.utc).isoformat(),
+    "session_id": session_id,
+    "cwd": cwd,
+    "event": "stop-hook-flow-check",
+    "closing_marker_found": phase13 or trivial,
+    "phase13": phase13,
+    "trivial": trivial,
+    "mode": "warn",
+}
+
+try:
+    TELEMETRY_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with TELEMETRY_PATH.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry) + "\n")
+except Exception:
+    pass
+
+try:
+    clear_flow_required(session_id)
+except Exception:
+    pass
+'@
+
+$pyScript | & $python.Source - | Out-Null
+
+# Belt-and-braces marker cleanup (safe even if the Python block crashed).
+if ($sessionId -match '^[A-Za-z0-9._-]{1,128}$') {
+    Remove-Item -LiteralPath $wfMarker -ErrorAction SilentlyContinue
+}
+
+exit 0

package/config/hooks/stop.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS v2 — Stop Hook (Flow Completion Validator, WARN mode v1)
+#
+# When the classifier marked the session as flow-required, this hook checks
+# whether the final assistant message contains [arka:phase:13] or
+# [arka:trivial]. If absent, a structured warning is appended to
+# ~/.arkaos/telemetry/enforcement.jsonl. The hook NEVER blocks in v1.
+#
+# Promotion to strict mode is planned for v2.21.0 after ≥ 2 weeks of clean
+# telemetry. Until then, this hook is observation only.
+#
+# Timeout: 5s | Always exit 0.
+# ============================================================================
+
+input=$(cat)
+
+SESSION_ID=""
+TRANSCRIPT_PATH=""
+STOP_HOOK_ACTIVE=""
+CWD=""
+if command -v jq &>/dev/null; then
+  SESSION_ID=$(echo "$input" | jq -r '.session_id // ""' 2>/dev/null)
+  TRANSCRIPT_PATH=$(echo "$input" | jq -r '.transcript_path // ""' 2>/dev/null)
+  STOP_HOOK_ACTIVE=$(echo "$input" | jq -r '.stop_hook_active // ""' 2>/dev/null)
+  CWD=$(echo "$input" | jq -r '.cwd // ""' 2>/dev/null)
+fi
+
+# Prevent infinite loops when Stop hook was triggered by its own decision.
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+# Only evaluate sessions where the classifier flagged a creation intent.
+WF_MARKER="/tmp/arkaos-wf-required/$SESSION_ID"
+if [ -z "$SESSION_ID" ] || [ ! -f "$WF_MARKER" ]; then
+  exit 0
+fi
+
+# Resolve ARKAOS_ROOT
+if [ -z "${ARKAOS_ROOT:-}" ]; then
+  if [ -f "$HOME/.arkaos/.repo-path" ]; then
+    ARKAOS_ROOT=$(cat "$HOME/.arkaos/.repo-path")
+  elif [ -d "$HOME/.arkaos" ]; then
+    ARKAOS_ROOT="$HOME/.arkaos"
+  else
+    ARKAOS_ROOT="${ARKA_OS:-$HOME/.claude/skills/arkaos}"
+  fi
+fi
+
+if ! command -v python3 &>/dev/null; then
+  exit 0
+fi
+if [ ! -f "$ARKAOS_ROOT/core/workflow/flow_enforcer.py" ]; then
+  exit 0
+fi
+
+# Reuse the last-messages reader to check for a closing phase marker.
+SESSION_ID_VAL="$SESSION_ID" \
+TRANSCRIPT_PATH_VAL="$TRANSCRIPT_PATH" \
+CWD_VAL="$CWD" \
+ARKAOS_ROOT_VAL="$ARKAOS_ROOT" \
+python3 - <<'PY' 2>/dev/null
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT_VAL"])
+try:
+    from core.workflow.flow_enforcer import (
+        _load_last_assistant_messages,
+        TELEMETRY_PATH,
+        clear_flow_required,
+    )
+except Exception:
+    sys.exit(0)
+
+session_id = os.environ.get("SESSION_ID_VAL", "")
+transcript_path = os.environ.get("TRANSCRIPT_PATH_VAL", "")
+cwd = os.environ.get("CWD_VAL", "")
+
+# Only inspect the very last assistant message for closing markers.
+messages = _load_last_assistant_messages(transcript_path, n=1)
+last = messages[-1] if messages else ""
+
+phase13 = bool(re.search(r"\[arka:phase:13\]", last, re.IGNORECASE))
+trivial = bool(re.search(r"\[arka:trivial\]", last, re.IGNORECASE))
+closing_ok = phase13 or trivial
+
+entry = {
+    "ts": datetime.now(timezone.utc).isoformat(),
+    "session_id": session_id,
+    "cwd": cwd,
+    "event": "stop-hook-flow-check",
+    "closing_marker_found": closing_ok,
+    "phase13": phase13,
+    "trivial": trivial,
+    "mode": "warn",
+}
+
+try:
+    TELEMETRY_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with TELEMETRY_PATH.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry) + "\n")
+except Exception:
+    pass
+
+# Clean up the session marker once Stop has evaluated.
+try:
+    clear_flow_required(session_id)
+except Exception:
+    pass
+PY
+
+# Belt-and-braces: remove the marker at shell level in case the Python
+# block above crashed before reaching clear_flow_required(). Session_id
+# is already validated by the Python helper; this shell remove is scoped
+# to the exact marker path and is idempotent.
+case "$SESSION_ID" in
+  *[!A-Za-z0-9._-]*|"") ;;  # reject unsafe/empty session ids
+  *) rm -f "$WF_MARKER" 2>/dev/null ;;
+esac
+
+exit 0

package/config/hooks/user-prompt-submit.sh

@@ -83,14 +83,23 @@ mkdir -p "$CACHE_DIR" 2>/dev/null
 
 # ─── Extract user input from hook JSON ───────────────────────────────────
 user_input=""
+SESSION_ID=""
 if command -v jq &>/dev/null; then
   user_input=$(echo "$input" | jq -r '.userInput // .message // ""' 2>/dev/null)
+  SESSION_ID=$(echo "$input" | jq -r '.session_id // ""' 2>/dev/null)
 fi
 # Fallback: try to get the raw text
 if [ -z "$user_input" ]; then
   user_input=$(echo "$input" | head -c 2000)
 fi
 
+# ─── Load shared workflow classifier ─────────────────────────────────────
+_CLASSIFIER_LIB="$(dirname "$0")/_lib/workflow-classifier.sh"
+if [ -f "$_CLASSIFIER_LIB" ]; then
+  # shellcheck disable=SC1090
+  . "$_CLASSIFIER_LIB"
+fi
+
 # ─── Try Python Synapse bridge first ────────────────────────────────────
 python_result=""
 BRIDGE_SCRIPT="${ARKAOS_ROOT}/scripts/synapse-bridge.py"
@@ -276,21 +285,18 @@ When [knowledge:N chunks] is present, cite at least one source.
 If [knowledge:N chunks] is absent on a non-trivial ArkaOS topic, query Obsidian first."
 
 # ─── Workflow Classifier (hard enforcement for creation/implementation) ──
-# Classifies the user prompt. If it looks like a creation/implementation/
-# modification request that is NOT already routed with an explicit /prefix,
-# emits a directive that the agent MUST acknowledge with [arka:routing]
-# BEFORE using any write tool. Trivial quick questions pass through
-# untouched. Explicit slash commands pass through untouched.
+# Uses the shared _lib/workflow-classifier.sh. When a creation/implementation
+# verb is detected, the session is marked as flow-required so PreToolUse
+# can block Write/Edit/MultiEdit until the agent emits [arka:routing] or
+# [arka:trivial]. Explicit slash commands and bang shells pass through.
 _WORKFLOW_DIRECTIVE=""
-if [ -n "$user_input" ]; then
-  # Skip: explicit slash command (already routed)
-  _FIRST_CHAR=$(echo "$user_input" | head -c 1)
-  if [ "$_FIRST_CHAR" != "/" ] && [ "$_FIRST_CHAR" != "!" ]; then
-    # Match creation/implementation verbs in EN and PT (case-insensitive).
-    _VERB_PATTERN='(criar?|crie[ms]?|cria[mr]?|adicionar?|adiciona[mr]?|implementar?|implementa[mr]?|desenvolver?|desenvolve[mr]?|construir?|constru[ií]a?[mr]?|fazer?|faz[ae][mr]?|refactor(izar?)?|corrigir?|corrige[mr]?|consertar?|conserta[mr]?|create[sd]?|creating|build(s|ing)?|add(s|ed|ing)?|implement(s|ed|ing)?|develop(s|ed|ing)?|fix(es|ed|ing)?|refactor(s|ed|ing)?|make[sd]?|making)'
-    _NOUN_PATTERN='(feature|funcionalidade|skill|squad|agent[e]?|workflow|endpoint|api|component[e]?|module|m[oó]dulo|page|p[aá]gina|hook|pipeline|integration|integra[cç][aã]o|dashboard|report|report[eó]|script|test[es]?)'
-    if echo "$user_input" | grep -qiE "\b${_VERB_PATTERN}\b"; then
-      _WORKFLOW_DIRECTIVE="
+if [ -n "$user_input" ] && command -v arka_wf_classify &>/dev/null; then
+  if [ "$(arka_wf_classify "$user_input")" = "true" ]; then
+    # Mark session as flow-required (consumed by pre-tool-use.sh and stop.sh)
+    if command -v arka_wf_mark_required &>/dev/null; then
+      arka_wf_mark_required "$SESSION_ID"
+    fi
+    _WORKFLOW_DIRECTIVE="
 [ARKA:WORKFLOW-REQUIRED] Your user request matched a CREATION/IMPLEMENTATION pattern.
 The ArkaOS mandatory 13-phase flow applies. It is NON-NEGOTIABLE (constitution rule
 mandatory-flow). You MUST walk every phase, in order, emitting a [arka:phase:N] tag
@@ -323,7 +329,6 @@ Anything else runs the full 13 phases. Source: arka/skills/flow/SKILL.md.
 This is enforced by the hook and the session-start systemMessage, not by convention.
 Skipping violates: mandatory-flow, squad-routing, spec-driven, mandatory-qa,
 sequential-validation, full-visibility, arka-supremacy."
-    fi
   fi
 fi
 

package/core/workflow/flow_enforcer.py

@@ -0,0 +1,272 @@
+"""Mandatory 13-phase flow enforcement for write-mutation tools.
+
+Invoked by the Claude Code `PreToolUse` hook. Decides whether a `Write`,
+`Edit`, or `MultiEdit` tool call may proceed, based on markers observed
+in the last N assistant messages of the session transcript.
+
+Design contract:
+- Stateless transcript parse (no /tmp state for decisions).
+- Side effects limited to reading the transcript path supplied by the hook.
+- Signals permission when the assistant has emitted one of the flow markers:
+  `[arka:routing]`, `[arka:trivial]`, or `[arka:phase:`.
+- Respects `ARKA_BYPASS_FLOW=1` env var (installer/`/arka update` internal).
+- Honors feature flag `hooks.hardEnforcement` in `~/.arkaos/config.json`.
+- Gated tool list is closed: anything outside it is always allowed.
+"""
+
+import json
+import os
+import re
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+try:
+    import fcntl  # POSIX only
+    _HAS_FLOCK = True
+except ImportError:
+    _HAS_FLOCK = False
+
+
+@contextmanager
+def _locked_append(path: Path):
+    """Append to `path` under an exclusive advisory lock (POSIX flock).
+
+    On Windows or any platform without fcntl, falls back to a plain append
+    (single-process writers remain safe; cross-process interleaving is
+    mitigated by `O_APPEND` atomicity for writes up to PIPE_BUF).
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fh = path.open("a", encoding="utf-8")
+    try:
+        if _HAS_FLOCK:
+            fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+        yield fh
+    finally:
+        if _HAS_FLOCK:
+            try:
+                fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+            except OSError:
+                pass
+        fh.close()
+
+GATED_TOOLS: frozenset[str] = frozenset({"Write", "Edit", "MultiEdit"})
+
+ROUTING_RE = re.compile(r"\[arka:routing\]\s*[\w-]+\s*->\s*\w+", re.IGNORECASE)
+TRIVIAL_RE = re.compile(r"\[arka:trivial\]\s*\S+", re.IGNORECASE)
+PHASE_RE = re.compile(r"\[arka:phase:\d+\]", re.IGNORECASE)
+SAFE_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+
+ASSISTANT_WINDOW = 3
+CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
+BYPASS_AUDIT_PATH = Path.home() / ".arkaos" / "audit" / "bypass.log"
+TELEMETRY_PATH = Path.home() / ".arkaos" / "telemetry" / "enforcement.jsonl"
+FLOW_REQUIRED_DIR = Path("/tmp/arkaos-wf-required")
+
+
+def _safe_session_id(session_id: str) -> str | None:
+    """Validate session_id against a strict allowlist (prevents path traversal).
+
+    Returns the id if safe, or None if it contains path separators, dots-dots,
+    or characters outside `[A-Za-z0-9._-]`. Callers MUST treat None as reject.
+    """
+    if not session_id or not isinstance(session_id, str):
+        return None
+    if not SAFE_SESSION_ID_RE.match(session_id):
+        return None
+    return session_id
+
+
+@dataclass
+class Decision:
+    """Outcome of enforcement evaluation for a single tool call."""
+
+    allow: bool
+    reason: str
+    marker_found: str | None = None
+    phase_observed: str | None = None
+    bypass_used: bool = False
+
+    def to_stderr_message(self) -> str:
+        if self.allow:
+            return ""
+        return (
+            f"[ARKA:ENFORCEMENT] Flow marker missing. "
+            f"Emit `[arka:routing] <dept> -> <lead>` or `[arka:trivial] <reason>` "
+            f"before any Write/Edit/MultiEdit. Reason: {self.reason}"
+        )
+
+
+def _feature_flag_on() -> bool:
+    if not CONFIG_PATH.exists():
+        return False
+    try:
+        data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return False
+    return bool(data.get("hooks", {}).get("hardEnforcement", False))
+
+
+def _bypass_env_active() -> bool:
+    return os.environ.get("ARKA_BYPASS_FLOW", "").strip() == "1"
+
+
+def _audit_bypass(session_id: str, tool: str, cwd: str) -> None:
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "session_id": session_id,
+        "tool": tool,
+        "cwd": cwd,
+        "reason": os.environ.get("ARKA_BYPASS_REASON", ""),
+    }
+    with _locked_append(BYPASS_AUDIT_PATH) as fh:
+        fh.write(json.dumps(entry) + "\n")
+
+
+def record_telemetry(
+    session_id: str, tool: str, decision: Decision, cwd: str
+) -> None:
+    """Append a structured record to the enforcement telemetry log."""
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "session_id": session_id,
+        "tool": tool,
+        "cwd": cwd,
+        **asdict(decision),
+    }
+    with _locked_append(TELEMETRY_PATH) as fh:
+        fh.write(json.dumps(entry) + "\n")
+
+
+def _flow_required_for_session(session_id: str) -> bool:
+    """Check whether the UserPromptSubmit classifier flagged this session."""
+    safe = _safe_session_id(session_id)
+    if safe is None:
+        return False
+    marker = FLOW_REQUIRED_DIR / safe
+    return marker.exists()
+
+
+def _extract_text(content: object) -> str:
+    """Flatten Claude transcript message content into a single string."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, dict):
+                if "text" in item:
+                    parts.append(str(item["text"]))
+                elif item.get("type") == "tool_use":
+                    parts.append(f"<tool_use:{item.get('name', '')}>")
+            elif isinstance(item, str):
+                parts.append(item)
+        return "\n".join(parts)
+    return ""
+
+
+def _load_last_assistant_messages(transcript_path: str, n: int) -> list[str]:
+    """Read the last `n` assistant messages from a JSONL transcript."""
+    path = Path(transcript_path) if transcript_path else None
+    if path is None or not path.exists():
+        return []
+    messages: list[str] = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        if not line.strip():
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        role = record.get("role") or record.get("message", {}).get("role")
+        if role != "assistant":
+            continue
+        content = record.get("content")
+        if content is None:
+            content = record.get("message", {}).get("content")
+        text = _extract_text(content)
+        if text:
+            messages.append(text)
+    return messages[-n:]
+
+
+def _scan_markers(messages: list[str]) -> tuple[str | None, str | None]:
+    """Return (marker_found, phase_observed) across the given messages."""
+    marker_found: str | None = None
+    phase_observed: str | None = None
+    for text in messages:
+        if phase_observed is None:
+            phase_match = PHASE_RE.search(text)
+            if phase_match:
+                phase_observed = phase_match.group(0)
+        if marker_found is None:
+            if ROUTING_RE.search(text):
+                marker_found = "routing"
+            elif TRIVIAL_RE.search(text):
+                marker_found = "trivial"
+            elif PHASE_RE.search(text):
+                marker_found = "phase"
+    return marker_found, phase_observed
+
+
+def evaluate(
+    tool_name: str,
+    transcript_path: str,
+    session_id: str = "",
+    cwd: str = "",
+) -> Decision:
+    """Decide whether a tool call may proceed.
+
+    Returns a Decision. Caller is responsible for translating `allow=False`
+    into the appropriate hook exit code or permissionDecision output.
+    """
+    if tool_name not in GATED_TOOLS:
+        return Decision(allow=True, reason="tool-not-gated")
+
+    if not _feature_flag_on():
+        return Decision(allow=True, reason="feature-flag-off")
+
+    if _bypass_env_active():
+        _audit_bypass(session_id, tool_name, cwd)
+        return Decision(allow=True, reason="env-bypass", bypass_used=True)
+
+    if not _flow_required_for_session(session_id):
+        return Decision(allow=True, reason="classifier-did-not-match")
+
+    messages = _load_last_assistant_messages(transcript_path, ASSISTANT_WINDOW)
+    marker_found, phase_observed = _scan_markers(messages)
+
+    if marker_found is None:
+        return Decision(
+            allow=False,
+            reason="no-flow-marker-in-last-3-assistant-messages",
+            phase_observed=phase_observed,
+        )
+
+    return Decision(
+        allow=True,
+        reason=f"marker-found:{marker_found}",
+        marker_found=marker_found,
+        phase_observed=phase_observed,
+    )
+
+
+def mark_flow_required(session_id: str) -> None:
+    """Invoked by UserPromptSubmit when classifier matches creation intent."""
+    safe = _safe_session_id(session_id)
+    if safe is None:
+        return
+    FLOW_REQUIRED_DIR.mkdir(parents=True, exist_ok=True)
+    marker = FLOW_REQUIRED_DIR / safe
+    marker.write_text(datetime.now(timezone.utc).isoformat(), encoding="utf-8")
+
+
+def clear_flow_required(session_id: str) -> None:
+    """Clear the flow-required marker (end of session / rollout tooling)."""
+    safe = _safe_session_id(session_id)
+    if safe is None:
+        return
+    marker = FLOW_REQUIRED_DIR / safe
+    if marker.exists():
+        marker.unlink()

package/installer/adapters/claude-code.js

@@ -94,6 +94,19 @@ export default {
       { hooks: [hookEntry(hooksDir, "post-tool-use", 5)] },
     ];
 
+    // PreToolUse — Flow enforcement gate (gated by hooks.hardEnforcement
+    // feature flag in ~/.arkaos/config.json; no-op when flag is false).
+    settings.hooks.PreToolUse = [
+      { hooks: [hookEntry(hooksDir, "pre-tool-use", 10)] },
+    ];
+
+    // Stop — Flow completion validator (WARN mode in v2.20.0; promotion
+    // to STRICT mode is gated on ≥ 2 weeks of clean telemetry per ADR
+    // 2026-04-17-binding-flow-enforcement).
+    settings.hooks.Stop = [
+      { hooks: [hookEntry(hooksDir, "stop", 5)] },
+    ];
+
     // PreCompact — Session digest
     settings.hooks.PreCompact = [
       { hooks: [hookEntry(hooksDir, "pre-compact", 30)] },

package/installer/doctor.js

@@ -62,7 +62,19 @@ const checks = [
     name: "hooks-dir",
     description: "Hook scripts installed",
     severity: "fail",
-    check: () => existsSync(join(INSTALL_DIR, "config", "hooks", `user-prompt-submit${HOOK_EXT}`)),
+    check: () => {
+      const required = [
+        "session-start",
+        "user-prompt-submit",
+        "post-tool-use",
+        "pre-compact",
+        "cwd-changed",
+        "pre-tool-use",
+        "stop",
+      ];
+      const hooksDir = join(INSTALL_DIR, "config", "hooks");
+      return required.every((h) => existsSync(join(hooksDir, `${h}${HOOK_EXT}`)));
+    },
     fix: () => "Run: npx arkaos install --force",
   },
   {

package/installer/index.js

@@ -450,6 +450,8 @@ function installHooks(installDir) {
     "post-tool-use",
     "pre-compact",
     "cwd-changed",
+    "pre-tool-use",
+    "stop",
   ];
   const hookExt = HOOK_EXT;
 
@@ -481,6 +483,19 @@ function installHooks(installDir) {
       ok(`Hook: ${filename}`);
     }
   }
+
+  const srcLibDir = join(srcHooksDir, "_lib");
+  if (existsSync(srcLibDir)) {
+    const destLibDir = join(hooksDir, "_lib");
+    ensureDir(destLibDir);
+    cpSync(srcLibDir, destLibDir, { recursive: true });
+    try {
+      for (const f of readdirSync(destLibDir)) {
+        if (f.endsWith(".sh")) chmodSync(join(destLibDir, f), 0o755);
+      }
+    } catch {}
+    ok("Hook lib: _lib/");
+  }
 }
 
 // Safe directory iteration. Returns an empty array instead of throwing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.20.0",
+  "version": "2.20.1",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.20.0"
+version = "2.20.1"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}