Expose notebook cell ids in reads

Author: SqlRush

docs/claude-code-go-rewrite-plan.md

@@ -170,7 +170,7 @@ test/parity/                 # golden tests against TS/official behavior
 
 当前进度：
 
-- Read/Edit/Write 初版已落地，覆盖文本 Read、PDF text/page-selection 初版（含常见 Page/Contents 间接对象、Pages/Kids 页序、FlateDecode 文本流和 UTF-16 BOM 字符串）、PNG/JPEG/GIF/WebP image Read、Jupyter notebook cell 渲染初版、Read 大文本 tool-result budget 截断/落盘、read-before-write、mtime stale guard、唯一匹配、`replace_all`、Write/Edit structured diff hunks、`.claude/settings.json`/`settings.local.json` 写前 JSON/语义校验、team-memory secret guard、Read 去重和跨 tool round read-state。
+- Read/Edit/Write 初版已落地，覆盖文本 Read、PDF text/page-selection 初版（含常见 Page/Contents 间接对象、Pages/Kids 页序、FlateDecode 文本流和 UTF-16 BOM 字符串）、PNG/JPEG/GIF/WebP image Read、Jupyter notebook cell 渲染初版（含真实 cell id 和 `cell-N` fallback 的可见/结构化输出）、Read 大文本 tool-result budget 截断/落盘、read-before-write、mtime stale guard、唯一匹配、`replace_all`、Write/Edit structured diff hunks、`.claude/settings.json`/`settings.local.json` 写前 JSON/语义校验、team-memory secret guard、Read 去重和跨 tool round read-state。
 - NotebookEdit 初版已落地，按官方 `notebook_path`/`cell_id`/`new_source`/`cell_type`/`edit_mode` schema 支持 replace/insert/delete 主路径、真实 cell id 和 `cell-N` 索引、code cell 修改后清空 outputs/execution_count、read-before-edit/stale guard、read-state 刷新、`notebook_path` 权限路径识别、结构化结果和 cell-level diff/hunks；完整 notebook UI/file-history/golden parity 仍需继续补。
 - Bash 初版已落地，覆盖 command/timeout/description 输入校验、`/bin/sh -c` 执行、stdout/stderr/exit code/timeout 结构化结果、动态 read-only/concurrency-safe/destructive 分类、Git diff/log/show/status/ls-files/grep/rev-parse/branch/tag/ls-remote safe-flag 校验，Git remote/push/reflog/stash/worktree/merge-base/describe/cat-file/for-each-ref/rev-list/blame/shortlog/config-get 参数级安全分类、`git remote show/get-url` 参数收紧、`git ls-remote` URL/SSH/server-option guard、branch/tag 裸 positional 创建防护、`git reflog expire/delete`、`git stash drop/pop/clear` 和 `git worktree remove/prune` 破坏性分类、`find -delete/-exec rm` 与 `xargs rm` 破坏性分类、safe wrapper/env 前缀归一化（`time`/`nohup`/`timeout`/`nice`/`stdbuf`/`env`）后的只读/破坏性分类、临时环境赋值前缀后的破坏性命令识别、权限规则接入、后台启动、同会话 `BashOutput` 输出读取和 `KillBash` 取消；完整 shell parser、真实 sandbox、interrupt、后台任务完整生命周期和官方 golden 仍需继续补。
 - Glob/Grep 纯 Go 初版已落地，覆盖 `**` 递归 glob、Glob 绝对 pattern base-dir 提取、Glob 官方 pattern/path-only strict schema、Glob/Grep 输出工作目录相对路径、Glob 默认 no-ignore/hidden 搜索及 `CLAUDE_CODE_GLOB_NO_IGNORE`/`CLAUDE_CODE_GLOB_HIDDEN` env 切换、Grep 官方 VCS metadata 目录排除（`.git`/`.svn`/`.hg`/`.bzr`/`.jj`/`.sl`）、Grep 层级 `.gitignore`/`.ignore`/`.rgignore`、Grep `hidden`/`--hidden` 和 `no_hidden`/`--no-hidden` 隐藏文件遍历控制、Glob oldest-first modified/path 排序、Glob 截断 tool-result 提示、Grep regex/fixed string (`fixed_strings`/`-F`)、multiline 跨行 dotall 搜索、glob/iglob/type/type-not 过滤、Grep glob 空白/逗号多 pattern 与 brace alternation、Glob/Grep path 存在性校验和 Glob directory-only path 校验、`output_mode`/`outputMode` 的 `files`/`files_with_matches`/`content`/`count` 输出模式、Grep files/--files 不读内容列出将被搜索文件、Grep files_with_matches file-count summary、Grep count-mode occurrence/file summary、Grep `--max-columns 500` 长匹配/上下文行省略占位、`context`/`before_context`/`after_context` 及 `-C`/`-B`/`-A` 上下文行和官方 precedence（非 content 模式忽略）、`line_numbers`/`lineNumbers`/`-n` line-number 控制、`byte_offset`/`--byte-offset`/`-b`、`path_separator`/`--path-separator`、`null`/`--null`/`-0`、`field_match_separator`/`--field-match-separator`、`field_context_separator`/`--field-context-separator`、`context_separator`/`--context-separator` 和 `no_context_separator`/`--no-context-separator` 输出分隔符控制、`max_count`/`maxCount`/`-m` per-file match limiting、`offset`/`head_limit` 分页和 content-mode pagination tool-result 提示、默认 250 条 Grep head limit、`head_limit=0` unlimited、`ignore_case`/`case_insensitive`/`caseInsensitive`/`-i` 大小写不敏感搜索，以及 Grep 数字/布尔参数的 quoted semantic string 兼容；完整 ripgrep parity 和剩余输出参数仍需继续补。

