跳转到主要内容
beta.15 更新 task runtime state、平台 session identity 传递、Pi Agent 集成和 beta 文档。该版本也保留 beta.15 待发布 manifest 中的 shared-hook 清理项。

​
Behavior Changes

​
Session-scoped active task runtime

active task state 改为写入每个 session 自己的 runtime 文件： 
.trellis/.runtime/sessions/<session-key>.json
.trellis/.current-task 不再作为 active task fallback。
命令行为
task.py start <task>把当前 task 写入解析到的 session 文件
task.py current --source从解析到的 session 文件读取当前 task
task.py finish删除解析到的 session 文件
task.py archive <task>移动 task 前，删除仍指向该 task 的 session 文件
session 文件结构： 
{
  "platform": "session",
  "last_seen_at": "2026-04-27T01:43:24Z",
  "current_task": ".trellis/tasks/04-21-session-scoped-task-state",
  "current_run": null
}
没有 session identity 时，task.py start 以 exit code 1 退出： 
Error: Cannot set active task without a session identity.
Hint: run inside an AI IDE/session that exposes session identity, or set TRELLIS_CONTEXT_ID before running task.py start.

​
Bootstrap and joiner tasks

trellis init 仍会创建 bootstrap 和 joiner task 目录，但不再写 .trellis/.current-task。 生成的 PRD 会说明：AI 应在能提供 Trellis session identity 的 session 中启动该 task。

​
Workflow task-creation policy

workflow.md 和 hook fallback breadcrumb 放宽了 task 创建策略。
范围之前行为beta.15 行为
no_task 触发词命中触发词就要求创建 task命中触发词表示建议创建 task
简单任务没有明确豁免同时满足三项时不要求创建 task：本轮不写文件、一次回复能完成、无需超过读取 1-2 个 repo 文件的研究
用户显式跳过hook prompt 未说明当前轮出现 skip trellis、no task、just do it、跳过 trellis、别走流程、先别建任务 等短语时，本轮跳过 task 创建
in_progress 实现main session 被要求不要直接改代码默认仍派 trellis-implement / trellis-check；当前轮明确出现 do it inline、main session 写就行、不用 sub-agent 等短语时，允许 main session 直接实现

​
Platform Integration

​
Shell session identity handling

