protect-context 1.3.2 → 2.0.0

package/README.md

@@ -83,7 +83,7 @@ without turning the agent into a different agent.
 
 | Primitive | What it gives you | Where you meet it |
 |---|---|---|
-| **Brief** | Contract, recent trusted decisions and corrections, open loops, and the last evidence ID, injected before the agent starts a turn | Automatic in pi; `orientation`, `status`, `guard_journal` elsewhere |
+| **Brief** | Owner task, contract, recent trusted decisions and corrections, a short unverified section for the agent's own notes, open loops, and the last evidence ID — injected before a turn and re-asserted mid-run after a compaction | Automatic in pi; `orientation`, `status`, `guard_journal` elsewhere |
 | **Orientation** | Bounded repo digest: tree, languages, and conventions files (`CLAUDE.md`, `AGENTS.md`, `CONVENTIONS.md`, `README.md`, `README`) | Injected once per digest in pi; `orientation` in CLI/MCP |
 | **Evidence ledger** | Every verification run recorded as `ev-NNNN` with exit code, duration, command, and a bounded output digest | `guard_verify`, `protect-context verify`, `guard_evidence` |
 | **Loop brake** | Identical failing commands are fingerprinted; the Nth attempt is blocked instead of re-run | Hard block in pi and the CLI; reported through MCP |
@@ -284,8 +284,10 @@ PC Δ+88L/6f 0loop ev5 ctx8%
 | Verification evidence (`ev-NNNN`) | `guard_verify`, `/guard-verify` | `guard_verify` | `verify` |
 | Loop blocking | blocks the command | `guard_loop_check` reports and advises | `verify` refuses; `loops` exits 1 |
 | Scope audit | session-start baseline + warnings | `guard_diff_audit` (explicit baseline) | `diff --baseline REF` |
-| Journal write/read | `guard_note`, `/guard-note` | `guard_note`, `guard_journal` | `note`, `journal` |
-| Trusted re-injection of decisions | yes, after change or compaction | read views only | read views only |
+| Journal write/read | `guard_note`, `/guard-note`, `guard_journal` | `guard_note`, `guard_journal` | `note`, `journal` |
+| Trusted re-injection of decisions | yes, after change and after every compaction (incl. mid-run) | read views only | read views only |
+| Re-injection of the agent's own notes | yes, in an explicitly unverified section | read views only | read views only |
+| Owner task anchor | `/guard-task`, auto-captured from the first prompt | — | — |
 | Contract management | `/guard-contract` | `guard_contract` | `contract list\|add\|remove` |
 | Risky-command confirmation | one grouped confirm | host approval policy | — |
 | Status widget | yes | — | `status` |
@@ -302,6 +304,7 @@ Slash commands:
 | `/guard-contract` | `list` · `add <text>` · `remove <id>` — edit the persistent contract |
 | `/guard-verify` | Run a command through the evidence ledger |
 | `/guard-note` | Journal a `decision` · `correction` · `risk` · `note` |
+| `/guard-task` | Show · set `<text>` · `--clear` the owner task anchor that the brief re-injects |
 | `/guard-report` | Full session summary for handoff or review |
 
 Model-callable tools:
@@ -310,8 +313,9 @@ Model-callable tools:
 |---|---|---|
 | `guard_verify` | `command`, `timeout_s` (default 180, clamped 1–900) | Records `ev-NNNN`; refusal on a blocked loop |
 | `guard_note` | `type`, `text`, optional `tags` | Forced to the `agent` trust level |
+| `guard_journal` | `limit` (0–20, default 5), optional `type` | Read-only; recovers decisions, corrections, and the agent's own earlier notes after a compaction |
 | `guard_contract_check` | `summary` | Deterministic keyword coverage checklist, never a proof |
-| `guard_status` | — | Same data that feeds the widget |
+| `guard_status` | — | Same data that feeds the widget, including journal totals |
 
 ### MCP tools
 
@@ -497,7 +501,7 @@ when owner rows are malformed, preserving the original file for repair.
 | 3 | Editing too much / scope creep | Git diff audit over tracked, staged, and bounded non-ignored untracked work; safe explicit baselines | Warn/advisory |
 | 4 | Misunderstanding the repo | Worktree-root-aware bounded orientation digest in pi, CLI, and MCP; conventions-file discovery | Automatic context + explicit read |
 | 5 | Plausible but subtly wrong code | Deterministic contract checklist, verification gate, test-required seed | Heuristic/advisory |
-| 6 | Losing earlier context | Persistent journal; recent trusted decisions re-injected after change and compaction; CLI/MCP read views | Automatic context + explicit read |
+| 6 | Losing earlier context | Persistent journal; owner task anchor; recent trusted decisions re-injected after change and after every compaction (including mid-run threshold/overflow); agent notes re-injected as unverified; `guard_journal` read views | Automatic context + explicit read |
 | 7 | Repeating corrected behavior | Bounded tagged corrections; trusted corrections re-injected; model-authored entries retained for owner review | Automatic context + trust boundary |
 | 8 | Large diffs | Configurable line/file warning and hard-level notifications, status verdict, widget | Warn/advisory |
 | 9 | Repetitive debugging loops | Shared bash/evidence streak reconstruction; third identical failing command blocked by default in pi, CLI, and MCP | Hard block at configured threshold |
