tokens-for-good 0.4.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokens-for-good",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "type": "module",
   "description": "Donate your spare AI tokens to research nonprofits for Fierce Philanthropy",
   "bin": {

package/src/session-start-hook.js

@@ -3,9 +3,14 @@
 // ~/.claude/settings.json on every Claude Code session start.
 //
 // Reads state.json and, if the user's init choice hasn't been acted on yet,
-// emits instructions to stdout so Claude sees them as part of the session
-// context and acts on the pre-made choice immediately. Exits silently in
+// emits a JSON payload on stdout in Claude Code's SessionStart-hook format
+// so the message is injected into the session's context. Exits silently in
 // the normal steady state so users aren't nudged forever.
+//
+// Docs: https://code.claude.com/docs/en/hooks.md (SessionStart section).
+// Required output shape for SessionStart hooks:
+//   { "hookSpecificOutput": { "hookEventName": "SessionStart", "additionalContext": "<text>" } }
+// Plain stdout is ignored by Claude Code, which is why this needs JSON.
 import { loadState, isSnoozed } from './state.js';
 
 export function runSessionStartHook() {
@@ -16,7 +21,7 @@ export function runSessionStartHook() {
 
   // First session after init — emit the handoff instruction exactly once.
   if (!state.first_setup_complete) {
-    emitFirstSessionInstruction(state);
+    emit(firstSessionMessage(state));
     return;
   }
 
@@ -27,37 +32,45 @@ export function runSessionStartHook() {
     const last = state.last_contributed ? new Date(state.last_contributed) : null;
     const daysSince = last ? Math.floor((Date.now() - last.getTime()) / 86_400_000) : Infinity;
     if (daysSince >= 7) {
-      process.stdout.write(
+      emit(
         "Tokens for Good: It's been a while — say 'run /tfg' to research one org now, " +
-        "or 'run /tfg-schedule daily' to automate it from here on.\n"
+        "or 'run /tfg-schedule daily' to automate it from here on."
       );
     }
   }
 }
 
-function emitFirstSessionInstruction(state) {
+function emit(additionalContext) {
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SessionStart',
+      additionalContext,
+    },
+  }));
+}
+
+function firstSessionMessage(state) {
   const installedOn = state.installed_at
     ? new Date(state.installed_at).toISOString().slice(0, 10)
     : 'recently';
 
   if (state.intended_flow === 'scheduled') {
     const freq = state.intended_frequency || 'daily';
-    process.stdout.write(
+    return (
       `Tokens for Good: The user ran \`npx tokens-for-good init\` on ${installedOn} ` +
       `and chose scheduled research at ${freq} cadence. This is their first Claude Code ` +
       `session since. Before any other task, invoke the /tfg-schedule skill with ` +
       `frequency=${freq}. After /schedule confirms, the skill will call ` +
-      `mark_setup_complete on the TFG MCP to dismiss this prompt.\n`
+      `mark_setup_complete on the TFG MCP to dismiss this prompt.`
     );
-    return;
   }
 
   // one_off flow
-  process.stdout.write(
+  return (
     `Tokens for Good: The user ran \`npx tokens-for-good init\` on ${installedOn} ` +
     `and chose to do research manually (one-off, not scheduled). This is their first ` +
     `Claude Code session since. Offer to start a research task now by invoking the ` +
     `/tfg skill. After they submit their first report, the skill will call ` +
-    `mark_setup_complete on the TFG MCP to dismiss this prompt.\n`
+    `mark_setup_complete on the TFG MCP to dismiss this prompt.`
   );
 }