Ship shared plugin hooks (merge after release N)

.codex-plugin/plugin.json

@@ -14,7 +14,7 @@
   "interface": {
     "displayName": "Basecamp",
     "shortDescription": "Work with Basecamp from Codex.",
-    "longDescription": "Find assignments, create and update Basecamp work, and diagnose the integration. Requires the Basecamp CLI (basecamp) installed and on your PATH.",
+    "longDescription": "Find assignments, create and update Basecamp work, diagnose the integration, and connect Git commits to Basecamp todos. Requires the Basecamp CLI (basecamp) installed and on your PATH.",
     "developerName": "37signals",
     "category": "Productivity",
     "capabilities": [

AGENTS.md

@@ -35,6 +35,7 @@ basecamp-cli/
 │   └── version/      # Version info
 ├── e2e/              # BATS integration tests
 ├── skills/           # Agent skills
+├── hooks/            # Agent lifecycle hooks (both agents)
 ├── .claude-plugin/   # Claude Code integration
 └── .codex-plugin/    # Codex plugin manifest
 ```

README.md

@@ -150,9 +150,9 @@ Both `BASECAMP_OAUTH_CLIENT_ID` and `BASECAMP_OAUTH_CLIENT_SECRET` must be set t
 
 Both plugins require the `basecamp` CLI installed and on your PATH.
 
-**Claude Code:** `basecamp setup claude` — installs the plugin with skills and agent workflow support.
+**Claude Code:** `basecamp setup claude` — installs the plugin with skills, hooks, and agent workflow support.
 
-**Codex:** `basecamp setup codex` — registers the 37signals marketplace and installs the native plugin with Basecamp skills and diagnostics. Start a new Codex thread afterward to load the skills.
+**Codex:** `basecamp setup codex` — registers the 37signals marketplace and installs the native plugin with Basecamp skills, diagnostics, and opt-in hooks. In Codex, review and trust the plugin hooks with `/hooks`, then start a new thread to load the skills and hooks.
 
 Manual Codex installation uses the same marketplace:
 

hooks/hooks.json

@@ -0,0 +1,54 @@
+{
+  "description": "Basecamp agent hooks: session context and commit-reference nudges.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "basecamp agent-hook session-start",
+            "timeout": 5,
+            "statusMessage": "Checking Basecamp status"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "basecamp agent-hook pre-commit-snapshot",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "basecamp agent-hook post-commit",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "basecamp agent-hook post-commit",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

install.md

@@ -120,15 +120,15 @@ Both agent plugins require the `basecamp` CLI installed above — the plugin inv
 basecamp setup claude
 ```
 
-This registers the marketplace and installs the plugin with skills and agent workflow support.
+This registers the marketplace and installs the plugin with skills, hooks, and agent workflow support.
 
 ### Codex
 
 ```bash
 basecamp setup codex
 ```
 
-This installs the shared Basecamp skill, registers the 37signals Codex marketplace, and installs the native plugin. Start a new Codex thread after setup to load the skills.
+This installs the shared Basecamp skill, registers the 37signals Codex marketplace, and installs the native plugin. After setup, review and trust the plugin hooks with `/hooks` (Codex lists untrusted hooks but does not run them until trusted), then start a new Codex thread to load the skills and hooks.
 
 For a manual install:
 

internal/commands/wizard_codex.go

@@ -65,7 +65,10 @@ func runCodexSetup(cmd *cobra.Command, styles *tui.Styles) error {
 	fmt.Fprintln(w, styles.RenderStatus(true, "37signals marketplace ready"))
 	fmt.Fprintln(w, styles.RenderStatus(true, "Codex plugin installed and enabled"))
 	fmt.Fprintln(w)
-	fmt.Fprintln(w, styles.Muted.Render("  Start a new Codex thread to load the Basecamp skills."))
+	// Trust must come first: an untrusted SessionStart hook is silently
+	// skipped, so a thread started before trusting gets no hook context.
+	fmt.Fprintln(w, styles.Muted.Render("  Review and trust the plugin hooks with /hooks."))
+	fmt.Fprintln(w, styles.Muted.Render("  Then start a new Codex thread to load the Basecamp skills."))
 	return nil
 }
 

internal/commands/wizard_codex_test.go

@@ -156,9 +156,14 @@ func TestRunCodexSetupInteractiveExplainsNextSteps(t *testing.T) {
 
 	assert.Contains(t, output.String(), "Registering 37signals marketplace")
 	assert.Contains(t, output.String(), "Installing basecamp plugin")
-	assert.Contains(t, output.String(), "Start a new Codex thread")
-	// No hooks ship yet — setup must not point users at /hooks trust.
-	assert.NotContains(t, output.String(), "/hooks")
+	// Codex lists untrusted hooks but does not run them until trusted, and
+	// an untrusted SessionStart is skipped — so the trust step must come
+	// before the new-thread step.
+	trustAt := strings.Index(output.String(), "trust the plugin hooks with /hooks")
+	newThreadAt := strings.Index(output.String(), "start a new Codex thread")
+	require.GreaterOrEqual(t, trustAt, 0)
+	require.GreaterOrEqual(t, newThreadAt, 0)
+	assert.Less(t, trustAt, newThreadAt, "trust guidance must precede the new-thread step")
 }
 
 func TestRunCodexSetupInteractiveFailureWarnsAndContinues(t *testing.T) {