@fyso/awareness-framework 0.1.0 → 0.2.0

package/docs/hooks-and-scheduling.md

@@ -31,13 +31,19 @@ These files are private operational state. Do not commit them.
 
 | Lifecycle point | Command | Purpose |
 |-----------------|---------|---------|
-| Session start or resume | `awareness hook run --tool TOOL --event session-start` | Ensure private files exist and record that the agent refreshed awareness. |
+| Session start or resume | `awareness hook run --tool TOOL --event session-start` | Ensure private files exist, record that the agent refreshed awareness, and print the Current Focus so the host injects it as context. |
 | Stop or session end | `awareness hook run --tool TOOL --event stop` | Record that the agent reached an idle or handoff boundary. |
 | Pre-compaction | `awareness hook run --tool TOOL --event pre-compact` | Record a compaction boundary before context is summarized. |
-| Post-compaction | `awareness hook run --tool TOOL --event post-compact` | Record that the new compacted context may need `awareness refresh`. |
+| Post-compaction | `awareness hook run --tool TOOL --event post-compact` | Record that the new compacted context may need `awareness refresh`, and re-print the Current Focus so it survives compaction. |
 
 Hooks should not append daily worklog entries on every lifecycle event. The worklog is for human-relevant progress with task IDs and evidence.
 
+## Context Injection
+
+`session-start` and `post-compact` are **context-injection events**: hosts such as Claude Code append the hook's stdout to the agent's context. For these events `awareness hook run` always prints the `Current Focus` block (framed as a load-this-first instruction), so the agent actively loads its focus instead of relying on a passive, possibly stale file import.
+
+`--quiet` only suppresses the diagnostic lines (`Hook recorded`, `Runtime log`, `Warnings`). It does **not** suppress the focus payload — the installed hooks pass `--quiet` precisely so the only thing reaching the agent's context is the focus itself. Non-injection events (`stop`, `session-end`, `pre-compact`) never print the focus.
+
 ## Scheduled Cadence
 
 | Cadence | Command | Purpose |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyso/awareness-framework",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Methodology and helper CLI for agent awareness, initialization, daily worklogs, handoffs, and evaluation loops.",
   "type": "module",
   "author": "Fyso",

package/src/cli.js

@@ -434,6 +434,11 @@ function hookCommand(ctx, subcommand, opts) {
   }
 }
 
+// Events whose stdout the host agent injects into its context. For these we
+// always emit the Current Focus so the agent actually loads the protocol state,
+// even under --quiet (which only suppresses diagnostic noise, not the payload).
+const CONTEXT_INJECTION_EVENTS = new Set(['session-start', 'post-compact']);
+
 function hookRunCommand(ctx, opts) {
   const home = agentsHome(ctx, opts);
   const today = todayParts(ctx);
@@ -455,9 +460,27 @@ function hookRunCommand(ctx, opts) {
     out(ctx, warnings.length ? `Warnings: ${warnings.length}` : 'Warnings: none');
   }
 
+  if (CONTEXT_INJECTION_EVENTS.has(event)) {
+    emitFocusContext(ctx, home);
+  }
+
   return 0;
 }
 
+// Print the Current Focus as injectable context for the host agent. Framed as
+// an instruction so the agent treats it as actionable, not background noise.
+function emitFocusContext(ctx, home) {
+  const currentPath = awarenessPath(home);
+  if (!fs.existsSync(currentPath)) return;
+  const focus = extractSection(fs.readFileSync(currentPath, 'utf8'), 'Current Focus').trim();
+  if (!focus) return;
+  out(ctx, '[awareness] Load this before doing work — current focus:');
+  out(ctx, '');
+  out(ctx, focus);
+  out(ctx, '');
+  out(ctx, 'Follow the awareness protocol; run `awareness handoff` before yielding control.');
+}
+
 function hookInstallCommand(ctx, opts) {
   const tool = opts.tool || 'all';
   const userHome = userHomePath(ctx, opts);