docs/first-second-parity-audit.md

@@ -206,7 +206,7 @@ Covered behavior:
 - `Bash` `find` read-only classification now rejects deleting or file-writing actions such as `-delete`, `-fprint`, `-fprint0`, `-fprintf`, and `-fls`, avoiding commands that mutate files being auto-allowed as read-only.
 - `Bash` safety classification now excludes `find -exec*` forms from read-only auto-allow and detects destructive commands passed through `find -exec*`/`xargs`, including shell `-c` scripts and safe-wrapper/env/assignment forms such as `env rm`, `timeout rm`, and `xargs -I{} env sh -c ...`.
 - `PowerShell` native/external file-reading/search read-only classification now applies relative-path guards to `where.exe /R`, `file`, `tree`, and `findstr` path positionals and path-valued flags, rejecting Windows-drive, UNC, URI/provider-like, parent-directory, and missing path-flag values before read-only auto-allow; `where.exe` no longer uses allow-all flag acceptance.
-- `Read` line-number formatting, offset/limit slicing, mtime-based same-range dedup, text/binary/device guards, initial PDF text extraction with page-selection parsing, common Page/Contents indirect-object mapping, Pages/Kids page-order recovery, FlateDecode text streams, UTF-16 BOM PDF string decoding, PNG/JPEG/GIF/WebP image content-block reads, Jupyter notebook cell rendering, large text tool-result truncation/persistence, and read-state recording.
+- `Read` line-number formatting, offset/limit slicing, mtime-based same-range dedup, text/binary/device guards, initial PDF text extraction with page-selection parsing, common Page/Contents indirect-object mapping, Pages/Kids page-order recovery, FlateDecode text streams, UTF-16 BOM PDF string decoding, PNG/JPEG/GIF/WebP image content-block reads, Jupyter notebook cell rendering with visible/structured `cell_id` values for real IDs and `cell-N` fallbacks, large text tool-result truncation/persistence, and read-state recording.
 - `Write` create/update behavior, read-before-write validation for existing files, mtime stale detection, `.claude/settings.json` and `settings.local.json` JSON/semantic validation before writes, structured diff hunks, and post-write read-state refresh.
 - `Edit` exact replacement, nonexistent-file creation with empty `old_string`, unique-match enforcement, `replace_all`, quote-style preservation for curly quotes, CRLF preservation, `.claude/settings.json` and `settings.local.json` final-content validation before writes, structured diff hunks, and post-edit read-state refresh.
 - `NotebookEdit` initial notebook mutation behavior, including official input field names, replace/insert/delete modes, real cell IDs and `cell-N` fallback indexes, code-cell output/execution reset on replace, read-before-edit/stale guards, read-state refresh, `notebook_path` permission path extraction, structured result payloads, and cell-level diff/hunks.

