@event4u/agent-config 1.18.0 → 1.20.0

package/.agent-src/skills/subagent-orchestration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: subagent-orchestration
-description: "Use when orchestrating implementer/judge subagents — five modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate) — models from .agent-settings.yml."
+description: "Use when orchestrating implementer/judge subagents — six modes (do-and-judge, do-in-steps, do-in-parallel, do-competitively, judge-with-debate, do-in-worktrees) — models from .agent-settings.yml."
 source: package
 ---
 
@@ -44,7 +44,7 @@ judge is a fresh pair of eyes. If `.agent-settings.yml` resolves to
 identical implementer and judge models, surface the mismatch before
 running — do not silently continue.
 
-## The five modes
+## The six modes
 
 Each mode has a decision row: when to use, when not, and the expected
 model pairing. Defaults come from
@@ -100,6 +100,38 @@ migration, public API) where a single judge is too easy to fool.
 |---|---|---|
 | Security, data integrity, public API change | Routine internal refactor | judges = same tier (2x); meta-judge = one tier up |
 
+### 6. do-in-worktrees
+
+Cross-wing or cross-skill chain executed across isolated git
+worktrees — each handoff in the chain runs in its own worktree, so
+the workspace state of one step never leaks into the next. Operationalizes
+the worktree boundary clause in
+[`docs/contracts/cross-wing-handoff.md`](../../../docs/contracts/cross-wing-handoff.md)
+§ 3. State-machine layer only — worktree creation/destruction lives
+in [`using-git-worktrees`](../using-git-worktrees/SKILL.md) and
+[`finishing-a-development-branch`](../finishing-a-development-branch/SKILL.md).
+
+| When to use | When not | Model pairing |
+|---|---|---|
+| Multi-step cross-wing chain (≥2 senior skills, each ≥30 min) where one step's open files / branch state would confuse the next | Fast iteration where each step < 30 min — worktree overhead exceeds isolation benefit | implementers = same tier per step; judge = one tier up at chain end |
+
+**Handoff shape:** initiator-skill emits the typed output declared in
+its `## Output` block → control passes to delegated-skill in a fresh
+worktree → delegated-skill consumes the input shape declared in its
+`## Input` (or `## When the agent should load this`) block. The
+handoff is auditable; `lint_handoffs.py` validates the chain.
+
+**Example chain (W3 launch):** `positioning` (worktree A) →
+`messaging-architecture` (worktree B, consumes positioning's
+`positioning-statement.md`) → `gtm-launch` (worktree C, consumes
+both prior artifacts). Each worktree carries one branch; the chain
+end produces a single integration PR.
+
+**Anti-pattern:** do not use for fast iteration loops where each
+step is under ~30 minutes. The branch-creation, context-switch, and
+worktree-cleanup cost dominates. Stick with mode 1 (do-and-judge)
+or mode 2 (do-in-steps) for those.
+
 ## Procedure
 
 ### 1. Inspect the task shape

