feat(trace): capture specs during the whole session (#3524)

Author: migmartri

.opencode/plugins/chainloop-trace.ts

@@ -41,19 +41,27 @@ export const ChainloopTrace: Plugin = async ({ $, client }) => {
     }
   }
 
-  // startSession fires the session-start hook and returns what it wrote to
-  // stdout: the instruction for the model, if Chainloop has one.
-  async function startSession(sessionID: string): Promise<string> {
-    const json = JSON.stringify({ session_id: sessionID, hook_event_name: "session.created" })
+  // instructionFrom fires a hook that can answer with an instruction for the
+  // model, and returns what it wrote to stdout: that instruction, if
+  // Chainloop has one.
+  async function instructionFrom(event: string, sessionID: string, hookEventName: string): Promise<string> {
+    const json = JSON.stringify({ session_id: sessionID, hook_event_name: hookEventName })
     try {
-      const out = await $`echo ${json} | chainloop trace hook opencode session-start`.text()
+      const out = await $`echo ${json} | chainloop trace hook opencode ${event}`.text()
       return out.trim() ? (JSON.parse(out).instruction ?? "") : ""
     } catch (err) {
-      console.error(`chainloop-trace: session-start hook failed: ${err}`)
+      console.error(`chainloop-trace: ${event} hook failed: ${err}`)
       return ""
     }
   }
 
+  // childSessions holds the sessions of subagents, whose parent session
+  // already gets the instruction and the reminder.
+  const childSessions = new Set<string>()
+  // reminding holds the sessions that have a reminder being posted. The post
+  // is a message too, and must not ask for another reminder.
+  const reminding = new Set<string>()
+
   // postInstruction adds the instruction to the session as a context-only
   // message: noReply stores it without asking the model for an answer. The
   // caller waits for it, so a first turn sent right away still finds it.
@@ -73,22 +81,44 @@ export const ChainloopTrace: Plugin = async ({ $, client }) => {
       if (event.type === "session.created") {
         const info = event.properties?.info
         const sessionID = info?.id ?? ""
-        const instruction = await startSession(sessionID)
         // A child session belongs to a subagent, whose parent already has
         // the instruction.
+        if (info?.parentID) childSessions.add(sessionID)
+        const instruction = await instructionFrom("session-start", sessionID, "session.created")
         if (instruction && !info?.parentID) await postInstruction(sessionID, instruction)
       }
       if (event.type === "session.deleted") {
         const sessionID = event.properties?.info?.id ?? ""
+        childSessions.delete(sessionID)
         await fire("session-end", { session_id: sessionID, hook_event_name: "session.deleted" })
       }
     },
+    // At each user message, the user-prompt-submit hook can answer with a
+    // short reminder to capture a new or changed spec. A message made only of
+    // synthetic parts is one that the plugin posted itself.
+    "chat.message": async (input, output) => {
+      const sessionID = input.sessionID
+      if (childSessions.has(sessionID) || reminding.has(sessionID)) return
+      const parts: any[] = output?.parts ?? []
+      if (parts.length > 0 && parts.every((p) => p?.synthetic)) return
+      const reminder = await instructionFrom("user-prompt-submit", sessionID, "chat.message")
+      if (!reminder) return
+      reminding.add(sessionID)
+      try {
+        await postInstruction(sessionID, reminder)
+      } finally {
+        reminding.delete(sessionID)
+      }
+    },
     "tool.execute.before": async (input, output) => {
       if (commandTools.includes(input.tool)) {
+        // callID pairs this hook with the tool.execute.after of the same
+        // call, so overlapping commands keep their own snapshots.
         await fire("pre-tool-use", {
           session_id: input.sessionID,
           hook_event_name: "tool.execute.before",
           tool_name: input.tool,
+          tool_use_id: input.callID,
         })
         return
       }
@@ -108,6 +138,7 @@ export const ChainloopTrace: Plugin = async ({ $, client }) => {
           session_id: input.sessionID,
           hook_event_name: "tool.execute.after",
           tool_name: input.tool,
+          tool_use_id: input.callID,
         })
         return
       }

