feat(events): context injection for opencode and JSON-envelope agent hooks (#3934)

* feat(events): context injection for opencode and JSON-envelope agent hooks

Adds first-class context injection to agent runtime events:

1. opencode: maps session_start to experimental.chat.system.transform (injects into system prompt) and user_prompt_submit to chat.message (injects synthetic TextPart). TS plugin captures runEvent stdout (stdio pipe, encoding utf-8) and pushes into output objects. Part IDs derive from output.parts[last].id to preserve OpenCode's prt_ brand and prevent session schema crashes.

2. JSON-envelope hook wrapping: adds events_context_envelope to IntegrationBase so agents that require JSON on stdout receive their target envelope via the dispatcher's 5th argument:
   - gemini, tabnine, qwen, devin: hookSpecificOutput.additionalContext on session_start/user_prompt_submit; suppress on non-injectable events (prevents systemMessage user-facing noise)
   - copilot: top-level additionalContext on session_start
   - cursor: top-level additional_context on session_start; suppress elsewhere
   - claude, codex: plain stdout passthrough (already injected)

3. Dispatcher template and resolve_and_run_event_command parse the 5th envelope arg and wrap stdout accordingly.

Tests added for opencode TextPart schema, part ID derivation, envelope command generation, and dispatcher output wrapping. All 162 events/integration tests pass.

* fix(events): address code review on #3934

- Qwen/Gemini/Tabnine/Devin: include native hookEventName inside
  hookSpecificOutput envelope (required by Qwen's hooks spec). Thread
  the native event name from the integration's CANONICAL_TO_NATIVE
  through _dispatcher_command as a 6th dispatcher argument, through
  the dispatcher template's main()/_run_inline()/_emit(), and through
  resolve_and_run_event_command()/_emit_event_stdout().
- Copilot: map user_prompt_submit to additionalContext (previously
  unmapped, breaking per-prompt context injection despite Copilot CLI
  supporting it via userPromptSubmitted).
- OpenCode: guard experimental.chat.system.transform so canonical
  session_start handlers only run when input.sessionID is present —
  OpenCode fires this hook for non-session operations (e.g. agent
  generation) with no sessionID.

Assisted-by: opencode (model: glm-5.2, supervised)

* fix(events): address second Copilot review round on #3934

- Positional arg alignment: always emit default timeout (60s) as the
  4th dispatcher argument even when timeout_seconds is omitted, so the
  envelope (5th) and native_event (6th) land in the correct argv slots.
  Previously, omitting timeout_seconds caused the envelope to be parsed
  as an invalid timeout, silently falling back to plain stdout.
- OpenCode session_start caching: cache handler output per sessionID in
  the generated TS plugin so non-idempotent handlers (setup, telemetry,
  file-mutating scripts) run once per session instead of on every LLM
  request. Cache is evicted on session.deleted.
- Updated PR description to reflect Copilot user_prompt_submit now maps
  to additionalContext (was documented as plain/unprocessed).

Assisted-by: opencode (model: glm-5.2, supervised)

Author: kanfil

src/specify_cli/events.py

@@ -957,6 +957,20 @@ def supports_events(self) -> bool:
         """Return True if this integration supports agent-native events."""
         return bool(getattr(self, "CANONICAL_TO_NATIVE", None) and getattr(self, "events_config_file", None))
 
+    # Context-injection envelope for hook stdout, keyed by canonical event
+    # (with "*" as the fallback). Not every agent injects a hook's plain-text
+    # stdout as model context: Gemini/Tabnine/Qwen/Devin are JSON-only
+    # protocols (plain text becomes user-facing noise), Copilot discards
+    # non-JSON stdout, and Cursor parses stdout as JSON. Values:
+    #   "hookSpecificOutput" → {"hookSpecificOutput": {"additionalContext": ...}}
+    #   "additionalContext"  → {"additionalContext": ...}   (top-level, Copilot)
+    #   "additional_context" → {"additional_context": ...}  (top-level, Cursor)
+    #   "suppress"           → emit nothing (strict-JSON agents on events whose
+    #                          output can't be used)
+    # Absent (no matching key and no "*") → plain stdout passthrough
+    # (Claude/Codex inject plain stdout; opencode injects via its TS plugin).
+    events_context_envelope: dict[str, str] = {}
+
     # -- Convenience helpers for subclasses -------------------------------
 
     def install(

src/specify_cli/integrations/base.py

@@ -152,6 +152,14 @@ class CopilotIntegration(IntegrationBase):
     }
     events_config_file = ".github/hooks/speckit.json"
     events_format = "copilot-json"
+    # Copilot sessionStart and userPromptSubmitted inject a top-level
+    # additionalContext field into the model-facing prompt (C13). Non-JSON
+    # stdout is discarded harmlessly by Copilot on other events, so no other
+    # event needs an envelope.
+    events_context_envelope = {
+        "session_start": "additionalContext",
+        "user_prompt_submit": "additionalContext",
+    }
 
     # Mutable flag set by setup() — indicates the active scaffolding mode.
     _skills_mode: bool = True

src/specify_cli/integrations/copilot/__init__.py

@@ -48,6 +48,14 @@ class CursorAgentIntegration(SkillsIntegration):
     }
     events_config_file = ".cursor/hooks.json"
     events_format = "json-flat"
+    # Cursor sessionStart injects a top-level additional_context (snake_case)
+    # field (C13). beforeSubmitPrompt has no context output field (block/allow
+    # only), and plain text on any hook fails Cursor's JSON parse — suppress
+    # everything else.
+    events_context_envelope = {
+        "*": "suppress",
+        "session_start": "additional_context",
+    }
 
     def build_exec_args(
         self,

src/specify_cli/integrations/cursor_agent/__init__.py

@@ -44,6 +44,13 @@ class DevinIntegration(SkillsIntegration):
     # top-level "hooks" wrapper (U2), unlike the settings.json formats. The
     # json-root-nested writer/remover operate directly on the root event keys.
     events_format = "json-root-nested"
+    # Devin's hooks protocol is JSON-stdout; additionalContext is the
+    # documented injection field for SessionStart/UserPromptSubmit (C13).
+    events_context_envelope = {
+        "*": "suppress",
+        "session_start": "hookSpecificOutput",
+        "user_prompt_submit": "hookSpecificOutput",
+    }
 
     def build_exec_args(
         self,

src/specify_cli/integrations/devin/__init__.py

@@ -33,6 +33,15 @@ class GeminiIntegration(TomlIntegration):
     }
     events_config_file = ".gemini/settings.json"
     events_format = "json-nested"
+    # Gemini mandates JSON-only hook stdout ("silence is mandatory"): plain
+    # text becomes a user-facing systemMessage, never context. Inject via
+    # hookSpecificOutput.additionalContext on the two context events and
+    # suppress stdout everywhere else (C13).
+    events_context_envelope = {
+        "*": "suppress",
+        "session_start": "hookSpecificOutput",
+        "user_prompt_submit": "hookSpecificOutput",
+    }
     # Gemini measures hook timeouts in milliseconds, unlike Claude/Cursor/Codex
     # which use seconds. The shared formatter converts via _native_timeout (#7)
     # so the default 60s becomes 60000ms instead of terminating the dispatcher

src/specify_cli/integrations/gemini/__init__.py

@@ -23,7 +23,15 @@ class OpencodeIntegration(MarkdownIntegration):
     CANONICAL_TO_NATIVE = {
         "pre_tool_use": "tool.execute.before",
         "post_tool_use": "tool.execute.after",
-        "session_start": "session.created",
+        # session_start maps to the system-prompt transform hook (not the
+        # session.created event) so the handler's stdout is injected into the
+        # system prompt — session.created has no output channel. The hook
+        # fires per LLM request, which keeps the context present across
+        # compaction at the cost of running the handler per turn.
+        "session_start": "experimental.chat.system.transform",
+        # user_prompt_submit maps to chat.message so handler stdout is
+        # injected as a synthetic text part on the user's message.
+        "user_prompt_submit": "chat.message",
         "session_end": "session.deleted",
     }
     events_config_file = "opencode.json"

src/specify_cli/integrations/opencode/__init__.py

@@ -30,6 +30,12 @@ class QwenIntegration(MarkdownIntegration):
     }
     events_config_file = ".qwen/settings.json"
     events_format = "json-nested"
+    # Qwen hooks are a JSON stdin/stdout protocol (Gemini-derived) (C13).
+    events_context_envelope = {
+        "*": "suppress",
+        "session_start": "hookSpecificOutput",
+        "user_prompt_submit": "hookSpecificOutput",
+    }
     # Qwen Code's command hooks measure timeout in milliseconds (default
     # 60000), per the Qwen Code hooks documentation. Declaring the unit makes
     # the shared formatter convert the 60s default to 60000ms instead of

src/specify_cli/integrations/qwen/__init__.py

@@ -33,6 +33,12 @@ class TabnineIntegration(TomlIntegration):
     }
     events_config_file = ".tabnine/agent/settings.json"
     events_format = "json-nested"
