Theo dõi Cursor: agent hook, payload và trình quan sát đơn giản

Cách tôi dùng agent hook của Cursor để quan sát prompt, phần suy nghĩ, lời gọi công cụ, lần thực thi MCP, chỉnh sửa tệp và subagent mà không thay đổi hành vi của agent.

Ngày 23 tháng 8 năm 2026 · 15 phút đọc · Christophe Nasarre

Trong bài viết trước về MCP server và skill, tôi đã trình bày cách giúp một AI coding agent dùng đúng các công cụ chẩn đoán trong quy trình điều tra bộ nhớ và luồng. Khi những công cụ này đã hoạt động trong Cursor, Claude Code và Copilot, một câu hỏi nhanh chóng xuất hiện: các agent có thật sự dùng chúng theo cách tôi mong đợi không?

Cụ thể:

  • Agent có nạp skill đúng lúc không?
  • Nó gọi công cụ MCP nào, với tham số và kết quả nào?
  • Công việc có được giao cho subagent không?
  • Toàn bộ thao tác tiêu tốn bao nhiêu thời gian và dung lượng ngữ cảnh?

Nằm giữa prompt của tôi và model là một agent harness; trong trường hợp này là Cursor IDE hoặc Cursor CLI. Cursor chuẩn bị ngữ cảnh, yêu cầu quyền, khởi chạy subagent, thu gọn hội thoại và hiển thị câu trả lời do model tạo ra. Vì muốn hiểu rõ hơn điều gì đang diễn ra, tôi đã hỏi chính Cursor cách theo dõi hoạt động của Cursor. Dùng AI để hiểu AI rõ hơn.

May mắn là tôi không cần dịch ngược Cursor hay chặn lưu lượng mạng. Cursor cung cấp cơ chế hook được hỗ trợ chính thức tại một số ranh giới đáng chú ý của vòng lặp agent. Bài viết này không đề cập đến kịch bản cloud agent.

<

Đây là phần đầu của một loạt bài:

  1. Theo dõi Cursor: agent hook, payload và trình quan sát đơn giản
  2. Khôi phục hội thoại của Agent: session, turn, thought, tool, MCP, skill và summary
  3. Theo dõi Claude Code: nhiều sự kiện vòng đời hơn, nhưng có các điểm mù khác
  4. Theo dõi GitHub Copilot hai lần: hook của CLI và VS Code
  5. Vượt ra ngoài hook: bổ sung log transcript cho session đang chạy
  6. SessionViewer và Cursor: khôi phục lịch sử từ JSONL, SQLite và plan

Hai mươi mốt cửa sổ nhìn vào Cursor

Hook là một chương trình do Cursor khởi chạy khi một sự kiện cụ thể xảy ra. Cursor ghi một đối tượng JSON vào standard input của chương trình và đọc phản hồi JSON từ standard output.

Tại thời điểm viết bài, tài liệu hook của Cursor liệt kê 21 sự kiện:

  • Session và vòng lặp model: sessionStart, sessionEnd, beforeSubmitPrompt, afterAgentThought, afterAgentResponse, preCompact, stop.
  • Công cụ: preToolUse, postToolUse, postToolUseFailure, beforeShellExecution, afterShellExecution, beforeMCPExecution, afterMCPExecution, beforeReadFile, afterFileEdit.
  • Subagent: subagentStart, subagentStop.
  • Editor và workspace: beforeTabFileRead, afterTabFileEdit, workspaceOpen.

Nhóm đầu mô tả vòng đời của hội thoại và các turn. Một turn là khoảng thời gian từ lúc nhập prompt đến khi nhận được câu trả lời. Nhóm thứ hai cho biết Cursor thực thi gì thay mặt model. Nhóm thứ ba cho thấy việc giao nhiệm vụ cho agent khác. Nhóm cuối tách các lần hoàn thành inline bằng Tab và hoạt động workspace diễn ra trong vòng lặp agent.

Điểm phân biệt quan trọng là hook không quan sát “AI” như một thao tác nguyên khối. Nó nhận thông báo về các sự kiện của harness diễn ra xung quanh model.

Đăng ký trình theo dõi

Hook có thể được đăng ký cho một project trong .cursor/hooks.json, hoặc cho user hiện tại trong ~/.cursor/hooks.json trên Linux hay C:\Users\<current user>\.cursor\hooks.json trên Windows.

Một cấu hình tối giản có thể trỏ các sự kiện cần theo dõi đến cùng một chương trình:

{ "version": 1, "hooks": { "sessionStart": [{ "command": "C:\\dev\\CursorSpy.Hook.exe", "timeout": 2 }], "beforeSubmitPrompt": [{ "command": "C:\\dev\\CursorSpy.Hook.exe", "timeout": 2 }], "preToolUse": [{ "command": "C:\\dev\\CursorSpy.Hook.exe", "timeout": 2 }] } }

