arkaos 4.48.0 → 4.49.0

package/README.md

@@ -2,7 +2,7 @@
 
 **The Operating System for AI Agent Teams.**
 
-89 agents. 17 departments. 332 skills. Enterprise frameworks. Multi-runtime. One install.
+89 agents. 17 departments. 333 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 258 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 259 skills, generated straight from the same sources the core uses. Inside Claude Code:
 
 ```
 /plugin marketplace add andreagroferreira/arka-os

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v4.48.0 — 89 agents, 17 departments, 332 skills, 297 commands, 19 ADRs.
+> v4.49.0 — 89 agents, 17 departments, 333 skills, 298 commands, 19 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is
@@ -45,7 +45,7 @@ answers as a generic assistant.
 | `/do` | 1 |
 | `/ecom` | 18 |
 | `/fin` | 10 |
-| `/kb` | 22 |
+| `/kb` | 23 |
 | `/landing` | 17 |
 | `/lead` | 10 |
 | `/mkt` | 30 |

package/VERSION

@@ -1 +1 @@
-4.48.0
+4.49.0

package/arka/SKILL.md

@@ -47,7 +47,7 @@ complementary, not alternatives.
 # ArkaOS — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**
-> 89 agents. 17 departments. 332 skills. Multi-runtime. Dashboard. Knowledge RAG.
+> 89 agents. 17 departments. 333 skills. Multi-runtime. Dashboard. Knowledge RAG.
 
 ## ⛔ Evidence flow — 4 gates (NON-NEGOTIABLE)
 

package/config/hooks/_lib/fastpath/engine.cjs

@@ -152,6 +152,28 @@ function hardEnforcementOn(configResult, manifest) {
   return pythonTruthy(hooks[key]);
 }
 
+/** flow_enforcer.shadow_deny_on (PR-A5a): DEFAULT ON — missing config
+ *  file, corrupt JSON, or missing key all mean ON; an explicit value is
+ *  python-truthy. A missing MANIFEST entry (old manifest + new engine,
+ *  mid-upgrade only) also means ON: delegation is the
+ *  degrade-to-latency direction, never a skipped state write. */
+function shadowDenyOn(configResult, manifest) {
+  const spec = manifest.flags && manifest.flags.shadowDeny;
+  if (!spec) return true;
+  if (configResult.state !== "ok") return true;
+  const [section, key] = spec.path;
+  const data = configResult.data;
+  const hooks =
+    data && typeof data === "object" && !Array.isArray(data)
+      ? data[section]
+      : null;
+  if (!hooks || typeof hooks !== "object" || Array.isArray(hooks)) {
+    return true;
+  }
+  if (!(key in hooks)) return true;
+  return pythonTruthy(hooks[key]);
+}
+
 function telemetryLine(prefix, template, now) {
   return JSON.stringify({ ...prefix, ...template }) + "\n";
 }
@@ -319,16 +341,17 @@ function decidePost(payload, manifest, ctx) {
   }
 
   // Q6/Q7 — the only remaining Python work on this path is the flow-auth
-  // confirm rescan. Redundant when enforcement is off (the pre-side flag
-  // check short-circuits before ever reading auth) or when a confirmed
-  // auth is fresh; load-bearing otherwise (GRACE_CAP exhaustion) →
-  // delegate.
+  // confirm rescan. Load-bearing when hard enforcement OR shadow-deny
+  // (PR-A5a) consumes the grace/confirm state — without the rescan the
+  // shadow grace ladder overstates would_block; redundant only when
+  // both are off or a confirmed auth is fresh → delegate otherwise.
   const sid = String(payload.session_id || "");
   const enforcementOff =
     ctx.config.state !== "missing"
       ? !hardEnforcementOn(ctx.config, manifest)
       : true; // missing config file → flag definitively false
-  if (!enforcementOff && !flowAuthFresh(sid, manifest, ctx)) {
+  const shadowOn = shadowDenyOn(ctx.config, manifest);
+  if ((!enforcementOff || shadowOn) && !flowAuthFresh(sid, manifest, ctx)) {
     return { action: "delegate", reason: "flow-auth-not-fresh" };
   }
 
@@ -369,6 +392,7 @@ module.exports = {
   pythonTruthy,
   readJsonFile,
   safeSessionId,
+  shadowDenyOn,
   toolText,
   validateManifest,
 };

package/config/hooks/gate-manifest.json

@@ -605,6 +605,16 @@
         "hooks",
         "hardEnforcement"
       ]
+    },
+    "shadowDeny": {
+      "coercion": "python-truthy",
+      "on_corrupt": true,
+      "on_missing_file": true,
+      "on_missing_key": true,
+      "path": [
+        "hooks",
+        "shadowDeny"
+      ]
     }
   },
   "home_paths": {
@@ -675,7 +685,10 @@
       "marker_found": null,
       "phase_observed": null,
       "reason": "tool-not-gated",
-      "warning": ""
+      "shadow_ms": 0.0,
+      "shadow_reason": "",
+      "warning": "",
+      "would_block": false
     },
     "kb_first_prefix_keys": [
       "ts",

package/core/hooks/gate_manifest.py

@@ -249,6 +249,18 @@ def _flags_and_budget() -> dict:
             "on_corrupt": False,
             "coercion": "python-truthy",
         },
+        "shadowDeny": {
+            "path": ["hooks", "shadowDeny"],
+            # flow_enforcer.shadow_deny_on: DEFAULT ON — missing file,
+            # corrupt JSON, or missing key all mean ON (PR-A5a telemetry
+            # collects by default); an explicit value is python-truthy.
+            # The engine additionally treats a MISSING MANIFEST ENTRY as
+            # ON: delegation is the degrade-to-latency direction.
+            "on_missing_file": True,
+            "on_corrupt": True,
+            "on_missing_key": True,
+            "coercion": "python-truthy",
+        },
         "budget": {
             "section": "budget",
             "cap_keys": ["hardCapUsd", "dailyCapUsd"],

package/core/hooks/post_tool_use.py

@@ -685,7 +685,36 @@ def _enqueue_cognition_capture(session_id: str, tool_text: str) -> None:
 # ─── Section 10: metrics ─────────────────────────────────────────────────
 
 
-def _log_metrics(duration_ms: int) -> None:
+def _shadow_attribution() -> dict:
+    """PR-A5a: label this (delegated) run with the flag states. The
+    labels partition by FLAG STATE only — stateful-tool and error-turn
+    delegations carry the same flags — so the shadow-forced population
+    is isolated by combining them with the ``delegation`` field
+    (``_delegation_kind``): enforcement=false, shadow=true,
+    delegation="benign" is the flow-auth rescan population that only
+    reaches Python because of shadow-deny (engine.cjs Q6), plus the
+    negligible direct-invocation/fastpath-off runs. Empty on stripped
+    installs."""
+    try:
+        from core.workflow.flow_enforcer import _feature_flag_on, shadow_deny_on
+        return {"enforcement": _feature_flag_on(), "shadow": shadow_deny_on()}
+    except Exception:
+        return {}
+
+
+def _delegation_kind(stdin_json: dict, tool_name: str, benign: bool) -> str:
+    """Why this run reached Python, derived from the payload in the same
+    precedence the shim decides delegation (engine.cjs decidePost:
+    failure event, then the stateful set, then the error trigger —
+    everything else on this path is the Q6 flow-auth rescan)."""
+    if get_str(stdin_json, "hook_event_name") == "PostToolUseFailure":
+        return "error"
+    if tool_name in ("ExitPlanMode", "Task", "Agent"):
+        return "stateful"
+    return "benign" if benign else "error"
+
+
+def _log_metrics(duration_ms: int, attribution: dict | None = None) -> None:
     metrics_file = Path.home() / ".arkaos" / "hook-metrics.json"
     lock_file = Path.home() / ".arkaos" / "hook-metrics.lock"
     metrics_file.parent.mkdir(parents=True, exist_ok=True)
@@ -706,6 +735,7 @@ def _log_metrics(duration_ms: int) -> None:
                     "hook": "post-tool-use",
                     "duration_ms": duration_ms,
                     "timestamp": now,
+                    **(attribution or {}),
                 })
                 tmp = metrics_file.with_suffix(".json.tmp")
                 tmp.write_text(json.dumps(entries[-500:]), encoding="utf-8")
@@ -776,9 +806,17 @@ def main(stdin_json: dict | None = None) -> int:
             _record_pattern_stub(tool_text, prompt)
         _record_activation(subagent_type, session_id)
 
-    # Only process further if there was an error signal (same early exit
-    # as the bash version — violations/metrics only run on error turns).
+    # Only process violations/gotchas further on error turns (same early
+    # exit as the bash version). Metrics ARE logged here first: benign
+    # turns are exactly where the shadow-forced flow-auth delegations
+    # live — skipping them left the kill-switch population unrecorded
+    # (QG r2, Eduardo B1 + Francisca B3).
     if exit_code in ("0", "") and not _ERROR_TRIGGER_RE.search(tool_text):
+        _log_metrics(
+            int((time.monotonic() - start) * 1000),
+            {**_shadow_attribution(),
+             "delegation": _delegation_kind(stdin_json, tool_name, True)},
+        )
         print("{}")
         return 0
 
@@ -802,7 +840,11 @@ def main(stdin_json: dict | None = None) -> int:
     )
 
     _enqueue_cognition_capture(session_id, tool_text)
-    _log_metrics(int((time.monotonic() - start) * 1000))
+    _log_metrics(
+        int((time.monotonic() - start) * 1000),
+        {**_shadow_attribution(),
+         "delegation": _delegation_kind(stdin_json, tool_name, False)},
+    )
 
     if violation_msg:
         # The runtime drops context whose hookEventName differs from the

package/core/hooks/pre_tool_use.py

@@ -28,6 +28,7 @@ from __future__ import annotations
 
 import contextlib
 import sys
+import time
 from pathlib import Path
 
 from core.hooks._shared import (
@@ -55,7 +56,8 @@ def _query_hint(tool_input: dict) -> str:
 
 
 class _MessagesOnce:
-    """Parse the transcript at most once, lazily, across both gates.
+    """Parse the transcript at most once, lazily, across the gates
+    (specialist, frontend and flow all consume the same instance).
 
     ``peek()`` never triggers a read — gates that have their own cheaper
     early-outs (feature flag off, marker-cache hit) pass ``peek()`` so the
@@ -67,6 +69,7 @@ class _MessagesOnce:
         self._path = transcript_path
         self._messages: list[str] | None = None
         self._sidechain: bool | None = None
+        self._load_ms: float = 0.0
 
     def peek(self) -> list[str] | None:
         return self._messages
@@ -75,8 +78,19 @@ class _MessagesOnce:
         """Scope of the most recent assistant record; None before load()."""
         return self._sidechain
 
+    def consume_load_ms(self) -> float:
+        """The parse cost in ms, claimable ONCE (PR-A5a shadow timing).
+
+        The parse a shadow evaluation forces happens here, outside every
+        gate's own timer — the first shadow caller claims it into its
+        Decision.shadow_ms; subsequent callers get 0.0 so the cost is
+        never double-attributed."""
+        elapsed, self._load_ms = self._load_ms, 0.0
+        return elapsed
+
     def load(self) -> list[str] | None:
         if self._messages is None:
+            start = time.perf_counter()
             try:
                 # Scope-aware since P0.2: the window counts MAIN-scope
                 # messages only, so interleaved subagent records cannot
@@ -88,6 +102,10 @@ class _MessagesOnce:
                 self._sidechain = split.active_sidechain
             except Exception:
                 return None
+            finally:
+                self._load_ms = round(
+                    (time.perf_counter() - start) * 1000, 3
+                )
         return self._messages
 
 
@@ -121,6 +139,17 @@ def _kb_gate(root: str, tool_name: str, session_id: str, query: str) -> int | No
     return None
 
 
+def _claim_parse_cost(decision, messages: _MessagesOnce) -> None:
+    """Attribute the parse a shadow evaluation forced (QG r1, Francisca
+    B2): the load ran outside the gate's timer, so the first shadow
+    decision claims it — consume_load_ms() returns 0.0 when another
+    gate already did, or when enforcement (not shadow) paid for it."""
+    if decision.shadow_reason:
+        decision.shadow_ms = round(
+            decision.shadow_ms + messages.consume_load_ms(), 3
+        )
+
+
 def _specialist_gate(
     root: str,
     tool_name: str,
@@ -137,6 +166,7 @@ def _specialist_gate(
     if not module_path.is_file():
         return None
     try:
+        from core.workflow.flow_enforcer import shadow_deny_on
         from core.workflow.specialist_enforcer import (
             _feature_flag_on,
             evaluate,
@@ -145,9 +175,11 @@ def _specialist_gate(
     except Exception:
         return None  # specialist-import-failed → allow
     # Load (and share) the transcript only when the gate will actually
-    # scan it — flag-off sessions keep the zero-read fast path.
+    # scan it — flag-off sessions with the shadow kill-switch thrown
+    # keep the zero-read fast path; shadow sessions share ONE parse
+    # across the specialist, frontend and flow gates (PR-A5a).
     shared = messages.peek()
-    if shared is None and _feature_flag_on():
+    if shared is None and (_feature_flag_on() or shadow_deny_on()):
         shared = messages.load()
     decision = evaluate(
         tool_name=tool_name,
@@ -158,6 +190,7 @@ def _specialist_gate(
         messages=shared,
         is_sidechain=messages.sidechain_active(),
     )
+    _claim_parse_cost(decision, messages)
     with contextlib.suppress(Exception):
         record_telemetry(
             session_id=session_id,

package/core/workflow/flow_enforcer.py

@@ -16,12 +16,15 @@ Design contract:
 - Gated tool list is closed: anything outside it is always allowed.
 """
 
+import contextlib
 import json
 import os
 import re
+import time
 from contextlib import contextmanager
 from dataclasses import asdict, dataclass
-from datetime import datetime, timezone
+from datetime import UTC, datetime
+from functools import lru_cache
 from pathlib import Path
 
 from core.shared import safe_session_id as _safe_session_id_module
@@ -51,10 +54,8 @@ def _locked_append(path: Path):
         yield fh
     finally:
         if _HAS_FLOCK:
-            try:
+            with contextlib.suppress(OSError):
                 fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
-            except OSError:
-                pass
         fh.close()
 
 # PR11 v2.33.0 — Discovery vs Effect tool taxonomy (Conclave Phase 5).
@@ -107,7 +108,7 @@ _BASH_DISCOVERY_FIRST: frozenset[str] = frozenset({
     "shopt", "trap", "wait", "eval", "exec",
     # Test runners (read state but don't mutate canonical files)
     "pytest", "jest", "vitest", "phpunit", "pest", "rspec", "mocha",
-    "go", "cargo",
+    "cargo",
 })
 
 # Bash classifier — patterns that indicate mutation (anywhere in command).
@@ -182,10 +183,8 @@ def bash_is_effect(command: str) -> bool:
         first = first_tokens[0] if first_tokens else ""
     if not first:
         return False
-    if first in _BASH_DISCOVERY_FIRST:
-        return False
-    # Unknown command — default to requiring routing.
-    return True
+    # Unknown commands default to requiring routing.
+    return first not in _BASH_DISCOVERY_FIRST
 
 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)
@@ -227,6 +226,17 @@ class Decision:
     # Interaction Reform PR3 — plan-approval telemetry (WARN phase):
     # "approved" | "missing" | "no-plan" | "unknown" | "" (not gated).
     approval_state: str = ""
+    # PR-A5a shadow-deny: with hardEnforcement off, the gate still runs
+    # and records what it WOULD have decided. `would_block` is True when
+    # enforcement would have denied; `shadow_reason` carries the inner
+    # decision's reason (shadow ran iff it is non-empty); `shadow_ms`
+    # (float, sub-ms preserved) measures the added evaluation cost for
+    # the pre-side p90 kill-switch criterion — the post-side cost is
+    # attributed separately in hook-metrics.json (see wiki/16). All
+    # three stay at their defaults on enforced paths.
+    would_block: bool = False
+    shadow_reason: str = ""
+    shadow_ms: float = 0.0
 
     def to_stderr_message(self) -> str:
         if self.allow:
@@ -257,13 +267,37 @@ def _feature_flag_on() -> bool:
     return bool(data.get("hooks", {}).get("hardEnforcement", False))
 
 
+@lru_cache(maxsize=1)
+def shadow_deny_on() -> bool:
+    """``hooks.shadowDeny`` — the shadow-telemetry kill-switch (PR-A5a).
+
+    DEFAULT ON: a missing config file, corrupt or undecodable JSON, or a
+    missing key all mean ON (the telemetry that gates the A5b flip
+    collects by default); only an explicit falsy value turns it off.
+    Mirrored by engine.cjs ``shadowDenyOn`` via the gate manifest — keep
+    the two in lockstep. Cached per process (each hook invocation is a
+    fresh interpreter, so the cache scope is one tool call; tests call
+    ``shadow_deny_on.cache_clear()`` after rewriting the config).
+    """
+    if not CONFIG_PATH.exists():
+        return True
+    try:
+        data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except (ValueError, OSError):
+        return True
+    hooks = data.get("hooks") if isinstance(data, dict) else None
+    if not isinstance(hooks, dict) or "shadowDeny" not in hooks:
+        return True
+    return bool(hooks["shadowDeny"])
+
+
 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(),
+        "ts": datetime.now(UTC).isoformat(),
         "session_id": session_id,
         "tool": tool,
         "cwd": cwd,
@@ -278,7 +312,7 @@ def record_telemetry(
 ) -> None:
     """Append a structured record to the enforcement telemetry log."""
     entry = {
-        "ts": datetime.now(timezone.utc).isoformat(),
+        "ts": datetime.now(UTC).isoformat(),
         "session_id": session_id,
         "tool": tool,
         "cwd": cwd,
@@ -407,7 +441,7 @@ def _annotate_plan_approval(decision: Decision, session_id: str) -> Decision:
             )
         else:
             decision.approval_state = "no-plan"
-    except Exception:  # noqa: BLE001 — annotation must never break a hook
+    except Exception:
         decision.approval_state = "unknown"
     return decision
 
@@ -462,11 +496,61 @@ def _evaluate_flow(
     if not is_gated:
         return Decision(allow=True, reason="tool-not-gated")
 
-    if not _feature_flag_on():
+    if _feature_flag_on():
+        return _decide_gated(
+            tool_name, transcript_path, session_id, cwd, messages
+        )
+    if not shadow_deny_on():
         return Decision(allow=True, reason="feature-flag-off")
+    return _shadow_decision(
+        tool_name, transcript_path, session_id, cwd, messages
+    )
+
+
+def _shadow_decision(
+    tool_name: str,
+    transcript_path: str,
+    session_id: str,
+    cwd: str,
+    messages: list[str] | None,
+) -> Decision:
+    """Run the gated chain in shadow (PR-A5a): allow regardless, record
+    what enforcement would have decided. Silent by construction — the
+    inner decision's warning/stderr never propagates."""
+    start = time.perf_counter()
+    inner = _decide_gated(
+        tool_name, transcript_path, session_id, cwd, messages, shadow=True
+    )
+    return Decision(
+        allow=True,
+        reason="feature-flag-off",
+        marker_found=inner.marker_found,
+        phase_observed=inner.phase_observed,
+        would_block=not inner.allow,
+        shadow_reason=inner.reason,
+        shadow_ms=round((time.perf_counter() - start) * 1000, 3),
+    )
+
+
+def _decide_gated(
+    tool_name: str,
+    transcript_path: str,
+    session_id: str,
+    cwd: str,
+    messages: list[str] | None,
+    shadow: bool = False,
+) -> Decision:
+    """The enforcement chain behind the feature flag.
 
+    ``shadow=True`` runs the identical chain for the telemetry-only
+    caller; the sole suppressed side effect is the bypass audit — an env
+    bypass of an inactive gate is not a bypass and must not pollute the
+    accountability log. State writes (confirm/grace) run in both modes
+    so the shadow would_block rate is the rate a flip would produce.
+    """
     if _bypass_env_active():
-        _audit_bypass(session_id, tool_name, cwd)
+        if not shadow:
+            _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):
@@ -485,6 +569,11 @@ def _evaluate_flow(
         messages = _load_last_assistant_messages(
             transcript_path, ASSISTANT_WINDOW
         )
+    return _decide_from_markers(session_id, messages)
+
+
+def _decide_from_markers(session_id: str, messages: list[str]) -> Decision:
+    """Marker scan + persistent-auth fallback + grace ladder."""
     marker_found, phase_observed = _scan_markers(messages)
 
     if marker_found is not None:
@@ -511,12 +600,15 @@ def _evaluate_flow(
         return Decision(
             allow=True, reason="turn-grace", phase_observed=phase_observed
         )
+    return _decide_grace(session_id, phase_observed)
+
 
-    # First effect-tool of a turn with no confirmed auth. A hard deny here
-    # is a false positive (the assistant may have routed in this very
-    # message — invisible to us). Grace it with a warning; escalate to a
-    # real block only after GRACE_CAP consecutive graced turns without any
-    # confirmation (a normally-routing session confirms by turn 2).
+def _decide_grace(session_id: str, phase_observed: str | None) -> Decision:
+    """First effect-tool of a turn with no confirmed auth. A hard deny
+    here is a false positive (the assistant may have routed in this very
+    message — invisible to us). Grace it with a warning; escalate to a
+    real block only after GRACE_CAP consecutive graced turns without any
+    confirmation (a normally-routing session confirms by turn 2)."""
     grace = flow_authorization.register_grace(session_id)
     if grace.escalate:
         return Decision(
@@ -545,7 +637,7 @@ def mark_flow_required(session_id: str) -> 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")
+    marker.write_text(datetime.now(UTC).isoformat(), encoding="utf-8")
 
 
 def clear_flow_required(session_id: str) -> None: