wicked-garden 12.27.0

package/scripts/_session.py

@@ -0,0 +1,502 @@
+#!/usr/bin/env python3
+"""
+_session.py — Session state shared across hook script invocations.
+
+Hook scripts run as separate processes, so they cannot share in-memory state.
+This module persists a lightweight JSON state file keyed by CLAUDE_SESSION_ID
+so all hooks within a session read/write a consistent view.
+
+State file location:
+    {tempfile.gettempdir()}/wicked-garden-session-{SESSION_ID}.json
+
+Atomic writes: write to .tmp, then os.replace — prevents partial reads.
+
+Usage (hook scripts):
+    from _session import SessionState
+
+    state = SessionState.load()
+    state.turn_count += 1
+    state.save()
+
+    # Or update multiple fields at once:
+    state.update(setup_complete=True)
+"""
+
+import json
+import os
+import sys
+import tempfile
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+# ---------------------------------------------------------------------------
+# Session ID resolution
+# ---------------------------------------------------------------------------
+
+_SESSION_ID_ENV = "CLAUDE_SESSION_ID"
+_FALLBACK_SESSION_ID = "default"
+
+# Characters that could be used for path traversal — strip them from session IDs
+_SAFE_ID_RE = None  # initialized lazily
+
+
+def _get_session_id() -> str:
+    """Read and sanitize the Claude session ID from the environment.
+
+    Returns a safe string usable as a filename component.
+    """
+    import re
+
+    raw = os.environ.get(_SESSION_ID_ENV, _FALLBACK_SESSION_ID)
+    # Strip any path traversal or shell-special characters — keep only
+    # alphanumerics, hyphens, and underscores.
+    safe = re.sub(r"[^a-zA-Z0-9\-_]", "_", raw)
+    return safe or _FALLBACK_SESSION_ID
+
+
+def _state_file_path() -> Path:
+    """Return the path to the session state JSON file for the current session."""
+    tmpdir = os.environ.get("TMPDIR") or tempfile.gettempdir()
+    session_id = _get_session_id()
+    filename = f"wicked-garden-session-{session_id}.json"
+    return Path(tmpdir) / filename
+
+
+# ---------------------------------------------------------------------------
+# SessionState dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SessionState:
+    """Lightweight session state persisted across hook script invocations.
+
+    All fields have safe defaults so a missing or partial state file never
+    causes a hook to crash.
+
+    Fields:
+        setup_complete: True when config.json has setup_complete == true.
+        active_project: Dict summary of the active crew project, or None.
+        agents_loaded:  Number of agents loaded at bootstrap.
+        turn_count:     Number of user prompts in this session (incremented by
+                        prompt_submit.py on each UserPromptSubmit hook).
+    """
+
+    setup_complete: bool = False
+    active_project: dict | None = None
+    agents_loaded: int = 0
+    turn_count: int = 0
+    session_ended: bool = False
+
+    # One-time nudge flags (reset per session)
+    task_suggest_shown: bool = False
+
+    # Stale files accumulated this session (flushed to SM on demand)
+    stale_files: list | None = None
+
+    # QE change tracking nudge flag
+    qe_nudged: bool = False
+
+    # Set by bootstrap.py when onboarding is incomplete; checked by prompt_submit gate
+    needs_onboarding: bool = False
+
+    # Set by prompt_submit gate when /wicked-garden:setup passes through;
+    # allows subsequent user answers (AskUserQuestion responses) through the gate
+    setup_in_progress: bool = False
+
+    # True when Claude Code is running in dangerous mode (skipDangerousModePermissionPrompt).
+    # AskUserQuestion is broken in this mode — commands must use plain text questions instead.
+    dangerous_mode: bool = False
+
+    # Failure counts per tool (for issue reporter threshold)
+    failure_counts: dict | None = None
+
+    # Queued issue records (pending_issues + mismatches)
+    pending_issues: list | None = None
+
+    # Subagent dispatch log (post_tool.py Task handler)
+    subagent_dispatches: list | None = None
+
+    # Detected agentic frameworks (post_tool.py Read handler)
+    detected_frameworks: list | None = None
+
+    # Bash command counter (post_tool.py Bash handler)
+    bash_count: int = 0
+
+    # Memory compliance tracking (set by bootstrap + incremented by task_completed.py)
+    # memory_compliance_required: True when a crew project is active (enables directives)
+    # memory_compliance_tasks_completed: count of TaskCompleted events this session
+    memory_compliance_required: bool = False
+    memory_compliance_tasks_completed: int = 0
+
+    # Crew recommendation heuristic — shown at most once per session on SLOW path
+    # when complexity >= 2 and no active crew project exists.
+    crew_hint_shown: bool = False
+
+    # Context dedup hash — tracks the last session state hash to skip redundant
+    # re-injection on HOT path when state hasn't changed between turns.
+    context_hash: str = ""
+
+    # Escalation counter: incremented by task_completed.py on each deliverable completion.
+    # Reset by post_tool.py when a wicked-brain:memory Skill call succeeds.
+    memory_compliance_escalations: int = 0
+
+    # Written by bootstrap.py when onboarding is confirmed complete (both memories and index).
+    # prompt_submit.py reads this as the primary signal, bypassing per-turn re-check.
+    onboarding_complete: bool = False
+
+    # Separate from cp_project_id (which is a CP UUID reference).
+    # active_project_id is the LOCAL project name (slug) for a project that is currently
+    # in an active (non-complete) phase in this workspace. None when no active project.
+    active_project_id: str | None = None
+
+    # One-per-session gate for jam suggestion (reset each session).
+    jam_hint_shown: bool = False
+
+    # Operational log verbosity level for this session.
+    # "" means "not set" — the logger defaults to "normal".
+    # Valid values: "normal", "verbose", "debug"
+    # Written by /wicked-garden:platform:debug; read by _logger._resolve_level().
+    log_level: str = ""
+
+    # Cached integration-discovery results for this session.
+    # Maps domain name to selected tool name ("linear", "jira", "notion") or "local".
+    # None means discovery has not run yet this session.
+    integration_tools: dict | None = None
+
+    # Resolved tool lists from capability-based routing.
+    # Maps agent_name -> list of resolved tool names.
+    # None means resolution has not run yet this session.
+    resolved_capabilities: dict | None = None
+
+    # wicked-brain dependency check (set by bootstrap.py at SessionStart).
+    # True  — wicked-brain plugin is installed (found in enabledPlugins).
+    # False — not installed; bootstrap emits an install hint to the briefing.
+    # None  — check has not run yet this session (e.g., early-exit before setup).
+    brain_available: bool | None = None
+
+    # Fast-path sentinel: set by bootstrap.py when config.json setup_complete=True.
+    # Allows prompt_submit.py guard to skip config.json file read on every turn.
+    # Once True for a session, it never goes back to False.
+    setup_confirmed: bool = False
+
+    # Onboarding mode selected during this session's wizard run.
+    # Written by setup.md Step 5. Values: None | "full" | "quick" | "skip"
+    onboarding_mode: str | None = None
+
+    # Dedup guard for PreCompact hook — ISO timestamp of last compaction.
+    # If compaction happened <60s ago, skip redundant WIP save.
+    last_compact_ts: str = ""
+
+    # Cumulative bytes read via the Read tool this session (post_tool.py).
+    # Used for escalating context-window warnings.
+    read_bytes_total: int = 0
+
+    # Number of large-file-read warnings emitted this session.
+    # Escalation tiers: first warning is informational, repeated warnings
+    # become more urgent.
+    read_large_warn_count: int = 0
+
+    # Subagent permission failure counter (post_tool.py Task handler).
+    # Incremented when a subagent completes without doing work due to
+    # Bash permission issues or tool-access failures (Issue #318).
+    subagent_permission_failures: int = 0
+
+    # Discovery hints shown this session — tracks which "did you know?" hints
+    # have been emitted so each is shown at most once (Issue #322).
+    # List of hint IDs like ["grep_search", "manual_review", "debugging"].
+    hints_shown: list | None = None
+
+    # Claim sentinel (scripts/sentinel/invariants.py::claim_tick) — Stop-hook
+    # debounce. The answer tier nudges at most once per unproven HEAD sha per
+    # session when a done/passing claim is made without a re-derived verdict;
+    # this records the sha already nudged so the same unproven state never
+    # re-fires within a session. MUST be a declared field — update() drops
+    # unknown keys, so a transient attr would never persist across Stop calls.
+    sentinel_claim_sha: str = ""
+
+    # OneDrive / spaces-in-paths resolution (Issue #321).
+    # Stores the resolved canonical base path when cwd is under a OneDrive
+    # or CloudStorage directory (macOS ~/Library/CloudStorage/OneDrive - .../...).
+    # Empty string means not applicable (cwd is not under OneDrive).
+    onedrive_base_path: str = ""
+
+    # Turn progress visibility (Issue #323).
+    # turn_start_ts: ISO timestamp when the current turn began (set by prompt_submit).
+    # turn_tool_count: number of tool calls in the current turn (incremented by post_tool).
+    turn_start_ts: str = ""
+    turn_tool_count: int = 0
+
+    # v10 Phase 1 (#813) — intent variable, the keystone for steer-not-block.
+    # One explicit, queryable value replaces five overlapping classifiers
+    # in prompt_submit.py (HOT fast-exit, near-HOT guard, complexity scorer,
+    # _should_emit_context_assembly, _resolve_pull_phase).
+    #
+    # Vocabulary (locked, do not extend without a brainstorm):
+    #   simple-edit | feature | rigor | research
+    #
+    # Lifecycle:
+    #   - None     : not yet detected (turn 1 before _detect_intent runs)
+    #   - <value>  : auto-detected on turn 1-2 OR explicitly set by skill
+    #
+    # `intent_explicit` is True only when /wicked-garden:intent set the
+    # value (or a command self-declared via that skill). Used to decide
+    # whether to echo the bare `<wg intent="X" t=N />` label in the
+    # system-reminder — auto-detected values stay invisible to prevent
+    # confirmation-bias drift.
+    #
+    # Sticky for the session. SessionEnd hook (stop.py) resets via delete().
+    # Design record: brainstorms/v10-session-01-intent-and-hook-gating.md
+    intent: str | None = None
+    intent_explicit: bool = False
+
+    # v11: LLM-classified work-shape archetype + signals.
+    # Populated by the wicked-garden:classify skill. When set, the
+    # prompt_submit hook prefers this over the regex detector.
+    # archetypes_v11: list of {name, score, evidence} dicts (top-3).
+    # signals_v11: dict of boolean signal flags (blast_radius_high, etc.).
+    # classified_at: ISO timestamp; None means not classified yet.
+    archetypes_v11: list | None = None
+    signals_v11: dict | None = None
+    classified_at: str | None = None
+
+    # PostToolUse hook latency profiling (Issue #312).
+    # Cumulative milliseconds spent in the post_tool.py main() function.
+    post_tool_total_ms: int = 0
+    # Total number of PostToolUse hook invocations this session.
+    post_tool_call_count: int = 0
+    # Per-handler cumulative milliseconds: {"Read": 42, "Write|Edit": 15, ...}
+    post_tool_handler_ms: dict | None = None
+
+    # v6 facilitator re-evaluation (Gate 3, epic #428).
+    # task_completed.py sets these when a task with metadata.chain_id completes.
+    # prompt_submit.py reads on the next turn, emits a re-eval directive, then clears.
+    facilitator_reeval_due: bool = False
+    facilitator_reeval_chain: str | None = None  # chain_id needing re-eval
+
+    # v6 phase-start heuristic gate (AC-11). task_completed.py sets this when
+    # a completed task is the last in a phase; prompt_submit.py dispatches
+    # phase_start_gate.py::check() on next turn and emits the directive.
+    # MUST be a declared dataclass field — asdict() only serializes declared
+    # attributes, so setting it as a transient attr won't persist. (Caught by
+    # senior-engineer review of this very project — meta bug fix.)
+    phase_start_gate_due: bool = False
+
+    # Name of the last phase the user approved this session (#462).
+    # Written by scripts/crew/phase_manager.py::approve_phase() after a
+    # successful approval. Read by stop.py to decide whether to promote
+    # the guard pipeline profile (scalpel → standard) when build just closed.
+    # None when no approval has happened yet this session.
+    last_phase_approved: str | None = None
+
+    # Telemetry producers (#459). Read optimistically by
+    # scripts/delivery/telemetry.py::_extract_session_extras at session-close.
+    # - skip_reeval_count: count of --skip-reeval approvals in this session.
+    #   Incremented by scripts/crew/phase_manager.py::approve_phase when the
+    #   addendum-freshness bypass path is taken.
+    # - complexity_at_session_open: ProjectState.complexity_score as observed
+    #   at session-start (bootstrap) when an active crew project exists, or on
+    #   the first approve_phase of the session. Used by telemetry to compute
+    #   complexity_delta = complexity_close - complexity_open.
+    # - complexity_score: current ProjectState.complexity_score mirror, kept
+    #   on the session for telemetry close-out.
+    skip_reeval_count: int = 0
+    complexity_at_session_open: int | None = None
+    complexity_score: int = 0
+
+    # #500 — HMAC-signed dispatch-log secret. Session-scoped; lazily
+    # generated on first use via ``secrets.token_hex(32)``. Promotes the
+    # dispatch-log orphan check to authentication: an attacker who forges
+    # both a gate-result and a dispatch entry still cannot produce a
+    # correct HMAC without the in-session secret.
+    #
+    # Storage intent:
+    #   - NEVER logged, NEVER included in audit records (see
+    #     ``scripts/crew/gate_ingest_audit.py``).
+    #   - Persisted inside the session-state JSON, which already lives
+    #     in a per-session temp file. Cross-session lookup is explicitly
+    #     NOT supported — legacy (pre-HMAC) entries fall back to
+    #     orphan-detection only with a stderr WARN.
+    dispatch_log_hmac_secret: str = ""
+
+    # #506 — pre-flip monitoring: latch the post-cutover INFO banner so
+    # it fires at most once per session even across multiple SessionStart
+    # callbacks in the same session.
+    strict_mode_active_announced: bool = False
+
+    # #544 — wicked-testing peer-plugin gate (SessionStart hard-block).
+    # Set by bootstrap.py after running _wicked_testing_probe.probe().
+    # True  — probe returned status != "ok"; crew commands are blocked.
+    # False — probe returned "ok" (or escape hatch active); crew may proceed.
+    # None  — probe has not run yet this session (early-exit before setup).
+    wicked_testing_missing: bool | None = None
+
+    # Cached probe result dict from _wicked_testing_probe.probe().
+    # Persisted as part of session extras for crew_command_gate() reads.
+    # Lives in extras["wicked_testing_probe"] per the design spec.
+    # extras is a general-purpose dict for probe / diagnostic results that
+    # don't warrant individual dataclass fields.
+    extras: dict | None = None
+
+    # Hook-reminder latches (v9.2.2 — per-session noise suppression).
+    # SessionState.update silently drops unknown keys, so prior to v9.2.2
+    # the latches below were write-only — the hooks SET them but the values
+    # never persisted, causing the reminders they were meant to gate to fire
+    # every time. Declaring the fields here turns the writes into reads on
+    # the next Stop / PostToolUse and the latches actually take.
+    #
+    # instruction_sync_fired: list of filenames (CLAUDE.md / AGENTS.md) for
+    #   which the [Sync] reminder has already fired this session.
+    # memory_reminder_shown: True when stop.py's [Memory] reminder has
+    #   already fired once this session — replaces the prior every-turn fire.
+    instruction_sync_fired: list | None = None
+    memory_reminder_shown: bool = False
+
+    # v9.2.3 — fields previously USED via getattr/state.update but NEVER
+    # declared. Each was silently failing because update() drops unknown keys.
+    # Audit ran 2026-05-06 against all `state.update(X=...)` and
+    # `getattr(state, "X", ...)` call sites in hooks/ and scripts/.
+    #
+    # active_chain_id: string identifier of the active crew chain (e.g.
+    #   "{slug}.root" or "{slug}.{phase}"). Read by smaht events_adapter for
+    #   chain-aware scoring (CLAUDE.md "Chain-aware smaht scoring"). Producer
+    #   was never wired — the smaht scoring has been silently degraded. The
+    #   field declaration here makes the read return None cleanly until a
+    #   producer is added.
+    # crew_project: REMOVED in v9.2.5. The single read site in post_tool.py
+    #   was a phantom — nothing ever wrote the field. Replaced the read with
+    #   `getattr(state, "active_project_id", None)` which is the same intent
+    #   ("is a crew project active?") and has a real producer in bootstrap.
+    # last_reeval_ts / last_reeval_task_count: read by prompt_submit when
+    #   building re-evaluation context. Currently read-only; declared so the
+    #   read returns the documented default rather than via getattr fallback.
+    # legacy_reeval_entries_detected: written by bootstrap.py:1215 when a
+    #   project has pre-v6 re-eval entries needing migration. Was a write-
+    #   only orphan; declaration makes it persistable.
+    # unready_plugins: written by bootstrap.py:1279 with names of plugins
+    #   whose readiness probe failed. Was a write-only orphan; declaration
+    #   makes it persistable.
+    active_chain_id: str | None = None
+    last_reeval_ts: str = ""
+    last_reeval_task_count: int = 0
+    legacy_reeval_entries_detected: bool = False
+    unready_plugins: list | None = None
+
+    # v9.2.12 — per-turn / change-gated latches for hook-emission anti-patterns
+    # surfaced by the v9.2.11 audit. Each field gates a banner that previously
+    # re-fired on every PostToolUse / Stop without checking actual state.
+    #
+    # last_status_turn: turn_count value when the [Status] long-turn banner
+    #   was last shown. post_tool.py only emits if turn_count > last_status_turn,
+    #   so each long-running turn surfaces exactly one [Status] line instead of
+    #   one per tool call past the threshold.
+    # last_outcome_pending_count / last_outcome_mismatch_count: counts at last
+    #   [Issue Reporter] banner emission. stop.py only re-emits when the count
+    #   has CHANGED — silent when nothing new accumulates, surfacing only when
+    #   the queue actually grows.
+    last_status_turn: int = 0
+    last_outcome_pending_count: int = 0
+    last_outcome_mismatch_count: int = 0
+
+    # ------------------------------------------------------------------
+    # Persistence
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def load(cls) -> "SessionState":
+        """Load state from the session file.
+
+        Returns a fresh default-valued SessionState if the file does not exist
+        or contains invalid JSON — ensures hooks never crash on missing state.
+        """
+        path = _state_file_path()
+
+        if not path.exists():
+            return cls()
+
+        try:
+            raw = path.read_text(encoding="utf-8")
+            data = json.loads(raw)
+        except (json.JSONDecodeError, OSError):
+            # Corrupted or unreadable state — return clean defaults
+            return cls()
+
+        # Build from dict; unknown keys are silently ignored so older state
+        # files remain compatible with newer code that adds fields.
+        return cls._from_dict(data)
+
+    def save(self) -> None:
+        """Atomically persist the current state to the session file."""
+        path = _state_file_path()
+        tmp_path = path.with_suffix(".tmp")
+
+        data = asdict(self)
+
+        try:
+            tmp_path.write_text(json.dumps(data, indent=2), encoding="utf-8")
+            os.replace(tmp_path, path)
+        except OSError as exc:
+            print(
+                f"[wicked-garden] Failed to save session state: {exc}",
+                file=sys.stderr,
+            )
+
+    def update(self, **kwargs: Any) -> None:
+        """Update one or more fields and immediately save to disk.
+
+        Only recognised field names are applied; unknown keys are silently
+        dropped so callers cannot accidentally corrupt the state schema.
+
+        Args:
+            **kwargs: Field name -> new value pairs.
+        """
+        valid_fields = {f for f in self.__dataclass_fields__}
+        for key, value in kwargs.items():
+            if key in valid_fields:
+                object.__setattr__(self, key, value)
+            else:
+                print(
+                    f"[wicked-garden] SessionState.update: unknown field {key!r} ignored",
+                    file=sys.stderr,
+                )
+        self.save()
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @classmethod
+    def _from_dict(cls, data: dict) -> "SessionState":
+        """Construct a SessionState from a dict, ignoring unknown keys."""
+        valid_fields = {f for f in cls.__dataclass_fields__}
+        filtered = {k: v for k, v in data.items() if k in valid_fields}
+        return cls(**filtered)
+
+    def to_dict(self) -> dict:
+        """Return a plain dict representation (JSON-safe)."""
+        return asdict(self)
+
+    def increment_turn(self) -> int:
+        """Increment turn_count, persist, and return the new value."""
+        self.turn_count += 1
+        self.save()
+        return self.turn_count
+
+    # ------------------------------------------------------------------
+    # Session file cleanup (called by stop.py)
+    # ------------------------------------------------------------------
+
+    def delete(self) -> None:
+        """Remove the session state file at session end.
+
+        Silently succeeds if the file does not exist.
+        """
+        path = _state_file_path()
+        try:
+            path.unlink(missing_ok=True)
+        except OSError as exc:
+            print(
+                f"[wicked-garden] Failed to delete session state file: {exc}",
+                file=sys.stderr,
+            )