package/.agent-src/skills/unit-economics-modeling/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: unit-economics-modeling
+description: "Use when modeling CAC, LTV, gross-margin payback, or contribution margin per customer — for SaaS, marketplace, or transactional businesses."
+status: active
+tier: senior
+source: package
+---
+
+# unit-economics-modeling
+
+## When to use
+
+- A board ask: "is this business unit-economic?" — needs CAC / LTV / payback, not vibes.
+- A new channel is scaling and the question is whether the CAC payback period is sustainable.
+- A pricing or packaging change needs to be tested against contribution margin per cohort.
+
+Do NOT use for full-business intrinsic-value modeling, OKR setting, funnel-stage diagnosis, or backlog ranking (see Related Skills).
+
+## Procedure
+
+### Step 0: Inspect
+
+1. Confirm the business shape — SaaS / marketplace / transactional. The three canonical cases differ in **revenue recognition** and **churn definition**, not in arithmetic.
+2. Confirm a fully-loaded CAC is computable: paid spend + sales comp + content/SEO allocation + tooling. Marketing-spend-only CAC is a vanity metric.
+
+### Step 1: Compute CAC per channel
+
+1. CAC = `(fully-loaded acquisition spend in window) / (new paying customers acquired in same window)`. Match window to sales-cycle length, not calendar quarter.
+2. Compute by channel **and** blended. Blended-only hides the channel that is breaking the average.
+3. Anti-pattern: counting trial signups as customers. Customer = first paid charge cleared.
+
+### Step 2: Compute gross margin
+
+1. Gross margin = `(revenue − COGS) / revenue`. COGS includes hosting, payment fees, third-party APIs the customer's usage drives, and direct customer-success cost.
+2. Gross margin must be **per dollar of revenue**, not per customer. Per-customer gross margin is contribution margin (Step 3).
+3. SaaS healthy band: 70–85%. Marketplace: 15–40%. Transactional: 5–25%. Outside these — the business is mislabelled or the COGS allocation is wrong.
+
+### Step 3: Compute LTV
+
+1. Pick the canonical formula for the case:
+   - **SaaS:** `LTV = ARPA × gross_margin / monthly_churn_rate`. Use net-dollar churn for self-serve, gross logo churn for high-touch.
+   - **Marketplace:** `LTV = take_rate × GMV_per_user × retention_curve_AUC` over 24 months. Steady-state extrapolation is dishonest below 24 months of cohort data.
+   - **Transactional:** `LTV = avg_order_value × gross_margin × purchases_per_year × avg_lifetime_years`.
+2. Cap implied lifetime at 5 years for any business with < 3 years of cohort history. Anything longer is a fairy tale.
+3. State the formula used inline. Do not let the reader infer.
+
+### Step 4: Compute payback and ratio
+
+1. **CAC payback** (months) = `CAC / (ARPA × gross_margin)` for SaaS; analogue for marketplace and transactional. Healthy SaaS: ≤ 12 months.
+2. **LTV / CAC ratio**: target ≥ 3.0. Below 1.5 is acquisition-loss territory; above 5.0 means under-investment in growth (or bad LTV math).
+3. Both numbers, not one. Payback drives capital efficiency; ratio drives long-run economics.
+
+### Step 5: Cohort the answer
+
+1. Run Steps 1–4 by signup-quarter cohort. Trends matter more than the point estimate.
+2. If LTV/CAC is improving but payback is lengthening, you are buying retention with discounting — flag.
+3. If both deteriorate, the channel mix has shifted to a worse channel — segment by channel to find the leak.
+
+### Step 6: Validate
+
+1. Sanity-check LTV against revenue retention. If implied LTV > 8× annual revenue per customer with monthly churn > 2%, the math is wrong.
+2. Sanity-check CAC against fully-loaded P&L. If channel CACs sum to less than total acquisition spend, allocations are missing.
+
+## Gotcha
+
+- Marketing-spend-only CAC is the most common deception. Sales comp, BDR salaries, content production, and tooling all belong in fully-loaded CAC.
+- Net-dollar retention > 100% does not justify ignoring logo churn — they answer different questions.
+- ARPA averaged across plan tiers hides churn concentrated in one tier. Compute per tier when tiers differ in price by more than 2×.
+- Payback period using contribution margin (post variable-cost) is honest; payback using gross revenue is the kind of math VCs see in pitch decks and discount on sight.
+
+## Do NOT
+
+- Do NOT extrapolate LTV beyond observable cohort data without saying so explicitly.
+- Do NOT mix freemium activation rates with paid CAC; they live in different universes.
+- Do NOT report a single LTV/CAC for a business with multiple distinct customer segments — segment first.
+
+## Related Skills
+
+**WHEN to use this**
+
+- The question is per-customer economics (CAC, LTV, payback, contribution margin).
+- The decision is whether to scale a channel or pricing tier.
+
+**WHEN NOT to use this**
+
+- Whole-business intrinsic value with terminal value — route to [`dcf-modeling`](../dcf-modeling/SKILL.md).
+- Diagnosing where conversion drops — route to [`funnel-analysis`](../funnel-analysis/SKILL.md).
+- Ranking competing initiatives — route to [`rice-prioritization`](../rice-prioritization/SKILL.md).
+- Setting team objectives that move these metrics — route to [`okr-tree-modeling`](../okr-tree-modeling/SKILL.md).
+
+## When the agent should load this
+
+- "What's our LTV / CAC?"
+- "Is this channel paying back fast enough?"
+- "Compute unit economics for this pricing tier."
+- "Are we unit-economic at this CAC?"
+- "Cohort our payback period."
+
+## Output
+
+1. **`unit-econ-table.md`** — table per channel and blended: CAC · ARPA · gross margin · payback months · LTV · LTV/CAC. With cohort columns (last 4 quarters).
+2. **`assumptions.md`** — formula chosen (SaaS / marketplace / transactional), churn definition, COGS allocation method, lifetime cap. One bullet per choice.
+3. **`cohort-trend.md`** — trend chart (ASCII or markdown table) of CAC, payback, LTV/CAC over the last 4–8 cohorts. Annotate channel-mix shifts.
+4. **`sanity-checks.md`** — explicit cross-checks (LTV vs annual revenue, channel CAC sum vs P&L). Flag any that fail with a one-line investigation pointer.