app/cli/cmd/trace_hook.go

@@ -130,6 +130,7 @@ func newTraceHookClaudeCmd() *cobra.Command {
 
 	cmd.AddCommand(
 		newTraceHookClaudeSessionStartCmd(),
+		newTraceHookClaudeUserPromptSubmitCmd(),
 		newTraceHookClaudeSessionEndCmd(),
 		newTraceHookClaudePreToolUseCmd(),
 		newTraceHookClaudePostToolUseCmd(),
@@ -153,6 +154,21 @@ func newTraceHookClaudeSessionStartCmd() *cobra.Command {
 	}
 }
 
+func newTraceHookClaudeUserPromptSubmitCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "user-prompt-submit",
+		Short: "Remind Claude Code to capture new or changed specs at each user prompt",
+		Annotations: map[string]string{
+			"skipActionOptsInit": "true",
+		},
+		RunE: func(_ *cobra.Command, _ []string) error {
+			cleanup := InitHookLogger()
+			defer cleanup()
+			return action.HandleAgentPromptSubmit(claude.New(), logger)
+		},
+	}
+}
+
 func newTraceHookClaudeSessionEndCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "session-end",
@@ -266,6 +282,7 @@ func newTraceHookOpenCodeCmd() *cobra.Command {
 
 	cmd.AddCommand(
 		newTraceHookOpenCodeSessionStartCmd(),
+		newTraceHookOpenCodeUserPromptSubmitCmd(),
 		newTraceHookOpenCodeSessionEndCmd(),
 		newTraceHookOpenCodePreToolUseCmd(),
 		newTraceHookOpenCodePostToolUseCmd(),
@@ -289,6 +306,21 @@ func newTraceHookOpenCodeSessionStartCmd() *cobra.Command {
 	}
 }
 
+func newTraceHookOpenCodeUserPromptSubmitCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "user-prompt-submit",
+		Short: "Remind opencode to capture new or changed specs at each user prompt",
+		Annotations: map[string]string{
+			"skipActionOptsInit": "true",
+		},
+		RunE: func(_ *cobra.Command, _ []string) error {
+			cleanup := InitHookLogger()
+			defer cleanup()
+			return action.HandleAgentPromptSubmit(opencode.New(), logger)
+		},
+	}
+}
+
 func newTraceHookOpenCodeSessionEndCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "session-end",

app/cli/internal/trace/claude/announce_test.go

@@ -159,6 +159,46 @@ func TestAnnounceSessionStart(t *testing.T) {
 	}
 }
 
+// TestAnnouncePromptSubmit pins the prompt-submit wire shape: Claude Code adds
+// additionalContext of a UserPromptSubmit response to the context of the turn.
+func TestAnnouncePromptSubmit(t *testing.T) {
+	const reminder = "Chainloop spec capture. Folder: /repo/.chainloop/specs/abc-123"
+
+	testCases := []struct {
+		name        string
+		reminder    string
+		wantEmitted bool
+	}{
+		{name: "a reminder reaches the model", reminder: reminder, wantEmitted: true},
+		{name: "nothing to say emits nothing", reminder: "", wantEmitted: false},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			out := captureStdout(t, func() {
+				require.NoError(t, New().AnnouncePromptSubmit(tc.reminder))
+			})
+
+			if !tc.wantEmitted {
+				assert.Empty(t, out)
+				return
+			}
+
+			var got map[string]any
+			require.NoError(t, json.Unmarshal([]byte(out), &got))
+
+			// The reminder is for the model only: a banner at every turn
+			// would distract the user.
+			assert.NotContains(t, got, "systemMessage")
+
+			hookOut, ok := got["hookSpecificOutput"].(map[string]any)
+			require.True(t, ok, "hookSpecificOutput must be present")
+			assert.Equal(t, "UserPromptSubmit", hookOut["hookEventName"], "the event must be the one that fired")
+			assert.Equal(t, tc.reminder, hookOut["additionalContext"])
+		})
+	}
+}
+
 // captureStdout runs fn with os.Stdout redirected to a pipe and returns
 // everything written to it. Reads to EOF rather than into a fixed buffer: a
 // truncated read would corrupt the payload these tests parse as JSON.

