v0.5.0-beta.15

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:

.trellis/.runtime/sessions/<session-key>.json

.trellis/.current-task is no longer used as the active-task fallback.

Command	Behavior
`task.py start <task>`	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 <task>`	Deletes session files that still point at the archived task before moving it

Session file shape:

{
  "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:

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:

{
  "matcher": "Task|Subagent"
}

inject-subagent-context.py also parses Cursor custom-agent payloads in these shapes:

{ "custom": { "name": "trellis-implement" } }

{ "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_<hash>`

Nested Pi sub-agent runs receive the same TRELLIS_CONTEXT_ID.

Workflow-state override copy

workflow-state breadcrumbs now use exact Trellis agent names:

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:

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/<session-key>.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:

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:

TRELLIS_CONTEXT_ID=my-session python3 .trellis/scripts/task.py start .trellis/tasks/<task>

Fresh install:

npm i -g @mindfoldhq/[email protected]

Start Here

Advanced

Use Cases

Resource Marketplace

Community

Behavior Changes

Session-scoped active task runtime

Bootstrap and joiner tasks

Workflow task-creation policy

Platform Integration

Shell session identity handling

Cursor sub-agent hook matching

Pi Agent session runtime

Workflow-state override copy

Bug Fixes

OpenCode sub-agent name normalization

Git-backed private registries

Shared-hook cleanup

Docs

Beta task docs

Multi-agent docs

Upgrade

​Behavior Changes

​Session-scoped active task runtime

​Bootstrap and joiner tasks

​Workflow task-creation policy

​Platform Integration

​Shell session identity handling

​Cursor sub-agent hook matching

​Pi Agent session runtime

​Workflow-state override copy

​Bug Fixes

​OpenCode sub-agent name normalization

​Git-backed private registries

​Shared-hook cleanup

​Docs

​Beta task docs

​Multi-agent docs

​Upgrade

Behavior Changes

Session-scoped active task runtime

Bootstrap and joiner tasks

Workflow task-creation policy

Platform Integration

Shell session identity handling

Cursor sub-agent hook matching

Pi Agent session runtime

Workflow-state override copy

Bug Fixes

OpenCode sub-agent name normalization

Git-backed private registries

Shared-hook cleanup

Docs

Beta task docs

Multi-agent docs

Upgrade