Tôi tạo file c:\dev\research\AI\HarnessSpy\.cursor\hooks.json ở cấp project khi xây dựng và kiểm thử proof of concept. Nhờ vậy, chỉ các prompt phục vụ nghiên cứu trong thư mục này được theo dõi, thay vì toàn bộ session AI trên máy.

Trường command trỏ đến cùng một executable cho cả 21 sự kiện. Mỗi lần hook được kích hoạt, Cursor khởi chạy một process ngắn hạn mới. Trong bản thử nghiệm, tôi dùng đường dẫn đầy đủ đến ứng dụng console C# ở thư mục Debug. Với cách dùng thực tế hơn, script hoặc ứng dụng hook có thể được đặt trong thư mục hooks. Trường matcher cho phép lọc thời điểm gọi hook; trong trường hợp này tôi muốn nhận mọi sự kiện.

Để tìm nguyên nhân payload JSON rỗng và xác định hook nào bị lỗi, tôi bổ sung tham số dòng lệnh --hook <hook name> và tăng timeout lên 5 giây.

Tài liệu cũng đề cập loại hook prompt, trong đó một LLM nhỏ đánh giá cần làm gì khi hook được kích hoạt. Chẳng hạn:

{ "hooks": { "beforeShellExecution": [{ "type": "prompt", "prompt": "Does this command look safe to execute? Only allow read-only operations.", "timeout": 10 }] } }

Tôi phải thừa nhận rằng mình chưa thử loại hook này.

Đừng để trình quan sát làm hỏng đối tượng được quan sát

Hook không chỉ dùng để quan sát. Nó có thể từ chối lời gọi công cụ, viết lại input, thêm ngữ cảnh hoặc tự động gửi prompt tiếp theo. Một command hook kết thúc với mã 2 sẽ chặn hành động. Tùy sự kiện, hook còn có thể cho phép hoặc từ chối, thay đổi input/output hay chèn thêm ngữ cảnh.

Quyền năng đó hữu ích cho việc thực thi chính sách, nhưng trái ngược với mục tiêu của tôi. Lỗi của hệ thống giám sát tuyệt đối không được chặn công việc thật trong Cursor hoặc thay đổi quyết định của agent.

Ứng dụng console C# của hook mở standard input dưới dạng UTF-8, bật nhận diện BOM, đọc toàn bộ payload rồi lưu bản gốc trước khi phân tích và chuyển tiếp. Mọi ngoại lệ đều được bắt và ghi vào file cursorspy-hook-errors.log. Cuối cùng, chương trình luôn ghi chính xác {} vào standard output và kết thúc với mã 0.

Cách làm này ẩn chứa ba quy tắc:

  1. Lưu trước: payload gốc được lưu trước khi parse và chuyển tiếp, nên vẫn có bằng chứng rằng hook đã chạy.
  2. Bắt mọi lỗi: lỗi phân tích, lưu trữ, pipe hoặc chẩn đoán không được phép lan ra ngoài.
  3. Luôn trả về phản hồi vô tác dụng: standard output là giao thức hook, không phải luồng log.

Điểm cuối rất quan trọng. Nếu vô tình in thông tin chẩn đoán vào standard output, trình quan sát có thể biến thành một chỉ thị cho Cursor. Vì vậy lỗi được ghi riêng và ngay cả thao tác ghi log cũng mang tính best-effort.

Đây là hợp đồng an toàn thụ động của tôi: trình theo dõi ghi lại những gì có thể, nhưng không bao giờ trả về permission, continue, updated_input, additional_context hay trường nào có thể ảnh hưởng đến harness.

Thoát khỏi process chỉ tồn tại vài mili giây

Process hook phải kết thúc nhanh để không làm Cursor bị chặn. Vì muốn theo dõi session trực tiếp, tôi xây dựng một ứng dụng WPF để hiển thị các hook đã kích hoạt và payload tương ứng.

Các file do ứng dụng console lưu được dùng để phát lại session cũ. Để theo dõi session đang chạy, tôi dùng named pipe cục bộ: ứng dụng WPF mở và lắng nghe pipe, còn ứng dụng console gửi payload hook qua đó.

Named pipe có tên HarnessSpy.Ingest.v1, timeout kết nối là 150 mili giây. Nếu viewer đang chạy, nó nhận một envelope được phân tách bằng newline. Nếu viewer không chạy, kết nối bị hủy sau 150 mili giây và hook vẫn thành công.

Phía WPF tạo named pipe với PipeOptions.CurrentUserOnly, chấp nhận nhiều client ngắn hạn đồng thời và chuyển từng observation hợp lệ về UI thread.

Envelope chỉ bổ sung metadata thu thập bên ngoài payload nguyên bản:

{ "ingressVersion": 1, "eventId": "...", "observedAtUtc": "2026-08-23T08:42:11.765Z", "sourceFilePath": "C:\\...\\Payloads\\hp_...json", "payload": { "hook_event_name": "beforeSubmitPrompt", "conversation_id": "...", "generation_id": "...", "prompt": "Can you investigate this memory leak?" } }

Giữ nguyên payload gốc là chủ ý. Schema của hook có thể thay đổi; nếu chỉ làm phẳng các trường mà tôi hiểu hôm nay, tôi sẽ âm thầm làm mất thông tin của ngày mai.

Bắt đầu với các trường dùng chung

Mỗi agent hook nhận một nhóm trường chung bên cạnh payload riêng của sự kiện:

  • conversation_id: định danh ổn định của hội thoại qua nhiều prompt.
  • generation_id: định danh của lần sinh hiện tại; thay đổi với mỗi message của user và là khóa tự nhiên của một turn.
  • hook_event_name: tên hook được kích hoạt.
  • model, model_id: model được chọn, gồm tên và định danh có cấu trúc nếu có.
  • model_params: một số tham số như thinking, kích thước context hoặc effort.
  • cursor_version: phiên bản Cursor tạo payload.
  • workspace_roots: một hoặc nhiều thư mục workspace.
  • user_email: user đã xác thực nếu có.
  • transcript_path: đường dẫn đến transcript chính của hội thoại.

workspaceOpen chạy bên ngoài agent session nên không có trường conversation, generation hoặc model. sessionStart còn thêm session_id, được Cursor mô tả là cùng định danh với conversation_id.

Hai ID đầu là chìa khóa để khôi phục hội thoại: conversation_id nhóm một session, còn generation_id nhóm mọi sự kiện do một prompt tạo ra.

model_params hữu ích nhưng không nên bị nhầm với request hoàn chỉnh gửi đến model. Nó chỉ cho biết một số điều khiển được chọn như thinking, context hoặc effort, chứ không cung cấp system prompt đã ghép hay toàn bộ context. Theo tài liệu, trường này còn không bắt buộc và trong các lần thử tôi chưa từng thấy nó xuất hiện.

Prompt, phản hồi và áp lực context

Các hook của session và vòng lặp model cho thấy hội thoại tiến triển như thế nào:

  • workspaceOpen: cho biết workspace và instance Cursor đã hoạt động.
  • sessionStart: cho biết session tương tác hay chạy nền và mode ban đầu như agent hoặc ask.
  • beforeSubmitPrompt: chứa nội dung user nhập và các file hoặc rule đính kèm.
  • afterAgentThought: chứa text Cursor hiển thị trong “Thought for xxx s”, thường xuất hiện trước các lời gọi công cụ.
  • afterAgentResponse: chứa phản hồi hoàn tất của model cùng input_tokens, output_tokens, cache_read_tokens và cache_write_tokens.
  • preCompact: cho biết khi nào và vì sao Cursor sắp tóm tắt context gần đầy, cùng các trường như context_usage_percent, context_tokens, context_window_size và message_count.
  • stop: cho biết turn hoàn tất, thất bại hay bị hủy; loop_count luôn bằng 0 trong các thử nghiệm của tôi.
  • sessionEnd: cho biết lý do, thời lượng, trạng thái cuối và thông báo lỗi khi toàn bộ hội thoại kết thúc.

beforeSubmitPrompt đặc biệt thú vị vì nó được kích hoạt cùng prompt của user. Payload có thể gồm prompt, attachments, conversation_id, generation_id, model, composer_mode, session_id, cursor_version, workspace_roots, user_email và transcript_path.

Tôi không nhận được attachment nào, kể cả khi chủ động dùng tham chiếu @filename hoặc kéo file từ Explorer. Tài liệu Cursor cho biết attachment có thể có loại file hoặc rule, cùng trường file_path. Rule là các file .mdc cung cấp chỉ thị cấp system cho Agent, có thể đóng gói prompt, script và nhiều thành phần khác.

Theo hiểu biết của tôi, afterAgentThought được kích hoạt sau khi Cursor nhận phản hồi đầu tiên từ model về prompt. Nó hữu ích để hiểu mạch suy luận được hiển thị, nhưng đây là một khối tổng hợp do harness chọn và render, không nên xem là bản sao đầy đủ của chain-of-thought riêng tư của model.

Các lời gọi công cụ thường xuất hiện trước afterAgentResponse. Hook này chứa câu trả lời cuối cùng cùng các số liệu token. Hook stop được kích hoạt khi user hủy prompt hoặc khi model trả lời thành công.

Những công cụ nào được gọi?

Mỗi lời gọi công cụ kích hoạt preToolUse. Trường tool_name cho biết tên công cụ, còn tham số nằm trong tool_input. Một số công cụ như Grep được Cursor triển khai tự nhiên.