不同宿主暴露 session identity 的方式不一样。beta.15 为 task.py start/current/finish 增加宿主侧处理。
平台变更
Claude Codesession-start.py 通过 CLAUDE_ENV_FILE 写入 TRELLIS_CONTEXT_ID
Codextask.py 直接识别 Codex 命令环境里的 CODEX_SESSION_ID 和 Codex Desktop 的 CODEX_THREAD_ID
CursorbeforeShellExecution 为匹配的 task.py 命令写入短生命周期 .trellis/.runtime/cursor-shell/*.json ticket
OpenCodeBash tool command 前置 TRELLIS_CONTEXT_ID
PiBash tool call 和嵌套 pi --mode json sub-agent run 接收 TRELLIS_CONTEXT_ID
其他平台同样使用 .trellis/.runtime/sessions/ 存储 active task state，但 beta.15 没有为它们新增 shell-command 处理。
平台组beta.15 状态
GitHub Copilot平台专用 SessionStart hook 会为上下文注入解析 session identity。宿主导出 COPILOT_* session env 时，task.py 可以直接使用；否则手动 shell start 仍需显式 TRELLIS_CONTEXT_ID。
Gemini CLI、Qoder、CodeBuddy、Droid、Kiroshared hook 从 hook input 或平台 env 解析 session identity。beta.15 没有新增 shell-command bridge；宿主不导出 session id 时，手动 shell start 仍使用 TRELLIS_CONTEXT_ID。
Kilo、Antigravity、Windsurf没有 hook 集成。使用各自 workflow/command 文件；手动运行 task.py start 时显式传入 TRELLIS_CONTEXT_ID。
.agents/skills consumers没有 Trellis 管理的 hook 层。使用 .trellis/ core 和宿主自己的 prelude/env 注入能力。

​
Cursor sub-agent hook matching

Cursor hooks.json 现在同时匹配两个 tool name： 
{
  "matcher": "Task|Subagent"
}
inject-subagent-context.py 也能解析 Cursor custom-agent payload： 
{ "custom": { "name": "trellis-implement" } }

{ "type": { "case": "custom", "value": { "name": "trellis-implement" } } }

​
Pi Agent session runtime

Pi Agent 现在从 .trellis/.runtime/sessions/ 读取 active task state。 context key 来源优先级：
来源示例
显式 envTRELLIS_CONTEXT_ID
Pi session managersessionManager.getSessionId()
Pi envPI_SESSION_ID, PI_SESSIONID
Transcript pathtranscript_path / transcriptPath
Process fallbackpi_process_<hash>
嵌套 Pi sub-agent run 会接收同一个 TRELLIS_CONTEXT_ID。

​
Workflow-state override copy

workflow-state breadcrumb 现在使用准确的 Trellis agent 名称： 
trellis-implement
trellis-check
trellis-research
breadcrumb 也记录了每轮生效的显式 override 短语，用于跳过 task 创建或允许 main session 直接实现。

​
Bug Fixes

​
OpenCode sub-agent name normalization

OpenCode 现在：
  • 识别 OPENCODE_RUN_ID 作为 session identity
  • 匹配 sub-agent 名称前去掉 trellis- 前缀
  • 保持重命名 agent 的 implement.jsonl / check.jsonl 注入可用

​
Git-backed private registries

Template registry 下载现在支持私有 Git-backed registry。registry source 需要本机 Git 凭证时，Trellis 会通过 Git 读取 index.json 并复制 template 目录，不再依赖匿名 raw HTTP。 这覆盖 self-hosted GitLab / GitHub Enterprise source 和 SSH registry URL。registry 错误会区分 authentication failure、missing ref、missing path、invalid index.json 和 network failure，trellis init --registry 不再把这些情况误判成 direct-download mode。

​
Shared-hook cleanup

writeSharedHooks 和 collectSharedHooks 现在使用同一张平台能力表： 
SHARED_HOOKS_BY_PLATFORM
Claude Code statusLine 默认不再安装。新项目不会写 .claude/hooks/statusline.py，也不会在 .claude/settings.json 里配置 statusLine。 manifest 包含 11 条 hash-verified safe-file-delete entry，用于清理曾写入项目但现在已经孤立或默认禁用的 hook。
删除路径原因
.claude/hooks/statusline.pyClaude Code statusLine 默认禁用
.cursor/hooks/statusline.pyCursor 没有 statusLine event
.codex/hooks/statusline.pyCodex 没有 statusLine event
.gemini/hooks/statusline.pyGemini 没有 statusLine event
.qoder/hooks/statusline.pyQoder 没有 statusLine event
.github/copilot/hooks/statusline.pyCopilot 没有 statusLine event
.codebuddy/hooks/statusline.pyCodeBuddy 没有 statusLine event
.factory/hooks/statusline.pyFactory Droid 没有 statusLine event
.kiro/hooks/statusline.pyKiro 没有 statusLine event
.kiro/hooks/session-start.pyKiro 只暴露 agentSpawn
.kiro/hooks/inject-workflow-state.pyKiro 只暴露 agentSpawn
本地修改过的文件会保留，并在 update 输出中提示。

​
Docs

​
Beta task docs

beta 文档现在描述：
  • current task state 位于 .trellis/.runtime/sessions/<session-key>.json
  • task 归属按 session 计算，不再使用全局项目指针
  • continue / finish-work 是主要用户命令
  • task.py start 是 session-bound operation
  • Cursor、Codex、Claude Code、OpenCode、Pi 的 hook/sub-agent 行为

​
Multi-agent docs

beta multi-agent 文档改为描述原生 Git worktree 加 Trellis task。移除 Trellis 托管 /trellis:parallel 和 worktree.yaml 相关说明。

​
Upgrade

已有项目： 
trellis update
beta.15 不需要 --migrate gate。 已有 task 目录和 jsonl 文件保持有效。已有 .trellis/.current-task 文件会保留，但新的 active-task resolver 会忽略它。 手动 shell 使用需要显式 context id： 
TRELLIS_CONTEXT_ID=my-session python3 .trellis/scripts/task.py start .trellis/tasks/<task>
全新安装： 
npm i -g @mindfoldhq/[email protected]