arkaos 4.47.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.47.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.47.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/egress/policy.py

@@ -28,6 +28,7 @@ import re
 from dataclasses import dataclass, field
 from datetime import datetime
 from pathlib import Path
+from typing import Any
 
 from core.egress import allowlist, audit, redact
 from core.governance.harness_scanner import secret_labels
@@ -42,7 +43,7 @@ class Finding:
     #          # | audit-unavailable | payload-not-text | guard-failure
     token: str
 
-    def to_audit(self, salt: bytes = b"") -> dict:
+    def to_audit(self, salt: bytes = b"") -> dict[str, Any]:
         return {
             "kind": self.kind,
             "token_sha16": (
@@ -64,7 +65,7 @@ class EgressDecision:
     redacted_sha256: str = ""
     audited: bool = False
 
-    def to_audit(self, salt: bytes = b"") -> dict:
+    def to_audit(self, salt: bytes = b"") -> dict[str, Any]:
         return {
             "allowed": self.allowed,
             "destination": self.destination,
@@ -99,26 +100,43 @@ def evaluate(
 ) -> EgressDecision:
     """Judge one payload against the policy. Never raises.
 
-    ``home`` scopes the home-path check and the default allowlist /
-    audit locations; ``now`` pins allowlist expiry for tests.
+    ``home`` scopes the home-path check, the redaction config and the
+    default allowlist / audit locations; ``now`` pins allowlist expiry
+    for tests.
     """
     destination = _safe_str(destination)
-    # Digest computed ONCE, before any failure path, so no handler
-    # ever re-executes the operation that failed (QG D1 r2 E-B1).
-    payload_digest = _sha256(text) if isinstance(text, str) else ""
+    # ONCE, before any failure path, so no handler re-runs what
+    # failed. Named `digest`: `payload_digest` shadowed the public
+    # function here (QG D2 r12, Francisca M2).
+    digest = payload_digest(text) if isinstance(text, str) else ""
     try:
         decision = _judge(
             text, destination, config_path, home, allowlist_path, now
         )
     except Exception as exc:  # never-raises boundary — deny, not crash
-        decision = EgressDecision(
-            allowed=False, destination=destination,
-            payload_sha256=payload_digest,
-            findings=[Finding("guard-failure", type(exc).__name__)],
-        )
+        decision = _guard_failure(destination, digest, exc)
     return _audited(decision, home, audit_path, now)
 
 
+def _guard_failure(
+    destination: str, digest: str, exc: BaseException
+) -> EgressDecision:
+    return EgressDecision(
+        allowed=False, destination=destination, payload_sha256=digest,
+        findings=[Finding("guard-failure", type(exc).__name__)],
+    )
+
+
+def default_redaction_config_path(home: Path | None = None) -> Path:
+    """The identifier list *home* implies.
+
+    Mirrors ``leak_scanner._DEFAULT_CONFIG_PATH`` for the real home, so
+    scoping by ``home`` never changes production behaviour — pinned by
+    ``test_egress_policy.py`` rather than by this comment.
+    """
+    return (home or Path.home()) / ".arkaos" / "redaction-clients.json"
+
+
 def _safe_str(value: object) -> str:
     try:
         return str(value)
@@ -150,7 +168,7 @@ def _audited(
     return decision
 
 
-def enforce(text: object, destination: str, **kwargs) -> str:
+def enforce(text: object, destination: str, **kwargs: Any) -> str:
     """The redacted text cleared to leave, or :class:`EgressDeniedError`."""
     decision = evaluate(text, destination, **kwargs)
     if not decision.allowed or decision.redacted_text is None:
@@ -167,41 +185,70 @@ def _judge(
     now: datetime | None,
 ) -> EgressDecision:
     if not isinstance(text, str):
-        return EgressDecision(
-            allowed=False, destination=destination, payload_sha256="",
-            findings=[Finding("payload-not-text", type(text).__name__)],
-        )
+        return _not_text(destination, text)
     decision = EgressDecision(
         allowed=False, destination=destination,
-        payload_sha256=_sha256(text),
+        payload_sha256=payload_digest(text),
     )
-    clean, failure = _redacted(text, config_path)
-    if failure is not None:
-        decision.findings.append(failure)
+    # One scoped path for both layers: scoping only the redaction call
+    # left residual_identifiers reading the real machine's list
+    # (QG D2 r3, Francisca B1).
+    scoped = _scoped_config(config_path, home)
+    clean = _redacted(text, scoped)
+    if isinstance(clean, Finding):
+        decision.findings.append(clean)
         return decision
     _collect_findings(
-        decision, clean, destination, config_path, home, allowlist_path, now
+        decision, clean, destination, scoped, home, allowlist_path, now
     )
     if not decision.findings:
         decision.allowed = True
         decision.redacted_text = clean
-        decision.redacted_sha256 = _sha256(clean)
+        decision.redacted_sha256 = payload_digest(clean)
     return decision
 
 
-def _sha256(text: str) -> str:
+def _not_text(destination: str, text: object) -> EgressDecision:
+    return EgressDecision(
+        allowed=False, destination=destination, payload_sha256="",
+        findings=[Finding("payload-not-text", type(text).__name__)],
+    )
+
+
+def payload_digest(text: str) -> str:
     """Total over any str — surrogatepass, because a payload holding a
     lone surrogate (routine from errors="surrogateescape" decoding or
     json.loads of an escape) must be DIGESTIBLE to be denied with an
-    audit line (QG D1 r2 E-B1)."""
+    audit line (QG D1 r2 E-B1).
+
+    Public because callers outside this package need the same digest
+    the audit trail records; reaching for a private symbol made a D1
+    rename a silent runtime break downstream (QG D2 r1, Francisca M6).
+    """
     payload = text.encode("utf-8", errors="surrogatepass")
     return hashlib.sha256(payload).hexdigest()
 
 
-def _redacted(
-    text: str, config_path: Path | None
-) -> tuple[str | None, Finding | None]:
-    """``(clean_text, None)`` or ``(None, denial_finding)``.
+def _scoped_config(config_path: Path | None, home: Path | None) -> Path | None:
+    """The redaction config *home* implies, unless one was named.
+
+    ``home`` scoped ``allowlist_path`` and ``audit_path`` but NOT the
+    redaction config, so a caller passing ``home=`` and forgetting
+    ``config_path`` judged paths against one home while redacting
+    against another (QG D2 r1, Francisca M7).
+
+    Called from inside ``_judge``, i.e. inside ``evaluate``'s try: the
+    same defaulting one frame up sat OUTSIDE it, and a non-Path home
+    turned the never-raises boundary into a TypeError — the very shape
+    QG D1 r2 F-M5 already closed once.
+    """
+    if config_path is not None or home is None:
+        return config_path
+    return default_redaction_config_path(home)
+
+
+def _redacted(text: str, config_path: Path | None) -> str | Finding:
+    """The clean text, or the finding that denies it.
 
     A redaction that CRASHES proves nothing about the payload — same
     posture as a missing config: denied, never allowlistable (QG D1
@@ -209,11 +256,16 @@ def _redacted(
     """
     try:
         clean, _counts = redact.redact(text, config_path)
-        return clean, None
+        # Annotated: redact() is untyped, so `clean` arrives as Any and
+        # the union return silently degrades to Any (mypy no-any-return,
+        # surfaced only with --follow-imports=skip —
+        # QG D2 r3, Francisca M3).
+        clean_text: str = clean
+        return clean_text
     except redact.SanitizerConfigMissing:
-        return None, Finding("redaction-config-missing", "")
+        return Finding("redaction-config-missing", "")
     except Exception as exc:
-        return None, Finding("redaction-failed", type(exc).__name__)
+        return Finding("redaction-failed", type(exc).__name__)
 
 
 def _collect_findings(

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/kb/__init__.py

@@ -0,0 +1,9 @@
+"""Knowledge-base integrations that reach outside the machine.
+
+Everything here goes through ``core.egress.policy`` before a byte
+leaves. The package is deliberately absent from the critical path:
+``tests/python/test_notebooklm_chokepoint.py`` asserts by import graph
+that ``core/governance``, ``core/workflow`` and ``core/release`` never
+import it, so an upstream tool breaking can stall research but never a
+gate or a release.
+"""