feat: reconcile hook files per entry with host-local enablement state

cmd/loaf/installed_distribution_test.go

@@ -163,9 +163,52 @@ func writeInstalledDistributionFixture(t *testing.T, repo string, version string
 	writeFixtureFile(t, filepath.Join(root, "config", "hooks.yaml"), "hooks:\n  pre-tool:\n    - id: check-secrets\n")
 	writeFixtureFile(t, filepath.Join(root, "dist", "cursor", "skills", "foundations", "SKILL.md"), "# Current Foundations\n")
 	writeFixtureFile(t, filepath.Join(root, "dist", "cursor", "hooks.json"), `{"version":1,"hooks":{"PostToolUse":[{"command":"loaf journal log --from-hook","matcher":"Bash","loaf-managed":true}]}}`)
+	writeFixtureHookDistribution(t, filepath.Join(root, "dist", "cursor"), version)
 	return root
 }
 
+// writeFixtureHookDistribution adds the two files a current build emits beside
+// a Cursor distribution: the adapter manifest the installer reads, and the hook
+// catalog reconciliation resolves entry identity through. A distribution
+// carrying neither is stale, and upgrade refuses it rather than falling back to
+// the whole-file merge it replaced.
+func writeFixtureHookDistribution(t *testing.T, dist string, version string) {
+	t.Helper()
+	writeFixtureFile(t, filepath.Join(dist, ".loaf-target-manifest.json"), `{
+  "version": 1,
+  "target": "cursor",
+  "package_version": "`+version+`",
+  "capability_contract_version": 3,
+  "adapters": ["cursor-test-adapter-v1"],
+  "artifacts": [
+    {
+      "id": "managed-instructions",
+      "kind": "instruction",
+      "destination": "project-instructions",
+      "sha256": "`+strings.Repeat("0", 64)+`"
+    }
+  ]
+}
+`)
+	writeFixtureFile(t, filepath.Join(dist, ".loaf-hook-catalog.json"), `{
+  "version": 1,
+  "target": "cursor",
+  "package_version": "`+version+`",
+  "entries": [
+    {
+      "event": "beforeShellExecution",
+      "hook_id": "validate-commit",
+      "type": "command",
+      "template": {"command": "loaf check --hook validate-commit", "matcher": "Bash", "loaf-managed": true},
+      "signatures": [["loaf", "check", "--hook", "validate-commit"]],
+      "stems": [["--hook", "validate-commit"]]
+    }
+  ],
+  "cohorts": []
+}
+`)
+}
+
 // writeStaleCheckoutFixture lays out an older Loaf source checkout: package
 // metadata, a .git marker, the Go module that makes it a checkout rather than
 // an unpacked distribution, content, and stale built dist/ output.

config/target-capabilities.json