package/.agent-src/skills/using-git-worktrees/SKILL.md

@@ -15,6 +15,7 @@ source: package
 * Experimenting with a refactor that may be thrown away — a throwaway
   worktree is cheaper than a throwaway commit
 * A long-running build or test suite is busy in the current worktree
+* `subagent-orchestration` mode 6 (`do-in-worktrees`) was selected for a cross-wing chain — this skill is the executor that creates the per-step isolated worktrees the chain expects
 
 Do NOT use when:
 

package/.agent-src/skills/verify-completion-evidence/SKILL.md

@@ -128,7 +128,12 @@ When reporting completion to the user:
 3. **Result** — numeric breakdown (tests passed/failed/skipped, errors,
    warnings)
 4. **Caveats** — anything the output flagged but you chose to accept
-5. **Next step** — e.g. "Ready for `/commit`" or "Awaiting review"
+5. **Untracked files** — if `git status --short` shows any untracked
+   files in the working tree, list them verbatim in the report. This
+   prevents silently-shipped artefacts (logs, scratch scripts, ad-hoc
+   notes) from disappearing into a future commit. Empty list means
+   omit the section.
+6. **Next step** — e.g. "Ready for `/commit`" or "Awaiting review"
 
 ## Gotchas
 
@@ -188,3 +193,5 @@ Before sending a completion message:
 * [ ] No warnings or skips are hidden
 * [ ] Targeted tests green → full suite green → quality pipeline clean
 * [ ] `git status` reflects only the intended change set
+* [ ] If `git status --short` shows untracked files, the report lists
+      them verbatim under "Untracked files"

package/.agent-src/templates/agent-settings.md

@@ -122,7 +122,7 @@ eloquent:
 
 # --- Chat history (crash recovery) ---
 #
-# Persistent JSONL log at .agent-chat-history (project root, git-ignored).
+# Persistent JSONL log at agents/.agent-chat-history (project root, git-ignored).
 # Keeps a durable record of the conversation so a crashed or switched
 # agent session can be resumed. See scripts/chat_history.py for the API.
 #
@@ -141,26 +141,6 @@ chat_history:
   # Overflow behavior: rotate (drop oldest) | compress (summarize)
   on_overflow: rotate
 
-  # Heartbeat marker visibility: on | off | hybrid
-  #   on     — print marker every reply (~20 tokens/reply, legacy)
-  #   off    — never print (zero tokens, no drift signal)
-  #   hybrid — print only on drift (missing/foreign/returning); silent otherwise
-  # YAML 1.1 booleanizes bare on/off — both are accepted, no quoting needed.
-  heartbeat: hybrid
-
-  # Population path: hook | checkpoint | manual
-  #   hook       — platform fires lifecycle hooks; agent observes only
-  #                (Claude Code, Augment CLI, Cursor 1.7+, Cline non-Windows,
-  #                 Windsurf, Gemini CLI). scripts/install.py wires hooks.
-  #   checkpoint — agent invokes /chat-history-checkpoint at phase boundaries
-  #                (Augment IDE plugin, Cursor < 1.7, Cline on Windows).
-  #                Cooperative three-gate Iron Law applies.
-  #   manual     — rule is inert (cloud surfaces). Persistence is local-only.
-  # Default `checkpoint` is the safest cooperative fallback. HOOK platforms
-  # set this to `hook` automatically when scripts/install.py merges the
-  # platform's settings file.
-  path: checkpoint
-
 # --- Work-engine hooks ---
 #
 # Lifecycle hook surface of the `work_engine` Python engine
