# v0.20.0 Release Notes

> v0.19.9 -> v0.20.0

## Summary

Session lifecycle adds a friendly-name layer plus three routing prefixes: subagent name dispatch, `:<name>` one-shot CLI prefix, and skill-arg pass-through. Runtime gains a UID/PID singleton with per-session state tracking. go-utils upgraded to v0.9.4.

<details>
<summary>翻譯</summary>
Session 生命週期加入友善名稱層與三條路由：subagent name 分派、`:<name>` CLI one-shot 前綴、skill 前綴 args 透傳。Runtime 新增 UID／PID singleton 與 per-session 狀態軌跡。go-utils 升級至 v0.9.4。
</details>

## Changes

### FEAT

- Add `:<name>` session override prefix and skill-arg pass-through routing (@pardnchiu) [1565f3f]
- Add name dispatch for invoke_subagent and prefix-aware ask_user gate (@pardnchiu) [fb20bab]
- Add CLI session config, new, and switch commands keyed off bot.md name (@pardnchiu) [61529e0]
- Add per-session bot.md persona, idempotent SaveBot, and default_session_prompt embed (@pardnchiu) [d5e1b89]

<details>
<summary>翻譯</summary>

- `internal/session/match.go` 新增 `session.Match(input) (name, effective)` 解析 `:bot ship v0.20` 前綴；`exec.Run` 最外層先解析（早於 `MatchExternal`／`MatchSkillCall`），命中時 `GetSessionIDByName` 解析 sid 後寫入 `ExecData.SessionID`、effective 文字往下派；`getSession.go` 偵測 `SessionID != ""` 走 override 早期分支（`IsDir` 驗證 → 載入 history／summary／system prompt → 寫 user message／DBSessionHist），**不**讀寫 `filesystem.ConfigPath` 保留全域 cli 指標。Composable：`:bot /commit-generate v0.20` 順序為 session resolve → skill match。範圍 CLI／TUI only（HTTP 已有 body `session_id`、Discord 走 `dc-` per-channel）。前綴選擇 `:`：`@` 撞 agent 檔案 reference 慣例、`$` 是 shell metachar 雙引號內被展開，`:` 不是 shell metachar、無 agent 慣例
- Skill 前綴路由（`MatchSkillCall`）對 `/skill-name <args>` 回傳 args tail 作為 user message（無 args 時 fallback 為完整 trimmed）；`skill_execution.md` 新增 Mandatory Principle #5「The user message carrying this skill activation is binding context, not noise」與 Execution Flow step 2 (capture user input) ／step 5 (visibly reflect user context)，強制 LLM 把使用者文字編進 skill 輸出（version target／scope hint／tone 等），SKILL.md 描述 default behavior，使用者文字 override／augment default
- `invoke_subagent` 新增 `name` 參數（透過 `session.GetSessionIDByName` 掃 `cli-*`／`http-*` 的 bot.md frontmatter 解析為 sid，未命中即 error），優先級高於 `session_id`；`ask_user` handler 入口加 `cli-*` prefix gate，非 `cli-` session 回傳格式化引導訊息要求 LLM 改以回覆文字向使用者問問題；`system_prompt.md` 新增「轉派具名 helper」forced-routing entry 涵蓋「呼叫 X 來 Y」「請 X 處理 Y」等中英自然語句；`http-` session 從 `CleanupSessions` 白名單移除（語意對齊 persist=true → 永久保留）
- `agen new [name]` 建立 `cli-` session 並切換主指標（衝突檢查走 frontmatter `name` 字面相等）；`agen switch <name>` 依 name 切換主指標；`agen config` 開啟 `$EDITOR` 編輯當前 CLI session 的 `bot.md`；makefile 對應加入 `make new`／`make switch`／`make config` targets
- 每個 session 在建立目錄時冪等寫入 `bot.md`（YAML frontmatter `name`，預設等於 sessionID；body 為 `configs/prompts/default_session_prompt.md` embed），`SaveBot(sessionID, name, force)` 控制是否覆寫；system prompt 新增 `{{.BotPersona}}` 佔位於最頂端（`exec.GetSystemPrompt` 末參新增 `sessionID` 用於補建與讀取）；`internal/session/bot.go` 提供 `SaveBot`／`GetBot`／`GetSessionIDByName` 共用 helper

</details>

### UPDATE

- Upgrade go-utils to v0.9.4 and refine tool event logging (@pardnchiu) [6029f43]

<details>
<summary>翻譯</summary>

- 升級 `github.com/pardnchiu/go-utils` 至 v0.9.4；`internal/session/actionLog.go` 與 `internal/agents/exec/execute.go` 的 tool event 寫入時序與訊息收斂；`fetchPage` 與 `runEvents` 同步調整以對齊新版 utils API

</details>

### ADD

- Add runtime singleton control, per-session status.json, and rotating action.log (@pardnchiu) [d0d645a]

<details>
<summary>翻譯</summary>

- `internal/runtime`：新增 `runtime.uid` singleton 控制檔（`{uid, pid, started_at}`），`runApp` 啟動時 SIGTERM(5s) → SIGKILL 取代既有 server process；CLI／run 路徑只讀不寫；新增 `IsAlive`／`IsCurrent` PID liveness check；`internal/session/status.go`：新增 `status.json`（`state` + `active []Task` + `ended_at`），`Online(sid, input)` 回傳 task UUID 並 push、`Idle(sid, taskID)` 移除指定 task、空 active 即降為 idle，外部 reader 可 `GET /v1/session/:id/status`；`internal/session/actionLog.go`：新增 `action.log` append-only 軌跡（`AppendActionUserInput`／`Record`，1MB rotate 至 768KB headroom，按 `\n` 對齊），`GET /v1/session/:id/log` SSE 串流尾端 100 行；`runApp` 啟動清理串聯 `runtime.Init` → `CleanupSessions`（`temp-*` 1h idle）→ `ClearAllActive`；CLI／run 路徑進場以 `runtime.IsCurrent()` 判斷是否清理該 session 的 stale active 任務

</details>

## Scope

- `cmd/app/` — FEAT (`runConfig.go`／`runNew.go`／`runSwitch.go`／`main.go`)
- `configs/` — FEAT (`prompts/default_session_prompt.md`／`prompts/system_prompt.md`／`prompts/skill_execution.md`／`configs.go`)
- `internal/session/` — FEAT, ADD (`bot.go`／`match.go`／`status.go`／`actionLog.go`／`session.go`)
- `internal/runtime/` — ADD (`runtime.go`)
- `internal/agents/exec/` — FEAT (`execWithSubagent.go`／`getSession.go`／`execute.go`／`run.go`)
- `internal/skill/` — FEAT (`scanner.go`)
- `internal/tools/` — FEAT (`askUser.go`／`agent/subagent/invokeSubagent.go`)
- `internal/discord/` — FEAT (`session.go`)
- `internal/routes/handler/` — ADD (`send.go`)
- `go.mod`／`go.sum` — UPDATE (go-utils v0.9.4)
- `makefile` — FEAT (new/switch/config targets)

***

Generated by [SKILL](https://github.com/pardnchiu/skill-version-generate)