> ## Documentation Index > Fetch the complete documentation index at: https://docs.trytrellis.app/llms.txt > Use this file to discover all available pages before exploring further. # v0.5.0-beta.15 > 2026-04-27 Beta.15 updates task runtime state, platform session identity propagation, Pi Agent integration, and beta documentation. It also keeps the shared-hook cleanup manifest entries from the pending beta.15 release. ## Behavior Changes ### Session-scoped active task runtime Active task state now uses a per-session runtime file: ```text theme={null} .trellis/.runtime/sessions/.json ``` `.trellis/.current-task` is no longer used as the active-task fallback. | Command | Behavior | | -------------------------- | ---------------------------------------------------------------------------- | | `task.py start ` | Writes the current task into the resolved session file | | `task.py current --source` | Reads the current task from the resolved session file | | `task.py finish` | Deletes the resolved session file | | `task.py archive ` | Deletes session files that still point at the archived task before moving it | Session file shape: ```json theme={null} { "platform": "session", "last_seen_at": "2026-04-27T01:43:24Z", "current_task": ".trellis/tasks/04-21-session-scoped-task-state", "current_run": null } ``` `task.py start` exits with code `1` when no session identity is available: ```text theme={null} 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` still creates bootstrap and joiner task directories, but it no longer writes `.trellis/.current-task`. The generated PRDs now tell the AI to start the task from a session that exposes Trellis session identity. ### Workflow task-creation policy `workflow.md` and hook fallback breadcrumbs now use a softer task-creation policy. | Area | Previous behavior | beta.15 behavior | | ---------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `no_task` trigger words | Treat matching words as requiring task creation | Treat matching words as task-creation signals | | Simple turns | No explicit exemption | Task not required when all three hold: zero file writes, one-reply answer, no research beyond reading 1-2 repo files | | User opt-out | Not documented in the hook prompt | Current-turn phrases such as `skip trellis`, `no task`, `just do it`, `跳过 trellis`, `别走流程`, `先别建任务` skip task creation for that turn | | `in_progress` implementation | Main session was told not to edit code | Sub-agent dispatch remains the default; explicit current-turn requests such as `do it inline`, `main session 写就行`, `不用 sub-agent` allow main-session implementation | ## Platform Integration ### Shell session identity handling Several hosts expose session identity differently. beta.15 adds host-specific handling for `task.py start/current/finish`. | Platform | Change | | ----------- | ------------------------------------------------------------------------------------------------------------------------- | | Claude Code | `session-start.py` writes `TRELLIS_CONTEXT_ID` through `CLAUDE_ENV_FILE` | | Codex | `task.py` resolves native command env such as `CODEX_SESSION_ID` and Codex Desktop `CODEX_THREAD_ID` | | Cursor | `beforeShellExecution` writes short-lived `.trellis/.runtime/cursor-shell/*.json` tickets for matching `task.py` commands | | OpenCode | Bash tool commands are prefixed with `TRELLIS_CONTEXT_ID` | | Pi | Bash tool calls and nested `pi --mode json` sub-agent runs receive `TRELLIS_CONTEXT_ID` | Other platforms use the same `.trellis/.runtime/sessions/` storage, but beta.15 does not add new shell-command handling for them. | Platform group | beta.15 status | | ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | GitHub Copilot | The platform-specific SessionStart hook resolves session identity for context injection. `task.py` can use exported `COPILOT_*` session env vars when the host provides them; otherwise use `TRELLIS_CONTEXT_ID` for manual shell starts. | | Gemini CLI, Qoder, CodeBuddy, Droid, Kiro | Shared hooks resolve session identity from hook input or platform env vars. No new shell-command bridge was added in beta.15. Manual shell starts still use `TRELLIS_CONTEXT_ID` when the host does not export a session id. | | Kilo, Antigravity, Windsurf | No hook integration. Use their workflow/command files plus explicit `TRELLIS_CONTEXT_ID` when running `task.py start` manually. | | `.agents/skills` consumers | No Trellis-managed hook layer. They use the `.trellis/` core and whatever prelude or env injection the host provides. | ### Cursor sub-agent hook matching Cursor `hooks.json` now matches both tool names: ```json theme={null} { "matcher": "Task|Subagent" } ``` `inject-subagent-context.py` also parses Cursor custom-agent payloads in these shapes: ```json theme={null} { "custom": { "name": "trellis-implement" } } ``` ```json theme={null} { "type": { "case": "custom", "value": { "name": "trellis-implement" } } } ``` ### Pi Agent session runtime Pi Agent now reads active task state from `.trellis/.runtime/sessions/`. Context key sources, in priority order: | Source | Example | | ------------------ | ------------------------------------ | | Explicit env | `TRELLIS_CONTEXT_ID` | | Pi session manager | `sessionManager.getSessionId()` | | Pi env | `PI_SESSION_ID`, `PI_SESSIONID` | | Transcript path | `transcript_path` / `transcriptPath` | | Process fallback | `pi_process_` | Nested Pi sub-agent runs receive the same `TRELLIS_CONTEXT_ID`. ### Workflow-state override copy `workflow-state` breadcrumbs now use exact Trellis agent names: ```text theme={null} trellis-implement trellis-check trellis-research ``` The breadcrumbs also document explicit per-turn override phrases for skipping task creation or allowing main-session implementation. ## Bug Fixes ### OpenCode sub-agent name normalization OpenCode now: * recognizes `OPENCODE_RUN_ID` as session identity * strips the `trellis-` prefix before matching sub-agent names * keeps `implement.jsonl` / `check.jsonl` injection working with renamed agents ### Git-backed private registries Template registry downloads now support private Git-backed registries. When a registry source requires local Git credentials, Trellis uses Git to read `index.json` and copy template directories instead of relying on anonymous raw HTTP. This applies to self-hosted GitLab / GitHub Enterprise sources and SSH registry URLs. Registry errors are classified separately for authentication failures, missing refs, missing paths, invalid `index.json`, and network failures, so `trellis init --registry` no longer misclassifies those cases as direct-download mode. ### Shared-hook cleanup `writeSharedHooks` and `collectSharedHooks` now use the same platform capability table: ```text theme={null} SHARED_HOOKS_BY_PLATFORM ``` Claude Code statusLine is no longer installed by default for new projects. New installs do not write `.claude/hooks/statusline.py` or configure `statusLine` in `.claude/settings.json`. Existing projects keep their installed Claude Code statusLine behavior: `trellis update` preserves `.claude/hooks/statusline.py` and carries an existing `.claude/settings.json` `statusLine` entry forward into the updated settings file. The manifest includes 10 hash-verified `safe-file-delete` entries for hooks that were written to projects but are now orphaned. | Removed path | Reason | | -------------------------------------- | --------------------------------------- | | `.cursor/hooks/statusline.py` | Cursor has no `statusLine` event | | `.codex/hooks/statusline.py` | Codex has no `statusLine` event | | `.gemini/hooks/statusline.py` | Gemini has no `statusLine` event | | `.qoder/hooks/statusline.py` | Qoder has no `statusLine` event | | `.github/copilot/hooks/statusline.py` | Copilot has no `statusLine` event | | `.codebuddy/hooks/statusline.py` | CodeBuddy has no `statusLine` event | | `.factory/hooks/statusline.py` | Factory Droid has no `statusLine` event | | `.kiro/hooks/statusline.py` | Kiro has no `statusLine` event | | `.kiro/hooks/session-start.py` | Kiro exposes only `agentSpawn` | | `.kiro/hooks/inject-workflow-state.py` | Kiro exposes only `agentSpawn` | Modified local files are preserved with a warning. ## Docs ### Beta task docs Updated beta docs now describe: * current task state under `.trellis/.runtime/sessions/.json` * session-scoped task ownership instead of a global project pointer * `continue` / `finish-work` as the primary user-facing task commands * `task.py start` as a session-bound operation * Cursor, Codex, Claude Code, OpenCode, and Pi hook/sub-agent behavior ### Multi-agent docs The beta multi-agent docs now describe native Git worktrees plus Trellis tasks. Removed references to Trellis-managed `/trellis:parallel` and `worktree.yaml`. ## Upgrade Existing projects: ```bash theme={null} trellis update ``` No `--migrate` gate is required for beta.15. Existing task directories and jsonl files remain valid. Existing `.trellis/.current-task` files are preserved but ignored by the new active-task resolver. Manual shell usage requires an explicit context id: ```bash theme={null} TRELLIS_CONTEXT_ID=my-session python3 .trellis/scripts/task.py start .trellis/tasks/ ``` Fresh install: ```bash theme={null} npm i -g @mindfoldhq/trellis@0.5.0-beta.15 ```