@@ -197,7 +177,7 @@ hooks:
   # routing drift.
   directive_set_guard: true
 
-  # Chat-history hooks — populate .agent-chat-history structurally from
+  # Chat-history hooks — populate agents/.agent-chat-history structurally from
   # the engine. Gated by BOTH this block AND the global
   # chat_history.enabled above; either off → no chat-history hook
   # registers. Keep both on for the HOOK path; flip either off to fall
@@ -217,6 +197,21 @@ pipelines:
   # Included by every cost_profile except `custom`.
   skill_improvement: true
 
+# --- Roadmap execution ---
+#
+# Controls when /roadmap execute runs the project's quality pipeline.
+# Step checkboxes and the dashboard are ALWAYS updated in the same
+# response — that cadence is governed by `roadmap-progress-sync` and
+# is non-negotiable. This setting only governs *quality tool runs*.
+roadmap:
+  # When to run quality tools during /roadmap execute.
+  #   end_of_roadmap = once, before archiving (default — fastest, fewest tokens)
+  #   per_phase      = once after every completed phase
+  #   per_step       = after every completed step (legacy; highest token cost)
+  # Iron Law `verify-before-complete` still applies — fresh output is
+  # mandatory before any "roadmap complete" claim, regardless of cadence.
+  quality_cadence: end_of_roadmap
+
 # --- Subagent orchestration ---
 subagents:
   # Model for implementer subagents (empty = same tier as the session model)
@@ -348,20 +343,20 @@ lives under `personal:` in YAML.
 | `project.improvement_pr_branch_prefix` | string | `improve/agent-` | Branch prefix for agent improvement PRs. |
 | `github.pr_reply_method` | `replies_endpoint`, `create_review_comment`, `auto` | `create_review_comment` | GitHub API method for replying to PR review comments. `auto` detects on first use. |
 | `eloquent.access_style` | `getters_setters`, `get_attribute`, `magic_properties` | `getters_setters` | How to access Eloquent model attributes. See `eloquent` skill for details. |
-| `chat_history.enabled` | `true`, `false` | `true` | Persist chat events to `.agent-chat-history` (JSONL) for crash recovery. |
+| `chat_history.enabled` | `true`, `false` | `true` | Persist chat events to `agents/.agent-chat-history` (JSONL) for crash recovery. |
 | `chat_history.frequency` | `per_turn`, `per_phase`, `per_tool` | per profile | Logging granularity. Defaults: `minimal`→`per_turn`, `balanced`→`per_phase`, `full`→`per_tool`. |
 | `chat_history.max_size_kb` | integer | per profile | Max file size before overflow handling. Defaults: `minimal`→`128`, `balanced`→`256`, `full`→`512`. |
 | `chat_history.on_overflow` | `rotate`, `compress` | per profile | On overflow: `rotate` drops oldest entries; `compress` marks the file for summarization on the next turn. Defaults: `minimal`/`balanced`→`rotate`, `full`→`compress`. |
