@event4u/agent-config 1.19.0 → 1.20.0

package/.agent-src/commands/chat-history/resume.md

@@ -1,183 +0,0 @@
----
-name: chat-history:resume
-cluster: chat-history
-sub: resume
-description: Load the persistent chat-history log into the current conversation — picks match/returning/foreign flow and supports resume, merge, replace, or continue
-disable-model-invocation: true
-suggestion:
-  eligible: false
-  rationale: "Explicit resume mechanic with foreign/returning state machine."
----
-<!-- cloud_safe: noop -->
-
-# /chat-history resume
-Reconnects the current conversation with an existing `.agent-chat-history`
-file. Depending on the 4-state ownership check, it routes to the right
-flow: silent summarize, adopt, merge, or replace.
-
-Use after a crashed chat, after switching tools (Augment → Claude Code),
-or when the agent showed the foreign- or returning-session prompt from
-the [`chat-history`](../rules/chat-history-ownership.md) rule and the user picked
-"resume".
-
-## When NOT to use
-
-- Just inspect metadata → [`/chat-history`](chat-history.md).
-- Start fresh instead of resuming → [`/chat-history-clear`](chat-history-clear.md)
-  or pick "New start" in the foreign prompt.
-- Logging is disabled (`chat_history.enabled: false`) → enable it in
-  `.agent-settings.yml` first; this command refuses to run otherwise.
-
-## Preconditions
-
-- `.agent-settings.yml` exists and `chat_history.enabled: true`.
-- `.agent-chat-history` exists at the project root.
-
-If either is missing, tell the user and stop — do not create files here.
-
-## Steps
-
-### 1. Load status
-
-Run `scripts/chat_history.py status`. If `exists: false` or
-`entries: 0`, tell the user there is nothing to resume and stop.
-
-### 2. Determine ownership state
-
-Run `scripts/chat_history.py state --first-user-msg "<current first user
-message>"`. Branch on the result:
-
-- `match` → step 3a (already owner)
-- `returning` → step 3b (pick Merge / Replace / Continue)
-- `foreign` → step 3c (pick Resume / New start / Ignore)
-- `missing` → header corrupt; tell the user and suggest
-  `/chat-history-clear` to start fresh. Stop.
-
-### 3a. `match` — already owner
-
-Nothing to adopt. Skip to step 4 (summarize) for the user's benefit.
-
-### 3b. `returning` — this chat once owned the file
-
-Another session took over. Present the Returning-Prompt from the rule
-and wait for a number:
-
-```
-> 📒 Welcome back. This chat once owned the history file; another
-> session has written to it since.
->
-> On-file entries: {N}   Size: {X} KB
->
-> 1. Merge — my in-memory history first, the foreign entries after
-> 2. Replace — wipe the foreign entries, keep only my history
-> 3. Continue — leave the file as-is; only new entries from now on
-```
-
-- **1 (Merge)** — build the in-memory entries list (see below), then:
-  ```bash
-  scripts/chat_history.py prepend --entries-json '<list>'
-  scripts/chat_history.py adopt --first-user-msg "<msg>"
-  ```
-- **2 (Replace)** — build the in-memory entries list, then:
-  ```bash
-  scripts/chat_history.py reset --first-user-msg "<msg>" \
-    --freq <frequency> --entries-json '<list>'
-  ```
-- **3 (Continue)** —
-  ```bash
-  scripts/chat_history.py adopt --first-user-msg "<msg>"
-  ```
-
-### 3c. `foreign` — new chat finds an unknown session's file
-
-Present the Foreign-Prompt from the rule and wait for a number:
-
-```
-> 📒 Found chat history from an unknown session.
->
-> Entries on file: {N}   Size: {X} KB
->
-> 1. Resume — adopt this file, load entries as context, keep appending
-> 2. New start — archive to .agent-chat-history.bak, init fresh
-> 3. Ignore — leave the file untouched, disable logging for this session
-```
-
-- **1 (Resume)** — `adopt --first-user-msg "<msg>"`.
-- **2 (New start)** — rename file to `.agent-chat-history.bak`, run
-  `init --first-user-msg "<msg>" --freq <frequency>`. Skip summary.
-- **3 (Ignore)** — do nothing. Report that logging is off for this
-  conversation. Stop.
-
-### 3d. Building the in-memory entries list (Merge / Replace)
-
-Reconstruct the agent's prior turns as a JSON array:
-
-- one `{"t":"user","text":"<preview>","ts":"<iso>"}` per user message
-- one `{"t":"agent","text":"<preview>","ts":"<iso>"}` per agent reply
-- `text` previews capped at ~200 chars (whitespace flattened)
-- timestamps in ISO-8601 UTC (current time is acceptable if exact times
-  are unknown; order is what matters)
-- no tool-call payloads, no file contents, no secrets
-
-If the list is large (>30 KB), stream it via stdin:
-`prepend --entries-stdin` or `reset --entries-stdin`.
-
-### 4. Overflow check
-
-After any Merge or Replace, run
-`scripts/chat_history.py rotate --max-kb <max_size_kb>
---mode <on_overflow>` so the combined body stays within the user's
-budget.
-
-### 5. Summarize into conversation context
-
-Read the entries via the helper (`read --all` or `read --last N` for
-bounded). Produce a short, structured summary — **not** a verbatim dump:
-
-```
-> 📒 Resumed chat-history ({entries} entries, {age})
->
-> ## What was done
-> - {1–3 bullets from agent/decision entries}
->
-> ## Open threads
-> - {1–3 bullets from the most recent entries and any pending questions}
->
-> ## Key decisions
-> - {decisions captured during the prior session}
->
-> Ready to continue. What would you like to do?
-```
-
-Keep the summary under ~25 lines. Rationale: this is input into the new
-turn, not a display artifact (see
-[`token-efficiency`](../rules/token-efficiency.md)).
-
-### 6. Hand control back to the user
-
-After presenting the summary, stop and wait. Do not auto-resume work —
-the user decides what to do next.
-
-## Gotchas
-
-- **Iron law — one question at a time.** Even if the log contains
-  several open threads, ask about one at a time after the summary
-  (see [`ask-when-uncertain`](../rules/ask-when-uncertain.md)).
-- `adopt` rewrites the header in place and pushes the previous fp into
-  `former_fps` (capped at 10). No backup is created — use
-  `/chat-history-clear` first if you want a clean slate.
-- `reset` discards whatever was on disk. Only use it when the user
-  explicitly picks "Replace".
-- The summary is derived from the agent's reading of the JSONL. Old
-  entries may be incomplete (especially under `per_turn` with
-  previews only). Flag gaps explicitly.
-
-## See also
-
-- [`chat-history`](../rules/chat-history-ownership.md) — the rule that triggers
-  this command via the foreign- and returning-session prompts
-- [`/chat-history`](chat-history.md) — status inspection without adopting
-- [`/chat-history-clear`](chat-history-clear.md) — wipe instead of adopt
-- [`/agent-handoff`](agent-handoff.md) — complementary: generates a
-  paste-into-new-chat prompt (no disk file)
-- [`scripts/chat_history.py`](../../../scripts/chat_history.py) — helper API

