arkaos 4.14.4 → 4.16.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-86 agents. 17 departments. 274 skills. Enterprise frameworks. Multi-runtime. One install.
+86 agents. 17 departments. 275 skills. Enterprise frameworks. Multi-runtime. One install.
 
 ```bash
 npx arkaos install
@@ -95,7 +95,7 @@ npx arkaos doctor    # Health check
 
 ### Skill packs, à la carte
 
-The default install ships a curated core so your context window stays lean. Everything else lives in the ArkaOS plugin marketplace: 16 department packs with 205 skills, generated straight from the same sources the core uses. Inside Claude Code:
+The default install ships a curated core so your context window stays lean. Everything else lives in the ArkaOS plugin marketplace: 16 department packs with 206 skills, generated straight from the same sources the core uses. Inside Claude Code:
 
 ```
 /plugin marketplace add andreagroferreira/arka-os

package/VERSION

@@ -1 +1 @@
-4.14.4
+4.16.0

package/arka/SKILL.md

@@ -25,7 +25,7 @@ measures citation compliance per turn.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 86 agents. 17 departments. 274 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 86 agents. 17 departments. 275 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/core/hooks/pre_tool_use.py

@@ -26,6 +26,7 @@ the specialist and flow gates via their ``messages=`` params.
 
 from __future__ import annotations
 
+import contextlib
 import sys
 from pathlib import Path
 
@@ -65,19 +66,26 @@ class _MessagesOnce:
     def __init__(self, transcript_path: str):
         self._path = transcript_path
         self._messages: list[str] | None = None
+        self._sidechain: bool | None = None
 
     def peek(self) -> list[str] | None:
         return self._messages
 
+    def sidechain_active(self) -> bool | None:
+        """Scope of the most recent assistant record; None before load()."""
+        return self._sidechain
+
     def load(self) -> list[str] | None:
         if self._messages is None:
             try:
-                from core.workflow.flow_enforcer import (
-                    _load_last_assistant_messages,
-                )
-                self._messages = _load_last_assistant_messages(
-                    self._path, _ASSISTANT_WINDOW
-                )
+                # Scope-aware since P0.2: the window counts MAIN-scope
+                # messages only, so interleaved subagent records cannot
+                # evict the routing marker; sidechain-ness feeds the
+                # specialist gate's persistence guard.
+                from core.workflow.transcript_scope import split_from_path
+                split = split_from_path(self._path)
+                self._messages = split.main[-_ASSISTANT_WINDOW:]
+                self._sidechain = split.active_sidechain
             except Exception:
                 return None
         return self._messages
@@ -104,10 +112,8 @@ def _kb_gate(root: str, tool_name: str, session_id: str, query: str) -> int | No
     decision = evaluate_research_gate(
         tool_name=tool_name, session_id=session_id, query=query
     )
-    try:
+    with contextlib.suppress(Exception):
         record_telemetry(session_id=session_id, tool=tool_name, decision=decision)
-    except Exception:
-        pass
     if not decision.allow:
         return _deny(decision.to_stderr_message())
     if decision.nudge and decision.to_stderr_message():
@@ -150,8 +156,9 @@ def _specialist_gate(
         cwd=cwd,
         tool_input=tool_input,
         messages=shared,
+        is_sidechain=messages.sidechain_active(),
     )