+    # Tabnine is Gemini-hooks-compatible (JSON-only stdout) (C13).
+    events_context_envelope = {
+        "*": "suppress",
+        "session_start": "hookSpecificOutput",
+        "user_prompt_submit": "hookSpecificOutput",
+    }
     # Tabnine mirrors Gemini's hook schema (BeforeTool/AfterTool) and, like
     # Gemini, measures hook timeouts in milliseconds. Declaring the unit makes
     # the shared formatter convert the 60s default to 60000ms instead of

src/specify_cli/integrations/tabnine/__init__.py

@@ -251,6 +251,8 @@ def test_opencode_limited(self):
         integration = OpencodeIntegration()
         assert integration.supports_events() is True
         assert integration.CANONICAL_TO_NATIVE["pre_tool_use"] == "tool.execute.before"
+        assert integration.CANONICAL_TO_NATIVE["session_start"] == "experimental.chat.system.transform"
+        assert integration.CANONICAL_TO_NATIVE["user_prompt_submit"] == "chat.message"
         assert "stop" not in integration.CANONICAL_TO_NATIVE
 
     def test_copilot_mapping(self):
@@ -671,6 +673,104 @@ def test_copilot_stop_mapping(self):
 
 # -- Shell quoting & matcher escaping (R2, R4) -------------------------------
 
