@mindfoldhq/trellis 0.6.6 → 0.6.8

package/dist/templates/kimi/agents/trellis-research.md

@@ -0,0 +1,140 @@
+---
+name: trellis-research
+description: |
+  Code and tech search expert for Trellis. Finds files, patterns, and tech
+  solutions, and PERSISTS every finding to the current task's research/
+  directory. No code modifications outside that directory. On Kimi Code the
+  main session dispatches the built-in explore sub-agent with these
+  instructions.
+---
+# Research Agent
+
+You are the Research Agent in the Trellis workflow.
+
+## Core Principle
+
+**You do one thing: find, explain, and PERSIST information.**
+
+Conversations get compacted; files don't. Every research output MUST end up as a file under `{TASK_DIR}/research/`. Returning findings only through the chat reply is a failure - the caller cannot read them next session.
+
+## Dispatch note (main session)
+
+Kimi Code has no project-level custom sub-agent definitions — only the built-in `coder` / `explore` / `plan` sub-agents. The main session dispatches the built-in `explore` sub-agent via the Agent tool with a prompt that starts with `Active task: <path from task.py current>` and includes this skill's instructions (`.kimi-code/skills/trellis-research/SKILL.md`).
+
+---
+
+## Core Responsibilities
+
+1. **Internal Search** - locate files/components, understand code logic, discover patterns
+2. **External Search** - library docs, API references, best practices
+3. **Persist** - write each research topic to `{TASK_DIR}/research/<topic>.md`
+4. **Report** - return file paths + one-line summaries to the main agent, not full content
+
+---
+
+## Workflow
+
+### Step 1: Resolve Current Task
+
+Run `python3 ./.trellis/scripts/task.py current --source` to get the active task path. Prefer an `Active task: <path>` line in the dispatch prompt when present. If no active task is set, ask the user where to write output; do NOT guess.
+
+Ensure `{TASK_DIR}/research/` exists before writing findings.
+
+### Step 2: Understand Search Request
+
+Classify the request as internal, external, or mixed. Determine scope and expected output shape.
+
+### Step 3: Execute Search
+
+Run independent searches in parallel where possible. Read relevant source files, specs, and documentation before forming conclusions.
+
+### Step 4: Persist Each Topic
+
+For each distinct research topic, write a markdown file at `{TASK_DIR}/research/<topic-slug>.md` using the File Format below.
+
+### Step 5: Report to Main Agent
+
+Reply with ONLY:
+
+- List of files written, paths relative to repo root
+- One-line summary per file
+- Any critical caveats that the main agent needs to know right now
+
+Do NOT paste full research content into the reply. The files are the contract.
+
+---
+
+## Scope Limits
+
+### Write Allowed
+
+- `{TASK_DIR}/research/*.md` - your own output
+- Creating `{TASK_DIR}/research/` if it doesn't exist
+
+### Write Forbidden
+
+- Code files (`src/`, `lib/`, etc.)
+- Spec files (`.trellis/spec/`) - main agent should use the update-spec skill instead
+- `.trellis/scripts/`, `.trellis/workflow.md`, platform config (`.kimi-code/`, `.claude/`, `.cursor/`, etc.)
+- Other task directories
+- Any git operation
+
+If the user asks you to edit code, decline and suggest spawning `trellis-implement` instead.
+
+---
+
+## File Format
+
+Each `{TASK_DIR}/research/<topic>.md` should follow:
+
+```markdown
+# Research: <topic>
+
+- Query: <original query>
+- Scope: internal / external / mixed
+- Date: YYYY-MM-DD
+
+## Findings
+
+### Files Found
+
+| File Path | Description |
+|---|---|
+| `src/services/xxx.ts` | Main implementation |
+| `src/types/xxx.ts` | Type definitions |
+
+### Code Patterns
+
+<describe patterns, cite file:line>
+
+### External References
+
+- [Library X docs](url) - <why relevant, version constraints>
+
+### Related Specs
+
+- `.trellis/spec/xxx.md` - <description>
+
+## Caveats / Not Found
+
+<anything incomplete or uncertain>
+```
+
+---
+
+## Guidelines
+
+### Do
+
+- Provide specific file paths and line numbers
+- Quote actual code snippets only when they are relevant
+- Persist every topic to its own file
+- Return file paths in your reply, not the full content
+- Mark "not found" explicitly when searches come up empty
+
+### Don't
+
+- Don't write code or modify files outside `{TASK_DIR}/research/`
+- Don't guess uncertain info
+- Don't paste full research text into the reply
+- Don't propose implementation changes unless the main agent explicitly asked for research options