-    try:
+    with contextlib.suppress(Exception):
         record_telemetry(
             session_id=session_id,
             tool=tool_name,
@@ -160,8 +167,6 @@ def _specialist_gate(
             target_file=str(tool_input.get("file_path", "")),
             model_requested=str(tool_input.get("model", "")),
         )
-    except Exception:
-        pass
     if not decision.allow:
         return _deny(decision.to_stderr_message())
     return None
@@ -206,10 +211,8 @@ def _frontend_gate(
         tool_input=tool_input,
         messages=messages.load(),
     )
-    try:
+    with contextlib.suppress(Exception):
         record_telemetry(session_id=session_id, tool=tool_name, decision=decision)
-    except Exception:
-        pass
     if not decision.allow:
         return _deny(decision.to_stderr_message())
     if decision.to_stderr_message():
@@ -259,12 +262,10 @@ def _flow_gate(
         # env bypass, classifier flag, marker cache) before reading.
         messages=messages.peek(),
     )
-    try:
+    with contextlib.suppress(Exception):
         record_telemetry(
             session_id=session_id, tool=tool_name, decision=decision, cwd=cwd
         )
-    except Exception:
-        pass
     if decision.allow:
         # Grace path: allow, but surface the non-blocking warning so the
         # operator sees the routing nudge instead of a silent pass.
@@ -326,4 +327,4 @@ if __name__ == "__main__":
     except Exception:
         # Fail open — the bash version piped every heredoc through
         # `2>/dev/null` and exited 0 on internal errors.
-        raise SystemExit(0)
+        raise SystemExit(0) from None

package/core/workflow/specialist_authorization.py

@@ -0,0 +1,140 @@
+"""Persistent per-session persona — closes the specialist gate fail-open.
+
+The specialist gate reads the persona from the last ``[arka:routing]`` /
+``[arka:dispatch]`` marker in a 20-message window. When the marker rolls
+out of the window the gate returned ALLOW (``no-routing-tag``) — 4,093
+of 5,683 telemetry records (72%). Routing once and hammering the gate
+with 20 messages of noise was a winning strategy.
+
+Fix mirrors ``design_authorization`` (#297, frontend gate): **persist on
+observe, consult before allow**. Whenever ``evaluate`` sees a marker in
+the window it confirms the resolved persona here; when the window shows
+nothing, a valid persisted persona for the session decides exactly as if
+the marker were still visible — including deciding BLOCK.
+
+Two deliberate properties:
+
+- **The record is keyed by session_id AND the transcript file's name.**
+  A dispatched subagent runs on its own transcript (ADR
+  2026-05-28-specialist-dispatch-subagent-blindspot), so it can never
+  inherit the parent's persisted persona and be blocked from the very
+  files it was dispatched to write — even if it shares the session_id.
+- **A session that never routed stays un-restored** (``never-routed``
+  keeps today's ALLOW): this module only closes the eviction hole; the
+  hard flip for never-routed sessions is a separate, telemetry-gated
+  decision.
+
+State dir: ``/tmp/arkaos-specialist-auth`` (override via
+``ARKA_SPECIALIST_AUTH_DIR``).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+import time
+from pathlib import Path
+
+from core.shared import safe_session_id as _safe_session_id_module
+from core.shared.temp_paths import arkaos_temp_dir
+
+_safe_session_id = _safe_session_id_module.safe_session_id
+
+# A working session; a stale /tmp record expires on its own.
+DEFAULT_TTL_SECONDS = 12 * 60 * 60
+
+
+def _base_dir() -> Path:
+    override = os.environ.get("ARKA_SPECIALIST_AUTH_DIR", "").strip()
+    return Path(override) if override else arkaos_temp_dir(
+        "arkaos-specialist-auth"
+    )
+
+
+def _auth_path(session_id: str) -> Path | None:
+    safe = _safe_session_id(session_id)
+    return (_base_dir() / f"{safe}.json") if safe else None
+
+
+def _read(path: Path | None) -> dict:
+    if path is None or not path.exists():
+        return {}
+    try:
+        # errors="replace", like transcript_scope: a non-UTF8 byte in an
+        # operator-writable /tmp file must degrade to "no record", never
+        # raise through evaluate() into the hook's exit-0 (QG redo 3 —
+        # an uncaught UnicodeDecodeError WAS a silent gate bypass).
+        raw = path.read_text(encoding="utf-8", errors="replace")
+        data = json.loads(raw)
+    except (ValueError, OSError):  # JSONDecodeError/UnicodeDecodeError ⊂ ValueError
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def confirm(
+    session_id: str,
+    transcript_path: str,
+    persona: str,
+    marker: str,
+    persona_raw: str | None = None,
+    alias_resolved: bool = False,
+) -> None:
+    """Persist the persona observed in the window (marker seen)."""
+    if not persona or not transcript_path:
+        return
+    path = _auth_path(session_id)
+    if path is None:
+        return
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps({
+                "persona": persona,
+                "marker": marker,
+                "persona_raw": persona_raw,
+                "alias_resolved": bool(alias_resolved),
+                "transcript": Path(transcript_path).name,
+                "confirmed_ts": time.time(),
+            }),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass  # authorization state must never block the hook
+
+
+def confirmed(
+    session_id: str,
+    transcript_path: str,
+    ttl_seconds: int = DEFAULT_TTL_SECONDS,
+) -> dict | None:
+    """Return the persisted persona record, or None.
+
+    None unless: record exists, TTL holds, the persona is non-empty AND
+    the record was written for THIS transcript file — the property that
+    keeps a parent's persona out of a subagent's evaluation.
+    """
+    if not transcript_path:
+        return None
+    data = _read(_auth_path(session_id))
+    ts = data.get("confirmed_ts")
+    # isinstance, not float(): a string in a corrupt-but-valid JSON would
+    # raise straight through evaluate() — the same silent-bypass class as
+    # the non-UTF8 hole (QG redo 3).
+    if not isinstance(ts, (int, float)) or time.time() - ts > ttl_seconds:
+        return None
+    if data.get("transcript") != Path(transcript_path).name:
+        return None
+    persona = data.get("persona")
+    if not isinstance(persona, str) or not persona:
+        return None
+    return data
+
+
+def clear(session_id: str) -> None:
+    """Remove authorization state for a session (tests / session end)."""
+    path = _auth_path(session_id)
+    if path is None:
+        return
+    with contextlib.suppress(FileNotFoundError, OSError):
+        path.unlink()

package/core/workflow/specialist_enforcer.py

@@ -13,13 +13,25 @@ Used bypasses are logged to telemetry for accountability.
 Feature flag: `hooks.specialistEnforcement` in ~/.arkaos/config.json.
 
 Architectural note (per ADR 2026-05-28-specialist-dispatch-subagent-
-blindspot): the enforcer is a NEGATIVE gate on the parent transcript
-only. Subagent writes pass through as `no-routing-tag` because Claude
+blindspot, amended by P0.2): the enforcer is a NEGATIVE gate on the
+parent transcript only. Subagent writes pass through because Claude
 Code isolates subagent transcripts from the parent. The positive
 `owner-match` path is exercised when the parent emits `[arka:dispatch]`
 inline (e.g., the orchestrator impersonating a specialist) and remains
 for forward compatibility if parent-transcript visibility ever ships.
 
+Fail-open closed (P0.2): a marker that rolls out of the 20-message
+window no longer reopens the gate — the persona observed in the window
+is persisted per session+transcript (specialist_authorization) and
+restored when the window shows nothing, deciding exactly as if the
+marker were visible. The old blanket `no-routing-tag` (72% of all
+telemetry) splits into `never-routed` (session never emitted a marker;
+still ALLOW — hardening THAT is a separate, telemetry-gated decision)
+and `subagent-scope` (sidechain evaluation; ADR behavior, now
+measurable). The window itself counts main-scope messages only
+(transcript_scope), so interleaved subagent records cannot evict the
+marker.
+
 Read by: config/hooks/pre-tool-use.sh between the KB-gate and the
 flow-gate. Same Decision JSON contract as core.workflow.flow_enforcer.
 """
@@ -36,7 +48,7 @@ from pathlib import Path
 import yaml
 
 from core.shared import safe_session_id as _safe_session_id_module
-from core.workflow.flow_enforcer import _load_last_assistant_messages
+from core.workflow import specialist_authorization, transcript_scope
 
 try:
     import fcntl  # POSIX only
@@ -120,6 +132,12 @@ class Decision:
     # "frontend-dev" — record both so telemetry can prove the fix.
     persona_raw: str | None = None
     alias_resolved: bool = False
+    # Fail-open taxonomy (P0.2): where the persona came from ("window" |
+    # "persisted" | ""), whether the ACTIVE scope is a sidechain, and how
+    # far the marker sits from the window's end (None = not in window).
+    persona_source: str = ""
+    is_sidechain: bool = False
+    msgs_since_marker: int | None = None
 
     def to_stderr_message(self) -> str:
         """The message a blocked session reads.
@@ -148,8 +166,10 @@ class Decision:
             f"    [arka:dispatch] {persona} -> {owner}\n"
             f"    Task(subagent_type=\"{owner}\", prompt=\"<what you were "
             f"about to write>\")\n"
-            f"Audited exception (visible to the operator in "
-            f"`/arka enforcement`) — ONLY if no specialist can do this:\n"
+            f"Audited exception (visible to the operator in the "
+            f"specialist-dispatch telemetry: `arka-py -m "
+            f"core.governance.specialist_telemetry_cli today`) — ONLY if "
+            f"no specialist can do this:\n"
             f"    [arka:specialist-bypass owner={owner} reason=<24+ chars "
             f"explaining why a specialist cannot>]"
         )
@@ -172,6 +192,11 @@ class _Ctx:
     alias_resolved: bool = False
     config: dict = field(default_factory=dict)
     preloaded_messages: list[str] | None = None
+    persona_source: str = ""
+    # None = self-detect from the transcript; the consolidated hook passes
+    # the value it computed while parsing (parse-once contract, PR-6).
+    is_sidechain: bool | None = None
+    msgs_since_marker: int | None = None
 
 
 # ─── Config + Ownership loaders ────────────────────────────────────────
@@ -392,6 +417,15 @@ def _is_lead_allowed(file_path: str, patterns: list[str]) -> bool:
 # ─── Pipeline stages (B1 refactor) ─────────────────────────────────────
 
 
+def _scope_fields(ctx: _Ctx) -> dict:
+    """The P0.2 taxonomy fields every post-populate Decision carries."""
+    return {
+        "persona_source": ctx.persona_source,
+        "is_sidechain": bool(ctx.is_sidechain),
+        "msgs_since_marker": ctx.msgs_since_marker,
+    }
+
+
 def _check_tool_gated(ctx: _Ctx) -> Decision | None:
     if ctx.tool_name not in GATED_TOOLS:
         return Decision(allow=True, reason="tool-not-gated")
@@ -404,8 +438,15 @@ def _check_feature_flag(ctx: _Ctx) -> Decision | None:
     return None
 
 
+def _msgs_since_marker(messages: list[str]) -> int | None:
+    for i, text in enumerate(reversed(messages)):
+        if DISPATCH_RE.search(text) or ROUTING_RE.search(text):
+            return i
+    return None
+
+
 def _populate_context(ctx: _Ctx) -> None:
-    """Extract file_path, load ownership config, load + resolve transcript."""
+    """Extract file_path, load ownership, resolve persona (P0.2 fail-open)."""
     if ctx.tool_input and isinstance(ctx.tool_input, dict):
         ctx.file_path = str(
             ctx.tool_input.get("file_path")
@@ -416,18 +457,55 @@ def _populate_context(ctx: _Ctx) -> None:
     if ctx.preloaded_messages is not None:
         ctx.messages = ctx.preloaded_messages[-ASSISTANT_WINDOW:]
     else:
-        ctx.messages = _load_last_assistant_messages(
-            ctx.transcript_path, ASSISTANT_WINDOW
-        )
+        split = transcript_scope.split_from_path(ctx.transcript_path)
+        ctx.messages = split.main[-ASSISTANT_WINDOW:]
+        if ctx.is_sidechain is None:
+            ctx.is_sidechain = split.active_sidechain
+    ctx.is_sidechain = bool(ctx.is_sidechain)
+    _resolve_or_restore_persona(ctx)
+
+
+def _resolve_or_restore_persona(ctx: _Ctx) -> None:
+    """Persist-on-observe + consult-before-allow (P0.2, mirrors #297).
+
+    Marker in the window -> persist the resolved persona. Window empty of
+    markers -> a valid persisted persona for THIS session+transcript
+    decides as if the marker were still visible — including deciding
+    BLOCK. Sidechain evaluations never consult the parent's persistence
+    (the dispatched specialist must keep writing with no block, per the
+    ADR).
+    """
     ctx.persona, ctx.marker, ctx.persona_raw, ctx.alias_resolved = (
         _resolve_persona(ctx.messages)
     )
+    if ctx.persona is not None:
+        ctx.persona_source = "window"
+        ctx.msgs_since_marker = _msgs_since_marker(ctx.messages)
+        specialist_authorization.confirm(
+            ctx.session_id, ctx.transcript_path,
+            persona=ctx.persona, marker=ctx.marker or "",
+            persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved,
+        )
+    elif not ctx.is_sidechain:
+        restored = specialist_authorization.confirmed(
+            ctx.session_id, ctx.transcript_path
+        )
+        if restored:
+            ctx.persona = restored["persona"]
+            ctx.marker = restored.get("marker") or None
+            ctx.persona_raw = restored.get("persona_raw")
+            ctx.alias_resolved = bool(restored.get("alias_resolved"))
+            ctx.persona_source = "persisted"
 
 
 def _check_no_persona(ctx: _Ctx) -> Decision | None:
     if ctx.persona is None:
+        # Taxonomy (P0.2): the old blanket "no-routing-tag" (72% of all
+        # telemetry) splits into what actually happened.
+        reason = "subagent-scope" if ctx.is_sidechain else "never-routed"
         return Decision(
-            allow=True, reason="no-routing-tag", target_file=ctx.file_path,
+            allow=True, reason=reason, target_file=ctx.file_path,
+            **_scope_fields(ctx),
         )
     return None
 
@@ -438,7 +516,7 @@ def _check_c_suite(ctx: _Ctx) -> Decision | None:
         return Decision(
             allow=True, reason="c-suite-override",
             current_persona=ctx.persona, marker_found=ctx.marker,
-            target_file=ctx.file_path,
+            target_file=ctx.file_path, **_scope_fields(ctx),
         )
     return None
 
@@ -449,7 +527,7 @@ def _check_lead_allowed_file(ctx: _Ctx) -> Decision | None:
         return Decision(
             allow=True, reason="lead-allowed-file",
             current_persona=ctx.persona, marker_found=ctx.marker,
-            target_file=ctx.file_path,
+            target_file=ctx.file_path, **_scope_fields(ctx),
         )
     return None
 
@@ -461,7 +539,7 @@ def _decide_open_access(
     return Decision(
         allow=True, reason=reason, current_persona=ctx.persona,
         marker_found=ctx.marker, target_file=ctx.file_path,
-        required_owners=owners,
+        required_owners=owners, **_scope_fields(ctx),
     )
 
 
@@ -470,7 +548,8 @@ def _decide_owner_match(ctx: _Ctx, owners: list[str]) -> Decision:
         allow=True, reason=f"owner-match:{ctx.persona}",
         current_persona=ctx.persona, marker_found=ctx.marker,
         target_file=ctx.file_path,
-        persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved, required_owners=owners,
+        persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved,
+        required_owners=owners, **_scope_fields(ctx),
     )
 
 
@@ -479,8 +558,9 @@ def _decide_bypass(ctx: _Ctx, owners: list[str], reason: str) -> Decision:
         allow=True, reason="bypass-with-reason",
         current_persona=ctx.persona, marker_found=ctx.marker,
         target_file=ctx.file_path,
-        persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved, required_owners=owners,
-        bypass_used=True, bypass_reason=reason,
+        persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved,
+        required_owners=owners, bypass_used=True, bypass_reason=reason,
+        **_scope_fields(ctx),
     )
 
 
@@ -491,7 +571,8 @@ def _decide_block(ctx: _Ctx, owners: list[str]) -> Decision:
         reason=f"lead-blocked:{ctx.persona}-not-in-[{','.join(owners_lower)}]",
         current_persona=ctx.persona, marker_found=ctx.marker,
         target_file=ctx.file_path,
-        persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved, required_owners=owners,
+        persona_raw=ctx.persona_raw, alias_resolved=ctx.alias_resolved,
+        required_owners=owners, **_scope_fields(ctx),
     )
 
 
@@ -516,7 +597,7 @@ def _resolve_ownership_outcome(ctx: _Ctx) -> Decision:
         return Decision(
             allow=True, reason="no-ownership-rule",
             current_persona=ctx.persona, marker_found=ctx.marker,
-            target_file=ctx.file_path,
+            target_file=ctx.file_path, **_scope_fields(ctx),
         )
     return _resolve_with_owners(ctx, owners, rule_reason)
 
@@ -531,16 +612,19 @@ def evaluate(
     cwd: str = "",
     tool_input: dict | None = None,
     messages: list[str] | None = None,
+    is_sidechain: bool | None = None,
 ) -> Decision:
     """Decide whether a Write/Edit/MultiEdit/NotebookEdit may proceed.
 
     ``messages`` (PR-6 hook consolidation): pre-parsed assistant messages;
     when None the transcript is read from ``transcript_path``.
+    ``is_sidechain`` (P0.2): the active scope, when the caller computed it
+    while parsing; None self-detects (only possible without ``messages``).
     """
     ctx = _Ctx(
         tool_name=tool_name, transcript_path=transcript_path,
         session_id=session_id, cwd=cwd, tool_input=tool_input or {},
-        preloaded_messages=messages,
+        preloaded_messages=messages, is_sidechain=is_sidechain,
     )
     for early_check in (_check_tool_gated, _check_feature_flag):
         decision = early_check(ctx)

package/core/workflow/transcript_scope.py

@@ -0,0 +1,74 @@
+"""Scope-aware transcript reading — the sidechain guard (specialist P0.2).
+
+The specialist gate's 20-message window was counted over EVERY assistant
+record in the JSONL. Two scope leaks follow:
+
+- where a harness interleaves subagent (sidechain) records into the same
+  transcript, a burst of subagent activity evicts the routing marker and
+  reopens the fail-open the persisted-persona fix exists to close;
+- the persisted persona itself must never cross scopes — a dispatched
+  specialist evaluated under the PARENT's persisted persona would be
+  blocked from the very files it was dispatched to write.
+
+This module splits a transcript into main-scope and sidechain-scope
+assistant messages and reports which scope is ACTIVE (the scope of the
+most recent assistant record — at PreToolUse time, the agent whose tool
+call is being judged). Parsing mirrors
+``flow_enforcer._load_last_assistant_messages`` exactly; records without
+an ``isSidechain`` field are main-scope, so a transcript that predates
+the field behaves as before.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from core.workflow.flow_enforcer import _extract_text
+
+
+@dataclass
+class ScopeSplit:
+    """Assistant messages of a transcript, separated by scope."""
+
+    main: list[str] = field(default_factory=list)
+    sidechain: list[str] = field(default_factory=list)
+    active_sidechain: bool = False
+
+
+def split_by_scope(raw_text: str) -> ScopeSplit:
+    """Split raw JSONL transcript text into main/sidechain scopes."""
+    split = ScopeSplit()
+    for line in raw_text.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 not text:
+            continue
+        side = bool(record.get("isSidechain", False))
+        (split.sidechain if side else split.main).append(text)
+        split.active_sidechain = side
+    return split
+
+
+def split_from_path(transcript_path: str) -> ScopeSplit:
+    """Read and split a transcript file; any failure is an empty split."""
+    path = Path(transcript_path) if transcript_path else None
+    if path is None or not path.exists():
+        return ScopeSplit()
+    try:
+        raw = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ScopeSplit()
+    return split_by_scope(raw)