@@ -4,7 +4,7 @@
     {
       "target": "claude-code",
       "surface": "cli",
-      "version": "2.1.223",
+      "version": "2.1.226",
       "platform": "darwin-arm64",
       "installed_mode": "plugin-dir",
       "context": {
@@ -20,9 +20,9 @@
             "status": "supported",
             "model_visible": true,
             "evidence": {
-              "source": "docs/changes/20260807-self-carried-release-guardrail/research/claude-code-2.1.223-plugin-startup-smoke.json",
+              "source": "docs/changes/20260808-hooks-entry-reconciliation/research/claude-code-2.1.226-plugin-startup-smoke.json",
               "level": "installed-smoke",
-              "summary": "Claude Code 2.1.223 startup smoke returned SessionStart additionalContext and the isolated marker was model-visible exactly."
+              "summary": "Claude Code 2.1.226 startup smoke returned SessionStart additionalContext and the isolated marker was model-visible exactly."
             }
           },
           {
@@ -243,7 +243,7 @@
     {
       "target": "codex",
       "surface": "cli",
-      "version": "0.146.0",
+      "version": "0.147.0",
       "platform": "darwin-arm64",
       "installed_mode": "isolated-codex-home",
       "context": {
@@ -259,9 +259,9 @@
             "status": "supported",
             "model_visible": true,
             "evidence": {
-              "source": "docs/changes/20260807-self-carried-release-guardrail/research/codex-0.146.0-isolated-startup-smoke.json",
+              "source": "docs/changes/20260808-hooks-entry-reconciliation/research/codex-0.147.0-isolated-startup-smoke.json",
               "level": "installed-smoke",
-              "summary": "Codex 0.146.0 isolated CODEX_HOME startup smoke observed exact native SessionStart hookSpecificOutput and the random marker was returned by the model."
+              "summary": "Codex 0.147.0 isolated CODEX_HOME startup smoke observed exact native SessionStart hookSpecificOutput and the random marker was returned by the model."
             }
           },
           {
@@ -340,7 +340,7 @@
             "status": "supported",
             "model_visible": true,
             "evidence": {
-              "source": "docs/changes/20260807-self-carried-release-guardrail/research/opencode-1.18.13-isolated-request-smoke.json",
+              "source": "docs/changes/20260808-hooks-entry-reconciliation/research/opencode-1.18.13-isolated-request-smoke.json",
               "level": "installed-smoke",
               "summary": "OpenCode 1.18.13 isolated-XDG request smoke returned the exact random continuity marker through the model-visible plugin system transformation."
             }

content/skills/loaf-reference/SKILL.md

@@ -56,6 +56,7 @@ Names and one-line purposes only. Run `loaf <command> --help` for options, argum
 | `loaf install` | Onboard Loaf into a folder or a not-yet-installed AI tool configuration | — |
 | `loaf upgrade` | Refresh Loaf in place: harness content sync plus deprecation cleanup anywhere, and project-surface refresh only inside a detected Loaf repo | — |
 | `loaf config` | Validate and refresh project Loaf config | check |
+| `loaf hooks` | Inspect and set which Loaf hooks project into an installed harness's hooks file | list, enable, disable |
 | `loaf init` | Initialize a project with Loaf structure | — |
 | `loaf release` | Create a new release with changelog, version bump, and tag | — |
 | `loaf search` | Search SQLite artifact bodies, journal entries, and indexed docs | — |

dist/amp/skills/loaf-reference/SKILL.md

@@ -62,6 +62,7 @@ Names and one-line purposes only. Run `loaf <command> --help` for options, argum
 | `loaf install` | Onboard Loaf into a folder or a not-yet-installed AI tool configuration | — |
 | `loaf upgrade` | Refresh Loaf in place: harness content sync plus deprecation cleanup anywhere, and project-surface refresh only inside a detected Loaf repo | — |
 | `loaf config` | Validate and refresh project Loaf config | check |
+| `loaf hooks` | Inspect and set which Loaf hooks project into an installed harness's hooks file | list, enable, disable |
 | `loaf init` | Initialize a project with Loaf structure | — |
 | `loaf release` | Create a new release with changelog, version bump, and tag | — |
 | `loaf search` | Search SQLite artifact bodies, journal entries, and indexed docs | — |

dist/codex/.loaf-hook-catalog.json

@@ -0,0 +1,93 @@
+{
+  "version": 1,
+  "target": "codex",
+  "package_version": "0.2.20",
+  "entries": [
+    {
+      "event": "SessionStart",
+      "hook_id": "session-start-loaf",
+      "type": "command",
+      "template": {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "{{LOAF_EXECUTABLE}} journal context --from-hook --codex-hook",
+            "commandWindows": "{{LOAF_EXECUTABLE}} journal context --from-hook --codex-hook"
+          }
+        ]
+      },
+      "signatures": [
+        [
+          "{{LOAF_EXECUTABLE}}",
+          "journal",
+          "context",
+          "--from-hook",
+          "--codex-hook"
+        ],
+        [
+          "loaf",
+          "journal",
+          "context"
+        ],
+        [
+          "loaf",
+          "journal",
+          "context",
+          "--from-hook"
+        ]
+      ],
+      "stems": [
+        [
+          "journal",
+          "context",
+          "--from-hook"
+        ]
+      ]
+    }
+  ],
+  "cohorts": [
+    {
+      "version": "2.0.0-alpha.14",
+      "hook_ids": [
+        "session-start-loaf"
+      ]
+    },
+    {
+      "version": "2.0.0-alpha.15",
+      "hook_ids": [
+        "session-start-loaf"
+      ]
+    },
+    {
+      "version": "2.0.0-alpha.16",
+      "hook_ids": [
+        "session-start-loaf"
+      ]
+    },
+    {
+      "version": "2.0.0-alpha.17",
+      "hook_ids": [
+        "session-start-loaf"
+      ]
+    },
+    {
+      "version": "2.0.0-alpha.18",
+      "hook_ids": [
+        "session-start-loaf"
+      ]
+    },
+    {
+      "version": "2.0.0-alpha.19",
+      "hook_ids": [
+        "session-start-loaf"
+      ]
+    },
+    {
+      "version": "0.2.20",
+      "hook_ids": [
+        "session-start-loaf"
+      ]
+    }
+  ]
+}

dist/codex/.loaf-target-manifest.json

@@ -7,13 +7,6 @@
     "codex-session-start-v1"
   ],
   "artifacts": [
-    {
-      "id": "hook-projection:.codex/hooks.json",
-      "kind": "hook-projection",
-      "source_path": ".codex/hooks.json",
-      "destination": "hooks.json",
-      "sha256": "443f549b2d4ee0a7ab796f95f5a9a60c92613a63e9409d8bb2962564d066db02"
-    },
     {
       "id": "managed-instructions",
       "kind": "instruction",

dist/codex/skills/loaf-reference/SKILL.md

@@ -62,6 +62,7 @@ Names and one-line purposes only. Run `loaf <command> --help` for options, argum
 | `loaf install` | Onboard Loaf into a folder or a not-yet-installed AI tool configuration | — |
 | `loaf upgrade` | Refresh Loaf in place: harness content sync plus deprecation cleanup anywhere, and project-surface refresh only inside a detected Loaf repo | — |
 | `loaf config` | Validate and refresh project Loaf config | check |
+| `loaf hooks` | Inspect and set which Loaf hooks project into an installed harness's hooks file | list, enable, disable |
 | `loaf init` | Initialize a project with Loaf structure | — |
 | `loaf release` | Create a new release with changelog, version bump, and tag | — |
 | `loaf search` | Search SQLite artifact bodies, journal entries, and indexed docs | — |