-| `chat_history.heartbeat` | `on`, `off`, `hybrid` | `hybrid` | Visibility of the `📒 chat-history:` marker. `on` = every reply (~20 tokens), `off` = silent, `hybrid` = print only on drift states (`missing`/`foreign`/`returning`). YAML `on`/`off` accepted bare. |
-| `chat_history.path` | `hook`, `checkpoint`, `manual` | `checkpoint` | Population path. `hook` = platform fires lifecycle hooks; `checkpoint` = agent invokes `/chat-history-checkpoint` at phase boundaries; `manual` = rule inert (cloud). `scripts/install.py` flips this to `hook` when the platform's hook config is deployed. See [`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md). |
+| `chat_history.text_limits.{user,agent,tool,phase}` | integer (chars) | `user=0`, `agent=5000`, `tool=200`, `phase=200` | Per-entry-type text-length cap. `0` = verbatim, no slice. `N > 0` = collapse whitespace, slice to N chars, append `" … [+K chars]"` so the log self-reports truncation. Defaults match `DEFAULT_TEXT_LIMITS` in `scripts/chat_history.py`. |
 | `hooks.enabled` | `true`, `false` | `false` | Master switch for the work-engine hook layer. When `false` (default) the registry stays empty and golden replay is byte-stable. See [`agents/contexts/work-engine-hooks.md`](../../../agents/contexts/work-engine-hooks.md). |
 | `hooks.trace` | `true`, `false` | `false` | Emit per-event trace lines on stderr. Useful for debugging; off by default because it is noisy. |
 | `hooks.halt_surface_audit` | `true`, `false` | `true` | Defense-in-depth check that every halt surfaced by the dispatcher carries the expected shape. Cheap. |
 | `hooks.state_shape_validation` | `true`, `false` | `true` | Re-run the state schema validator on `AFTER_LOAD` and `BEFORE_SAVE`. Cheap, catches drift. |
 | `hooks.directive_set_guard` | `true`, `false` | `true` | Verify the dispatcher-resolved directive set matches the input envelope intent. Cheap, catches routing drift. |
-| `hooks.chat_history.enabled` | `true`, `false` | `true` | Register the four chat-history hooks (turn-check, append, halt-append, heartbeat). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. |
+| `hooks.chat_history.enabled` | `true`, `false` | `true` | Register chat-history hooks (`append` on `after_step`, `halt_append` on `on_halt`). Gated by **both** this flag AND `chat_history.enabled`; either off → no chat-history hook registers. Schema v4: every entry self-identifies via 16-char session fingerprint, no ownership/sidecar layer. |
 | `hooks.chat_history.script` | path | `scripts/chat_history.py` | Override path to the chat-history CLI. Set only when the script lives outside the standard location. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
+| `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap execute` runs the project's quality pipeline. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. `verify-before-complete` still requires fresh output before any "roadmap complete" claim. |
 | `subagents.implementer_model` | model alias or empty | _(empty)_ | Model for implementer subagents. Empty = same tier as session model. See [subagent-configuration](../contexts/subagent-configuration.md). |
 | `subagents.judge_model` | model alias or empty | _(empty)_ | Model for judge subagents. Empty = one tier above implementer (opus if sonnet, sonnet if haiku). |
 | `subagents.max_parallel` | integer | `3` | Maximum parallel subagent invocations. `1` serializes. |

package/.agent-src/templates/roadmaps.md

@@ -39,11 +39,16 @@ Templates for roadmap files stored in `agents/roadmaps/` or `app/Modules/{Module
 
 ---
 
-## Quality Gates (always apply)
+## Quality Gates (always apply at completion)
 
-Every roadmap must pass these before it is considered done:
+Every roadmap must pass the project's quality pipeline before it is
+considered done. **When** the pipeline runs during `/roadmap execute` is
+governed by `roadmap.quality_cadence` in `.agent-settings.yml`
+(`end_of_roadmap` default → once before archival; `per_phase` → after
+every phase; `per_step` → after every step). Either way, a final fresh
+run is mandatory before "complete" per `verify-before-complete`.
 
-Run the project's quality pipeline and test suite. Common commands:
+Common commands:
 
 ```bash
 # PHP projects (inside Docker container if applicable)

package/.agent-src/templates/scripts/work_engine/hook_bootstrap.py

@@ -17,10 +17,10 @@ from .hooks import HookRegistry
 from .hooks.builtin import (
     ChatHistoryAppendHook,
     ChatHistoryHaltAppendHook,
-    ChatHistoryHeartbeatHook,
-    ChatHistoryTurnCheckHook,
+    DecisionTraceHook,
     DirectiveSetGuardHook,
     HaltSurfaceAuditHook,
+    MemoryVisibilityHook,
     StateShapeValidationHook,
     TraceHook,
 )
@@ -56,6 +56,13 @@ def _build_hook_registry(args: argparse.Namespace) -> HookRegistry:
         StateShapeValidationHook().register(registry)
     if settings.directive_set_guard:
         DirectiveSetGuardHook().register(registry)
