Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

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

kanfil99970560db03
diff --git a/src/specify_cli/events.py b/src/specify_cli/events.py
index ec2b5228d..8ca1de370 100644
--- a/src/specify_cli/events.py
+++ b/src/specify_cli/events.py
@@ -251,7 +251,7 @@ def _resolve_argv(template_path, project_root, ext_id):
return [str(script_abs), *rest]
-def _run_inline(command_name, payload, project_root, timeout):
+def _run_inline(command_name, payload, project_root, timeout, envelope="plain", native_event=""):
"""Resolve and run the event command with stdlib only (no specify_cli)."""
template_path, ext_id = _find_command_template(command_name, project_root)
if not template_path:
@@ -269,7 +269,7 @@ def _run_inline(command_name, payload, project_root, timeout):
cwd=str(project_root),
)
if result.stdout:
- sys.stdout.write(result.stdout)
+ _emit(result.stdout, envelope, native_event)
if result.returncode != 0:
if result.stderr:
sys.stderr.write(result.stderr)
@@ -283,6 +283,46 @@ def _run_inline(command_name, payload, project_root, timeout):
return 2
+def _emit(output, envelope, native_event=""):
+ """Write handler output to stdout in the agent's context-injection shape.
+
+ 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, never context), Copilot discards non-JSON stdout, and
+ Cursor parses stdout as JSON. The native hook command passes the envelope
+ as the dispatcher's 5th argument (see events_context_envelope on the
+ integration classes), and the native event name as the 6th argument so
+ hookSpecificOutput can include hookEventName:
+
+ hookSpecificOutput β†’ {"hookSpecificOutput": {"hookEventName": ..., "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)
+ plain (default) β†’ passthrough (Claude/Codex inject plain stdout)
+
+ Empty output emits nothing under any envelope (an empty additionalContext
+ is useless noise).
+ """
+ if not output:
+ return
+ if envelope == "suppress":
+ return
+ if envelope == "hookSpecificOutput":
+ payload = {"additionalContext": output}
+ if native_event:
+ payload["hookEventName"] = native_event
+ sys.stdout.write(json.dumps({"hookSpecificOutput": payload}) + "\\n")
+ return
+ if envelope == "additionalContext":
+ sys.stdout.write(json.dumps({"additionalContext": output}) + "\\n")
+ return
+ if envelope == "additional_context":
+ sys.stdout.write(json.dumps({"additional_context": output}) + "\\n")
+ return
+ sys.stdout.write(output)
+
+
def main():
if len(sys.argv) < 3:
sys.exit(0)
@@ -297,6 +337,16 @@ def main():
timeout = int(sys.argv[3])
except (TypeError, ValueError):
timeout = 120
+ # Optional 5th arg: context-injection envelope for stdout (C13): plain
+ # (default), hookSpecificOutput, additionalContext, additional_context,
+ # or suppress. Unknown values fall back to plain passthrough.
+ envelope = sys.argv[4] if len(sys.argv) >= 5 else "plain"
+ if envelope not in ("plain", "hookSpecificOutput", "additionalContext", "additional_context", "suppress"):
+ envelope = "plain"
+ # Optional 6th arg: native event name for hookSpecificOutput's
+ # hookEventName field (required by Qwen's hooks spec; included by
+ # Gemini/Tabnine/Devin which derive from the same protocol).
+ native_event = sys.argv[5] if len(sys.argv) >= 6 else ""
payload = sys.stdin.read() if not sys.stdin.isatty() else "{}"
project_root = Path(__file__).parent.parent.resolve()
@@ -307,14 +357,14 @@ def main():
from specify_cli.events import resolve_and_run_event_command
sys.exit(
resolve_and_run_event_command(
- command_name, _event_name, payload, project_root, timeout=timeout
+ command_name, _event_name, payload, project_root, timeout=timeout, envelope=envelope, native_event=native_event
)
)
- except ImportError:
+ except (ImportError, TypeError):
pass
# Fallback: self-contained stdlib resolver (one-time/temporary installs).
- sys.exit(_run_inline(command_name, payload, project_root, timeout))
+ sys.exit(_run_inline(command_name, payload, project_root, timeout, envelope, native_event))
if __name__ == "__main__":
@@ -362,17 +412,21 @@ function resolveDispatcher(directory: string): void {{
) as string;
}}
-function runEvent(command: string, event: string, input: any, output: any, timeoutSec: number): void {{
- if (!DISPATCHER) return;
+function runEvent(command: string, event: string, input: any, output: any, timeoutSec: number): string {{
+ if (!DISPATCHER) return '';
try {{
// execFileSync with an argv array invokes the interpreter directly β€” no
// shell β€” so command/event strings with metacharacters can't break out
// of the dispatcher argument (C9). The dispatcher arg is seconds; the
// execFileSync timeout is ms with a buffer so the outer cap fires after
- // the dispatcher's inner subprocess (S3).
- execFileSync(INTERPRETER, [DISPATCHER, command, event, String(timeoutSec)], {{
+ // the dispatcher's inner subprocess (S3). stdout is captured and
+ // returned so context-injection hooks (experimental.chat.system.transform,
+ // chat.message) can push it into their outputs; stderr stays inherited so
+ // dispatcher errors remain visible (C11).
+ return execFileSync(INTERPRETER, [DISPATCHER, command, event, String(timeoutSec)], {{
input: JSON.stringify({{ input, output }}),
- stdio: ['pipe', 'inherit', 'inherit'],
+ stdio: ['pipe', 'pipe', 'inherit'],
+ encoding: 'utf-8',
timeout: (timeoutSec + {buffer}) * 1000,
}});
}} catch (e) {{
@@ -382,6 +436,12 @@ function runEvent(command: string, event: string, input: any, output: any, timeo
}}
}}
+// Cache session_start handler output per sessionID so non-idempotent
+// handlers (setup, telemetry, file-mutating scripts) run once per session
+// instead of on every LLM request (experimental.chat.system.transform
+// fires per LLM turn). Evicted on session.deleted.
+const sessionStartCache = new Map<string, string>();
+
{event_entries}
export default (async ({{ client, project, directory, $ }}) => {{
@@ -585,12 +645,26 @@ def resolve_and_run_event_command(
project_root: Path,
*,
timeout: int = 120,
+ envelope: str = "plain",
+ native_event: str = "",
) -> int:
"""Core entry point to resolve and execute an event-driven command.
*timeout* is the per-handler timeout in seconds, passed through from the
native hook config via the dispatcher (S4) so a handler configured above
the previous fixed 120s cap can run for its full duration.
+
+ *envelope* selects how the handler's stdout is emitted for the agent's
+ context-injection protocol (C13): ``plain`` passthrough (Claude/Codex
+ inject plain stdout), ``hookSpecificOutput``/``additionalContext``/
+ ``additional_context`` JSON wrappers (Gemini/Tabnine/Qwen/Devin, Copilot,
+ Cursor respectively), or ``suppress`` (strict-JSON agents on events whose
+ output can't be used).
+
+ *native_event* is the agent's native hookEventName (e.g. ``"SessionStart"``),
+ required inside ``hookSpecificOutput`` by Qwen's hooks spec (and included
+ by the Claude Code hooks spec Gemini/Tabnine/Devin derive from). Only
+ used when *envelope* is ``hookSpecificOutput``.
"""
template_path, ext_id = _find_command_template(command_name, project_root)
if not template_path:
@@ -610,7 +684,7 @@ def resolve_and_run_event_command(
cwd=str(project_root),
)
if result.stdout:
- sys.stdout.write(result.stdout)
+ _emit_event_stdout(result.stdout, envelope, native_event)
if result.returncode != 0:
if result.stderr:
sys.stderr.write(result.stderr)
@@ -624,6 +698,35 @@ def resolve_and_run_event_command(
return 2
+def _emit_event_stdout(output: str, envelope: str, native_event: str = "") -> None:
+ """Write handler stdout in the agent's context-injection shape (C13).
+
+ Mirrors the ``_emit`` helper inside the generated dispatcher template;
+ keep both in sync. Empty output emits nothing under any envelope.
+
+ *native_event* is the agent's native hookEventName, required inside
+ ``hookSpecificOutput`` by Qwen's hooks spec (and included by the
+ Claude Code hooks spec Gemini/Tabnine/Devin derive from).
+ """
+ if not output:
+ return
+ if envelope == "suppress":
+ return
+ if envelope == "hookSpecificOutput":
+ payload = {"additionalContext": output}
+ if native_event:
+ payload["hookEventName"] = native_event
+ sys.stdout.write(json.dumps({"hookSpecificOutput": payload}) + "\n")
+ return
+ if envelope == "additionalContext":
+ sys.stdout.write(json.dumps({"additionalContext": output}) + "\n")
+ return
+ if envelope == "additional_context":
+ sys.stdout.write(json.dumps({"additional_context": output}) + "\n")
+ return
+ sys.stdout.write(output)
+
+
# -- Sourcing events map (CLI/Orchestration domain) -------------------------
# Resolved events map: each canonical event name maps to an *ordered list* of
@@ -1018,7 +1121,17 @@ def _dispatcher_command(
When *timeout_seconds* is given, the resolved timeout (in the
integration's native unit) is appended as a 4th argument so the dispatcher
and inner runner honor the per-handler timeout instead of a fixed 120s cap
- that would kill a handler configured for longer (S4).
+ that would kill a handler configured for longer (S4). When omitted, a
+ default of 60s is emitted so the positional argument order
+ (command event timeout envelope native_event) stays aligned β€” otherwise
+ the envelope would land in the timeout slot and the dispatcher would
+ silently fall back to plain stdout.
+
+ When the integration declares a context-injection envelope for this
+ canonical event (``events_context_envelope``, C13), the envelope token is
+ appended as a 5th argument so the dispatcher wraps stdout in the JSON
+ shape the agent's hook protocol requires. Plain-passthrough agents
+ (Claude/Codex) declare no envelope and get no extra argument.
"""
if target_os == "host":
interpreter = _resolve_interpreter(project_root)
@@ -1038,16 +1151,44 @@ def _dispatcher_command(
# operator. Prefix & for the explicit windows target only.
prefix = "& " if target_os == "windows" else ""
base = f"{prefix}{q_interp} {dispatcher} {q_command} {q_event}"
- if timeout_seconds is not None:
- # R2: the dispatcher interprets this argument as seconds, so pass the
- # raw seconds β€” NOT _native_timeout(...) (which converts to ms for
- # Gemini/Qwen/Tabnine and would yield 60000 seconds). The buffer is
- # applied to the native hook timeout field (in the adapter formatters)
- # so the agent's outer cap fires after the inner subprocess timeout.
- base += f" {_shell_quote(str(int(timeout_seconds)), target_os)}"
+ # Always emit the timeout (4th positional arg) so the dispatcher's argv
+ # parsing stays aligned when an envelope (5th) or native_event (6th)
+ # follows. Without it the envelope would land in the timeout slot and
+ # the dispatcher would fall back to plain stdout (R3).
+ resolved_timeout = 60 if timeout_seconds is None else int(timeout_seconds)
+ # R2: the dispatcher interprets this argument as seconds, so pass the
+ # raw seconds β€” NOT _native_timeout(...) (which converts to ms for
+ # Gemini/Qwen/Tabnine and would yield 60000 seconds). The buffer is
+ # applied to the native hook timeout field (in the adapter formatters)
+ # so the agent's outer cap fires after the inner subprocess timeout.
+ base += f" {_shell_quote(str(resolved_timeout), target_os)}"
+ envelope = _context_envelope_for(integration, event_name)
+ if envelope:
+ base += f" {_shell_quote(envelope, target_os)}"
+ # hookSpecificOutput requires the native hookEventName inside the
+ # envelope (Qwen's hooks spec marks it mandatory; the Claude Code
+ # hooks spec that Gemini/Tabnine/Devin derive from includes it).
+ # Append the native event name as a 6th dispatcher argument so the
+ # dispatcher can populate hookEventName in the JSON output.
+ if envelope == "hookSpecificOutput":
+ native_event = getattr(integration, "CANONICAL_TO_NATIVE", {}).get(event_name, "")
+ if native_event:
+ base += f" {_shell_quote(native_event, target_os)}"
return base
+def _context_envelope_for(integration: IntegrationBase, canonical_event: str) -> str | None:
+ """Resolve the context-injection envelope for an integration + event (C13).
+
+ The event key wins; ``"*"`` is the fallback. Returns ``None`` when the
+ integration declares no envelope for the event (plain stdout passthrough).
+ """
+ mapping = getattr(integration, "events_context_envelope", None) or {}
+ if canonical_event in mapping:
+ return mapping[canonical_event]
+ return mapping.get("*")
+
+
def install_integration_events(
integration: IntegrationBase,
project_root: Path,
@@ -1590,6 +1731,14 @@ def _build_opencode_plugin(
an argv array (C9). Both the ``input`` and ``output`` callback arguments
are forwarded to ``runEvent`` (C7) so pre_tool_use can inspect tool
arguments and post_tool_use can inspect the result.
+
+ Context-injection natives get dedicated hook bodies: for
+ ``experimental.chat.system.transform`` the handlers' concatenated stdout
+ is pushed into ``output.system`` (system-prompt injection, re-applied per
+ LLM request so the context survives compaction); for ``chat.message`` it
+ is pushed as a synthetic text part on the user message (C11). Other
+ natives keep their side-effect behavior (tool.execute.* args mutation;
+ session.* lifecycle events via the generic ``event`` hook).
"""
event_entries: list[str] = []
plugin_returns: list[str] = []
@@ -1604,11 +1753,16 @@ def _build_opencode_plugin(
ev_lit = json.dumps(ev)
native_lit = json.dumps(native)
+ is_injection = native in ("experimental.chat.system.transform", "chat.message")
+
# Build the body: one runEvent() call per handler wrapped in try/catch,
# forwarding both input and output (C7). An optional tool-name matcher
# guard applies to tool.execute.* hooks. All handlers execute before
- # any aggregate error is thrown.
+ # any aggregate error is thrown. Injection hooks additionally collect
+ # each handler's stdout and return the concatenation.
body_lines: list[str] = [" const errors: string[] = [];"]
+ if is_injection:
+ body_lines.append(" const contexts: string[] = [];")
for cfg in handlers:
command = str(cfg.get("command", ""))
command_lit = json.dumps(command)
@@ -1630,6 +1784,10 @@ def _build_opencode_plugin(
body_lines.append(
f" try {{ runEvent({command_lit}, {ev_lit}, input, output, {timeout_sec}); }} catch (e) {{ errors.push((e as Error).message); }}"
)
+ elif is_injection:
+ body_lines.append(
+ f" try {{ const ctx = runEvent({command_lit}, {ev_lit}, input, output, {timeout_sec}); if (ctx) contexts.push(ctx); }} catch (e) {{ errors.push((e as Error).message); }}"
+ )
else:
body_lines.append(
f" try {{ runEvent({command_lit}, {ev_lit}, input, output, {timeout_sec}); }} catch (e) {{ errors.push((e as Error).message); }}"
@@ -1648,14 +1806,65 @@ def _build_opencode_plugin(
f" _{ev}(input, output);\n"
f" }},"
)
+ elif native == "experimental.chat.system.transform":
+ body_lines.append(' return contexts.join("\\n\\n");')
+ event_entries.append(
+ f"function _{ev}(input: any, output: any): string {{\n"
+ + "\n".join(body_lines) + "\n"
+ " }"
+ )
+ # OpenCode fires experimental.chat.system.transform for non-session
+ # operations (e.g. agent generation) with no sessionID. Guard so
+ # canonical session_start handlers only run when a session is
+ # present, preventing their output from being injected into
+ # internal prompts. Cache the handler output per sessionID so
+ # non-idempotent handlers (setup, telemetry, file-mutating
+ # scripts) execute once per session instead of on every LLM
+ # request; the cache is evicted on session.deleted.
+ plugin_returns.append(
+ f" {native_lit}: async (input: any, output: any) => {{\n"
+ f" if (!input.sessionID) return;\n"
+ f" let ctx = sessionStartCache.get(input.sessionID);\n"
+ f" if (ctx === undefined) {{\n"
+ f" ctx = _{ev}(input, output);\n"
+ f" sessionStartCache.set(input.sessionID, ctx ?? \"\");\n"
+ f" }}\n"
+ f" if (ctx) output.system.push(ctx);\n"
+ f" }},"
+ )
+ elif native == "chat.message":
+ body_lines.append(' return contexts.join("\\n\\n");')
+ event_entries.append(
+ f"function _{ev}(input: any, output: any): string {{\n"
+ + "\n".join(body_lines) + "\n"
+ " }"
+ )
+ # Part id must start with "prt" (opencode's Identifier brand): an
+ # invalid id fails the user-part schema validation and crashes the
+ # whole session (C12). Derive it from the last existing part so the
+ # brand survives an opencode prefix change, falling back to "prt_"
+ # when output.parts is empty.
+ plugin_returns.append(
+ f" {native_lit}: async (input: any, output: any) => {{\n"
+ f" const ctx = _{ev}(input, output);\n"
+ f" if (!ctx) return;\n"
+ f" const base = output.parts[output.parts.length - 1]?.id ?? \"prt_\" + Date.now().toString(36) + Math.random().toString(36).slice(2, 10);\n"
+ f" output.parts.push({{ id: base + \".speckit\" + Math.random().toString(36).slice(2, 8), sessionID: input.sessionID, messageID: output.message.id, type: \"text\", text: ctx, synthetic: true }});\n"
+ f" }},"
+ )
else:
event_entries.append(
f"function _{ev}(input: any, output: any) {{\n"
+ "\n".join(body_lines) + "\n"
" }"
)
+ # Evict the sessionStartCache when the session is deleted so the
+ # cache doesn't grow unbounded across sessions.
+ eviction = ""
+ if native == "session.deleted":
+ eviction = "if (event.sessionID) sessionStartCache.delete(event.sessionID); "
event_handlers.append(
- f" if (event.type === {native_lit}) {{ _{ev}(event, event); }}"
+ f" if (event.type === {native_lit}) {{ {eviction}_{ev}(event, event); }}"
)
if event_handlers:
diff --git a/src/specify_cli/integrations/base.py b/src/specify_cli/integrations/base.py
index ebcf8dde1..03c7a90e7 100644
--- a/src/specify_cli/integrations/base.py
+++ b/src/specify_cli/integrations/base.py
@@ -957,6 +957,20 @@ class IntegrationBase(ABC):
"""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(
diff --git a/src/specify_cli/integrations/copilot/__init__.py b/src/specify_cli/integrations/copilot/__init__.py
index 9c6b33b2a..0a9b4e159 100644
--- a/src/specify_cli/integrations/copilot/__init__.py
+++ b/src/specify_cli/integrations/copilot/__init__.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
diff --git a/src/specify_cli/integrations/cursor_agent/__init__.py b/src/specify_cli/integrations/cursor_agent/__init__.py
index 58bd89b21..45c5522a0 100644
--- a/src/specify_cli/integrations/cursor_agent/__init__.py
+++ b/src/specify_cli/integrations/cursor_agent/__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,
diff --git a/src/specify_cli/integrations/devin/__init__.py b/src/specify_cli/integrations/devin/__init__.py
index dea6b5d22..480736534 100644
--- a/src/specify_cli/integrations/devin/__init__.py
+++ b/src/specify_cli/integrations/devin/__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,
diff --git a/src/specify_cli/integrations/gemini/__init__.py b/src/specify_cli/integrations/gemini/__init__.py
index 2200e707c..1e824d451 100644
--- a/src/specify_cli/integrations/gemini/__init__.py
+++ b/src/specify_cli/integrations/gemini/__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
diff --git a/src/specify_cli/integrations/opencode/__init__.py b/src/specify_cli/integrations/opencode/__init__.py
index 660fd0b5f..007c1187b 100644
--- a/src/specify_cli/integrations/opencode/__init__.py
+++ b/src/specify_cli/integrations/opencode/__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"
diff --git a/src/specify_cli/integrations/qwen/__init__.py b/src/specify_cli/integrations/qwen/__init__.py
index 7ab55d978..e356f851c 100644
--- a/src/specify_cli/integrations/qwen/__init__.py
+++ b/src/specify_cli/integrations/qwen/__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
diff --git a/src/specify_cli/integrations/tabnine/__init__.py b/src/specify_cli/integrations/tabnine/__init__.py
index 5e8a803e6..17b78d111 100644
--- a/src/specify_cli/integrations/tabnine/__init__.py
+++ b/src/specify_cli/integrations/tabnine/__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
diff --git a/tests/integrations/test_events.py b/tests/integrations/test_events.py
index 1cb376e27..434cadec8 100644
--- a/tests/integrations/test_events.py
+++ b/tests/integrations/test_events.py
@@ -251,6 +251,8 @@ class TestCanonicalEventMapping:
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 @@ class TestCopilotAgentStop:
# -- 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 @@ class TestOpencodePluginMerging:
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 @@ class TestOpencodePluginMerging:
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 @@ class TestCommandRunner:
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