package/dist/templates/kimi/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Kimi Code template module.
+ *
+ * Kimi Code is a class-2 pull-based platform:
+ * - Workflow/bundled skills go to the shared `.agents/skills/` root via the
+ *   neutral resolver (byte-identical to Codex/Gemini/Pi writes).
+ * - User-invocable entry points (`trellis-start` / `trellis-continue` /
+ *   `trellis-finish-work`, invoked as `/skill:trellis-<name>`) and the Trellis
+ *   agent prompts live under `.kimi-code/skills/<name>/SKILL.md`.
+ *
+ * Kimi has no project-level hooks/settings file Trellis may write and no
+ * custom sub-agent definitions (built-in coder/explore/plan only), so the
+ * Trellis agent prompts ship as skills; trellis-implement / trellis-check get
+ * the pull-based prelude, trellis-research stays standalone.
+ */
+import { type AgentTemplate } from "../template-utils.js";
+/** Trellis agent prompts (trellis-implement, trellis-check, trellis-research), installed as Kimi skills. */
+export declare function getAllAgents(): AgentTemplate[];
+//# sourceMappingURL=index.d.ts.map

package/dist/templates/kimi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/kimi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAIhF,4GAA4G;AAC5G,wBAAgB,YAAY,IAAI,aAAa,EAAE,CAE9C"}

package/dist/templates/kimi/index.js

@@ -0,0 +1,22 @@
+/**
+ * Kimi Code template module.
+ *
+ * Kimi Code is a class-2 pull-based platform:
+ * - Workflow/bundled skills go to the shared `.agents/skills/` root via the
+ *   neutral resolver (byte-identical to Codex/Gemini/Pi writes).
+ * - User-invocable entry points (`trellis-start` / `trellis-continue` /
+ *   `trellis-finish-work`, invoked as `/skill:trellis-<name>`) and the Trellis
+ *   agent prompts live under `.kimi-code/skills/<name>/SKILL.md`.
+ *
+ * Kimi has no project-level hooks/settings file Trellis may write and no
+ * custom sub-agent definitions (built-in coder/explore/plan only), so the
+ * Trellis agent prompts ship as skills; trellis-implement / trellis-check get
+ * the pull-based prelude, trellis-research stays standalone.
+ */
+import { createTemplateReader } from "../template-utils.js";
+const { listMdAgents } = createTemplateReader(import.meta.url);
+/** Trellis agent prompts (trellis-implement, trellis-check, trellis-research), installed as Kimi skills. */
+export function getAllAgents() {
+    return listMdAgents();
+}
+//# sourceMappingURL=index.js.map

package/dist/templates/kimi/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/kimi/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,oBAAoB,EAAsB,MAAM,sBAAsB,CAAC;AAEhF,MAAM,EAAE,YAAY,EAAE,GAAG,oBAAoB,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/D,4GAA4G;AAC5G,MAAM,UAAU,YAAY;IAC1B,OAAO,YAAY,EAAE,CAAC;AACxB,CAAC"}

package/dist/templates/omp/extensions/trellis/index.ts.txt

@@ -40,7 +40,7 @@ function buildContextKey(platformName: string, kind: string, value: string): str
    return safeValue ? `${platformName}_${safeValue}` : `${platformName}_${hashValue(value)}`;
 }
 