+    if settings.decision_trace:
+        DecisionTraceHook().register(registry)
+    if settings.memory_visibility:
+        MemoryVisibilityHook(
+            cost_profile=settings.cost_profile,
+            visibility_off=settings.memory_visibility_off,
+        ).register(registry)
     if settings.chat_history_enabled:
         _register_chat_history_hooks(registry, settings)
 
@@ -65,12 +72,16 @@ def _build_hook_registry(args: argparse.Namespace) -> HookRegistry:
 def _register_chat_history_hooks(
     registry: HookRegistry, settings: HookSettings,
 ) -> None:
-    """Register the four chat-history hooks bound to the configured script."""
+    """Register the structural chat-history hooks bound to the configured script.
+
+    Hook-only contract (post road-to-chat-history-hook-only): only the
+    append + halt-append hooks remain; cooperative ``turn-check`` /
+    ``heartbeat`` hooks were removed when the cooperative always-rules
+    were retired.
+    """
     script = Path(settings.chat_history_script)
-    ChatHistoryTurnCheckHook(script).register(registry)
     ChatHistoryAppendHook(script).register(registry)
     ChatHistoryHaltAppendHook(script).register(registry)
-    ChatHistoryHeartbeatHook(script).register(registry)
 
 
 __all__ = ["_build_hook_registry", "_register_chat_history_hooks"]

package/.agent-src/templates/scripts/work_engine/hooks/__init__.py

@@ -22,10 +22,10 @@ from __future__ import annotations
 from .builtin import (
     ChatHistoryAppendHook,
     ChatHistoryHaltAppendHook,
-    ChatHistoryHeartbeatHook,
-    ChatHistoryTurnCheckHook,
+    DecisionTraceHook,
     DirectiveSetGuardHook,
     HaltSurfaceAuditHook,
+    MemoryVisibilityHook,
     StateShapeValidationHook,
     TraceHook,
 )