@@ -571,9 +575,13 @@ its count treated as a lower bound — the widget renders it as `Δ≥`.
 ### Trust and provenance
 
 Direct CLI and pi slash-command contract writes are treated as owner input.
-MCP/model journal writes are forcibly tagged `agent`: they stay inspectable
-through journal views but are not re-injected as trusted decisions or
-corrections. CLI and pi slash-command journal entries are trusted. Untagged
+MCP/model journal writes are forcibly tagged `agent`: they never enter the
+trusted `decisions:`/`corrections:` sections. They are not discarded either —
+the brief shows the newest two under `agent notes (unverified):`, clearly
+labelled and capped shorter than trusted text, and `guard_journal` returns the
+full stored entry. That keeps the model's own reasoning recoverable after a
+compaction without granting it authority. CLI and pi slash-command journal
+entries are trusted. Untagged
 legacy entries are treated as trusted for backward compatibility, because the
 frozen journal schema has no dedicated author field.
 
@@ -625,6 +633,9 @@ instead of leaving stale numbers in this README.
 | `Δ?` in the widget | Not a Git worktree, so no diff baseline | Run inside a repository, or use the CLI with an explicit `--baseline` |
 | `Δ≥` in the widget | Bounded untracked scan hit a cap | Treat the count as a lower bound; narrow the scan or review scope manually |
 | Loop never blocks | Commands differ (paths, flags) so fingerprints differ | Compare with `loops` / `guard_loop_check`; fingerprints intentionally ignore whitespace only |
+| Agent forgot its own earlier decision after a compaction | The brief shows only the newest 2 agent notes, 120 chars each | Read the full entry with `guard_journal` |
+| No guard block after an automatic compaction | Host emits no `context` event, so mid-run re-assertion cannot run | It returns at the next user prompt; check the host supports the `context` hook |
+| `task:` line is wrong or missing | Auto-capture ignores short prompts and slash commands, and an owner task always wins | Set it explicitly with `/guard-task <text>` or `/guard-task --clear` |
 | `PC_SESSION_ID` changes nothing in evidence | It scopes ledger *views*, not `state.json` | Expected: state is project-global by design |
 | MCP tool missing in host | Server not started with the venv interpreter | Point `command` at `.venv/bin/python` and pass `-m protect_context.mcp_server` |
 | Extension does not load | Node older than 22.19 or pi not restarted | Check `pi list`, then restart; use `pi -ne` to start without extensions |
@@ -662,15 +673,35 @@ instead of leaving stale numbers in this README.
 
 #### Determinism
 
-- The frozen brief carries at most 12 constraints. Overflow is visible, and
-  owner constraints are prioritized, but hidden constraints are not enforced by
-  context injection.
+- The frozen brief carries at most 12 constraints, 3 trusted decisions, 3
+  trusted corrections, and 2 agent notes. Overflow is visible (each section
+  announces what it hid) and points at `guard_journal`, but hidden entries are
+  not enforced by context injection.
 - Frozen fingerprint normalization collapses whitespace everywhere, including
   inside quoted shell strings. Semantically different commands can therefore
   share a loop fingerprint.
 - The deterministic contract checker is keyword coverage, not program analysis.
   Treat every `addressed` result as a review prompt, not proof.
 
+#### Compaction
+
+- Re-injection is only as good as the store. A constraint, decision, or task
+  that was never written down cannot be restored, and the brief is a bounded
+  pointer rather than a transcript; `guard_journal` returns the full entry.
+- A mid-run compaction (threshold or overflow recovery) resumes the turn
+  through `AgentStart`, where `before_agent_start` does not run. The extension
+  arms a `context` hook on `session_compact` and re-asserts the block on every
+  request until a persisted one is back in the conversation. On a host that
+  does not emit `context`, the block returns at the next user prompt instead.
+- Task capture stores the first substantive prompt (≤200 chars) in
+  `.agent-guard/state.json`. That is conversation content: it stays local and
+  gitignored, but review it before sharing a store, and clear it with
+  `/guard-task --clear`.
+- Agent notes are unverified context, never authority. A model that journals
+  "ignore the contract" is shown that sentence back under an explicitly
+  unverified heading; treat it as data, and keep owner constraints in the
+  contract where they are trusted.
+
 #### Store
 
 - `state.json` is project-global. Atomic replacement prevents torn JSON, but

package/extension/index.ts