+class TestContextInjectionEnvelopes:
+    """C13: context-injection envelope resolution and emission."""
+
+    def test_emit_event_stdout_wrapping(self, capsys):
+        from specify_cli.events import _emit_event_stdout
+
+        _emit_event_stdout("hello ctx", "plain")
+        assert capsys.readouterr().out == "hello ctx"
+
+        # hookSpecificOutput without native_event: no hookEventName (backward
+        # compat for callers that don't pass it).
+        _emit_event_stdout("hello ctx", "hookSpecificOutput")
+        assert json.loads(capsys.readouterr().out.strip()) == {
+            "hookSpecificOutput": {"additionalContext": "hello ctx"}
+        }
+
+        # hookSpecificOutput with native_event: hookEventName included
+        # (required by Qwen's hooks spec; derived from Claude Code's).
+        _emit_event_stdout("hello ctx", "hookSpecificOutput", "SessionStart")
+        assert json.loads(capsys.readouterr().out.strip()) == {
+            "hookSpecificOutput": {
+                "additionalContext": "hello ctx",
+                "hookEventName": "SessionStart",
+            }
+        }
+
+        _emit_event_stdout("hello ctx", "additionalContext")
+        assert json.loads(capsys.readouterr().out.strip()) == {
+            "additionalContext": "hello ctx"
+        }
+
+        _emit_event_stdout("hello ctx", "additional_context")
+        assert json.loads(capsys.readouterr().out.strip()) == {
+            "additional_context": "hello ctx"
+        }
+
+        _emit_event_stdout("hello ctx", "suppress")
+        assert capsys.readouterr().out == ""
+
+        # Empty output emits nothing under any envelope.
+        _emit_event_stdout("", "additionalContext")
+        assert capsys.readouterr().out == ""
+
+    def test_envelope_resolution_and_command_formatting(self):
+        from specify_cli.events import _dispatcher_command, _context_envelope_for
+        from specify_cli.integrations.gemini import GeminiIntegration
+        from specify_cli.integrations.qwen import QwenIntegration
+        from specify_cli.integrations.copilot import CopilotIntegration
+        from specify_cli.integrations.cursor_agent import CursorAgentIntegration
+        from specify_cli.integrations.claude import ClaudeIntegration
+        from specify_cli.integrations.codex import CodexIntegration
+
+        gemini = GeminiIntegration()
+        assert _context_envelope_for(gemini, "session_start") == "hookSpecificOutput"
+        assert _context_envelope_for(gemini, "user_prompt_submit") == "hookSpecificOutput"
+        assert _context_envelope_for(gemini, "pre_tool_use") == "suppress"
+
+        # hookSpecificOutput appends the native event name as a 6th dispatcher
+        # argument so the dispatcher can populate hookEventName. The default
+        # timeout (60s) is always emitted as the 4th arg to keep positional
+        # alignment (R3).
+        cmd_gemini_start = _dispatcher_command(gemini, Path("/proj"), "speckit.boot", "session_start")
+        assert cmd_gemini_start.endswith(" 60 hookSpecificOutput SessionStart")
+
+        cmd_gemini_prompt = _dispatcher_command(gemini, Path("/proj"), "speckit.prompt", "user_prompt_submit")
+        assert cmd_gemini_prompt.endswith(" 60 hookSpecificOutput BeforeAgent")
+
+        cmd_gemini_tool = _dispatcher_command(gemini, Path("/proj"), "speckit.guard", "pre_tool_use")
+        assert cmd_gemini_tool.endswith(" 60 suppress")
+
+        # Qwen uses the same hookSpecificOutput protocol with its own native
+        # event names; verify hookEventName threading for Qwen's CamelCase names.
+        qwen = QwenIntegration()
+        cmd_qwen_start = _dispatcher_command(qwen, Path("/proj"), "speckit.boot", "session_start")
+        assert cmd_qwen_start.endswith(" 60 hookSpecificOutput SessionStart")
+        cmd_qwen_prompt = _dispatcher_command(qwen, Path("/proj"), "speckit.prompt", "user_prompt_submit")
+        assert cmd_qwen_prompt.endswith(" 60 hookSpecificOutput UserPromptSubmit")
+
+        copilot = CopilotIntegration()
+        assert _context_envelope_for(copilot, "session_start") == "additionalContext"
+        assert _context_envelope_for(copilot, "user_prompt_submit") == "additionalContext"
+        cmd_copilot_start = _dispatcher_command(copilot, Path("/proj"), "speckit.boot", "session_start")
+        assert cmd_copilot_start.endswith(" 60 additionalContext")
+        cmd_copilot_prompt = _dispatcher_command(copilot, Path("/proj"), "speckit.prompt", "user_prompt_submit")
+        assert cmd_copilot_prompt.endswith(" 60 additionalContext")
+
+        cursor = CursorAgentIntegration()
+        assert _context_envelope_for(cursor, "session_start") == "additional_context"
+        assert _context_envelope_for(cursor, "user_prompt_submit") == "suppress"
+        cmd_cursor_start = _dispatcher_command(cursor, Path("/proj"), "speckit.boot", "session_start")
+        assert cmd_cursor_start.endswith(" 60 additional_context")
+
+        claude = ClaudeIntegration()
+        codex = CodexIntegration()
+        assert _context_envelope_for(claude, "session_start") is None
+        assert _context_envelope_for(codex, "session_start") is None
+
+
 class TestDispatcherCommandQuoting:
     """R2: dispatcher command components are shell-quoted so spaces and shell
     metacharacters are passed as single arguments, not reinterpreted."""