@@ -38,8 +38,7 @@ from .runner import HookRunner
 __all__ = [
     "ChatHistoryAppendHook",
     "ChatHistoryHaltAppendHook",
-    "ChatHistoryHeartbeatHook",
-    "ChatHistoryTurnCheckHook",
+    "DecisionTraceHook",
     "DirectiveSetGuardHook",
     "HaltSurfaceAuditHook",
     "HookCallback",
@@ -49,6 +48,7 @@ __all__ = [
     "HookHalt",
     "HookRegistry",
     "HookRunner",
+    "MemoryVisibilityHook",
     "StateShapeValidationHook",
     "TraceHook",
 ]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/__init__.py

@@ -13,20 +13,20 @@ from __future__ import annotations
 
 from .chat_history_append import ChatHistoryAppendHook
 from .chat_history_halt_append import ChatHistoryHaltAppendHook
-from .chat_history_heartbeat import ChatHistoryHeartbeatHook
-from .chat_history_turn_check import ChatHistoryTurnCheckHook
+from .decision_trace import DecisionTraceHook
 from .directive_set_guard import DirectiveSetGuardHook
 from .halt_surface_audit import HaltSurfaceAuditHook
+from .memory_visibility import MemoryVisibilityHook
 from .state_shape_validation import StateShapeValidationHook
 from .trace import TraceHook
 
 __all__ = [
     "ChatHistoryAppendHook",
     "ChatHistoryHaltAppendHook",
-    "ChatHistoryHeartbeatHook",
-    "ChatHistoryTurnCheckHook",
+    "DecisionTraceHook",
     "DirectiveSetGuardHook",
     "HaltSurfaceAuditHook",
+    "MemoryVisibilityHook",
     "StateShapeValidationHook",
     "TraceHook",
 ]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/_chat_history_base.py

@@ -12,9 +12,6 @@ import sys
 from pathlib import Path
 from typing import Callable, Sequence
 
-from ..context import HookContext
-from ..exceptions import HookError
-
 ProcessRunner = Callable[[Sequence[str]], "subprocess.CompletedProcess[str]"]
 """Callable that runs a subprocess. Production default: ``_default_runner``."""
 
@@ -28,65 +25,24 @@ def _default_runner(cmd: Sequence[str]) -> "subprocess.CompletedProcess[str]":
     return subprocess.run(list(cmd), capture_output=True, text=True, check=False)
 
 
-def _derive_first_user_msg(ctx: HookContext) -> str | None:
-    """Pull a stable first-user-msg out of the available context.
+class _ChatHistoryHookBase:
+    """Shared plumbing — script path and runner.
 
-    CLI-layer events carry ``ctx.work`` (the v1 envelope); dispatcher-layer
-    events (``before_step`` / ``after_step`` / ``on_halt``) carry only
-    ``ctx.delivery`` (the legacy :class:`DeliveryState`). Both shapes feed
-    the same ``id: title`` / ``raw`` derivation so chat-history entries
-    stay stable across the lifecycle. Returns ``None`` when the shape is
-    unknown — callers raise ``HookError`` so the runner converts it to
-    a warning.
+    Schema v4 derives session attribution from the platform ``session_id``
+    (passed by the platform-hook dispatcher), not from a derived
+    first-user-msg. work-engine internal hooks have no platform session
+    in scope, so they omit ``--session-id`` and entries land in the
+    ``<unknown>`` session bucket.
     """
-    work = ctx.work
-    if work is not None and getattr(work, "input", None) is not None:
-        inp = work.input
-        data = getattr(inp, "data", None) or {}
-        kind = getattr(inp, "kind", None)
-        if kind == "prompt":
-            raw = data.get("raw")
-            if raw:
-                return str(raw)
-        elif kind == "ticket":
-            joined = _ticket_msg(data)
-            if joined:
-                return joined
-
-    delivery = ctx.delivery
-    if delivery is not None:
-        ticket = getattr(delivery, "ticket", None) or {}
-        joined = _ticket_msg(ticket)
-        if joined:
-            return joined
-    return None
-
-
-def _ticket_msg(ticket: dict) -> str:
-    ticket_id = ticket.get("id") or ""
-    title = ticket.get("title") or ""
-    return f"{ticket_id}: {title}".strip(": ").strip()
-
-
-class _ChatHistoryHookBase:
-    """Shared plumbing — script path, runner, and first-msg derivation."""
 
     def __init__(
         self,
         script_path: Path,
         *,
         runner: ProcessRunner | None = None,
-        first_user_msg: str | None = None,
     ) -> None:
         self.script_path = Path(script_path)
         self._runner = runner or _default_runner
-        self._fixed_msg = first_user_msg
-
-    def _resolve_msg(self, ctx: HookContext) -> str:
-        msg = self._fixed_msg or _derive_first_user_msg(ctx)
-        if not msg:
-            raise HookError("chat-history hook: cannot derive first-user-msg")
-        return msg
 
     def _invoke(self, *args: str) -> "subprocess.CompletedProcess[str]":
         cmd = [sys.executable, str(self.script_path), *args]

package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_append.py

@@ -29,10 +29,9 @@ class ChatHistoryAppendHook(_ChatHistoryHookBase):
         result = ctx.result
         if result is None or getattr(result, "outcome", None) != Outcome.SUCCESS:
             return
-        msg = self._resolve_msg(ctx)
         payload: dict[str, Any] = {"step": ctx.step_name or "<unknown>"}
         proc = self._invoke(
-            "append", "--first-user-msg", msg,
+            "append",
             "--type", "phase", "--json", json.dumps(payload),
         )
         if proc.returncode != EXIT_OK:

package/.agent-src/templates/scripts/work_engine/hooks/builtin/chat_history_halt_append.py

@@ -22,7 +22,6 @@ class ChatHistoryHaltAppendHook(_ChatHistoryHookBase):
         registry.register(HookEvent.ON_HALT, self._on_halt)
 
     def _on_halt(self, ctx: HookContext) -> None:
-        msg = self._resolve_msg(ctx)
         questions: list[str] = []
         if ctx.result is not None:
             questions = list(getattr(ctx.result, "questions", []) or [])
@@ -30,7 +29,7 @@ class ChatHistoryHaltAppendHook(_ChatHistoryHookBase):
             questions = list(getattr(ctx.delivery, "questions", []) or [])
         payload = {"step": ctx.step_name or "<unknown>", "questions": questions}
         proc = self._invoke(
-            "append", "--first-user-msg", msg,
+            "append",
             "--type", "decision", "--json", json.dumps(payload),
         )
         if proc.returncode != EXIT_OK: