/foundry:learn-capture

The third learnings PRODUCER (feat-foundry-session-learnings-capture) — for the plain operator-driven direct/lean session that returns no value, spawns no worker, and leaves no worktree. Siblings: the worker structured-return + worktree-sidecar producers (foundry-harvest-learnings.sh). Consumer: /foundry:learn-distill (unchanged; the schema authority).

How it works (opt-in: FOUNDRY_SESSION_LEARNINGS=on)

• Off by default since v1.18 (operator decision 2026-09-25): the Stop-time block interrupted ordinary sessions, so it now fires only when FOUNDRY_SESSION_LEARNINGS is on or full (see the knob below). Unset, it exits 0 and never blocks; /foundry:learn-capture still works on demand.
• When enabled, a Stop hook (hooks/foundry-session-learnings.sh stop, wired in hooks.json) fires when the session goes idle and — once per session, re-entrancy-guarded by stop_hook_active + a per-session marker, interactive sessions only, and only for a substantive session (see the substance gate below) — injects a single reflection turn.
• What you see, and why it says "error". The reflection arrives as a blocked Stop hook, and Claude Code captions every blocked Stop hook as an error — including this one, which is working exactly as designed. That caption is upstream's (anthropics/claude-code#12667, #34600, #62139) and Foundry cannot change it. What Foundry does control is the contents: the operator-facing reason is two short lines that say so plainly, while the model-facing runbook rides in hookSpecificOutput.additionalContext where it costs you no screen space (AC-RUX-1). Nothing is wrong when you see it.
• The model distills the session into learning records (JSONL) and emits them via the bare PATH command foundry-learn-capture (added to the Bash tool PATH while the plugin is enabled — no version in the path, no $CLAUDE_PLUGIN_ROOT), with an absolute-path fallback for the post-update window:

  if command -v foundry-learn-capture >/dev/null 2>&1; then \
    cat <records.jsonl> | foundry-learn-capture --final --session-id <id> --project-dir "$CLAUDE_PROJECT_DIR"; \
  else \
    cat <records.jsonl> | "${CLAUDE_PLUGIN_ROOT}"/hooks/foundry-session-learnings.sh capture --session-id <id>; \
  fi

  (records on stdin, never on argv). Zero records is fine for a low-value session.
• CLI-only write path (AC-LBC-3). Emit records ONLY through this capture CLI (which validates each line and partitions the write) — never write a file directly under .foundry/session-learnings/. A hand-written file the distiller cannot read (wrong shape, or in the buffer root instead of a YYYY-MM-DD/ partition) is silently lost (the doctor buffer-drift signal this line originally named was retired with the drop-in registry — check the partition by hand); it counts as any residual. A non-object/unparseable line piped to the CLI is rejected + counted (content-free), not written.
• The shared writer lands them content-addressed + idempotent in .foundry/session-learnings/<date>/<sid>__session__<hash>.jsonl (channel session), through a mechanical secret-scrub (best-effort defense-in-depth — see AC-SLEARN-7), fail-open, with a reconciliation row in .harvest-log.jsonl (the per-channel doctor surfacing this line originally named was retired with the drop-in registry).

Cadence + the opt-in switch (FOUNDRY_SESSION_LEARNINGS)

The substance gate (AC-RUX-2). A session that provably did nothing worth reflecting on never reflects. The hook reads the harness-supplied transcript and treats the session as substantive if any of: a mutation tool call (Edit / Write / MultiEdit / NotebookEdit); a delegation (Agent / Task / Workflow); or at least FOUNDRY_SESSION_LEARNINGS_MIN_TURNS genuine user turns (default 3). A one-shot read-only probe — /foundry:doctor and friends — is therefore silent. Bash is deliberately not a substantiveness signal (classifying it would mean parsing arbitrary shell); a real Bash session qualifies on turn count instead.

The gate is conservative in exactly one direction: an absent, unreadable, or unparseable transcript counts as substantive. It can only ever suppress on positive proof of insubstantiality — a read failure can never silently switch capture off.

The knob (AC-RUX-3). Claude Code has no per-hook disable — only disableAllHooks (which would also disable the git-discipline and cwd-enforce hooks) or uninstalling the plugin. So Foundry ships its own; reach for this, not disableAllHooks:

Set it per-session in your shell, or persistently via the env block in .claude/settings.json.

Public programmatic entrypoint — foundry-learn-capture

A consumer skill body (model-invoked Bash, NOT a hook) that wants to append one learning record the moment an insight is filed uses the PATH-installed public command foundry-learn-capture (bin/foundry-learn-capture, auto-added to the Bash tool PATH while the plugin is enabled). It reads records as JSONL on STDIN only (never argv) and self-resolves its shared library relative to its own location (no $CLAUDE_PLUGIN_ROOT, no version path).

Consumer-binding contract (REQUIRED). Because a skill-body Bash call does NOT reliably export CLAUDE_SESSION_ID / CLAUDE_PROJECT_DIR, a consumer skill body MUST pass --session-id and --project-dir (supplied via skill/command-file inline ${…} substitution, not the Bash env):

printf '%s\n' '{"lesson":"…","context":"…"}' \
  | foundry-learn-capture --session-id "<sid>" --project-dir "<workspace-root>"

• Default mode is append — it writes records and does not touch the once-per-session reflection marker (so a mid-session append can never suppress the session's own Stop reflection).
• --final is the explicit closer (the Stop reflection turn) — it writes records then CASes the marker requested→done (and refuses to manufacture a done from an absent marker).
• An unresolved --project-dir (and no $CLAUDE_PROJECT_DIR) fails closed (a content-free stderr loss signal, nothing written) rather than writing into the wrong repo; an unresolved --session-id fails closed in --final (records still written) and warns in append.
• --strict makes a reject/loss/fail-closed-root exit non-zero (default is fail-open exit 0).

Manual capture (escape hatch)

Run the capture CLI yourself to record a learning on demand (same partition/format):

printf '%s\n' '{"lesson":"…","context":"…"}' \
  | "${CLAUDE_PLUGIN_ROOT}"/hooks/foundry-session-learnings.sh capture --session-id "$CLAUDE_SESSION_ID"

Notes / anti-patterns

• Do not put secrets in records. The producer scrub is best-effort; the authoritative control is operator review at the public boundary (/foundry:upstream-submit). Distill lessons, not raw spans.
• Not per-turn, but re-armed per manual /compact. Reflection fires at the first qualifying idle and is then re-armed at each MANUAL compaction boundary by the PreCompact hook (foundry-session-learnings.sh precompact), which resets the per-session marker to rearmed so the next idle re-injects — once per compaction SEGMENT rather than once per whole session (the operator's real episode boundary). Auto-compaction does NOT re-arm (no system-triggered amplification). See its authorizing spec.
• A session that dies before its first idle (or before its next idle after a /compact) loses that segment's learnings — the accepted bounded residual of the inline-only design (the post-hoc fallback was dropped after the deep spec audit; matches inline-only systems), now strictly smaller thanks to the per-compaction re-arm.
• Self-test the producer: hooks/foundry-session-learnings.sh --selftest.