package/.agent-src/rules/chat-history-cadence.md

@@ -1,143 +0,0 @@
----
-type: "auto"
-tier: "mechanical-already"
-description: "Appending to .agent-chat-history — cadence boundaries (per_turn/per_phase/per_tool), turn-check ownership refusal handling, never writing the file directly; cadence is the trigger, not reply length"
-alwaysApply: false
-source: package
----
-
-<!-- cloud_safe: noop -->
-
-# Chat History — Cadence
-
-Owns gate 2 of the chat-history Iron Law: WHEN to call `append`.
-Ownership (gate 1) lives in [`chat-history-ownership`](chat-history-ownership.md);
-visibility (gate 3) lives in [`chat-history-visibility`](chat-history-visibility.md).
-File I/O is owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py)
-— this rule decides the trigger boundaries, not the file format.
-
-## Iron Law — gate 2 (append at every cadence boundary)
-
-```
-EVERY CADENCE BOUNDARY GETS ONE append CALL — WITH --first-user-msg.
-SKIPPING IS A RULE VIOLATION. NEVER WRITE .agent-chat-history DIRECTLY.
-ON HOOK / ENGINE PATHS, THE PLATFORM / ENGINE PERFORMS append STRUCTURALLY
-— THE AGENT MUST NOT DUPLICATE.
-```
-
-Cadence is **gated by ownership**: gate 1 (turn-check from
-[`chat-history-ownership`](chat-history-ownership.md)) must have cleared
-this turn before any append fires. Skip turn-check → append refuses with
-exit `3` (`OWNERSHIP_REFUSED`).
-
-## Append cadence — boundaries
-
-Cadence comes from `chat_history.frequency` in `.agent-settings.yml`:
-
-- `per_turn` → one entry at the end of every agent turn.
-- `per_phase` → at phase boundaries (user question answered, decision
-  taken, task-list item completed, significant tool sequence finished).
-  Pure clarification turns may skip.
-- `per_tool` → after each tool-call sequence.
-
-Every append goes through
-
-```bash
-scripts/chat_history.py append --first-user-msg "<msg>" \
-  --type <user|agent|tool|decision|phase> --json '<obj>'
-```
-
-Never write the file directly. Prefer `phase` over `agent` for boundaries.
-**Cadence is the trigger, not reply length** — a one-line reply that
-crosses a boundary still appends; a 200-line reply that doesn't cross
-one still doesn't. **Do not batch missed turns** — crashes happen
-between turns, and a batched append loses the timeline that crash
-recovery depends on.
-
-## Ownership refusal — exit `3`
-
-`append` exits `3` when the file's ownership header doesn't match the
-current session (`turn-check` was skipped or the file was hijacked
-between turns). Surface the failure to the user, **do not swallow it**:
-
-1. Stop the current append.
-2. Render the Foreign-Prompt from [`chat-history-ownership`](chat-history-ownership.md)
-   so the user re-handshakes.
-3. Resume cadence only after gate 1 clears again.
-
-This is the structural enforcement layer that catches the case where
-an agent technically called `turn-check` but on the wrong platform path
-(e.g. HOOK platform also tried CHECKPOINT cooperative gates and the
-file got into a mixed state).
-
-## Path-specific behavior
-
-**CHECKPOINT path** — gates 1 + 2 are cooperative. The agent runs
-`turn-check` first, then runs `append` at every cadence boundary.
-`/chat-history-checkpoint` is the recommended boundary-trigger; it
-captures phase entries with the right metadata.
-
-**HOOK path** — `work_engine` and platform `SessionStart` /
-`PreToolUse` hooks fire `turn-check` and `append` structurally. The
-agent must **not** call either — double-write produces interleaved
-entries and breaks the JSONL schema. Hooks emit the same exit codes,
-so refusal handling stays identical.
-
-**ENGINE path** — `work_engine` fires `append --type phase` per
-successful step and `append --type decision` on halt. Free-form prose
-around the engine output falls back to whatever path the platform
-supplies (HOOK or CHECKPOINT). Engine-driven turns inherit the
-structural guarantee for the duration of the dispatch cycle only.
-
-## What this rule does NOT do
-
-Manage ownership decisions (handshake, foreign/returning) — those
-live in [`chat-history-ownership`](chat-history-ownership.md).
-Manage the heartbeat marker — that lives in [`chat-history-visibility`](chat-history-visibility.md).
-Decide cadence dynamically based on reply content — cadence is
-the configured frequency, period.
-
-## Cloud Behavior
-
-On cloud surfaces (Claude.ai Web, Skills API) cadence is **inert** —
-no append calls, no `scripts/`, no JSONL file. Treat
-`chat_history.enabled` as `false`.
-
-## Copilot fallback
-
-GitHub Copilot has no `SessionStart` / `PostToolUse` / `Stop` hook
-surface, so `scripts/chat_history.py hook-dispatch` cannot fire
-structurally. `.agent-chat-history` is not maintained for the agent
-unless the agent runs the cooperative path itself.
-
-Treat Copilot as the **CHECKPOINT path** described above — gates 1 +
-2 are cooperative:
-
-1. Run `turn-check` on the first turn (and after any ownership
-   reset) to establish ownership against the first user message.
-2. Run `append --first-user-msg "<msg>" --type <…> --json '<…>'` at
-   every cadence boundary, exactly as the cooperative path
-   specifies.
-3. Surface ownership-refusal exit `3` to the user; do not swallow it.
-
-The state "file" the hook would have written is `.agent-chat-history`
-itself (JSONL, project root). The manual command that reproduces a
-single hook-dispatch step is the same one the dispatcher would
-have invoked:
-
-```bash
-scripts/chat_history.py hook-dispatch \
-  --platform copilot \
-  --event <session_start|post_tool_use|stop> \
-  < envelope.json
-```
-
-— but in practice the cooperative `turn-check` + `append` calls
-above are the supported Copilot path; `hook-dispatch` is mainly the
-dispatcher's entry point.
-
-## Interactions & references
-
-- Sibling rules: [`chat-history-ownership`](chat-history-ownership.md) (gate 1 — turn-check) · [`chat-history-visibility`](chat-history-visibility.md) (gate 3 — heartbeat marker).
-- `token-efficiency` — never load the full log; cadence keeps appends small and bounded.
-- API: [`scripts/chat_history.py`](../../../scripts/chat_history.py) `append` subcommand. Settings: [`agent-settings`](../templates/agent-settings.md) `chat_history.frequency`. Engine hooks: [`agents/contexts/work-engine-hooks.md`](../../../agents/contexts/work-engine-hooks.md).

