# TaskStop

依 runtime handle 停止一個執行中的背景任務——shell 指令、已派發的代理或遠端工作階段。用它來回收資源、取消已無用處的工作，或在任務卡住時恢復。

## 使用時機

- 一條背景 shell 指令執行得比預期久，且你不再需要其結果。
- 本地代理陷入迴圈或停擺，必須及時中止。
- 使用者改變方向，之前方向的背景工作應放棄。
- 遠端工作階段即將逾時或正佔用你需要的資源。
- 在重新啟動同一項任務之前，你需要一個乾淨的起點。

讓短命的背景工作自行結束比較好。`TaskStop` 是留給「繼續執行毫無價值或實際造成傷害」的情況。

## 參數

- `task_id`（string，必填）：背景任務啟動時回傳的 runtime handle。與 `TaskOutput` 接受的是同一個識別碼，而非任務清單的 `taskId`。

## 範例

### 範例 1

停止失控的背景 shell 指令。

```
TaskStop(task_id: "bash_01HXYZ...")
```

該指令會收到終止訊號；至此緩衝的輸出仍可在其輸出路徑讀取。

### 範例 2

使用者改變方向後取消已派發的代理。

```
TaskStop(task_id: "agent_01ABCD...")
```

## 注意事項

- `TaskStop` 要求終止；它不保證即時關閉。守規矩的任務會迅速退出，但正在做阻塞 I/O 的程序可能需要一小段時間才會結束。
- 停止任務不會刪除其輸出。對於背景 shell 任務，磁碟上的輸出檔會保留並仍可用 `Read` 讀取。對於代理與工作階段，在停止前擷取到的輸出仍可透過 `TaskOutput` 取得。
- 未知的 `task_id`，或已經結束的任務，會傳回錯誤或為 no-op。這是安全的——你可以在不事先檢查狀態的情況下保險地呼叫 `TaskStop`。
- 若你打算重啟同一件工作，請先停掉舊任務再派發新任務，以避免兩個平行執行在共享資源（檔案、通訊埠、資料庫列）上競爭。
- `TaskStop` 不會影響團隊任務清單中的條目。要取消已追蹤的任務，請用 `TaskUpdate` 將其狀態更新為 `deleted`。