@@ -46,12 +46,17 @@ import {
 } from "./lib/contract.ts";
 import {
   appendJournal,
+  boundedReadLimit,
+  countJournal,
   isJournalType,
   type JournalType,
   readJournal,
-  recentCorrections,
-  recentDecisions,
+  READ_LIMIT_DEFAULT,
+  recentAgentEntries,
+  recentJournal,
+  renderJournal,
   tagsWithRequired,
+  trustedEntries,
 } from "./lib/journal.ts";
 import { toolCallEvent, toolResultEvent, bashExitFromResult, type EventRecord } from "./lib/events.ts";
 import {
@@ -61,7 +66,14 @@ import {
   shouldBlockLoop,
   type LoopInfo,
 } from "./lib/loops.ts";
-import { buildBrief, sha1Hex, BRIEF_MAX_CONTRACT_LINES, CMD_DISPLAY_MAX, truncLine } from "./lib/brief.ts";
+import {
+  buildBrief,
+  sha1Hex,
+  BRIEF_MAX_CONTRACT_LINES,
+  CMD_DISPLAY_MAX,
+  TASK_DISPLAY_MAX,
+  truncLine,
+} from "./lib/brief.ts";
 import { parseNumstat, parseUntrackedPaths, scanUntrackedFiles } from "./lib/gitparse.ts";
 import { renderWidget } from "./lib/widget.ts";
 import { checkContractSummary, renderChecklist } from "./lib/contract_check.ts";
@@ -82,6 +94,9 @@ const WIDGET_ID = "protect-context";
 const BRIEF_CUSTOM_TYPE = "guard-brief";
 /** Upper clamp for guard_verify timeouts (keep in sync with verify.TIMEOUT_MAX_S). */
 const MAX_VERIFY_TIMEOUT_S = 900;
+/** A prompt shorter than this is a follow-up ("continue", "go on"), not a task
+ *  statement — capturing it would erase the real request. */
+const TASK_MIN_CAPTURE_CHARS = 20;
 
 export default function (pi: ExtensionAPI) {
   // Session-scoped state (rebuilt on every session_start; new extension
@@ -100,6 +115,13 @@ export default function (pi: ExtensionAPI) {
   const startTimes = new Map<string, { start: number; tool: string; cmd: string | null }>();
   let lastDiff = { lines: 0, files: 0, available: false, lowerBound: false };
   let lastCtxPct: number | null = null;
+  // Mid-run re-injection (SPEC §5): a threshold/overflow compaction retries the
+  // run via AgentStart, so before_agent_start never fires for it. session_compact
+  // arms this flag; the `context` handler (per LLM request) then re-asserts the
+  // guard block until a persisted one is seen again. Outside that window the
+  // handler is an O(1) no-op; inside it the block is rebuilt per request, so a
+  // note written after the compaction is included.
+  let pendingReinject = false;
 
   // In-memory guardrail state (goal #12: O(1) hot paths — the event handlers
   // and widget never re-parse the JSONL files; disk reads happen once per
@@ -138,8 +160,10 @@ export default function (pi: ExtensionAPI) {
 
   // --- helpers ---------------------------------------------------------
 
-  /** Run an event/command body without ever throwing (SPEC §5). */
-  async function attempt<T>(ctx: ExtensionContext, fn: () => Promise<T>): Promise<T | undefined> {
+  /** Run an event/command body without ever throwing (SPEC §5). Synchronous
+   *  bodies are accepted so a handler that only formats text does not need a
+   *  token `async` wrapper. */
+  async function attempt<T>(ctx: ExtensionContext, fn: () => Promise<T> | T): Promise<T | undefined> {
     try {
       return await fn();
     } catch (err) {
@@ -385,6 +409,7 @@ export default function (pi: ExtensionAPI) {
     const d = await gatherDiff(ctx);
     lastDiff = { files: d.files, lines: d.lines, available: d.available, lowerBound: d.scanLimited };
     const ev = sessionEvidence(ctx.cwd);
+    const journal = readJournal(ctx.cwd);
     return {
       session: session.id,
       gitHead: session.gitHead,
@@ -398,6 +423,10 @@ export default function (pi: ExtensionAPI) {
       loops: openLoopsFromMap(loopState, cfg.loop_block_after),
       evidenceCount: ev.count,
       contractCount: loadContract(ctx.cwd).constraints.length,
+      journalCount: journal.length,
+      agentNoteCount: journal.filter((entry) =>
+        (Array.isArray(entry.tags) ? entry.tags : []).includes("agent"),
+      ).length,
       lastVerify: ev.last,
       ctxPct: lastCtxPct,
       diffWarnLines: cfg.diff_warn_lines,
@@ -533,6 +562,7 @@ export default function (pi: ExtensionAPI) {
       // tree even if HEAD appears later, so commits cannot erase session diff.
       session.gitUnborn = repoRoot !== null && session.gitHead === null;
       // Warm the in-memory counters once per session (O(1) hot paths after this).
+      pendingReinject = false;
       rebuildLoopState(ctx.cwd);
       evidenceCount = sessionEvidence(ctx.cwd).count;
       try {
@@ -545,53 +575,136 @@ export default function (pi: ExtensionAPI) {
     }),
   );
 
-  pi.on("before_agent_start", async (_event, ctx) =>
-    attempt(ctx, async () => {
-      refreshLoopStateIfChanged(ctx.cwd);
-      const contract = loadContract(ctx.cwd);
-      const journal = readJournal(ctx.cwd);
-      const decisions = recentDecisions(journal, 3);
-      const corrections = recentCorrections(journal, 3);
-      // In-memory streaks are the merged view (bash events + guard_verify
-      // outcomes) — the disk events alone would miss verify streaks.
-      const loops = openLoopsFromMap(loopState, cfg.loop_block_after).slice(0, 2);
-      const last = sessionEvidence(ctx.cwd).last;
-      const brief = buildBrief({
-        contract: contract.constraints,
-        decisions,
-        corrections,
-        loops,
-        lastEvidence: last ? { id: last.id, exit: last.exit, cmd: last.cmd, ms: last.ms } : null,
-      });
+  /** Orientation text, scanned lazily once per session (goal #4). */
+  function ensureOrientation(ctx: ExtensionContext): string | null {
+    if (orientationText === null) {
+      try {
+        orientationText = renderOrientation(scanOrientation(ctx.cwd));
+      } catch {
+        orientationText = null;
+      }
+    }
+    return orientationText;
+  }
+
+  /** Compose the brief from the store. Cold path: the digest gate decides
+   *  re-injection, so this runs only when the text changed or after a
+   *  compaction (goal #12). */
+  function composeBrief(ctx: ExtensionContext): string {
+    refreshLoopStateIfChanged(ctx.cwd);
+    const contract = loadContract(ctx.cwd);
+    const journal = readJournal(ctx.cwd);
+    // In-memory streaks are the merged view (bash events + guard_verify
+    // outcomes) — the disk events alone would miss verify streaks.
+    const loops = openLoopsFromMap(loopState, cfg.loop_block_after).slice(0, 2);
+    const last = sessionEvidence(ctx.cwd).last;
+    return buildBrief({
+      task: state.task?.text ?? null,
+      contract: contract.constraints,
+      // Full lists, not a pre-slice: buildBrief owns the display caps and
+      // reports exactly how many entries those caps hid.
+      decisions: trustedEntries(journal, "decision"),
+      corrections: trustedEntries(journal, "correction"),
+      agentNotes: recentAgentEntries(journal, journal.length),
+      loops,
+      lastEvidence: last ? { id: last.id, exit: last.exit, cmd: last.cmd, ms: last.ms } : null,
+    });
+  }
+
+  /** Full guard block (orientation + brief), forced past the digest gate. Only a
+   *  compaction needs this: it removed the previously injected block. */
+  function composeGuardBlock(ctx: ExtensionContext): string {
+    const parts: string[] = [];
+    const orientation = ensureOrientation(ctx);
+    if (orientation !== null) parts.push(orientation);
+    const brief = composeBrief(ctx);
+    if (brief.trim() !== "") parts.push(brief);
+    return parts.join("\n\n");
+  }
+
+  pi.on("before_agent_start", (_event, ctx) =>
+    attempt(ctx, () => {
+      const brief = composeBrief(ctx);
       const digest = sha1Hex(brief);
       const briefDue = brief.trim() !== "" && (cfg.brief_mode !== "changed" || view.brief_digest !== digest);
 
-      // Orientation (goal #4): injected once per distinct digest, like the
-      // brief. Lazily re-scanned if session_start did not populate it.
-      if (orientationText === null) {
-        try {
-          orientationText = renderOrientation(scanOrientation(ctx.cwd));
-        } catch {
-          orientationText = null;
-        }
-      }
-      const orientDigest = orientationText === null ? null : sha1Hex(orientationText);
+      const orientation = ensureOrientation(ctx);
+      const orientDigest = orientation === null ? null : sha1Hex(orientation);
       const orientDue = orientDigest !== null && state.counters.orient_sha1 !== orientDigest;
 
       if (!briefDue && !orientDue) return undefined;
 
       const parts: string[] = [];
-      if (orientDue && orientationText !== null) parts.push(orientationText);
+      if (orientDue && orientation !== null) parts.push(orientation);
       if (briefDue) parts.push(brief);
       if (parts.length === 0) return undefined;
 
       if (orientDue && orientDigest !== null) state.counters.orient_sha1 = orientDigest;
       if (briefDue) view.brief_digest = digest;
+      // A persisted block now exists for this conversation, so the mid-run
+      // re-assertion below has nothing left to repair.
+      pendingReinject = false;
       saveState(ctx.cwd, state);
       return { message: { customType: BRIEF_CUSTOM_TYPE, content: parts.join("\n\n"), display: false } };
     }),
   );
 
+  // Mid-run compaction (threshold / overflow recovery) resumes the run through
+  // AgentStart, where before_agent_start never fires — so without this hook the
+  // hidden brief would stay gone until the next user prompt (SPEC §1 #6). The
+  // hook re-asserts the block on every request until a PERSISTED one is back in
+  // the conversation; the restored message itself is per-request, so it must be
+  // re-applied rather than remembered.
+  pi.on("context", (event, ctx) =>
+    attempt(ctx, () => {
+      if (!pendingReinject) return undefined;
+      const messages = Array.isArray(event.messages) ? event.messages : [];
+      const persisted = messages.some(
+        (message) => (message as { customType?: unknown } | null)?.customType === BRIEF_CUSTOM_TYPE,
+      );
+      if (persisted) {
+        pendingReinject = false;
+        return undefined;
+      }
+      const block = composeGuardBlock(ctx);
+      if (block.trim() === "") return undefined;
+      return {
+        messages: [
+          ...messages,
+          {
+            role: "custom",
+            customType: BRIEF_CUSTOM_TYPE,
+            content: block,
+            display: false,
+            timestamp: Date.now(),
+          },
+        ],
+      };
+    }),
+  );
+
+  // Task capture (SPEC §1 #6): the owner's actual request is what a compaction
+  // summary paraphrases away most often. The first substantive prompt becomes
+  // the project task; `/guard-task` can replace or clear it (owner text wins).
+  pi.on("input", (event, ctx) =>
+    attempt(ctx, () => {
+      // Extension-injected messages are not owner input, and `!` runs a shell
+      // command rather than stating a task.
+      if (event.source === "extension") return undefined;
+      const text = typeof event.text === "string" ? event.text.trim() : "";
+      if (text === "" || text.startsWith("/") || text.startsWith("!")) return undefined;
+      const captured = truncLine(text, TASK_DISPLAY_MAX);
+      if (captured === "" || Array.from(captured).length < TASK_MIN_CAPTURE_CHARS) return undefined;
+      const existing = state.task;
+      if (existing?.source === "owner" || existing?.text === captured) return undefined;
+      state.task = { text: captured, source: "prompt", ts: new Date().toISOString() };
+      // The brief changed: let this same turn re-inject it.
+      view.brief_digest = null;
+      saveState(ctx.cwd, state);
+      return undefined;
+    }),
+  );
+
   pi.on("tool_call", async (event, ctx) =>
     attempt(ctx, async () => {
       if (event.toolName !== "bash") return undefined;
@@ -812,11 +925,13 @@ export default function (pi: ExtensionAPI) {
 
   // Compaction removes the previously injected hidden brief from active
   // context. Invalidate both digests so the next turn re-injects constraints,
-  // trusted journal entries and orientation even when their text is unchanged.
+  // trusted journal entries, the task and orientation even when their text is
+  // unchanged, and arm the per-request re-assertion for a mid-run compaction.
   pi.on("session_compact", async (_event, ctx) =>
     attempt(ctx, async () => {
       view.brief_digest = null;
       delete state.counters.orient_sha1;
+      pendingReinject = true;
       saveState(ctx.cwd, state);
       return undefined;
     }),
@@ -966,6 +1081,54 @@ export default function (pi: ExtensionAPI) {
       }),
   });
 
+  // Task anchor (SPEC §1 #6): explicit owner control over the `task:` line that
+  // the brief re-injects, so a compaction summary cannot redefine the ask.
+  pi.registerCommand("guard-task", {
+    description: "protect-context: show | set <text> | --clear the owner task anchor",
+    handler: (args, ctx) =>
+      attempt(ctx, () => {
+        const trimmed = (args ?? "").trim();
+        let capped = false;
+        if (trimmed === "") {
+          const current = state.task;
+          if (ctx.hasUI) {
+            ctx.ui.notify(
+              current
+                ? `task (${current.source}): ${current.text}\nNudge: use /guard-task <text> to replace it, or /guard-task --clear.`
+                : "task: (none captured yet)\nNudge: it is captured from the first substantive prompt; /guard-task <text> sets it explicitly.",
+              "info",
+            );
+          }
+          return undefined;
+        }
+        if (trimmed === "--clear") {
+          state.task = undefined;
+        } else {
+          const text = truncLine(trimmed, TASK_DISPLAY_MAX);
+          if (text === "") {
+            if (ctx.hasUI) ctx.ui.notify("usage: /guard-task <text> | --clear", "warning");
+            return undefined;
+          }
+          state.task = { text, source: "owner", ts: new Date().toISOString() };
+          // Store and display share one cap: the brief can always show what was
+          // stored, and the owner is told when the input was cut.
+          capped = Array.from(trimmed).length > TASK_DISPLAY_MAX;
+        }
+        // The brief text changed: force the next prompt to re-inject it.
+        view.brief_digest = null;
+        saveState(ctx.cwd, state);
+        if (ctx.hasUI) {
+          ctx.ui.notify(
+            trimmed === "--clear"
+              ? "task cleared\nNudge: the brief no longer anchors the original request."
+              : `task recorded${capped ? ` (capped at ${TASK_DISPLAY_MAX} chars)` : ""}\nNudge: the brief re-injects it on your next prompt and after compaction.`,
+            "info",
+          );
+        }
+        return undefined;
+      }),
+  });
+
   pi.registerCommand("guard-report", {
     description: "protect-context: full session summary",
     handler: async (_args, ctx) =>
@@ -1018,11 +1181,13 @@ export default function (pi: ExtensionAPI) {
     label: "Guard Note",
     description:
       "Append a decision/correction/risk/note to the persistent journal (.agent-guard/journal.jsonl). " +
-      "Model-written entries are tagged agent and persisted for owner review; they are not trusted brief input. " +
-      "Only trusted slash-command/CLI decisions and corrections are re-injected.",
+      "Model-written entries are tagged agent and persisted for owner review; they are not trusted brief input, " +
+      "though the brief shows the newest few under an explicitly unverified heading. " +
+      "Only trusted slash-command/CLI decisions and corrections are re-injected as authority; read any entry back with guard_journal.",
     promptSnippet: "Record a durable decision or correction in the journal",
     promptGuidelines: [
       "Use guard_note to record durable decisions; when corrected, log a tagged correction with type=correction.",
+      "After a compaction, use guard_journal to re-read earlier decisions and your own notes.",
     ],
     parameters: Type.Object({
       // Enum as a plain string schema: providers that reject anyOf/const still
@@ -1054,6 +1219,38 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
+  // Read path for the journal (SPEC §4 parity with the MCP tool of the same
+  // name). Without it, the agent's own notes would be write-only in pi: the
+  // brief excludes `agent` entries from trusted sections, and a compaction then
+  // leaves no route back to them (SPEC §1 #6).
+  pi.registerTool({
+    name: "guard_journal",
+    label: "Guard Journal",
+    description:
+      "Read recent journal entries (read-only): timestamp, type, text, tags. limit is clamped to 0-20; type filters " +
+      "decision|correction|risk|note. Entries tagged agent are model-written notes — unverified, never owner authority, " +
+      "but the durable record of earlier reasoning; read them to recover decisions and rejected approaches.",
+    promptSnippet: "Read recent journal entries",
+    promptGuidelines: [
+      "Use guard_journal to recover earlier decisions, corrections, and your own notes after a compaction.",
+    ],
+    parameters: Type.Object({
+      limit: Type.Optional(Type.Integer({ description: "How many entries to read (0-20, default 5)" })),
+      type: Type.Optional(
+        Type.Unsafe<JournalType>({
+          type: "string",
+          enum: ["decision", "correction", "risk", "note"],
+        }),
+      ),
+    }),
+    execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const journal = readJournal(ctx.cwd);
+      const type = params.type;
+      const limit = params.limit === undefined ? READ_LIMIT_DEFAULT : boundedReadLimit(params.limit);
+      const text = renderJournal(recentJournal(journal, limit, type), countJournal(journal, type), type);
+      return Promise.resolve({ content: [{ type: "text", text }], details: {} });
+    },
+  });
   pi.registerTool({
     name: "guard_contract_check",
     label: "Guard Contract Check",

package/extension/lib/brief.ts

@@ -13,11 +13,17 @@ export function sha1Hex(s: string): string {
 }
 
 export interface BriefInput {
+  /** Owner-stated task captured for this project (SPEC §1 #6): the request that
+   *  a compaction summary is most likely to have paraphrased away. */
+  task?: string | null;
   contract: Constraint[];
   /** Most recent trusted decisions, newest first (already sliced). */
   decisions?: Array<{ type: string; text: string; tags: string[] }>;
   /** Most recent corrections, newest first (already sliced). */
   corrections: Array<{ type: string; text: string; tags: string[] }>;
+  /** Most recent model-written entries, newest first. Shown as explicitly
+   *  unverified: they are the agent's own notes, never owner authority. */
+  agentNotes?: Array<{ type: string; text: string; tags: string[] }>;
   loops: LoopInfo[];
   lastEvidence: { id: string; exit: number; cmd: string; ms: number | null } | null;
 }
@@ -25,7 +31,12 @@ export interface BriefInput {
 export const BRIEF_MAX_CONTRACT_LINES = 12;
 export const BRIEF_MAX_DECISIONS = 3;
 export const BRIEF_MAX_CORRECTIONS = 3;
+export const BRIEF_MAX_AGENT_NOTES = 2;
 export const BRIEF_MAX_LOOPS = 2;
+/** Owner task display cap (chars). */
+export const TASK_DISPLAY_MAX = 200;
+/** Agent-note display cap (chars) — shorter than a trusted entry on purpose. */
+export const AGENT_NOTE_DISPLAY_MAX = 120;
 /** Command display cap (chars) — matches Python's cmd[:60] discipline. */
 export const CMD_DISPLAY_MAX = 60;
 
@@ -68,27 +79,44 @@ export function selectBriefConstraints(contract: Constraint[]): Constraint[] {
     .map(({ constraint }) => constraint);
 }
 
+interface SectionInfo {
+  hidden: number;
+  truncated: boolean;
+}
+
+/** Render one journal section within its cap and report what the cap dropped,
+ *  so the brief can point at the read path instead of silently truncating. */
 function appendJournalSection(
   lines: string[],
-  heading: "decisions:" | "corrections:",
+  heading: "decisions:" | "corrections:" | "agent notes (unverified):",
   entries: Array<{ text: string; tags: string[] }>,
   cap: number,
-): void {
-  if (entries.length === 0) return;
+  textMax = 200,
+): SectionInfo {
+  if (entries.length === 0) return { hidden: 0, truncated: false };
   lines.push(heading);
+  let truncated = false;
   for (const entry of entries.slice(0, cap)) {
+    const full = normalizeOneLine(entry.text, 10_000);
+    const shown = trunc(full, textMax);
+    if (shown !== full) truncated = true;
     const safeTags = [...new Set((Array.isArray(entry.tags) ? entry.tags : []).map((tag) => truncLine(tag, 40)).filter(Boolean))]
       .slice(0, 8);
     const tags = safeTags.length > 0 ? ` [${safeTags.join(",")}]` : "";
-    lines.push(`- ${truncLine(entry.text)}${tags}`);
+    lines.push(`- ${shown}${tags}`);
   }
+  return { hidden: Math.max(0, entries.length - cap), truncated };
 }
 
-/** Build the compact brief: contract (≤12 lines), ≤3 trusted decisions,
- *  ≤3 trusted corrections, ≤2 loops, and last evidence. */
+/** Build the compact brief: owner task, contract (≤12 lines), ≤3 trusted
+ *  decisions, ≤3 trusted corrections, ≤2 unverified agent notes, ≤2 loops, and
+ *  last evidence. Anything a cap dropped is announced with the read path. */
 export function buildBrief(input: BriefInput): string {
   const lines: string[] = [];
 
+  const task = truncLine(input.task ?? "", TASK_DISPLAY_MAX);
+  if (task !== "") lines.push(`task: ${task}`);
+
   const contractLines = selectBriefConstraints(input.contract);
   if (contractLines.length > 0) {
     lines.push("contract:");
@@ -107,9 +135,19 @@ export function buildBrief(input: BriefInput): string {
     }
   }
 
-  appendJournalSection(lines, "decisions:", input.decisions ?? [], BRIEF_MAX_DECISIONS);
-  appendJournalSection(lines, "corrections:", input.corrections, BRIEF_MAX_CORRECTIONS);
-
+  const sections = [
+    appendJournalSection(lines, "decisions:", input.decisions ?? [], BRIEF_MAX_DECISIONS),
+    appendJournalSection(lines, "corrections:", input.corrections, BRIEF_MAX_CORRECTIONS),
+    appendJournalSection(
+      lines,
+      "agent notes (unverified):",
+      input.agentNotes ?? [],
+      BRIEF_MAX_AGENT_NOTES,
+      AGENT_NOTE_DISPLAY_MAX,
+    ),
+  ];
+  const hiddenEntries = sections.reduce((sum, info) => sum + info.hidden, 0);
+  const truncatedEntries = sections.some((info) => info.truncated);
   if (input.loops.length > 0) {
     lines.push("loops:");
     for (const l of input.loops.slice(0, BRIEF_MAX_LOOPS)) {
@@ -124,5 +162,14 @@ export function buildBrief(input: BriefInput): string {
     );
   }
 
+  // The caps above keep the brief constant-cost; these two lines keep the loss
+  // recoverable instead of silent (goal #6/#12).
+  if (hiddenEntries > 0) {
+    lines.push(`+${hiddenEntries} more journal entries — guard_journal reads them`);
+  }
+  if (truncatedEntries) {
+    lines.push("journal text truncated — guard_journal shows the full entry");
+  }
+
   return lines.join("\n");
 }

package/extension/lib/journal.ts

@@ -23,6 +23,9 @@ export function isJournalType(v: unknown): v is JournalType {
 export const TEXT_CAP = 500;
 export const TAG_COUNT_CAP = 8;
 export const TAG_TEXT_CAP = 40;
+/** Read-view bounds (mirror journal.READ_LIMIT_* in Python). */
+export const READ_LIMIT_DEFAULT = 5;
+export const READ_LIMIT_MAX = 20;
 
 /** Replace terminal/control formatting, collapse whitespace and bound output. */
 export function sanitizeJournalText(value: unknown, cap = TEXT_CAP): string {
@@ -89,6 +92,65 @@ export function recentTrustedEntries(
     .reverse();
 }
 
+/** Entries the model wrote itself (reserved `agent` provenance tag).
+ *
+ * They are never trusted input, but they are the agent's own durable notes:
+ * after a compaction the brief surfaces the newest few as explicitly
+ * unverified, and `guard_journal` returns the full text on demand (SPEC §1 #6).
+ * `risk` entries are excluded — they are telemetry, not memory. */
+export function recentAgentEntries(journal: JournalEntry[], n: number): JournalEntry[] {
+  // slice(-0) === slice(0) would return the WHOLE journal for n=0.
+  if (!(n > 0)) return [];
+  return journal
+    .filter((entry) => entry.type !== "risk" && sanitizeTags(entry.tags).includes("agent"))
+    .slice(-n)
+    .reverse();
+}
+/** All trusted (non-`agent`) entries of one type, newest first. Used by the
+ *  brief so its hidden-entry count reflects the whole journal, not a window. */
+export function trustedEntries(
+  journal: JournalEntry[],
+  type: "decision" | "correction",
+): JournalEntry[] {
+  return recentTrustedEntries(journal, type, journal.length);
+}
+
+/** Bounded read limit (mirrors journal._bounded_limit: never negative, never
+ *  unbounded). A model-supplied 0 yields no lines rather than a huge view. */
+export function boundedReadLimit(limit: unknown): number {
+  const value = typeof limit === "number" && Number.isFinite(limit) ? Math.trunc(limit) : READ_LIMIT_DEFAULT;
+  return Math.max(0, Math.min(value, READ_LIMIT_MAX));
+}
+
+/** Entries of one type (or all), oldest first — the read view's window. */
+export function recentJournal(journal: JournalEntry[], limit: number, type?: JournalType): JournalEntry[] {
+  const bounded = boundedReadLimit(limit);
+  if (bounded === 0) return [];
+  const filtered = type === undefined ? journal : journal.filter((entry) => entry.type === type);
+  return filtered.slice(-bounded);
+}
+
+export function countJournal(journal: JournalEntry[], type?: JournalType): number {
+  return type === undefined ? journal.length : journal.filter((entry) => entry.type === type).length;
+}
+
+/** Render a bounded one-line-per-entry journal view (same shape as
+ *  journal.render_recent on the Python side, so both surfaces read alike). */
+export function renderJournal(entries: JournalEntry[], total: number, type?: JournalType): string {
+  const window = entries.slice(-READ_LIMIT_MAX);
+  const scope = type === undefined ? "" : ` ${type}`;
+  const lines = [`PC journal${scope} · last ${window.length} of ${Math.max(0, Math.trunc(total))}`];
+  for (const entry of window) {
+    const ts = normalizeOneLine(entry.ts, 32) || "unknown-time";
+    const entryType = normalizeOneLine(entry.type, 16) || "unknown";
+    const text = sanitizeJournalText(entry.text) || "(blank legacy entry)";
+    const tags = sanitizeTags(entry.tags);
+    lines.push(`${ts} · ${entryType} · ${text}${tags.length > 0 ? ` [${tags.join(",")}]` : ""}`);
+  }
+  lines.push("Nudge: re-read durable decisions and corrections before resuming work.");
+  return lines.join("\n");
+}
+
 /** Most recent trusted corrections, newest first. */
 export function recentCorrections(journal: JournalEntry[], n: number): JournalEntry[] {
   return recentTrustedEntries(journal, "correction", n);

package/extension/lib/status.ts

@@ -30,6 +30,10 @@ export interface StatusData {
   diffWarnLines: number;
   diffHardLines: number;
   diffWarnFiles: number;
+  /** Journal size (optional: only populated where the view can read it). */
+  journalCount?: number;
+  /** Subset of journalCount tagged `agent` (model-written, never trusted). */
+  agentNoteCount?: number;
 }
 
 /** Two compact lines + Nudge. */
@@ -52,6 +56,10 @@ export function buildStatus(d: StatusData): string {
       `diff scan: lower bound (${d.diffSkippedFiles ?? 0} skipped, ${d.diffTruncatedFiles ?? 0} truncated)`,
     );
   }
+  if ((d.journalCount ?? 0) > 0) {
+    // Make the read path discoverable: journal entries are not all re-injected.
+    lines.push(`journal: ${d.journalCount} entries (${d.agentNoteCount ?? 0} agent) — guard_journal reads them`);
+  }
   if (d.lastVerify) {
     lines.push(`last verify: ${formatVerifyLine(d.lastVerify)}`);
   } else {

package/extension/lib/store.ts

@@ -508,6 +508,15 @@ export interface SessionState {
   updated?: string;
 }
 
+/** Owner-stated task for this project (SPEC §2). Captured from the first real
+ *  prompt of a session or set explicitly with `/guard-task`; re-injected at the
+ *  top of the brief so a compaction summary cannot silently redefine the ask. */
+export interface TaskCapture {
+  text: string;
+  source: "prompt" | "owner";
+  ts: string;
+}
+
 /** Baseline that belongs to ONE pi session. Concurrent sessions in one project
  *  keep separate entries so they cannot clobber each other (SPEC §2). */
 export interface GuardState {
@@ -516,6 +525,8 @@ export interface GuardState {
   /** Opaque passthrough on the Python side; the extension stores digests here
    *  (e.g. the orientation digest) alongside numeric counters. */
   counters: Record<string, number | string>;
+  /** Project-level task capture (absent = nothing captured yet). */
+  task?: TaskCapture;
 }
 
 /** How many per-session baselines to retain (newest first, current always). */
@@ -574,6 +585,19 @@ function readSession(raw: unknown): SessionState | null {
   };
 }
 
+/** Parse the optional task capture; malformed legacy values are dropped rather
+ *  than rendered into a brief. */
+function readTask(raw: unknown): TaskCapture | undefined {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return undefined;
+  const value = raw as Record<string, unknown>;
+  if (typeof value.text !== "string") return undefined;
+  return {
+    text: value.text,
+    source: value.source === "owner" ? "owner" : "prompt",
+    ts: typeof value.ts === "string" ? value.ts : "",
+  };
+}
+
 export function loadState(cwd: string): GuardState | null {
   const raw = readJson<unknown>(statePath(cwd));
   if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return null;
@@ -617,6 +641,7 @@ export function loadState(cwd: string): GuardState | null {
       counters[key] = candidate;
     }
   }
+  const task = readTask(value.task);
   return {
     current_session: {
       id: currentId,
@@ -625,6 +650,7 @@ export function loadState(cwd: string): GuardState | null {
     },
     sessions,
     counters,
+    ...(task === undefined ? {} : { task }),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "protect-context",
-  "version": "1.3.2",
+  "version": "2.0.0",
   "description": "Pi extension that adds agent guardrails: context brief, verification evidence, loop blocking, diff-scope warnings, and a durable journal.",
   "type": "module",
   "license": "MIT",