internal/tools/file/tools.go

@@ -397,6 +397,7 @@ type notebookDocument struct {
 }
 
 type notebookCell struct {
+	ID             string           `json:"id"`
 	CellType       string           `json:"cell_type"`
 	Source         any              `json:"source"`
 	Outputs        []notebookOutput `json:"outputs"`
@@ -456,7 +457,13 @@ func renderNotebook(displayPath string, doc notebookDocument) (string, []map[str
 		}
 		source := strings.TrimRight(notebookText(cell.Source), "\n")
 		outputs := notebookOutputTexts(cell.Outputs)
-		fmt.Fprintf(&b, "\n\nCell %d [%s]", i+1, cellType)
+		cellID := strings.TrimSpace(cell.ID)
+		fallbackCellID := fmt.Sprintf("cell-%d", i)
+		displayCellID := cellID
+		if displayCellID == "" {
+			displayCellID = fallbackCellID
+		}
+		fmt.Fprintf(&b, "\n\nCell %d [%s] cell_id=%s", i+1, cellType, displayCellID)
 		if cell.ExecutionCount != nil && cellType == "code" {
 			fmt.Fprintf(&b, " execution_count=%v", cell.ExecutionCount)
 		}
@@ -472,11 +479,14 @@ func renderNotebook(displayPath string, doc notebookDocument) (string, []map[str
 			}
 		}
 		cells = append(cells, map[string]any{
-			"index":           i + 1,
-			"cell_type":       cellType,
-			"source":          source,
-			"outputs":         outputs,
-			"execution_count": cell.ExecutionCount,
+			"index":            i + 1,
+			"cell_id":          displayCellID,
+			"id":               cellID,
+			"fallback_cell_id": fallbackCellID,
+			"cell_type":        cellType,
+			"source":           source,
+			"outputs":          outputs,
+			"execution_count":  cell.ExecutionCount,
 		})
 	}
 	return b.String(), cells

internal/tools/file/tools_test.go

@@ -389,7 +389,7 @@ func TestReadToolRendersNotebookCells(t *testing.T) {
 	dir := t.TempDir()
 	raw := `{
   "cells": [
-    {"cell_type": "markdown", "source": ["# Title\n", "body"]},
+    {"cell_type": "markdown", "id": "intro", "source": ["# Title\n", "body"]},
     {"cell_type": "code", "execution_count": 1, "source": "print('hi')\n", "outputs": [{"output_type": "stream", "name": "stdout", "text": ["hi\n"]}]}
   ],
   "metadata": {},
@@ -410,7 +410,7 @@ func TestReadToolRendersNotebookCells(t *testing.T) {
 		t.Fatal(err)
 	}
 	content := result.Content.(string)
-	for _, want := range []string{"Notebook: analysis.ipynb", "Cell 1 [markdown]:\n# Title\nbody", "Cell 2 [code] execution_count=1:\nprint('hi')", "Outputs:\nhi"} {
+	for _, want := range []string{"Notebook: analysis.ipynb", "Cell 1 [markdown] cell_id=intro:\n# Title\nbody", "Cell 2 [code] cell_id=cell-1 execution_count=1:\nprint('hi')", "Outputs:\nhi"} {
 		if !strings.Contains(content, want) {
 			t.Fatalf("notebook content missing %q:\n%s", want, content)
 		}
@@ -420,6 +420,10 @@ func TestReadToolRendersNotebookCells(t *testing.T) {
 	if len(cells) != 2 || cells[0]["cell_type"] != "markdown" || cells[1]["cell_type"] != "code" {
 		t.Fatalf("structured notebook cells = %#v", cells)
 	}
+	if cells[0]["cell_id"] != "intro" || cells[0]["id"] != "intro" || cells[0]["fallback_cell_id"] != "cell-0" ||
+		cells[1]["cell_id"] != "cell-1" || cells[1]["id"] != "" || cells[1]["fallback_cell_id"] != "cell-1" {
+		t.Fatalf("structured notebook cell ids = %#v", cells)
+	}
 	record, ok := EnsureReadState(ctx).Get(path)
 	if !ok || !strings.Contains(record.Content, `"nbformat": 4`) || record.PartialView {
 		t.Fatalf("notebook read state = %#v ok=%v", record, ok)