cocheck 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/README.md +17 -3
  2. package/dist/agent-transcripts.js +15 -12
  3. package/dist/attribution/evidence.js +2 -1
  4. package/dist/attribution/reconstruct.js +19 -0
  5. package/dist/attribution/tag.js +3 -3
  6. package/dist/build-info.json +1 -1
  7. package/dist/cli.js +31 -11
  8. package/dist/connector/export-view.js +1 -1
  9. package/dist/coverage.js +5 -3
  10. package/dist/credit-guard.js +59 -54
  11. package/dist/harness-cmd/create.js +76 -0
  12. package/dist/harness-cmd/index.js +19 -0
  13. package/dist/harness-cmd/record.js +327 -0
  14. package/dist/harness-cmd/scrub.js +25 -0
  15. package/dist/harness-cmd/test.js +318 -0
  16. package/dist/harnesses/README.md +5 -0
  17. package/dist/harnesses/claude/cocheck-harness.json +344 -0
  18. package/dist/harnesses/codex/cocheck-harness.json +212 -0
  19. package/dist/harnesses/copilot/cocheck-harness.json +296 -0
  20. package/dist/{copilot-helpers.js → helper-linker.js} +43 -32
  21. package/dist/hook-adapter.js +287 -63
  22. package/dist/hook-cli.js +73 -36
  23. package/dist/hook-journal.js +40 -12
  24. package/dist/hosts/claude.js +23 -159
  25. package/dist/hosts/codex.js +41 -81
  26. package/dist/hosts/compile.js +275 -0
  27. package/dist/hosts/copilot.js +7 -162
  28. package/dist/hosts/extras.js +55 -0
  29. package/dist/hosts/harnesses.js +66 -0
  30. package/dist/hosts/index.js +176 -8
  31. package/dist/hosts/install-block.js +332 -0
  32. package/dist/hosts/manifest.js +372 -0
  33. package/dist/hosts/shared.js +21 -0
  34. package/dist/hosts/tool-classes.js +6 -0
  35. package/dist/hosts/types.js +1 -0
  36. package/dist/install.js +69 -22
  37. package/dist/ledger.js +11 -0
  38. package/dist/normalize.js +33 -9
  39. package/dist/open-pick.js +5 -3
  40. package/dist/patch-secrets.js +11 -11
  41. package/dist/review-server.js +2 -2
  42. package/dist/timeline/attribution.js +2 -2
  43. package/dist/timeline/describe.js +20 -17
  44. package/dist/timeline/load.js +2 -2
  45. package/dist/timeline/rail/assets/review.js +1 -1
  46. package/dist/timeline/rail/model.js +8 -8
  47. package/dist/timeline/read-signal.js +4 -4
  48. package/dist/timeline/render/view-v1.js +2 -13
  49. package/dist/timeline/runs.js +9 -9
  50. package/dist/timeline/timeline.js +8 -8
  51. package/dist/timeline/write-signal.js +4 -3
  52. package/package.json +2 -2
  53. package/public-kit/harness/GUIDE.md +81 -0
  54. package/public-kit/harness/README.md +10 -0
  55. package/public-kit/harness/cases/claude/shell-writes-file.json +120 -0
  56. package/public-kit/harness/cases/codex/apply-patch-writes-files.json +177 -0
  57. package/public-kit/harness/cases/codex/helper-writes-file.json +160 -0
  58. package/public-kit/harness/cases/codex/shell-writes-and-fails.json +110 -0
  59. package/public-kit/harness/cases/copilot/camel-case-patch-and-failure.json +126 -0
  60. package/public-kit/harness/cases/copilot/helper-writes-file.json +209 -0
  61. package/public-kit/harness/cases/copilot/vscode-helper-writes-file.json +236 -0
  62. package/public-kit/harness/examples/toyagent/cases/write-notes.json +142 -0
  63. package/public-kit/harness/examples/toyagent/cocheck-harness.json +47 -0
  64. package/public-kit/harness/examples/toyagent/recordings/payloads.jsonl +8 -0
  65. package/public-kit/harness/harnesses/antigravity/README.md +32 -0
  66. package/public-kit/harness/harnesses/antigravity/cases/failed-edit.json +99 -0
  67. package/public-kit/harness/harnesses/antigravity/cases/helper-writes-file.json +270 -0
  68. package/public-kit/harness/harnesses/antigravity/cases/shell-ok-fail-and-denied.json +211 -0
  69. package/public-kit/harness/harnesses/antigravity/cases/write-then-edit.json +191 -0
  70. package/public-kit/harness/harnesses/antigravity/cocheck-harness.json +62 -0
  71. package/public-kit/harness/harnesses/antigravity/recordings/payloads.jsonl +63 -0
  72. package/public-kit/harness/harnesses/cursor/README.md +40 -0
  73. package/public-kit/harness/harnesses/cursor/cases/editor-write-edit-shell-helper.json +359 -0
  74. package/public-kit/harness/harnesses/cursor/cases/read-then-write-one-call-id.json +159 -0
  75. package/public-kit/harness/harnesses/cursor/cocheck-harness.json +67 -0
  76. package/public-kit/harness/harnesses/cursor/recordings/payloads.jsonl +28 -0
  77. package/public-kit/harness/scaffold/README.md +42 -0
  78. package/public-kit/harness/scaffold/cocheck-harness.json +72 -0
  79. package/public-kit/harness/scaffold/recordings/.gitkeep +0 -0
  80. package/public-kit/harness/spec/v1.md +286 -0
  81. package/scripts/hook-launch.sh +1 -1