@@ -783,6 +883,7 @@ def test_opencode_ts_plugin_generation(self, tmp_path):
         events = {
             "pre_tool_use": [{"command": "speckit.tdd.validate", "matcher": "Edit"}],
             "session_start": [{"command": "speckit.agent-context.update"}],
+            "session_end": [{"command": "speckit.agent-context.teardown"}],
         }
         install_integration_events(integration, tmp_path, manifest, events)
 
@@ -791,13 +892,50 @@ def test_opencode_ts_plugin_generation(self, tmp_path):
         content = plugin_path.read_text()
         assert "runEvent" in content
         assert "tool.execute.before" in content
-        assert "session.created" in content
+        assert "experimental.chat.system.transform" in content
         assert "speckit.tdd.validate" in content
         assert "speckit.agent-context.update" in content
         # #13: failures must propagate via throw, not process.exit(2) which
         # would kill the OpenCode host process.
         assert "process.exit(2)" not in content
         assert "throw new Error" in content
+        # session_start (experimental.chat.system.transform) must be guarded
+        # so canonical session-start handlers only run when a session is
+        # present — OpenCode fires this hook for non-session operations
+        # (e.g. agent generation) with no sessionID.
+        assert "if (!input.sessionID) return;" in content
+        # session_start handler output is cached per sessionID so non-idempotent
+        # handlers run once per session instead of on every LLM request.
+        assert "sessionStartCache" in content
+        assert "sessionStartCache.get(input.sessionID)" in content
+        assert "sessionStartCache.set(input.sessionID" in content
+        # Cache is evicted on session.deleted (session_end).
+        assert "sessionStartCache.delete(event.sessionID)" in content
+
+    def test_opencode_ts_plugin_chat_message_part_injection(self, tmp_path):
+        """user_prompt_submit emits chat.message pushing a synthetic TextPart.
+        The part ID derives from output.parts[last].id (prt_ brand preserved)
+        with a prt_ fallback to prevent OpenCode session schema crashes."""
+        integration = OpencodeIntegration()
+        manifest = MagicMock(spec=IntegrationManifest)
+        manifest.files = {}
+        manifest.record_file = MagicMock()
+        manifest.record_existing = MagicMock()
+
+        events = {
+            "user_prompt_submit": [{"command": "speckit.discover"}],
+        }
+        install_integration_events(integration, tmp_path, manifest, events)
+
+        plugin_path = tmp_path / ".opencode/plugin/speckit-events.ts"
+        assert plugin_path.is_file()
+        content = plugin_path.read_text()
+        assert "chat.message" in content
+        assert "output.parts.push" in content
+        assert "synthetic: true" in content
+        assert 'type: "text"' in content
+        assert "output.parts[output.parts.length - 1]?.id" in content
+        assert '?? "prt_"' in content
 
     def test_opencode_ts_plugin_resolves_interpreter_and_directory_at_load(self, tmp_path):
         """C8/C9: the dispatcher + interpreter are resolved per-project at
@@ -1126,7 +1264,7 @@ def test_dispatcher_is_self_contained(self, tmp_path):
         content = (tmp_path / EVENTS_DISPATCHER_REL).read_text()
         # Delegates to specify_cli when importable.
         assert "from specify_cli.events import resolve_and_run_event_command" in content
-        assert "except ImportError" in content
+        assert "except (ImportError, TypeError):" in content
         # Inline stdlib fallback resolver for one-time/temporary installs.
         assert "_run_inline" in content
         assert "_find_command_template" in content