package/.agent-src/rules/chat-history-ownership.md

@@ -1,124 +0,0 @@
----
-type: "auto"
-tier: "1"
-description: "First turn or reference to .agent-chat-history — detects ownership (match/returning/foreign/missing) and HOOK/ENGINE/CHECKPOINT/MANUAL path classification with numbered-options prompt"
-alwaysApply: false
-source: package
----
-
-<!-- cloud_safe: noop -->
-
-# Chat History — Ownership
-
-Owns gate 1 of the chat-history Iron Law: the first-turn handshake
-that decides whose `.agent-chat-history` file the current session is
-talking to. Cadence (gate 2) lives in [`chat-history-cadence`](chat-history-cadence.md);
-visibility (gate 3) lives in [`chat-history-visibility`](chat-history-visibility.md).
-File I/O is owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py)
-— this rule says **when** to handshake, not how the file is structured.
-
-## Two paths — platform decides which Iron Law applies
-
-Population of `.agent-chat-history` is **structural** (platform-driven)
-on platforms with native lifecycle hooks, and **cooperative**
-(agent-driven) on platforms without. Both paths converge on the same
-JSONL schema; only the trigger differs. Per-platform classification
-lives in
-[`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md).
-
-| Path | Platforms / Surfaces | Trigger | Agent's role |
-|---|---|---|---|
-| **HOOK** | Claude Code, Augment CLI, Cursor 1.7+, Cline non-Windows, Windsurf, Gemini CLI | Platform fires native lifecycle hooks → `./agent-config chat-history:hook --platform <name>` | Read-only — observe, do not duplicate appends |
-| **ENGINE** | `/implement-ticket`, `/work`, any flow driven by `scripts/work_engine/cli.py` | `work_engine` fires `turn-check` (before-dispatch), `append --type phase` (per successful step), `--type decision` (on-halt), `heartbeat` (after-dispatch) via the hook layer | Read-only during engine-driven turns — do not duplicate appends. See [`agents/contexts/work-engine-hooks.md`](../../../agents/contexts/work-engine-hooks.md) |
-| **CHECKPOINT** | Augment IDE plugin, Cursor < 1.7, Cline on Windows | Agent invokes `/chat-history-checkpoint` at phase boundaries | Cooperative — gates 1 + 2 + 3 are mandatory |
-| **MANUAL** | Cloud surfaces (Claude.ai Web, Skills API) | Rule is inert — see Cloud Behavior | None |
-
-Detect the path on first turn: read `chat_history.platform` from
-`.agent-settings.yml` if set, else fall back to `chat_history.path`
-(`hook` / `checkpoint` / `manual`). Missing both → assume CHECKPOINT
-(safest cooperative default; HOOK platforms install the platform
-config explicitly via `scripts/install.py`).
-
-## Iron Law — gate 1 (turn-check is the first tool call)
-
-```
-ON CHECKPOINT, turn-check IS THE FIRST TOOL CALL OF EVERY SESSION.
-ON HOOK, THE PLATFORM FIRES turn-check STRUCTURALLY — DO NOT DUPLICATE.
-ON ENGINE, work_engine FIRES turn-check BEFORE DISPATCH — DO NOT DUPLICATE.
-```
-
-CHECKPOINT path — run silently before any other tool call:
-
-```bash
-scripts/chat_history.py turn-check --first-user-msg "<first-user-msg>"
-```
-
-Exit codes: `0` = `ok`/`disabled` (proceed), `10` = `missing`
-(run `init --first-user-msg "..." --freq <freq>`), `11` = `foreign`
-(render Foreign-Prompt + stop), `12` = `returning` (render
-Returning-Prompt + stop). The script writes a one-line
-`ACTION REQUIRED:` hint to stderr on non-zero exits.
-
-## Activation & handshake
-
-Read `chat_history.*` from `.agent-settings.yml` **once per conversation**
-(first turn) and cache. `enabled: false` or section missing → all three
-chat-history rules are a **no-op** (do not read, write, or mention the
-file). Otherwise cache `frequency`, `max_size_kb`, `on_overflow`, and
-the **path** (HOOK / CHECKPOINT / MANUAL — see the table above).
-
-**HOOK path** — skip `turn-check` entirely. The platform's
-`SessionStart` hook already initialized the file; the agent's job is to
-read `status` once for context awareness (header preview, entry count)
-and otherwise leave I/O to the hook dispatcher. Foreign / Returning
-prompts still apply because hooks call into the same ownership state
-machine — when the dispatcher reports `foreign` or `returning` via
-exit code or stderr, render the corresponding prompt.
-
-**CHECKPOINT path** — run `turn-check` as the first tool call. State
-token branches to one of: `missing` → `init`, `ok` → continue,
-`foreign` → Foreign-Prompt, `returning` → Returning-Prompt.
-`/chat-history-checkpoint` is the recommended way to satisfy gate 2
-at phase boundaries (see [`chat-history-cadence`](chat-history-cadence.md)).
-
-In `foreign` and `returning`, **always read the file's current contents
-into the agent's working context before any write** — the user chose to
-log history for a reason; losing it silently is never acceptable. The
-legacy `state` subcommand still works for shell scripts; agents prefer
-`turn-check` (folds in `enabled` + distinct exit codes).
-
-## Foreign / Returning prompts — full mechanics
-
-When `turn-check` exits `11` (foreign) or `12` (returning), render the
-matching numbered-options block from
-[`agents/contexts/chat-history-handshake.md`](../../../agents/contexts/chat-history-handshake.md).
-That doc holds the prompt bodies, the option → script-call mapping
-(`adopt` / `init` / `prepend` / `reset`), the in-memory entries-list
-shape, free-text fallbacks, and the overflow handling per
-`on_overflow` (`rotate` / `compress`). Read it once on first foreign
-or returning event; cache the chosen option for the rest of the
-conversation.
-
-## What this rule does NOT do
-
-Display/reload/clear (`/chat-history*` commands). Auto-flip `enabled` or
-`on_overflow`. Run when `enabled: false`. Decide ownership
-heuristically — only `turn-check` / `state` does that. Double-write on
-HOOK platforms — when hooks fire structurally, the agent does **not**
-also call `turn-check`. Cadence (gate 2) and heartbeat (gate 3) are
-covered in their sibling rules.
-
-## Cloud Behavior
-
-On cloud surfaces (Claude.ai Web, Skills API) the rule is **fully inert** —
-no `.agent-chat-history`, no `scripts/`, no Iron Law gates, no foreign/returning
-prompts. Treat `chat_history.enabled` as `false`; persistence is a
-local-agent concern.
-
-## Interactions & references
-
-- Sibling rules: [`chat-history-cadence`](chat-history-cadence.md) (gate 2 — append timing) · [`chat-history-visibility`](chat-history-visibility.md) (gate 3 — heartbeat marker).
-- `ask-when-uncertain` + `user-interaction` — foreign/returning prompts use numbered options, one question per turn.
-- `language-and-tone` — prompt translated at runtime; `.md` stays English.
-- `onboarding-gate` — runs first; this rule activates only after it clears.
-- API: [`scripts/chat_history.py`](../../../scripts/chat_history.py). Commands: [`/chat-history`](../commands/chat-history.md), [`/chat-history-resume`](../commands/chat-history-resume.md), [`/chat-history-clear`](../commands/chat-history-clear.md), [`/chat-history-checkpoint`](../commands/chat-history-checkpoint.md). Settings: [`agent-settings`](../templates/agent-settings.md). Platform classification: [`agents/contexts/chat-history-platform-hooks.md`](../../../agents/contexts/chat-history-platform-hooks.md). Types: [`rule-type-governance`](rule-type-governance.md).

package/.agent-src/rules/chat-history-visibility.md

@@ -1,97 +0,0 @@
----
-type: "auto"
-tier: "mechanical-already"
-description: "Emitting the chat-history heartbeat marker — paste subprocess stdout verbatim or nothing, never type from memory, hybrid mode prints on drift only, slip handling per language-and-tone"
-alwaysApply: false
-source: package
----
-
-<!-- cloud_safe: noop -->
-
-# Chat History — Visibility
-
-Owns gate 3 of the chat-history Iron Law: the heartbeat marker that
-makes append-cadence drift visible. Ownership (gate 1) lives in
-[`chat-history-ownership`](chat-history-ownership.md); cadence (gate 2)
-lives in [`chat-history-cadence`](chat-history-cadence.md). File I/O is
-owned by [`scripts/chat_history.py`](../../../scripts/chat_history.py).
-
-## Iron Law — gate 3 (heartbeat is subprocess stdout, not memory)
-
-```
-HEARTBEAT IS THE SCRIPT OUTPUT OF THE CURRENT TURN, VERBATIM, OR NOTHING.
-NEVER TYPE THE LINE FROM MEMORY. NEVER REUSE THE PRIOR TURN'S MARKER.
-EMPTY STDOUT → NO MARKER LINE.
-```
-
-Run silently before emitting the final reply:
-
-```bash
-scripts/chat_history.py heartbeat --first-user-msg "<first-user-msg>"
-```
-
-Stdout is **at most** one line, e.g.
-`📒 chat-history: ok · 9 entries · per_phase · last 30s ago`. Non-empty →
-paste **verbatim** as the last line of the reply. Empty → emit nothing.
-Always exits 0 — observability, not a gate.
-
-## Visibility modes — `chat_history.heartbeat`
-
-| Mode | When marker prints | Token cost |
-|---|---|---|
-| `on` | every reply (legacy) | ~20 tokens / reply |
-| `off` | never — full silence | 0 |
-| `hybrid` *(default)* | drift states only (`missing`/`foreign`/`returning`) | 0 in normal flow, ~20 on drift |
-
-`hybrid` ships zero tokens when healthy, loud on ownership drift. YAML 1.1
-booleanizes bare `on`/`off`; the reader coerces both back, so
-`heartbeat: on` works unquoted.
-
-## Memory-typing the marker — rule violation, not a slip
-
-Format is memorizable; counts and timestamps are not. A typed-from-
-memory line shows stale entries and a healthy-looking `ok` while the
-file is silently behind — observability collapses, invisible until
-`status` is checked. Heartbeat is the script output of the **current
-turn**, verbatim, or nothing.
-
-**Self-check before send — MANDATORY.** (1) Did `heartbeat` run on
-this turn? (2) Is the line byte-identical to that subprocess stdout?
-(3) Empty stdout → no marker line. Any "no" → drop it.
-
-**Slip handling.** Stale marker called out → acknowledge once in the
-user's language; run `status`; on CHECKPOINT call `append` for
-missed phase-boundaries (see [`chat-history-cadence`](chat-history-cadence.md));
-run a real `heartbeat`; paste stdout verbatim or nothing. Don't promise
-"from now on" — only behaviour proves compliance (mirrors
-`language-and-tone` § slip handling).
-
-## Path-specific behavior
-
-Heartbeat (gate 3) stays useful for visibility on **every** path —
-HOOK, ENGINE, CHECKPOINT — because the marker reports the file's
-state, not the agent's intent. On HOOK and ENGINE paths the agent
-still emits the marker even though it didn't fire `turn-check` or
-`append` itself: the marker is read-only observability over whatever
-the platform / engine wrote.
-
-## What this rule does NOT do
-
-Manage ownership decisions — those live in [`chat-history-ownership`](chat-history-ownership.md).
-Manage append timing — that lives in [`chat-history-cadence`](chat-history-cadence.md).
-Auto-decide visibility mode — `chat_history.heartbeat` is the only
-trigger. Insert decoration: the marker is functional output per
-[`direct-answers`](direct-answers.md) emoji whitelist, not a status
-badge.
-
-## Cloud Behavior
-
-On cloud surfaces (Claude.ai Web, Skills API) heartbeat is **inert** —
-no marker line, no `scripts/`. Treat `chat_history.enabled` as `false`.
-
-## Interactions & references
-
-- Sibling rules: [`chat-history-ownership`](chat-history-ownership.md) (gate 1 — turn-check) · [`chat-history-cadence`](chat-history-cadence.md) (gate 2 — append).
-- `direct-answers` — emoji whitelist permits the `📒` marker as functional output, not decoration.
-- `language-and-tone` § slip handling — stale-marker acknowledgement.
-- API: [`scripts/chat_history.py`](../../../scripts/chat_history.py) `heartbeat` and `status` subcommands. Settings: [`agent-settings`](../templates/agent-settings.md) `chat_history.heartbeat`.

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

@@ -1,50 +0,0 @@
-"""``ChatHistoryHeartbeatHook`` — visibility marker before save.
-
-Fires on ``before_save``. Runs ``chat_history.py heartbeat`` and,
-if the script emits a marker line, threads it onto ``state.report``
-so the agent's reply naturally carries the heartbeat without manual
-copy/paste.
-
-Why ``before_save`` and not ``after_dispatch``: the marker must land
-in the report that gets persisted. ``cli._sync_back`` runs between
-``after_dispatch`` and ``before_save`` and reassigns
-``work.report = delivery.report`` — a marker written on
-``after_dispatch`` would be overwritten before ``_save``. Firing on
-``before_save`` runs after the sync, so the marker survives.
-"""
-from __future__ import annotations
-
-from ..context import HookContext
-from ..events import HookEvent
-from ..exceptions import HookError
-from ..registry import HookRegistry
-from ._chat_history_base import EXIT_OK, _ChatHistoryHookBase
-
-
-class ChatHistoryHeartbeatHook(_ChatHistoryHookBase):
-    """Run heartbeat before save; thread marker into ``state.report``."""
-
-    def register(self, registry: HookRegistry) -> None:
-        registry.register(HookEvent.BEFORE_SAVE, self._on_before_save)
-
-    def _on_before_save(self, ctx: HookContext) -> None:
-        msg = self._resolve_msg(ctx)
-        proc = self._invoke("heartbeat", "--first-user-msg", msg)
-        if proc.returncode != EXIT_OK:
-            raise HookError(
-                f"chat-history heartbeat failed (exit {proc.returncode})"
-            )
-        marker = (proc.stdout or "").strip()
-        if not marker or ctx.work is None:
-            return
-        existing = getattr(ctx.work, "report", "") or ""
-        if marker in existing:
-            return
-        sep = "\n\n" if existing else ""
-        try:
-            ctx.work.report = f"{existing}{sep}{marker}"
-        except AttributeError:
-            raise HookError("chat-history heartbeat: state.report not writable")
-
-
-__all__ = ["ChatHistoryHeartbeatHook"]

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

@@ -1,49 +0,0 @@
-"""``ChatHistoryTurnCheckHook`` — guards engine-driven turns.
-
-Fires on ``before_dispatch``; classifies the chat-history file via
-``scripts/chat_history.py turn-check``:
-
-- exit 0 (``ok``)        → continue
-- exit 10 (``missing``)  → continue (auto-init handled by chat_history.py)
-- exit 11 (``foreign``)  → raise :class:`HookHalt` so CLI exits 2
-- exit 12 (``returning``)→ raise :class:`HookHalt` so CLI exits 2
-- any other exit         → raise :class:`HookError` (warn, continue)
-"""
-from __future__ import annotations
-
-from ..context import HookContext
-from ..events import HookEvent
-from ..exceptions import HookError, HookHalt
-from ..registry import HookRegistry
-from ._chat_history_base import (
-    EXIT_FOREIGN,
-    EXIT_MISSING,
-    EXIT_OK,
-    EXIT_RETURNING,
-    _ChatHistoryHookBase,
-)
-
-
-class ChatHistoryTurnCheckHook(_ChatHistoryHookBase):
-    """Run ``turn-check`` at the start of dispatch; halt on drift."""
-
-    def register(self, registry: HookRegistry) -> None:
-        registry.register(HookEvent.BEFORE_DISPATCH, self._on_before_dispatch)
-
-    def _on_before_dispatch(self, ctx: HookContext) -> None:
-        msg = self._resolve_msg(ctx)
-        result = self._invoke("turn-check", "--first-user-msg", msg)
-        code = result.returncode
-        if code in (EXIT_OK, EXIT_MISSING):
-            return
-        if code in (EXIT_FOREIGN, EXIT_RETURNING):
-            text = (result.stderr or result.stdout or "").strip()
-            reason = "foreign" if code == EXIT_FOREIGN else "returning"
-            surface = [line for line in text.splitlines() if line] or [
-                f"chat-history turn-check: {reason}",
-            ]
-            raise HookHalt(f"chat_history_turn_check_{reason}", surface=surface)
-        raise HookError(f"chat-history turn-check failed (exit {code})")
-
-
-__all__ = ["ChatHistoryTurnCheckHook"]