@@ -0,0 +1,28 @@
1
+ {"event": "sessionStart", "argv": ["--event", "sessionStart"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"\", \"model\": \"grok-4.7-medium\", \"model_id\": \"grok-4.7\", \"model_params\": [{\"id\": \"context\", \"value\": \"256k\"}, {\"id\": \"reasoning_effort\", \"value\": \"medium\"}, {\"id\": \"fast\", \"value\": \"false\"}], \"is_background_agent\": false, \"composer_mode\": \"agent\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"sessionStart\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365062.802}
2
+ {"event": "beforeSubmitPrompt", "argv": ["--event", "beforeSubmitPrompt"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7-medium\", \"model_id\": \"grok-4.7\", \"model_params\": [{\"id\": \"context\", \"value\": \"256k\"}, {\"id\": \"reasoning_effort\", \"value\": \"medium\"}, {\"id\": \"fast\", \"value\": \"false\"}], \"composer_mode\": \"agent\", \"prompt\": \"This is a test run in a scratch folder. Please do these steps in order, one tool call each, and don't ask me anything:\\n1. Create a new file named hello.txt containing the single line: hello from cursor\\n2. Edit seed.txt: change the line \\\"status: draft\\\" to \\\"status: recorded\\\". Leave the other lines as they are.\\n3. Run this shell command: ls -la\\n4. Run this shell command, which is expected to fail, and just report that it failed: cat does-not-exist.txt\\n5. Use a subagent (the Task tool) to read hello.txt and reply with its contents. If you have no subagent tool, say so and skip this step.\\nThen give a one-line summary of what you did.\", \"attachments\": [], \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"beforeSubmitPrompt\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365063.174}
3
+ {"event": "preToolUse", "argv": ["--event", "preToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Read\", \"tool_input\": {\"file_path\": \"<folder>/hello.txt\"}, \"tool_use_id\": \"call-09bdd4e8-c214-483d-b0e3-37a516bd4133-0\\nfc_efc3824d-6272-9819-93fc-cbb67bf2de7e_0\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"preToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365079.64}
4
+ {"event": "postToolUseFailure", "argv": ["--event", "postToolUseFailure"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Read\", \"tool_input\": {\"file_path\": \"<folder>/hello.txt\"}, \"error_message\": \"File not found: <folder>/hello.txt\", \"failure_type\": \"error\", \"duration\": 2.492, \"tool_use_id\": \"call-09bdd4e8-c214-483d-b0e3-37a516bd4133-0\\nfc_efc3824d-6272-9819-93fc-cbb67bf2de7e_0\", \"is_interrupt\": false, \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"postToolUseFailure\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365079.82}
5
+ {"event": "preToolUse", "argv": ["--event", "preToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Write\", \"tool_input\": {\"file_path\": \"<folder>/hello.txt\", \"content\": \"hello from cursor\\n\"}, \"tool_use_id\": \"call-09bdd4e8-c214-483d-b0e3-37a516bd4133-0\\nfc_efc3824d-6272-9819-93fc-cbb67bf2de7e_0\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"preToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365079.952}
6
+ {"event": "afterFileEdit", "argv": ["--event", "afterFileEdit"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"file_path\": \"<folder>/hello.txt\", \"edits\": [{\"old_string\": \"\", \"new_string\": \"hello from cursor\\n\"}], \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"afterFileEdit\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365080.15}
7
+ {"event": "postToolUse", "argv": ["--event", "postToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Write\", \"tool_input\": {\"file_path\": \"<folder>/hello.txt\", \"content\": \"hello from cursor\\n\"}, \"tool_output\": \"{\\\"file_path\\\":\\\"<folder>/hello.txt\\\",\\\"success\\\":true}\", \"duration\": 15.341, \"tool_use_id\": \"call-09bdd4e8-c214-483d-b0e3-37a516bd4133-0\\nfc_efc3824d-6272-9819-93fc-cbb67bf2de7e_0\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"postToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365080.276}
8
+ {"event": "preToolUse", "argv": ["--event", "preToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Read\", \"tool_input\": {\"file_path\": \"<folder>/seed.txt\"}, \"tool_use_id\": \"call-1a0c295f-a03e-434d-957b-84212dabc35a-1\\nfc_7f434272-1c3a-43e5-86ec-be60809ca51d_0\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"preToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365082.416}
9
+ {"event": "postToolUse", "argv": ["--event", "postToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Read\", \"tool_input\": {\"file_path\": \"<folder>/seed.txt\"}, \"tool_output\": \"{\\\"file_path\\\":\\\"<folder>/seed.txt\\\",\\\"content_length\\\":51}\", \"duration\": 2.966, \"tool_use_id\": \"call-1a0c295f-a03e-434d-957b-84212dabc35a-1\\nfc_7f434272-1c3a-43e5-86ec-be60809ca51d_0\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"postToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365082.605}
10
+ {"event": "preToolUse", "argv": ["--event", "preToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Write\", \"tool_input\": {\"file_path\": \"<folder>/seed.txt\", \"content\": \"CoCheck recording seed\\nstatus: recorded\\nowner: nobody\\n\"}, \"tool_use_id\": \"call-1a0c295f-a03e-434d-957b-84212dabc35a-1\\nfc_7f434272-1c3a-43e5-86ec-be60809ca51d_0\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"preToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365082.78}
11
+ {"event": "afterFileEdit", "argv": ["--event", "afterFileEdit"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"file_path\": \"<folder>/seed.txt\", \"edits\": [{\"old_string\": \"status: draft\", \"new_string\": \"status: recorded\"}], \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"afterFileEdit\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365082.968}
12
+ {"event": "postToolUse", "argv": ["--event", "postToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Write\", \"tool_input\": {\"file_path\": \"<folder>/seed.txt\", \"content\": \"CoCheck recording seed\\nstatus: recorded\\nowner: nobody\\n\"}, \"tool_output\": \"{\\\"file_path\\\":\\\"<folder>/seed.txt\\\",\\\"success\\\":true}\", \"duration\": 9.555, \"tool_use_id\": \"call-1a0c295f-a03e-434d-957b-84212dabc35a-1\\nfc_7f434272-1c3a-43e5-86ec-be60809ca51d_0\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"postToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365083.092}
13
+ {"event": "preToolUse", "argv": ["--event", "preToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Shell\", \"tool_input\": {\"command\": \"ls -la\", \"cwd\": \"\", \"timeout\": 30000}, \"tool_use_id\": \"ecbec0ca-9c34-4a41-8b14-656478895237\", \"cwd\": \"\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"preToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365084.672}
14
+ {"event": "beforeShellExecution", "argv": ["--event", "beforeShellExecution"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"command\": \"ls -la\", \"cwd\": \"\", \"sandbox\": true, \"tool_use_id\": \"ecbec0ca-9c34-4a41-8b14-656478895237\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"beforeShellExecution\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365084.835}
15
+ {"event": "afterShellExecution", "argv": ["--event", "afterShellExecution"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"command\": \"ls -la\", \"output\": \"total 24\\ndrwxr-xr-x@ 7 <user> staff 224 Nov 22 11:31 .\\ndrwxr-x---+ 61 <user> staff 1952 Nov 22 11:29 ..\\ndrwxr-xr-x@ 5 <user> staff 160 Nov 22 11:15 .cursor\\n-rw-r--r--@ 1 <user> staff 637 Nov 22 11:15 PROMPT.txt\\ndrwxr-xr-x@ 3 <user> staff 96 Nov 22 11:15 capture\\n-rw-r--r--@ 1 <user> staff 18 Nov 22 11:31 hello.txt\\n-rw-r--r--@ 1 <user> staff 54 Nov 22 11:31 seed.txt\\n\", \"duration\": 492.336, \"sandbox\": true, \"tool_use_id\": \"ecbec0ca-9c34-4a41-8b14-656478895237\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"afterShellExecution\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365085.45}
16
+ {"event": "postToolUse", "argv": ["--event", "postToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Shell\", \"tool_input\": {\"command\": \"ls -la\", \"cwd\": \"\", \"timeout\": 30000}, \"tool_output\": \"{\\\"output\\\":\\\"total 24\\\\ndrwxr-xr-x@ 7 <user> staff 224 Nov 22 11:31 .\\\\ndrwxr-x---+ 61 <user> staff 1952 Nov 22 11:29 ..\\\\ndrwxr-xr-x@ 5 <user> staff 160 Nov 22 11:15 .cursor\\\\n-rw-r--r--@ 1 <user> staff 637 Nov 22 11:15 PROMPT.txt\\\\ndrwxr-xr-x@ 3 <user> staff 96 Nov 22 11:15 capture\\\\n-rw-r--r--@ 1 <user> staff 18 Nov 22 11:31 hello.txt\\\\n-rw-r--r--@ 1 <user> staff 54 Nov 22 11:31 seed.txt\\\\n\\\",\\\"exitCode\\\":0}\", \"duration\": 492.336, \"tool_use_id\": \"ecbec0ca-9c34-4a41-8b14-656478895237\", \"cwd\": \"\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"postToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365085.573}
17
+ {"event": "preToolUse", "argv": ["--event", "preToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Shell\", \"tool_input\": {\"command\": \"cat does-not-exist.txt\", \"cwd\": \"\", \"timeout\": 30000}, \"tool_use_id\": \"a63eefc0-84a9-4d8b-8efc-8587911281ec\", \"cwd\": \"\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"preToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365087.133}
18
+ {"event": "beforeShellExecution", "argv": ["--event", "beforeShellExecution"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"command\": \"cat does-not-exist.txt\", \"cwd\": \"\", \"sandbox\": true, \"tool_use_id\": \"a63eefc0-84a9-4d8b-8efc-8587911281ec\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"beforeShellExecution\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365087.324}
19
+ {"event": "afterShellExecution", "argv": ["--event", "afterShellExecution"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"command\": \"cat does-not-exist.txt\", \"output\": \"cat: does-not-exist.txt: No such file or directory\\n\", \"duration\": 150.739, \"sandbox\": true, \"tool_use_id\": \"a63eefc0-84a9-4d8b-8efc-8587911281ec\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"afterShellExecution\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365087.6}
20
+ {"event": "postToolUseFailure", "argv": ["--event", "postToolUseFailure"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7\", \"tool_name\": \"Shell\", \"tool_input\": {\"command\": \"cat does-not-exist.txt\", \"cwd\": \"\", \"timeout\": 30000}, \"error_message\": \"cat: does-not-exist.txt: No such file or directory\", \"failure_type\": \"error\", \"duration\": 150.739, \"tool_use_id\": \"a63eefc0-84a9-4d8b-8efc-8587911281ec\", \"is_interrupt\": false, \"cwd\": \"\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"postToolUseFailure\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365087.729}
21
+ {"event": "preToolUse", "argv": ["--event", "preToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"\", \"tool_name\": \"Task\", \"tool_input\": {\"description\": \"Read hello.txt contents\", \"prompt\": \"Read the file <folder>/hello.txt and reply with its exact contents and nothing else. Do not modify any files.\", \"subagent_type\": \"generalPurpose\", \"run_in_background\": false}, \"tool_use_id\": \"call-981e8a13-6224-4e6f-baa4-cf2aaefecf58-5\\nfc_58bb2bb6-3075-4bfe-8fe8-f20c8f622937_0\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"preToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365093.498}
22
+ {"event": "subagentStart", "argv": ["--event", "subagentStart"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7-medium\", \"subagent_id\": \"call-981e8a13-6224-4e6f-baa4-cf2aaefecf58-5\\nfc_58bb2bb6-3075-4bfe-8fe8-f20c8f622937_0\", \"subagent_type\": \"general-purpose\", \"task\": \"Read the file <folder>/hello.txt and reply with its exact contents and nothing else. Do not modify any files.\", \"parent_conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"tool_call_id\": \"call-981e8a13-6224-4e6f-baa4-cf2aaefecf58-5\\nfc_58bb2bb6-3075-4bfe-8fe8-f20c8f622937_0\", \"subagent_model\": \"grok-4.7-medium\", \"is_parallel_worker\": false, \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"subagentStart\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"parent_agent_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365093.703}
23
+ {"event": "preToolUse", "argv": ["--event", "preToolUse"], "stdin": "{\"conversation_id\": \"b0d6fa01-b7d8-4b6e-996f-e5158d433dce\", \"generation_id\": \"799cb1ac-2b29-4c9e-84ad-3e5e4c57e64f\", \"model\": \"grok-4.7-medium\", \"parent_tool_call_id\": \"call-981e8a13-6224-4e6f-baa4-cf2aaefecf58-5\\nfc_58bb2bb6-3075-4bfe-8fe8-f20c8f622937_0\", \"tool_name\": \"Read\", \"tool_input\": {\"file_path\": \"<folder>/hello.txt\"}, \"tool_use_id\": \"call-d8f4f580-e4e2-4cea-af81-a1720eca9e7c-1\\nfc_bfe28f19-e35e-421f-a5cc-f3d3c6f6c750_1\", \"session_id\": \"b0d6fa01-b7d8-4b6e-996f-e5158d433dce\", \"hook_event_name\": \"preToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"parent_agent_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365099.799}
24
+ {"event": "postToolUse", "argv": ["--event", "postToolUse"], "stdin": "{\"conversation_id\": \"b0d6fa01-b7d8-4b6e-996f-e5158d433dce\", \"generation_id\": \"799cb1ac-2b29-4c9e-84ad-3e5e4c57e64f\", \"model\": \"grok-4.7-medium\", \"parent_tool_call_id\": \"call-981e8a13-6224-4e6f-baa4-cf2aaefecf58-5\\nfc_58bb2bb6-3075-4bfe-8fe8-f20c8f622937_0\", \"tool_name\": \"Read\", \"tool_input\": {\"file_path\": \"<folder>/hello.txt\"}, \"tool_output\": \"{\\\"file_path\\\":\\\"<folder>/hello.txt\\\",\\\"content_length\\\":18}\", \"duration\": 2.658, \"tool_use_id\": \"call-d8f4f580-e4e2-4cea-af81-a1720eca9e7c-1\\nfc_bfe28f19-e35e-421f-a5cc-f3d3c6f6c750_1\", \"session_id\": \"b0d6fa01-b7d8-4b6e-996f-e5158d433dce\", \"hook_event_name\": \"postToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"parent_agent_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365099.999}
25
+ {"event": "postToolUse", "argv": ["--event", "postToolUse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7-medium\", \"tool_name\": \"Task\", \"tool_input\": {\"description\": \"Read hello.txt contents\", \"prompt\": \"Read the file <folder>/hello.txt and reply with its exact contents and nothing else. Do not modify any files.\", \"subagent_type\": \"generalPurpose\", \"run_in_background\": false}, \"tool_output\": \"{\\\"status\\\":\\\"success\\\",\\\"agentId\\\":\\\"b0d6fa01-b7d8-4b6e-996f-e5158d433dce\\\",\\\"durationMs\\\":15532,\\\"isBackground\\\":false}\", \"duration\": 15532, \"tool_use_id\": \"call-981e8a13-6224-4e6f-baa4-cf2aaefecf58-5\\nfc_58bb2bb6-3075-4bfe-8fe8-f20c8f622937_0\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"postToolUse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": null}", "ts": 1795365109.206}
26
+ {"event": "subagentStop", "argv": ["--event", "subagentStop"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7-medium\", \"subagent_id\": \"call-981e8a13-6224-4e6f-baa4-cf2aaefecf58-5\\nfc_58bb2bb6-3075-4bfe-8fe8-f20c8f622937_0\", \"subagent_type\": \"general-purpose\", \"status\": \"completed\", \"duration_ms\": 15709, \"parent_conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"child_conversation_id\": \"b0d6fa01-b7d8-4b6e-996f-e5158d433dce\", \"message_count\": 0, \"tool_call_count\": 0, \"loop_count\": 0, \"task\": \"Read the file <folder>/hello.txt and reply with its exact contents and nothing else. Do not modify any files.\", \"description\": \"Read hello.txt contents\", \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"subagentStop\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"parent_agent_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"user_email\": \"user@example.com\", \"transcript_path\": null, \"agent_transcript_path\": null}", "ts": 1795365109.393}
27
+ {"event": "afterAgentResponse", "argv": ["--event", "afterAgentResponse"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7-medium\", \"model_id\": \"grok-4.7\", \"model_params\": [{\"id\": \"context\", \"value\": \"256k\"}, {\"id\": \"reasoning_effort\", \"value\": \"medium\"}, {\"id\": \"fast\", \"value\": \"false\"}], \"text\": \"EXECUTE\\n\\nCreated `hello.txt` (`hello from cursor`), set `seed.txt` to `status: recorded`, listed the directory, confirmed `cat does-not-exist.txt` failed, and [Read hello.txt](b0d6fa01-b7d8-4b6e-996f-e5158d433dce) returned `hello from cursor`.\", \"input_tokens\": 136854, \"output_tokens\": 1977, \"cache_read_tokens\": 104320, \"cache_write_tokens\": 0, \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"afterAgentResponse\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": \"/Users/<user>/.cursor/projects/Users-<user>-cocheck-cursor-recording/agent-transcripts/c49868f9-7b4e-426e-942a-47796279c579/c49868f9-7b4e-426e-942a-47796279c579.jsonl\"}", "ts": 1795365114.615}
28
+ {"event": "stop", "argv": ["--event", "stop"], "stdin": "{\"conversation_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"generation_id\": \"bf81fa1c-bfc2-4e3e-8688-82e918a4b0ad\", \"model\": \"grok-4.7-medium\", \"model_id\": \"grok-4.7\", \"model_params\": [{\"id\": \"context\", \"value\": \"256k\"}, {\"id\": \"reasoning_effort\", \"value\": \"medium\"}, {\"id\": \"fast\", \"value\": \"false\"}], \"status\": \"completed\", \"loop_count\": 0, \"input_tokens\": 136854, \"output_tokens\": 1977, \"cache_read_tokens\": 104320, \"cache_write_tokens\": 0, \"session_id\": \"c49868f9-7b4e-426e-942a-47796279c579\", \"hook_event_name\": \"stop\", \"cursor_version\": \"3.31.15\", \"workspace_roots\": [\"<folder>\"], \"user_email\": \"user@example.com\", \"transcript_path\": \"/Users/<user>/.cursor/projects/Users-<user>-cocheck-cursor-recording/agent-transcripts/c49868f9-7b4e-426e-942a-47796279c579/c49868f9-7b4e-426e-942a-47796279c579.jsonl\"}", "ts": 1795365114.752}
@@ -0,0 +1,42 @@
1
+ # myagent: a CoCheck harness manifest
2
+
3
+ This folder describes one agent harness to CoCheck. `cocheck-harness.json` is the whole description; it holds data only, no code.
4
+ JSON has no comments, so each part of the manifest is explained here. The full reference is `spec/v1.md` in the kit (public-kit/harness/).
5
+
6
+ ## Next three commands
7
+
8
+ 1. Record real hook calls from your harness (it runs in a scratch folder; your own config is never touched):
9
+ `cocheck harness record myagent --manifest ./cocheck-harness.json --out ./recordings -- <your harness command>`
10
+ 2. Edit `cocheck-harness.json` until the recorded payloads read right (field paths, event names, tool names).
11
+ 3. Run the cases against it: `cocheck harness test --cases <cases folder> --manifest ./cocheck-harness.json`
12
+
13
+ To try it for real, copy this whole folder to `<CoCheck data home>/harnesses/myagent/` (or the folder `COCHECK_HARNESS_DIR` names), then run `cocheck status`.
14
+ To ship it with CoCheck, open a pull request that adds it under `harnesses/myagent/` at the repository root (data only, no code change).
15
+
16
+ ## What each part means
17
+
18
+ - `schema`: always `cocheck-harness/1`.
19
+ - `key`: the short name; it must equal this folder's name. Lowercase letters, digits and dashes.
20
+ - `displayName`, `fullName`, `chip`: the names and the one-letter badge shown to people.
21
+ - `testedVersions`: harness versions you have recorded against.
22
+ - `events`: the harness's event names, each mapped to a CoCheck kind (`prompt`, `tool-pre`, `tool-post`, `tool-failure`, `stop`, ...).
23
+ - `eventFrom`: where the event name comes from: `{"arg": "--event"}` (the hook command names it) or `{"payload": "<path>"}`.
24
+ - `unverifiedEvents`: event names you have not seen in a recording.
25
+ - `fields`: where each value sits in the payload (`a.b`, `a[0].b`). Only `session` is required; each missing one lowers what CoCheck can tell.
26
+ - `toolInputEncoding`: `json-text` when the tool input arrives as JSON text, else `object`.
27
+ - `callId`: the call's id path, or `synthesized` to make one up per session.
28
+ - `extraFields`: values kept in the record that CoCheck does not act on.
29
+ - `failure`: how a failed call looks (flags, text, interrupt) for `tool-failure` and `tool-post`.
30
+ - `refine`: rules that change an event's kind when a payload field is present or matches.
31
+ - `toolNameStrip`: a prefix taken off tool names.
32
+ - `toolClasses`: each tool name mapped to a class (`read`, `write`, `edit`, `shell`, ...) and its path fields. A tool not listed is unknown and still credited by inference; list a tool that never writes as `never-credited`.
33
+ - `narration`: where the harness's own words about what it is doing can be read.
34
+ - `sessionFile`: where the harness keeps its session file, from the session id.
35
+ - `capabilities`: what the harness can do (`failureEvent`, `helperSessions`, `launchKey`).
36
+ - `readsConfigsOf`: other harnesses whose hook config this one also reads.
37
+ - `sessionEnv`: the environment variable that holds the session id inside a shell call.
38
+ - `perAction`: for harnesses that send one event per edit or shell command: the tools and their field paths.
39
+ - `hostOwnedFiles`, `hostOwnedWhat`: files the harness writes itself, and a plain phrase for them.
40
+ - `install`: the hook config file (`path`, with `{home}` and `{env:NAME|fallback}`), its shape, and the events to install. Outsider install prints the snippet; it does not edit your config.
41
+ - `extras`: names of first-party code to opt into. A manifest in your own folder can name only the outsider-safe ones.
42
+ - `shape`: extra payload key lists used to tell this harness's payloads from another's.
@@ -0,0 +1,72 @@
1
+ {
2
+ "schema": "cocheck-harness/1",
3
+ "key": "myagent",
4
+ "displayName": "My Agent",
5
+ "fullName": "My Agent command-line tool",
6
+ "chip": "M",
7
+ "testedVersions": ["0.1"],
8
+ "events": {
9
+ "userPrompt": "prompt",
10
+ "beforeTool": "tool-pre",
11
+ "afterTool": "tool-post",
12
+ "toolFailed": "tool-failure",
13
+ "finished": "stop"
14
+ },
15
+ "eventFrom": { "arg": "--event" },
16
+ "unverifiedEvents": [],
17
+ "fields": {
18
+ "session": "sessionId",
19
+ "eventName": "eventName",
20
+ "cwd": "workspace.roots[0]",
21
+ "toolName": "tool.name",
22
+ "toolInput": "tool.args",
23
+ "toolResponse": "tool.result",
24
+ "agentId": "agent.id",
25
+ "agentType": "agent.type",
26
+ "transcriptPath": "transcriptPath",
27
+ "lastAssistantMessage": "final.message",
28
+ "prompt": "userText",
29
+ "parentSession": "parentSessionId",
30
+ "callReason": "reason"
31
+ },
32
+ "toolInputEncoding": "json-text",
33
+ "callId": { "payload": "tool.callId", "synthesized": true },
34
+ "extraFields": { "turnId": "turnId", "permissionMode": "permissionMode", "model": "model", "stopHookActive": "stopHookActive" },
35
+ "failure": {
36
+ "tool-failure": { "text": ["error.message"], "interrupt": "error.interrupted" },
37
+ "tool-post": { "flags": ["tool.result.isError"], "text": ["tool.result.error"], "inferred": true }
38
+ },
39
+ "refine": [{ "kinds": ["tool-post"], "becomes": "tool-failure", "whenPresent": "tool.result.error" }],
40
+ "toolNameStrip": { "prefix": "myagent_" },
41
+ "toolClasses": {
42
+ "read_file": { "class": "read" },
43
+ "write_file": { "class": "write", "pathFields": ["path"], "fileInput": true },
44
+ "edit_file": { "class": "edit", "pathFields": ["path"] },
45
+ "run_shell": { "class": "shell", "dialect": "bash", "backgroundable": true }
46
+ },
47
+ "narration": { "sources": [{ "kind": "closing-message", "readableAt": "post" }], "closingWaitMs": 0 },
48
+ "sessionFile": { "bySessionId": true, "defaultRoot": "{env:MYAGENT_HOME|{home}/.myagent}/sessions", "file": "{root}/{session}.jsonl" },
49
+ "capabilities": { "failureEvent": true, "helperSessions": false, "launchKey": false },
50
+ "readsConfigsOf": [],
51
+ "sessionEnv": "MYAGENT_SESSION_ID",
52
+ "perAction": { "fileEditTool": "edit_file", "shellTool": "run_shell", "fields": { "editPath": "tool.args.path", "command": "tool.args.command" } },
53
+ "hostOwnedFiles": [],
54
+ "hostOwnedWhat": "files My Agent writes itself",
55
+ "install": {
56
+ "format": "json",
57
+ "path": "{env:MYAGENT_HOME|{home}/.myagent}/hooks.json",
58
+ "mode": "owned",
59
+ "rootKey": "hooks",
60
+ "envelope": { "version": 1 },
61
+ "events": ["userPrompt", "beforeTool", "afterTool", "toolFailed", "finished"],
62
+ "entryTemplate": { "run": "{command}" },
63
+ "eventInCommand": true,
64
+ "skillRoot": ".myagent/skills",
65
+ "hostFlag": "myagent",
66
+ "folderFromPayloadCwd": true,
67
+ "notes": "Restart My Agent so it reads the new hooks.",
68
+ "checkPayload": { "payload": { "sessionId": "install-check", "workspace": { "roots": ["{folder}"] }, "tool": { "name": "run_shell", "args": "{\"command\":\"true\"}" } }, "event": "beforeTool" }
69
+ },
70
+ "extras": [],
71
+ "shape": {}
72
+ }
@@ -0,0 +1,286 @@
1
+ # CoCheck harness specification v1
2
+
3
+ Status: v1, experimental. A harness is an AI agent program that runs tools on a person's behalf (a coding agent, a desktop agent, a command-line assistant). CoCheck learns what such an agent did to the files in a folder by listening to the hooks the harness runs around its calls. This page says what CoCheck reads from a harness, how a harness describes itself in one JSON file, and what CoCheck loses when the harness cannot say something.
4
+
5
+ You do not write code to add a harness. You write a manifest, record a real session, and write cases that say what CoCheck must make of it. `cocheck harness test` checks the two against each other.
6
+
7
+ ## Contents
8
+
9
+ 1. The canonical event
10
+ 2. Levels
11
+ 3. The manifest
12
+ 4. What degrades without each field
13
+ 5. Outsider policy
14
+ 6. Cases
15
+ 7. Versioning
16
+
17
+ ## 1. The canonical event
18
+
19
+ Whatever shape a harness sends, CoCheck reads each hook call into one event, `NormalizedEvent` with `v: 1`. A consumer refuses any other `v`. Values pass through unchanged (never coerced), so an odd payload gives an odd value; CoCheck does not repair it.
20
+
21
+ ### Kinds
22
+
23
+ | kind | meaning |
24
+ | --- | --- |
25
+ | `tool-pre` | a tool call is about to run |
26
+ | `tool-post` | a tool call finished |
27
+ | `tool-failure` | the harness's own event for a failed call |
28
+ | `stop` | the main agent finished a turn |
29
+ | `subagent-stop` | a helper agent finished |
30
+ | `prompt` | the person submitted a prompt |
31
+ | `file-edit` | a file the harness changed, reported on its own event (see "Per-action events") |
32
+ | `shell-pre` | a shell run is about to start (per-action) |
33
+ | `shell-post` | a shell run finished (per-action) |
34
+ | `session-start` | a session began; carried, nothing is recorded for it yet |
35
+ | `session-end` | a session ended; carried, nothing is recorded for it yet |
36
+ | `other` | an event name CoCheck does not act on, or one a `refine` rule demotes (for example a helper's own prompt) |
37
+
38
+ ### Fields
39
+
40
+ Always present: `v`, `host` (the harness key), `kind`, `eventName` (the harness's own event name), `session`, `narratesBeforeCall` (true when the harness writes the call's words to its session file before the call), `sessionFileBySessionId` (the session file can be found from the session id alone), `extra`, `proof` and `synthetic`.
41
+
42
+ Present when the payload has them: `cwd`, `toolName`, `toolInput` (parsed when the harness sends JSON text), `toolResponse`, `toolUseId` (the call id), `agentId`, `agentType`, `failure` (`raw`, `interrupted`, and `inferred` when the failure was read from output text), `transcriptPath`, `lastAssistantMessage`, `prompt`. `extra` holds `turnId`, `permissionMode`, `model` and `stopHookActive` when the harness sends them. `proof` is empty and `synthetic` false for every harness today: the proof of who made a change is found by CoCheck's own check of the folder, not carried by the event.
43
+
44
+ A helper's events under its own session id carry the main session's id when the manifest names a `parentSession` field.
45
+
46
+ ### Joining calls
47
+
48
+ A Post with the call id of a call already open in the same session closes that call. A second Post of a closed call adds nothing. A harness that sends no call id is given one made up per call (see `callId` below).
49
+
50
+ ### Per-action events
51
+
52
+ A harness that reports each action on its own event instead of as a tool call maps those events to `file-edit`, `shell-pre` and `shell-post` and names, in `perAction`, the tool each stands for and where its parts sit in the payload. A `file-edit` is a call whose Pre and Post happen together: the change found in the folder since the last event is credited to it. A `shell-pre` is a tool Pre and a `shell-post` a tool Post for every rule after the entry. When a file edit is the first event in a folder, the file already holds the new text: its earlier state is rebuilt by undoing the reported edits (each new text found exactly once, and replaying the edits must give the file back), so the change shows. Bound: an edit that cannot be undone exactly (whole content only, a new text that is empty or found more than once) is found only as already present, and a rebuilt state never proves the edit.
53
+
54
+ ## 2. Levels
55
+
56
+ A harness joins at the level its hooks allow. Each level is complete on its own and adds to the one before.
57
+
58
+ - **L0, a session.** The manifest names the session id. CoCheck knows a session exists and when its events came. It cannot say what any call did.
59
+ - **L1, calls.** Adds a Pre and a Post for each call, with the tool's name and its input. CoCheck compares the folder before and after each call and credits a change to the call that was open. Without a call id, ids are made up (one per call, in order), so overlapping calls cannot be told apart.
60
+ - **L2, adds the details that make the credit sound.** A call id the harness sends (`callId`), a failed call (`failure`), helper agents (`agentId`, `agentType`, `parentSession`) and the closing message (`lastAssistantMessage`). Overlapping calls and helpers are credited to the right call, a failed call is not credited as if it had worked, and the closing message is shown.
61
+ - **L3, first-party extras.** Reading the harness's own session file for each call's words, finding helper files, install editors and trust checks for configs that are not JSON. These are code in CoCheck, named in the `extras` list of a built-in manifest. A manifest in your own folder can name only the outsider-safe extras (section 5), so L3 is for harnesses shipped with CoCheck.
62
+
63
+ Each case file declares the level it exercises.
64
+
65
+ ## 3. The manifest
66
+
67
+ One file, `cocheck-harness.json`, in a folder named after the harness key: `<key>/cocheck-harness.json`. It is JSON with `"schema": "cocheck-harness/1"`. It holds no code. A payload path is `a.b` or `a[0].b`: keys joined by dots, with `[n]` for a list position. A pattern is a regular expression of at most 200 characters, with no backreference, no lookaround and no repeated group that itself repeats or alternates (`(a+)+`). `cocheck` names the field of any error, for example `toyagent/cocheck-harness.json: events.beforeTool: unknown kind "tool-pree"`.
68
+
69
+ ### Identity
70
+
71
+ - `schema`: `"cocheck-harness/1"`.
72
+ - `key`: lowercase letters, digits and dashes, at most 32. It must match the folder name and cannot be a key that already exists (the built-in harnesses, `both`, `all`, `none`, `unknown`).
73
+ - `displayName`: the name shown on pages.
74
+ - `fullName`: optional longer name.
75
+ - `chip`: the short mark drawn beside the name.
76
+ - `testedVersions`: the versions of the harness the recordings came from.
77
+
78
+ ### Events
79
+
80
+ - `events`: the harness's event names mapped to a kind from section 1. At least one.
81
+ - `eventFrom`: where the event name is. `{ "payload": "<path>" }` when the payload names it, or `{ "arg": "--event" }` when the hook command names it (CoCheck then writes one hook entry per event, each passing its own name).
82
+ - `unverifiedEvents`: event names the harness documents but no recording shows. Declared, never mapped, never installed.
83
+ - `refine`: a list of rules that change an event's kind from the one its name maps to. Each has `kinds` (the kinds it applies to), `becomes` (the new kind), and one or both conditions, `whenPresent` (a path whose text is not empty) and `whenMatches` (`path` and `pattern`: the trimmed text at the path matches). Every given condition must hold; the first rule that holds wins.
84
+
85
+ ### Where each value sits (`fields`)
86
+
87
+ `fields` maps a canonical field to a payload path. `session` is required; the rest are optional.
88
+
89
+ - `session`: the session id.
90
+ - `eventName`: only when the name is also read from a path your other fields need.
91
+ - `cwd`: the folder the harness is working in.
92
+ - `toolName`: the called tool's name.
93
+ - `toolInput`: the call's arguments.
94
+ - `toolResponse`: the call's result.
95
+ - `agentId`, `agentType`: the helper that made the call, when it was a helper.
96
+ - `transcriptPath`: the harness's session file, when the payload names one.
97
+ - `lastAssistantMessage`: the closing message, on the stop event.
98
+ - `prompt`: the person's prompt.
99
+ - `parentSession`: a helper's events carry the main session's id here.
100
+ - `callReason`: not a path: the key of the tool input that holds a per-call reason (`description`).
101
+
102
+ Related top-level fields:
103
+
104
+ - `toolInputEncoding`: `"json-text"` when the tool input arrives as JSON text, else `"object"` (the default).
105
+ - `callId`: where the call id is, with member `payload` (a path) or `synthesized`. `{ "payload": "<path>" }` when the harness sends one, `{ "synthesized": true }` when it sends none and CoCheck should make one per call in the session, or both (the harness's id when present, else made up). Left out: calls have no id.
106
+ - `extraFields`: paths for `turnId`, `permissionMode`, `model` and `stopHookActive`. Kept in the record; CoCheck does not act on them.
107
+ - `toolNameStrip`: `{ "prefix": "<pattern>" }`, a pattern matched at the start of the tool name and taken off (for a harness that joins a namespace onto the name).
108
+
109
+ ### Failure (`failure`)
110
+
111
+ A failed call, per kind: `"tool-failure"` (the harness has its own failed-call event) and `"tool-post"` (a failed call arrives as an ordinary Post). Each holds a rule:
112
+
113
+ - `flags`: payload paths; the call failed when any holds `true`.
114
+ - `text`: paths; the failure's own words are the first that holds text.
115
+ - `nonEmpty`: for a `tool-post` rule, `true`: the call failed when `text` gives words that are not empty. For a harness whose Post carries an error field that is empty when the call worked. It needs `text`.
116
+ - `flaggedText`: where the words are when `text` gave none and a `flags` path is `true`. Each entry is a path, or `{ "path": "<path>", "blocks": true }` (with `blocks`, the value is a list of `{ "text": ... }` blocks, joined by a line break).
117
+ - `interrupt`: a path; `true` there marks the call as interrupted.
118
+ - `exitCode`: for a `tool-post` rule: `{ "from": "<path>", "pattern": "<pattern>" }`. The failure is a nonzero exit code stated in the text at `from`; the pattern has one group holding the code, and the last match wins.
119
+ - `inferred`: `true` when the failure was read from output text and not sent by the harness: a guess, never proof that other calls succeeded.
120
+
121
+ ### Tools (`toolClasses`)
122
+
123
+ `toolClasses` names each tool the harness reports and what it does, as a `class`, so that CoCheck's rules never test a tool's name. A tool missing from the table is unknown: CoCheck reads nothing from its input (no named file, no command, no helper), and a change found in the folder while its call is open is still credited to it, on the basis `inferred`, as for any call. Unknown is the safe direction: a tool that writes without being listed (an MCP tool, a tool added in a new harness version) keeps its credit. To say a tool never writes, list it as `never-credited` (or `read`, `read-only`). Classes:
124
+
125
+ - `write`: writes a whole file from content.
126
+ - `edit`: changes a file by replacing text in it.
127
+ - `notebook-edit`: changes a notebook's cells.
128
+ - `patch`: carries a patch whose headers name the files it changes.
129
+ - `shell`: runs a shell command.
130
+ - `launcher`: starts a helper agent.
131
+ - `wait`: waits on helpers and writes nothing.
132
+ - `read`: reads a file by path.
133
+ - `read-only`: looks at files or the folder and writes nothing.
134
+ - `never-credited`: never writes a file in the folder (bookkeeping, web and messaging tools).
135
+
136
+ Each entry may add:
137
+
138
+ - `dialect`: for `shell`, `"bash"` or `"powershell"`: how the command is read.
139
+ - `waitFlag`: for `wait`, the input flag that makes the call a wait.
140
+ - `anyCase`: the tool name varies in letter case, so it is matched in any case.
141
+ - `pathFields`: for `write`, `edit`, `notebook-edit`, the input fields that name the file, in order.
142
+ - `pathChecked`: for `write` and `edit`, a call whose input names an absolute file is credited only with that file.
143
+ - `fileInput`: the input has the file-tool shape (`file_path` plus `content`, `old_string` or `new_string`).
144
+ - `backgroundFlag`: for `launcher`, the call runs its helper in the background when its input says `run_in_background: true`.
145
+ - `resumesHelper`: a call that wakes a helper that already ran.
146
+ - `backgroundable`: for `shell`, the command can leave a process running past the call's result, so its text is read for detach forms.
147
+
148
+ ### Per-action events (`perAction`)
149
+
150
+ For a harness that maps events to `file-edit`, `shell-pre` or `shell-post`: `fileEditTool` and `shellTool` (names in `toolClasses` that those events stand for), and `fields` with `editPath` and `command` (required), and optionally `editList` (a list of edits), `editContent` (the file's whole new content), `exitCode` and `output`.
151
+
152
+ ### Words and the session file
153
+
154
+ - `narration`: where a call's words and the closing message can be read. `sources` is a ranked list; each has a `kind` (`text-before-call`, `commentary-before-call`, `closing-message`), `readableAt` (`"pre"` or `"post"`) and optional `reason` (`true`: the words are also the call's reason). `closingWaitMs` is how long a stop waits for the closing message to reach a session file that lags the hook. A plain manifest reads the closing message from `lastAssistantMessage`; reading a session file for the rest is an L3 extra.
155
+ - `sessionFile`: where the harness's session file is, from the session id alone: `bySessionId`, `defaultRoot` and `file` (path templates; `{home}` and `{env:NAME|fallback}`, and in `file` also `{root}` and `{session}`). `file` is needed when `bySessionId` is true.
156
+
157
+ ### Capabilities and other hosts
158
+
159
+ - `capabilities`: what the harness lacks or has, each `true` or `false`: `failureEvent` (it sends a failed-call event, so a call that closes with none succeeded), `argvTag` (its Pre hook can rewrite a shell call; built-in only), `helperSessions` (helper events arrive under the helper's own session id), `launchKey` (its payload may carry a key that binds a helper launch to its calls), `readsForeignHooks` (it also runs another harness's hooks).
160
+ - `foreignHookFingerprint`: for a harness that also runs another harness's hooks: `present` (keys that must be there), `strings` (keys that must be text) and `absent` (keys that must be missing), the payload shape of such a run. Another harness's hook that receives a matching payload records nothing (this harness's own hook records it). For a built-in harness the shape alone decides; for a harness in your own folder the fingerprint counts only while this harness's own CoCheck hook is installed for the payload's folder (section 5).
161
+ - `readsConfigsOf`: the harnesses whose config files this one also reads.
162
+ - `argvTag`: how a shell call is tagged so the change is proven: `tool`, `preOutput`, `envFileVar`, `shellEnv` and `sessionStartEvent`. Built-in only.
163
+ - `sessionEnv`: the environment variable the harness sets in the shell of its session to the session id.
164
+ - `hostOwnedFiles`, `hostOwnedWhat`: folder-relative files the harness's own app writes for its bookkeeping, and what the app is probably doing when it writes them (said after "Probably ").
165
+ - `shape`: the fields each event is expected to carry. Not read yet.
166
+
167
+ ### Install (`install`)
168
+
169
+ What `cocheck install --for <key>` needs. For a harness in your own folder, install prints the config path and the hook entries to add instead of editing (section 5).
170
+
171
+ - `skillRoot`: the folder under the person's home where the harness reads skills.
172
+ - `hostFlag`: the `--host` value written into the hook command.
173
+ - `projectDirEnv`: the environment variable the harness sets to the project folder.
174
+ - `folderFromPayloadCwd`: the payload's `cwd` is the task folder, used when the command names none.
175
+ - `promptContext`: `false` when the hook must print nothing at a recorded prompt.
176
+ - `ownsFile`: the config file is wholly CoCheck's (uninstall deletes it, only when it carries CoCheck's marker).
177
+ - `inBothAlias`: the harness is part of what `--for both` means. Built-in only.
178
+ - `reusesRecord`: the harness's hook has no `--folder`, so an install reuses `--home` and `--folder` from the record of a first install.
179
+ - `timingLabel`: the harness's name in the hook-timing line, when it differs from `displayName`.
180
+ - `afterInstall`: said after an install, when the person has a step to take before the hooks run.
181
+ - `notes`: a note printed after install (`{launcherDir}` and `{home}` are filled in).
182
+ - `checkPayload`: `{ "payload": {...}, "event": "<name>" }`, a harmless Pre in the harness's own shape that proves the hook records (`{folder}` in a string is the task folder).
183
+ - `editorExtra` and `events`: a first-party editor for a config that is not JSON, and the hook events it installs. Built-in only.
184
+
185
+ The JSON hook-config editor is described by these members of `install`:
186
+
187
+ - `format`: `"json"`.
188
+ - `path`: the config file, a template: `{home}` (the person's home), `{project}` (the task folder, for a harness whose hook config sits in the workspace, such as `{project}/.cursor/hooks.json`), `{env:NAME}` (a variable that must be set) and `{env:NAME|fallback}` (the fallback a template itself). Any other token is refused when the manifest loads. With `{project}`, install uses the folder given by `--folder` (else the folder it runs from), and `cocheck harness record` uses its scratch work folder.
189
+ - `mode`: `"merge"` (edit the person's file, keeping everything else) or `"owned"`.
190
+ - `rootKey`: the top-level key holding the hooks.
191
+ - `envelope`: extra top-level keys for a new file, such as `{ "version": 1 }`.
192
+ - `events`: the event names CoCheck installs.
193
+ - `entryTemplate`: the entry written per event; `{command}` and `{event}` are filled in.
194
+ - `entryTemplates`: optional, an object from event name to an entry, for a harness whose config takes a different entry shape for some events (a group with `hooks` for tool events, a plain handler for the rest). A listed event uses its own entry; every other event uses `entryTemplate`. Each key must be in `events` or `extraEvents`, and each entry must use `{command}`. Install, uninstall and the missing-hook check read each event in its own shape.
195
+ - `matcherEvents`: events whose entry carries a matcher, and its value.
196
+ - `eventInCommand`: the command names its event as an argument.
197
+ - `failOpenEvents`: events whose hook must exit 0 even when CoCheck fails.
198
+ - `windowsCommandKey`: the key holding the Windows variant of the command.
199
+ - `extraEvents`: events written on install and removed on uninstall that are never reported missing.
200
+ - `managedHost`: an entry is CoCheck's when its command parses as a command for this harness.
201
+
202
+ ### Extras
203
+
204
+ - `extras`: a list of first-party code the manifest opts into by name. An unknown name fails validation. The extras a manifest in your own folder may name are the outsider-safe ones: `codex-display-text` (turns a reply's file-citation directives into plain words). Every other extra reads files of a built-in harness or edits its config, and is for built-in manifests.
205
+
206
+ ## 4. What degrades without each field
207
+
208
+ CoCheck never refuses a harness for lacking a field; it records less, and says so. This table is what is lost.
209
+
210
+ | missing | what CoCheck does instead |
211
+ | --- | --- |
212
+ | `fields.session` | the manifest is refused: nothing can be grouped |
213
+ | `events` for the call events (`tool-pre`, `tool-post`) | L0: the session is known, no call is recorded, no file is credited |
214
+ | `fields.toolName` | calls are recorded without a name; no tool can be classed, so every call is read as an unknown tool: credited only by what changed in the folder while it was open |
215
+ | `toolClasses` entry for a tool | that tool is unknown: its input is not read (no named file, no command, no helper launch), and a change while its call is open is credited to it by inference alone; list it as `never-credited` to stop that |
216
+ | `fields.toolInput` | the call's arguments are not read: a write tool's named file and a shell call's command are unknown, and the credit rests on what changed in the folder while the call was open |
217
+ | `callId` | calls carry no id from the harness, so calls that overlap cannot be told apart; `{ "synthesized": true }` makes one per call, which is sound only for calls that do not overlap |
218
+ | `failure` | a failed call looks like one that worked, and may be credited with a change it did not make |
219
+ | `capabilities.failureEvent` false and no `tool-post` failure rule | a call that closes with no failure is taken as succeeded, though it may not have been |
220
+ | `fields.agentId`, `fields.agentType`, `fields.parentSession` | helper agents' calls are credited as the main agent's; a change by a helper is not told apart from a change by the main agent |
221
+ | `capabilities.helperSessions` false | a helper's events are not linked to the main session |
222
+ | `fields.lastAssistantMessage` | no closing message is recorded at a stop, unless a first-party extra reads it from the session file |
223
+ | `narration` | a call's words are not shown beside the call |
224
+ | `fields.cwd` | the task folder comes from the hook command (`--folder`), or from `install.projectDirEnv`; with neither, the hook has no folder |
225
+ | `fields.prompt` | the person's prompt is not recorded |
226
+ | `fields.transcriptPath` and `sessionFile` | the session file is not read: no per-call words, and no check that every call was seen |
227
+ | `fields.toolResponse` | the call's result is not kept (CoCheck reads it only to keep an MCP call's response) |
228
+ | `install` | `cocheck install --for <key>` has nothing to write; the person adds the hook entries by hand |
229
+ | `perAction` for a per-action kind | the manifest is refused: a `file-edit`, `shell-pre` or `shell-post` event needs it |
230
+
231
+ An event the harness sends that the manifest does not map is kind `other`: it is journaled and not acted on.
232
+
233
+ ## 5. Outsider policy
234
+
235
+ A manifest has two homes.
236
+
237
+ - **Your own folder.** Put it at `<CoCheck data home>/harnesses/<key>/cocheck-harness.json` (`$COCHECK_HARNESS_DIR` replaces that folder) to try a harness at once. It is loaded as an outsider.
238
+ - **A pull request.** Add it under `harnesses/<key>/` at the root of the CoCheck repository (a data folder that ships in the package; no code change) together with its recordings and cases, to ship it built in.
239
+
240
+ What a harness in your own folder gets, in v1:
241
+
242
+ - Its events never prove more than "inferred". A change is credited to that harness's call by what changed in the folder while the call was open, and never as a change the harness reported itself or one a tag proves. Built-in harnesses may earn the stronger bases (`host-reported-edit`, `argv-tag`); the same manifest, once shipped built in, may too.
243
+ - It may not tag shell calls (`argvTag`, `capabilities.argvTag`) or claim `install.inBothAlias`. A manifest that does is skipped with one plain line.
244
+ - Its `foreignHookFingerprint` (with `capabilities.readsForeignHooks`) makes another harness's hook skip a payload only while its own CoCheck hook is installed for the payload's folder: the config at `install.path` (with `{project}` set to the folder the payload names through `fields.cwd`) exists and carries CoCheck's entry for every event in `install.events`. Otherwise the payload is recorded as before. `cocheck status` names each fingerprint in force.
245
+ - `cocheck install --for <key>` prints the config path and the hook entries to add instead of editing the harness's config.
246
+ - It names only outsider-safe extras (section 3).
247
+ - Every pattern is bounded (section 3), and the text a pattern runs against is cut at 4096 characters.
248
+ - It cannot reuse a key that exists.
249
+
250
+ A manifest that does not load is skipped with one line (shown by `cocheck status`, and kept in the data home as `harness-skipped.txt` by the hook). Every other harness keeps recording.
251
+
252
+ ## 6. Cases
253
+
254
+ A case is one JSON file, `cocheck-harness-case/1`: a recorded run, the files it needs, and what CoCheck must make of it. `cocheck harness test --cases <dir> [--manifest <path>]` replays each case through the real hook path in a temporary data home and folder (your own data home and configs are never read or written), then checks the result. `--manifest` is the manifest of a harness that is not built in; the built-in harnesses use the manifests that ship.
255
+
256
+ ```json
257
+ {
258
+ "schema": "cocheck-harness-case/1",
259
+ "harness": "toyagent",
260
+ "description": "one plain sentence",
261
+ "level": "L2",
262
+ "recording": [
263
+ { "event": "beforeTool", "stdin": "<the payload text exactly as the hook received it>", "argv": ["--event", "beforeTool"] }
264
+ ],
265
+ "files": {
266
+ "before": { "data.txt": "a,b,c\n" },
267
+ "writes": [ { "afterEvent": 3, "path": "notes.txt", "content": "alpha\n" } ]
268
+ },
269
+ "expect": {
270
+ "normalized": [ { "kind": "tool-pre", "session": "s1", "toolName": "write_file" } ],
271
+ "credit": { "notes.txt": { "creditedTo": "call:<call id>", "basis": "inferred" } }
272
+ }
273
+ }
274
+ ```
275
+
276
+ - `recording`: the hook calls in order. `stdin` is the payload text; `<folder>` in it stands for the temporary task folder and `<root>` for the temporary root. `argv` holds the extra words of the hook command (the harness's `--event <name>` when its payload does not name the event).
277
+ - `files.before`: files in the task folder before the first call. `files.writes`: a file the harness's call left behind, written right after the recorded call number `afterEvent` (counting from 1), because a recording holds no file contents.
278
+ - `expect.normalized`: one entry per recorded call, in order. Each lists fields the normalized event must have (`kind`, `eventName`, `session`, `toolName`, `callId`, `agentId`, `agentType`, `prompt`, `lastAssistantMessage`, `failure`); an empty entry checks nothing for that call. An entry may list any field of the event.
279
+ - `expect.credit`: for each listed file, the call it ends up credited to (`call:<call id>`; several are joined by commas; `unattributed` when no call) and the basis (`inferred`, `host-reported-edit` or `argv-tag`). A file not listed is not checked.
280
+ - A case must credit at least one file, or say in its `description` why its level has none, using the words "no credit". A case that checks no credit gives false confidence.
281
+
282
+ `cocheck harness test` prints one line per case, `pass` or `FAIL` with the first difference in plain words, and exits non-zero if any case fails.
283
+
284
+ ## 7. Versioning
285
+
286
+ The manifest and the cases are v1. A field added later is optional. A manifest with a `schema` this CoCheck does not know is skipped with a line naming it.
@@ -33,7 +33,7 @@ if [ -z "$node" ] && [ -n "$home" ] && [ -r "$home/installed-node.txt" ]; then
33
33
  if [ -n "$candidate" ] && [ -x "$candidate" ]; then node=$candidate; fi
34
34
  fi
35
35
  if [ -z "$node" ]; then
36
- record "Node was not found. CoCheck needs Node 22.18 or newer (install it from nodejs.org), then restart Claude Code."
36
+ record "Node was not found. CoCheck needs Node 22.18 or newer (install it from nodejs.org), then restart your coding agent."
37
37
  echo "CoCheck: Node was not found, so this tool call was not recorded." >&2
38
38
  exit 1
39
39
  fi