-function deriveContextKey(ctx?: { sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string } }): string | null {
+function deriveContextKey(ctx?: { sessionManager?: { getSessionId?: () => string | undefined; getSessionFile?: () => string | undefined } }): string | null {
    const sessionId = ctx?.sessionManager?.getSessionId?.();
    if (sessionId) {
       return buildContextKey("omp", "session", sessionId);
@@ -336,7 +336,7 @@ export default function(pi: ExtensionAPI): void {
    let lastCompactionTs = 0;
    let lastInjectionTs = 0;
 
-   const rememberContextKey = (ctx?: { sessionManager?: { getSessionId?: () => string; getSessionFile?: () => string } }): string | null => {
+   const rememberContextKey = (ctx?: { sessionManager?: { getSessionId?: () => string | undefined; getSessionFile?: () => string | undefined } }): string | null => {
       const key = deriveContextKey(ctx);
       if (!key) return null;
       return key;
@@ -439,24 +439,38 @@ export default function(pi: ExtensionAPI): void {
          messages: [
             ...event.messages,
             {
-               role: "custom",
+               role: "custom" as const,
                customType: "trellis-workflow-state",
                content: cached.workflowMsg,
+               display: false,
                timestamp: Date.now(),
             },
          ],
       };
    });
 
+   // OMP passes Bash event.input through to the tool execution parameters, so
+   // inject the session key through the shell-agnostic env field. An explicit
+   // per-call value wins over the derived key.
+   pi.on("tool_call", (event, ctx) => {
+      if (event.toolName !== "bash") return;
+      const contextKey = rememberContextKey(ctx);
+      if (!contextKey) return;
+      const input = event.input as { env?: Record<string, string> };
+      input.env = {
+         TRELLIS_CONTEXT_ID: contextKey,
+         ...input.env,
+      };
+   });
+
    pi.on("input", async (_event, ctx) => {
       if (!projectRoot) {
          projectRoot = findProjectRoot(ctx.cwd);
       }
       // Resolve projectRoot on first input if session_start missed it
-      if (!projectRoot) return { action: "continue" };
+      if (!projectRoot) return;
       const contextKey = rememberContextKey(ctx);
       // Pre-warm the cache so before_agent_start and context can use it
       turnCache.get(projectRoot, contextKey);
-      return { action: "continue" };
    });
 }

package/dist/templates/opencode/lib/session-utils.js

@@ -8,8 +8,14 @@ import { debugLog } from "./trellis-context.js"
 const PYTHON_CMD = platform() === "win32" ? "python" : "python3"
 
 const FIRST_REPLY_NOTICE = `<first-reply-notice>
-First visible reply: say once in Chinese that Trellis SessionStart context is loaded, then answer directly.
-This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+On the first visible assistant reply in this session, briefly acknowledge that Trellis SessionStart context loaded.
+Choose the acknowledgment language in this order:
+1. Use the language of the user's current request (the user message that triggered this reply).
+2. If that request has no clear natural language, use an explicitly established project communication language.
+3. If neither provides a language, output the language-neutral fallback exactly: \`Trellis SessionStart ✓\`.
+Continue directly with the user's request after the acknowledgment.
+The acknowledgment must not alter the language used for the remainder of the response.
+This notice is one-shot: do not repeat it after the first visible assistant reply in this session.
 </first-reply-notice>`
 
 function hasCuratedJsonlEntry(jsonlPath) {

package/dist/templates/pi/extensions/trellis/index.ts.txt

@@ -84,8 +84,14 @@ const ABORT_KILL_GRACE_MS = 1500;
 const SESSION_OVERVIEW_TIMEOUT_MS = 1500;
 const THROTTLE_MS = 500;
 const FIRST_REPLY_NOTICE = `<first-reply-notice>
-First visible reply: say once in Chinese that Trellis SessionStart context is loaded, then answer directly.
-This notice is one-shot: do not repeat it after the first assistant reply in the same session.
+On the first visible assistant reply in this session, briefly acknowledge that Trellis SessionStart context loaded.
+Choose the acknowledgment language in this order:
+1. Use the language of the user's current request (the user message that triggered this reply).
+2. If that request has no clear natural language, use an explicitly established project communication language.
+3. If neither provides a language, output the language-neutral fallback exactly: \`Trellis SessionStart ✓\`.
+Continue directly with the user's request after the acknowledgment.
+The acknowledgment must not alter the language used for the remainder of the response.
+This notice is one-shot: do not repeat it after the first visible assistant reply in this session.
 </first-reply-notice>`;
 
 // ── State types ───────────────────────────────────────────────────────

package/dist/templates/pi/settings.json

@@ -3,9 +3,6 @@
   "extensions": [
     "./extensions/trellis/index.ts"
   ],
-  "skills": [
-    "./skills"
-  ],
   "prompts": [
     "./prompts"
   ]

package/dist/templates/shared-hooks/index.d.ts

@@ -12,7 +12,7 @@ export interface HookScript {
     content: string;
 }
 export type SharedHookName = "session-start.py" | "inject-shell-session-context.py" | "inject-workflow-state.py" | "inject-subagent-context.py";
-export type SharedHookPlatform = "claude" | "cursor" | "codex" | "gemini" | "qoder" | "copilot" | "codebuddy" | "droid" | "kiro" | "trae";
+export type SharedHookPlatform = "claude" | "cursor" | "codex" | "gemini" | "qoder" | "copilot" | "codebuddy" | "droid" | "kiro" | "trae" | "zcode";
 /**
  * Which shared hooks each platform actually invokes. Single source of truth
  * for shared-hook distribution — both `writeSharedHooks` (runtime install)
@@ -25,10 +25,11 @@ export type SharedHookPlatform = "claude" | "cursor" | "codex" | "gemini" | "qod
  * - `inject-workflow-state.py` — every platform with a UserPromptSubmit
  *   (or equivalent) event. Kiro + codex self-included; platforms without
  *   per-turn main-session hooks are excluded.
- * - `inject-subagent-context.py` — class-1 (push-based) platforms only.
- *   Class-2 (pull-based) platforms (codex, copilot, gemini, qoder) can't
- *   have hooks mutate sub-agent prompts — their sub-agents load context
- *   via a prelude instead.
+ * - `inject-subagent-context.py` — platforms with native sub-agent context
+ *   delivery. Most use a PreToolUse prompt mutation; Codex uses its
+ *   SubagentStart `additionalContext` event. Class-2 (pull-based) platforms
+ *   such as copilot, gemini, qoder, and trae still load context from a
+ *   self-loading agent profile.
  * - Kiro supports per-turn + spawn hooks on both surfaces (per the official
  *   docs https://kiro.dev/docs/cli/hooks/): the CLI custom agent declares
  *   `hooks.userPromptSubmit` + `hooks.agentSpawn`, and the IDE declares a
@@ -42,6 +43,11 @@ export type SharedHookPlatform = "claude" | "cursor" | "codex" | "gemini" | "qod
  *   or opt in to the Trellis one via `trellis init --with-statusline`
  *   (installed from `templates/claude/hooks/`, not from this table — no
  *   other platform has a statusLine event).
+ * - ZCode (3.x) ships a workspace hook config at `.zcode/config.json` covering
+ *   SessionStart + UserPromptSubmit in the main session, plus PreToolUse for
+ *   `Agent|Task`. Live probing confirmed `hookSpecificOutput.updatedInput`
+ *   reaches the sub-agent prompt, so ZCode is class-1 and ships
+ *   `inject-subagent-context.py`.
  */
 export declare const SHARED_HOOKS_BY_PLATFORM: Record<SharedHookPlatform, readonly SharedHookName[]>;
 /**

package/dist/templates/shared-hooks/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/shared-hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,iCAAiC,GACjC,0BAA0B,GAC1B,4BAA4B,CAAC;AAEjC,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,GACT,WAAW,GACX,OAAO,GACP,MAAM,GACN,MAAM,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAC3C,kBAAkB,EAClB,SAAS,cAAc,EAAE,CAgC1B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,EAAE,CAWnD;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,kBAAkB,GAC3B,UAAU,EAAE,CAGd"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/shared-hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAaH,MAAM,WAAW,UAAU;IACzB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,cAAc,GACtB,kBAAkB,GAClB,iCAAiC,GACjC,0BAA0B,GAC1B,4BAA4B,CAAC;AAEjC,MAAM,MAAM,kBAAkB,GAC1B,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,QAAQ,GACR,OAAO,GACP,SAAS,GACT,WAAW,GACX,OAAO,GACP,MAAM,GACN,MAAM,GACN,OAAO,CAAC;AAEZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,eAAO,MAAM,wBAAwB,EAAE,MAAM,CAC3C,kBAAkB,EAClB,SAAS,cAAc,EAAE,CAqC1B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,UAAU,EAAE,CAWnD;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,kBAAkB,GAC3B,UAAU,EAAE,CAGd"}

package/dist/templates/shared-hooks/index.js

@@ -25,10 +25,11 @@ function readTemplate(relativePath) {
  * - `inject-workflow-state.py` — every platform with a UserPromptSubmit
  *   (or equivalent) event. Kiro + codex self-included; platforms without
  *   per-turn main-session hooks are excluded.
- * - `inject-subagent-context.py` — class-1 (push-based) platforms only.
- *   Class-2 (pull-based) platforms (codex, copilot, gemini, qoder) can't
- *   have hooks mutate sub-agent prompts — their sub-agents load context
- *   via a prelude instead.
+ * - `inject-subagent-context.py` — platforms with native sub-agent context
+ *   delivery. Most use a PreToolUse prompt mutation; Codex uses its
+ *   SubagentStart `additionalContext` event. Class-2 (pull-based) platforms
+ *   such as copilot, gemini, qoder, and trae still load context from a
+ *   self-loading agent profile.
  * - Kiro supports per-turn + spawn hooks on both surfaces (per the official
  *   docs https://kiro.dev/docs/cli/hooks/): the CLI custom agent declares
  *   `hooks.userPromptSubmit` + `hooks.agentSpawn`, and the IDE declares a
@@ -42,6 +43,11 @@ function readTemplate(relativePath) {
  *   or opt in to the Trellis one via `trellis init --with-statusline`
  *   (installed from `templates/claude/hooks/`, not from this table — no
  *   other platform has a statusLine event).
+ * - ZCode (3.x) ships a workspace hook config at `.zcode/config.json` covering
+ *   SessionStart + UserPromptSubmit in the main session, plus PreToolUse for
+ *   `Agent|Task`. Live probing confirmed `hookSpecificOutput.updatedInput`
+ *   reaches the sub-agent prompt, so ZCode is class-1 and ships
+ *   `inject-subagent-context.py`.
  */
 export const SHARED_HOOKS_BY_PLATFORM = {
     claude: [
@@ -54,7 +60,7 @@ export const SHARED_HOOKS_BY_PLATFORM = {
         "inject-shell-session-context.py",
         "inject-subagent-context.py",
     ],
-    codex: ["inject-workflow-state.py"],
+    codex: ["inject-workflow-state.py", "inject-subagent-context.py"],
     gemini: ["session-start.py", "inject-workflow-state.py"],
     qoder: ["session-start.py", "inject-workflow-state.py"],
     copilot: ["inject-workflow-state.py"],
@@ -74,6 +80,11 @@ export const SHARED_HOOKS_BY_PLATFORM = {
         "inject-subagent-context.py",
     ],
     trae: ["session-start.py", "inject-workflow-state.py"],
+    zcode: [
+        "session-start.py",
+        "inject-workflow-state.py",
+        "inject-subagent-context.py",
+    ],
 };
 /**
  * Get all shared hook scripts. Content is platform-independent and can be

package/dist/templates/shared-hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/shared-hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AA2BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAGjC;IACF,MAAM,EAAE;QACN,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,MAAM,EAAE;QACN,kBAAkB;QAClB,iCAAiC;QACjC,4BAA4B;KAC7B;IACD,KAAK,EAAE,CAAC,0BAA0B,CAAC;IACnC,MAAM,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACxD,KAAK,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACvD,OAAO,EAAE,CAAC,0BAA0B,CAAC;IACrC,SAAS,EAAE;QACT,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,KAAK,EAAE;QACL,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,IAAI,EAAE;QACJ,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,IAAI,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;CACvD,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC;SACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SAChC,IAAI,EAAE,CAAC;IAEV,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAC7C,QAA4B;IAE5B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpE,OAAO,oBAAoB,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACnE,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/shared-hooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;AAEtC,SAAS,YAAY,CAAC,YAAoB;IACxC,OAAO,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,YAAY,CAAC,EAAE,OAAO,CAAC,CAAC;AAC9D,CAAC;AA4BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAGjC;IACF,MAAM,EAAE;QACN,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,MAAM,EAAE;QACN,kBAAkB;QAClB,iCAAiC;QACjC,4BAA4B;KAC7B;IACD,KAAK,EAAE,CAAC,0BAA0B,EAAE,4BAA4B,CAAC;IACjE,MAAM,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACxD,KAAK,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACvD,OAAO,EAAE,CAAC,0BAA0B,CAAC;IACrC,SAAS,EAAE;QACT,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,KAAK,EAAE;QACL,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,IAAI,EAAE;QACJ,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;KAC7B;IACD,IAAI,EAAE,CAAC,kBAAkB,EAAE,0BAA0B,CAAC;IACtD,KAAK,EAAE;QACL,kBAAkB;QAClB,0BAA0B;QAC1B,4BAA4B;KAC7B;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,oBAAoB;IAClC,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC;SACjC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;SAChC,IAAI,EAAE,CAAC;IAEV,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,+BAA+B,CAC7C,QAA4B;IAE5B,MAAM,OAAO,GAAG,IAAI,GAAG,CAAS,wBAAwB,CAAC,QAAQ,CAAC,CAAC,CAAC;IACpE,OAAO,oBAAoB,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AACnE,CAAC"}

package/dist/templates/shared-hooks/inject-subagent-context.py

@@ -80,9 +80,12 @@ def find_repo_root(start_path: str) -> str | None:
 
 
 def _detect_platform(input_data: dict) -> str | None:
+    if _hook_event_name(input_data) == "SubagentStart":
+        return "codex"
     if isinstance(input_data.get("cursor_version"), str):
         return "cursor"
     env_map = {
+        "ZCODE_PROJECT_DIR": "zcode",
         "CLAUDE_PROJECT_DIR": "claude",
         "CURSOR_PROJECT_DIR": "cursor",
         "CODEBUDDY_PROJECT_DIR": "codebuddy",
@@ -110,10 +113,20 @@ def _detect_platform(input_data: dict) -> str | None:
         return "droid"
     if ".kiro" in script_parts:
         return "kiro"
+    if ".zcode" in script_parts:
+        return "zcode"
     return None
 
 
-def get_current_task(repo_root: str, input_data: dict) -> str | None:
+def get_current_task(
+    repo_root: str,
+    input_data: dict,
+    *,
+    platform: str | None = None,
+    allow_single_session_fallback: bool = True,
+    allow_environment_context: bool = True,
+    require_existing: bool = False,
+) -> str | None:
     """Resolve current task directory through the unified active task resolver."""
     scripts_dir = Path(repo_root) / DIR_WORKFLOW / "scripts"
     if str(scripts_dir) not in sys.path:
@@ -126,8 +139,12 @@ def get_current_task(repo_root: str, input_data: dict) -> str | None:
     active = resolve_active_task(
         Path(repo_root),
         input_data,
-        platform=_detect_platform(input_data),
+        platform=platform or _detect_platform(input_data),
+        allow_single_session_fallback=allow_single_session_fallback,
+        allow_environment_context=allow_environment_context,
     )
+    if require_existing and active.stale:
+        return None
     return active.task_path
 
 
@@ -574,6 +591,98 @@ def _string_value(value: Any) -> str:
     return ""
 
 
+def _hook_event_name(input_data: dict) -> str:
+    """Return a hook event name from the documented snake/camel-case fields."""
+    return _string_value(
+        input_data.get("hook_event_name") or input_data.get("hookEventName")
+    )
+
+
+def _codex_subagent_type(input_data: dict) -> str:
+    """Return a Trellis Codex agent type only for a native start event."""
+    if _hook_event_name(input_data) != "SubagentStart":
+        return ""
+    agent_type = _string_value(
+        input_data.get("agent_type") or input_data.get("agentType")
+    )
+    return agent_type if agent_type in AGENTS_ALL else ""
+
+
+def build_codex_subagent_context(
+    subagent_type: str,
+    task_dir: str,
+    context: str,
+) -> str:
+    """Build developer context for a native, already-dispatched Codex role."""
+    role = subagent_type.removeprefix("trellis-")
+    return f"""<!-- trellis-hook-injected -->
+# Trellis Native {role.title()} Subagent
+
+You are the dispatched `{subagent_type}` role for this task. Perform that role
+directly; do not follow main-session dispatch or wait instructions, and do not
+spawn another Trellis subagent.
+
+Active task: {task_dir}
+
+## Curated Context
+
+{context}"""
+
+
+def _handle_codex_subagent_start(input_data: dict) -> None:
+    """Emit Codex developer context for a recognised native Trellis subagent.
+
+    The event supplies the parent session id. Disabling the generic
+    single-session fallback is essential here: native starts must never borrow
+    a task from another Codex window when that parent id is absent or stale.
+    """
+    subagent_type = _codex_subagent_type(input_data)
+    parent_session_id = _string_value(input_data.get("session_id"))
+    if not subagent_type or not parent_session_id:
+        return
+
+    cwd = _string_value(input_data.get("cwd")) or os.getcwd()
+    repo_root = find_repo_root(cwd)
+    if not repo_root:
+        return
+
+    task_dir = get_current_task(
+        repo_root,
+        {"session_id": parent_session_id},
+        platform="codex",
+        allow_single_session_fallback=False,
+        allow_environment_context=False,
+        require_existing=True,
+    )
+    if not task_dir:
+        return
+
+    if subagent_type in AGENTS_REQUIRE_TASK:
+        task_dir_full = Path(repo_root) / task_dir
+        if not task_dir_full.is_dir():
+            return
+
+    if subagent_type == AGENT_IMPLEMENT:
+        context = get_implement_context(repo_root, task_dir)
+    elif subagent_type == AGENT_CHECK:
+        context = get_check_context(repo_root, task_dir)
+    else:
+        context = get_research_context(repo_root, task_dir)
+
+    if not context:
+        return
+
+    output = {
+        "hookSpecificOutput": {
+            "hookEventName": "SubagentStart",
+            "additionalContext": build_codex_subagent_context(
+                subagent_type, task_dir, context
+            ),
+        }
+    }
+    print(json.dumps(output, ensure_ascii=False))
+
+
 def _extract_subagent_name(value: Any) -> str:
     """Extract a sub-agent name from common platform encodings.
 
@@ -652,10 +761,15 @@ def _parse_hook_input(input_data: dict) -> tuple[str, str, dict]:
     - Claude Code / Qoder / CodeBuddy / Droid: tool_name=Task|Agent, tool_input.subagent_type
     - Cursor: tool_name=Task|Subagent, tool_input.subagent_type
     - Copilot CLI: toolName=task (camelCase key, lowercase value)
+    - ZCode: toolName=Agent, toolInput/tool_input.subagent_type
     - Gemini CLI: tool_name IS the agent name (BeforeTool matcher already filtered)
     - Kiro: agentSpawn hook, agent_name field at top level
     """
     tool_input = input_data.get("tool_input", {})
+    if not isinstance(tool_input, dict):
+        tool_input = input_data.get("toolInput", {})
+    if not isinstance(tool_input, dict):
+        tool_input = {}
 
     # Standard format: Task/Agent tool with subagent_type
     tool_name = input_data.get("tool_name", "") or input_data.get("toolName", "")
@@ -692,6 +806,17 @@ def main():
         input_data = json.load(sys.stdin)
     except json.JSONDecodeError:
         sys.exit(0)
+    if not isinstance(input_data, dict):
+        sys.exit(0)
+
+    if _hook_event_name(input_data) == "SubagentStart":
+        try:
+            _handle_codex_subagent_start(input_data)
+        except Exception:
+            # A native context hook must never prevent Codex from spawning the
+            # requested child when its runtime state is unavailable or stale.
+            pass
+        sys.exit(0)
 
     subagent_type, original_prompt, tool_input = _parse_hook_input(input_data)
     cwd = input_data.get("cwd", os.getcwd())
@@ -745,23 +870,32 @@ def main():
     if not context:
         sys.exit(0)
 
-    # Return updated input — use a multi-format output that covers all platforms.
-    # Most platforms ignore unrecognized fields, so we include multiple formats.
-    # The platform picks whichever fields it understands.
+    # Return updated input. Most platforms ignore unrecognized fields, so we
+    # include multiple formats. ZCode is stricter; live probing confirmed the
+    # nested Claude-compatible shape below reaches the sub-agent prompt.
     updated = {**tool_input, "prompt": new_prompt}
-    output = {
-        # Claude Code / Qoder / CodeBuddy / Droid format
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "allow",
+    if _detect_platform(input_data) == "zcode":
+        output = {
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
+                "updatedInput": updated,
+            }
+        }
+    else:
+        output = {
+            # Claude Code / Qoder / CodeBuddy / Droid format
+            "hookSpecificOutput": {
+                "hookEventName": "PreToolUse",
+                "permissionDecision": "allow",
+                "updatedInput": updated,
+            },
+            # Cursor format
+            "permission": "allow",
+            "updated_input": updated,
+            # Gemini format
             "updatedInput": updated,
-        },
-        # Cursor format
-        "permission": "allow",
-        "updated_input": updated,
-        # Gemini format
-        "updatedInput": updated,
-    }
+        }
 
     print(json.dumps(output, ensure_ascii=False))
     sys.exit(0)