app/cli/internal/trace/claude/hooks.go

@@ -32,9 +32,10 @@ const (
 	settingsFile = ".claude/settings.json"
 
 	// Claude Code hook event names.
-	eventSessionStart = "SessionStart"
-	eventPreToolUse   = "PreToolUse"
-	eventPostToolUse  = "PostToolUse"
+	eventSessionStart     = "SessionStart"
+	eventUserPromptSubmit = "UserPromptSubmit"
+	eventPreToolUse       = "PreToolUse"
+	eventPostToolUse      = "PostToolUse"
 	// eventPostToolUseFailure fires instead of PostToolUse when a tool call
 	// fails. A failed shell command can still have changed files (e.g. a
 	// script that writes files and then runs a failing linter), so it runs
@@ -64,6 +65,7 @@ type hookEvent struct {
 
 var hookEvents = []hookEvent{
 	{eventSessionStart, "chainloop trace hook claude session-start", ""},
+	{eventUserPromptSubmit, "chainloop trace hook claude user-prompt-submit", ""},
 	{eventPreToolUse, "chainloop trace hook claude pre-tool-use", hookToolMatcher},
 	{eventPostToolUse, "chainloop trace hook claude post-tool-use", hookToolMatcher},
 	{eventPostToolUseFailure, "chainloop trace hook claude post-tool-use", hookToolMatcher},

app/cli/internal/trace/claude/hooks_test.go

@@ -44,6 +44,7 @@ func TestInstallHooks(t *testing.T) {
 
 		// Verify command contents
 		assertHookCommand(t, hooks, "SessionStart", "chainloop trace hook claude session-start")
+		assertHookCommand(t, hooks, "UserPromptSubmit", "chainloop trace hook claude user-prompt-submit")
 		assertHookCommand(t, hooks, "PreToolUse", "chainloop trace hook claude pre-tool-use")
 		assertHookCommand(t, hooks, "PostToolUse", "chainloop trace hook claude post-tool-use")
 		// A failed tool call fires PostToolUseFailure instead of PostToolUse,
@@ -131,6 +132,9 @@ func TestInstallHooks(t *testing.T) {
 		sessionStart := hooks["SessionStart"].([]any)
 		assert.Len(t, sessionStart, 1)
 
+		promptSubmit := hooks["UserPromptSubmit"].([]any)
+		assert.Len(t, promptSubmit, 1)
+
 		preToolUse := hooks["PreToolUse"].([]any)
 		assert.Len(t, preToolUse, 1)
 
@@ -211,6 +215,7 @@ func TestUninstallHooks(t *testing.T) {
 		hooks := settings["hooks"].(map[string]any)
 		assert.Contains(t, hooks, "PostToolUse")
 		assert.NotContains(t, hooks, "SessionStart")
+		assert.NotContains(t, hooks, "UserPromptSubmit")
 		assert.NotContains(t, hooks, "PreToolUse")
 		assert.NotContains(t, hooks, "PostToolUseFailure")
 	})
@@ -353,6 +358,7 @@ func TestInstallHooksForTraceRun(t *testing.T) {
 		hooks := settings["hooks"].(map[string]any)
 
 		assert.Contains(t, hooks, "SessionStart")
+		assert.Contains(t, hooks, "UserPromptSubmit")
 		assert.Contains(t, hooks, "PreToolUse")
 		assert.Contains(t, hooks, "PostToolUse")
 		assert.Contains(t, hooks, "PostToolUseFailure")

app/cli/internal/trace/claude/provider.go

@@ -249,6 +249,38 @@ func (p *Provider) AnnounceSessionStart(msg trace.SessionStartMessage) error {
 	return json.NewEncoder(os.Stdout).Encode(resp)
 }
 
+// SupportsPromptReminder is true for Claude Code: it adds the
+// additionalContext field of a UserPromptSubmit hook response to the context
+// of the turn.
+func (p *Provider) SupportsPromptReminder() bool {
+	return true
+}
+
+// AnnouncePromptSubmit emits a UserPromptSubmit hook response that carries
+// the reminder in additionalContext only. It has no systemMessage: a banner
+// at every turn would only distract the user.
+func (p *Provider) AnnouncePromptSubmit(reminder string) error {
+	if reminder == "" {
+		return nil
+	}
+
+	type hookSpecificOutput struct {
+		HookEventName     string `json:"hookEventName"`
+		AdditionalContext string `json:"additionalContext"`
+	}
+
+	resp := struct {
+		HookSpecificOutput hookSpecificOutput `json:"hookSpecificOutput"`
+	}{
+		HookSpecificOutput: hookSpecificOutput{
+			HookEventName:     eventUserPromptSubmit,
+			AdditionalContext: reminder,
+		},
+	}
+
+	return json.NewEncoder(os.Stdout).Encode(resp)
+}
+
 // AnnounceToUser emits a PostToolUse hook response on both of Claude Code's
 // delivery channels: systemMessage, which the client prints to the user
 // without involving the model, and additionalContext, which reaches the model

app/cli/internal/trace/cursor/announce_test.go

@@ -79,6 +79,16 @@ func TestAnnounceSessionStart(t *testing.T) {
 	}
 }
 
+// TestAnnouncePromptSubmit pins that Cursor gets no reminder: it documents no
+// channel that adds context at prompt submit (D-008 of Spec 003).
+func TestAnnouncePromptSubmit(t *testing.T) {
+	out := captureStdout(t, func() {
+		require.NoError(t, New().AnnouncePromptSubmit("Chainloop spec capture."))
+	})
+
+	assert.Empty(t, out)
+}
+
 // captureStdout runs fn and returns what it wrote to stdout.
 func captureStdout(t *testing.T, fn func()) string {
 	t.Helper()

app/cli/internal/trace/cursor/provider.go

@@ -123,6 +123,19 @@ func (p *Provider) SupportsSessionStartInstruction() bool {
 	return true
 }
 
+// SupportsPromptReminder is false for Cursor: it documents no channel that
+// adds context at prompt submit, so it gets the session-start instruction
+// only.
+func (p *Provider) SupportsPromptReminder() bool {
+	return false
+}
+
+// AnnouncePromptSubmit writes nothing for Cursor, which installs no
+// prompt-submit hook.
+func (p *Provider) AnnouncePromptSubmit(_ string) error {
+	return nil
+}
+
 // AnnounceToUser is unsupported for Cursor: it installs only sessionStart,
 // sessionEnd and afterFileEdit, so no hook fires after a shell command and
 // there is nowhere to deliver the message.

app/cli/internal/trace/opencode/announce_test.go

@@ -79,6 +79,39 @@ func TestAnnounceSessionStart(t *testing.T) {
 	}
 }
 
+// TestAnnouncePromptSubmit pins the prompt-submit response: the plugin reads
+// instruction and posts it to the session as a context-only message, as it
+// does at session start.
+func TestAnnouncePromptSubmit(t *testing.T) {
+	const reminder = "Chainloop spec capture. Folder: /repo/.chainloop/specs/abc-123"
+
+	testCases := []struct {
+		name     string
+		reminder string
+		want     map[string]any
+	}{
+		{name: "a reminder is emitted", reminder: reminder, want: map[string]any{"instruction": reminder}},
+		{name: "nothing to say emits nothing", reminder: ""},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			out := captureStdout(t, func() {
+				require.NoError(t, New().AnnouncePromptSubmit(tc.reminder))
+			})
+
+			if tc.want == nil {
+				assert.Empty(t, out)
+				return
+			}
+
+			var got map[string]any
+			require.NoError(t, json.Unmarshal([]byte(out), &got))
+			assert.Equal(t, tc.want, got)
+		})
+	}
+}
+
 // captureStdout runs fn and returns what it wrote to stdout.
 func captureStdout(t *testing.T, fn func()) string {
 	t.Helper()