Các công cụ đọc và ghi còn kích hoạt beforeReadFile và afterFileEdit với trường chung file_path. Hook đọc cung cấp nội dung đã đọc trong trường content, dù tên sự kiện có tiền tố before. Với afterFileEdit, trường edits chứa danh sách old_string và new_string, thuận tiện để dựng diff.

Với hành động tổng quát hơn, hook beforeShellExecution nhận các trường command, cwd và sandbox. Hook afterShellExecution bổ sung output đầy đủ và duration.

Lời gọi công cụ từ MCP server được nhận diện trong preToolUse.tool_name theo quy ước MCP:<tool name>, chẳng hạn MCP:get_duplicated_strings. Sau đó beforeMCPExecution cung cấp thêm tool_name, tool_input, mcp_server_name và command hoặc URL của server. afterMCPExecution được kích hoạt cùng kết quả công cụ.

Một điểm dễ mắc lỗi là tool_output, tool_input của MCP và result_json đôi khi là JSON được mã hóa thành chuỗi bên trong payload JSON bên ngoài. Viewer phải parse thêm lớp JSON thứ hai; nếu không, đường dẫn Windows sẽ có dấu gạch chéo kép và các trường hữu ích bị giấu trong một chuỗi dài.

Subagent không phải lời gọi công cụ thông thường

Subagent có vòng đời riêng:

  • subagentStart: subagent_id, subagent_type, task, parent_conversation_id, tool_call_id, subagent_model, is_parallel_worker và git_branch.
  • subagentStop: status, summary, duration_ms, message_count, tool_call_count, modified_files và agent_transcript_path.

Thông tin này phong phú hơn một sự kiện “Task tool được gọi”, chủ yếu vì trường task chứa prompt dùng cho tác vụ. Ta biết model nào chạy tác vụ, nó có phải worker song song hay không, đã tồn tại bao lâu, dùng bao nhiêu công cụ và sửa những file nào.

Tuy nhiên, tôi không tìm được quan hệ trực tiếp giữa các session có vẻ liên quan đến subtask thông qua tool_call_id hoặc subagent_id và session cha. Tệ hơn nữa, dường như không có hook sessionStart cho các session liên quan đến task.

Còn thiếu gì?

Payload hook chứa nhiều thông tin hơn tôi dự kiến, nhưng không phải tất cả:

  • model_params chỉ được cho là chứa một số thiết lập, không phải system prompt hoàn chỉnh hay request đã ghép gửi đến model; trong thử nghiệm, tôi còn chưa thấy trường này.
  • afterAgentThought là khối suy nghĩ tổng hợp do harness cung cấp, không được đảm bảo là chain-of-thought thô.
  • Cursor không có hook riêng cho câu hỏi agent đặt ra với user và câu trả lời của user.
  • Hook before... có thể đưa ra quyết định quyền, nhưng trình theo dõi thụ động này không thấy toàn bộ trao đổi trong giao diện phê duyệt. Một lỗi permission_denied về sau chỉ là bằng chứng gián tiếp.

Cảnh báo cuối: payload rất nhạy cảm

JSON được thu thập có thể chứa:

  • Prompt của user và phản hồi của model.
  • Nội dung source file và các chỉnh sửa.
  • Command shell cùng toàn bộ output.
  • Tham số và kết quả MCP.
  • Đường dẫn workspace, địa chỉ email và đường dẫn transcript.
  • Thông báo lỗi vô tình chứa secret.

Named pipe được giới hạn cho user hiện tại, nhưng bản proof of concept lưu file JSON dạng plaintext có thể đọc được. Không nên công khai thư mục Payloads làm dữ liệu kiểm thử nếu chưa xem xét và loại bỏ thông tin nhạy cảm. Hãy xóa capture khi không còn cần thiết.

Kết luận

Cursor hook có thể là cơ chế observability hữu ích vì ba lý do:

  1. Chúng bao phủ các ranh giới quan trọng của harness: prompt, output của model, tool, MCP, file, subagent và việc thu gọn context.
  2. Các định danh ổn định như conversation_id, generation_id, tool_use_id và subagent_id cung cấp dữ liệu nền để khôi phục quan hệ nhân quả.
  3. Một hook được thiết kế thụ động có thể quan sát các sự kiện mà không trở thành một phần trong hành vi hoặc đường dẫn lỗi của agent.

Đến đây, tôi đã có một dòng payload JSON an toàn và một viewer nhận được chúng. Thách thức tiếp theo thú vị hơn: biến dòng dữ liệu phẳng thành hội thoại, turn, lời gọi công cụ lồng nhau hoặc chạy song song, việc sử dụng skill và một bản tóm tắt hữu ích.

Tài liệu tham khảo