Skip to content

Commit 6513a26

Browse files
nik13claude
andcommitted
fix(hook-to-otlp): review fixes: guarded hooks, path privacy, turn parenting, root start (TH-8229)
Hooks never block the host: - Cursor hooks.json / hooks.user.json use the canonical guarded command `python3 -B <emit.py> cursor <Event> 2>/dev/null || true`; new test_cursor_hooks_config runs every shipped command through sh/zsh/bash with the emitter missing, python3 missing, and installed (exit 0, empty or expected stdout, no __pycache__). - A misregistered permission hook now prints nothing (Cursor fails open on no output) instead of answering {"permission": "allow"}. Privacy and doc truth: - Opted-in content keeps paths but replaces the user name in home paths with <user>; pages now say paths inside prompts/tool input/output are exported with content on, never as metadata. Test: error text with a path and user name is absent by default and scrubbed with content on. - State file keeps content only for open spans and turns closed as incomplete; a duplicate end of a completed turn is ignored. - Windows: inline send uses a 3 s default timeout; pages say background send and state locking are macOS/Linux only. - Cursor page: cache tokens are captured (removed from "not available"). Tree: - Tool/subagent/llm/event spans without a turn id go under the open turn and get coding_agent.turn.inferred=true (pages corrected; PRD R-02 deviation). - Children never start before the root once its start is fixed. - Subagent span key includes the turn and duration (no cross-turn overwrite). - Root model comes from session/turn/llm events only. - transcript_path test uses an unreadable canary and spies on os.open too. E2E tooling: replay --replace rewrites substrings (suffixed generation ids), run_e2e.sh gives any fixture fresh UUID ids. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 2d446bc commit 6513a26

12 files changed

Lines changed: 390 additions & 82 deletions

File tree

‎examples/coding-agents/cursor/hooks.json‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,61 +3,61 @@
33
"hooks": {
44
"sessionStart": [
55
{
6-
"command": "python3 .cursor/hooks/fi-hook-to-otlp/emit.py cursor sessionStart",
6+
"command": "python3 -B .cursor/hooks/fi-hook-to-otlp/emit.py cursor sessionStart 2>/dev/null || true",
77
"timeout": 10
88
}
99
],
1010
"beforeSubmitPrompt": [
1111
{
12-
"command": "python3 .cursor/hooks/fi-hook-to-otlp/emit.py cursor beforeSubmitPrompt",
12+
"command": "python3 -B .cursor/hooks/fi-hook-to-otlp/emit.py cursor beforeSubmitPrompt 2>/dev/null || true",
1313
"timeout": 10
1414
}
1515
],
1616
"postToolUse": [
1717
{
18-
"command": "python3 .cursor/hooks/fi-hook-to-otlp/emit.py cursor postToolUse",
18+
"command": "python3 -B .cursor/hooks/fi-hook-to-otlp/emit.py cursor postToolUse 2>/dev/null || true",
1919
"timeout": 10
2020
}
2121
],
2222
"postToolUseFailure": [
2323
{
24-
"command": "python3 .cursor/hooks/fi-hook-to-otlp/emit.py cursor postToolUseFailure",
24+
"command": "python3 -B .cursor/hooks/fi-hook-to-otlp/emit.py cursor postToolUseFailure 2>/dev/null || true",
2525
"timeout": 10
2626
}
2727
],
2828
"subagentStop": [
2929
{
30-
"command": "python3 .cursor/hooks/fi-hook-to-otlp/emit.py cursor subagentStop",
30+
"command": "python3 -B .cursor/hooks/fi-hook-to-otlp/emit.py cursor subagentStop 2>/dev/null || true",
3131
"timeout": 10
3232
}
3333
],
3434
"afterAgentThought": [
3535
{
36-
"command": "python3 .cursor/hooks/fi-hook-to-otlp/emit.py cursor afterAgentThought",
36+
"command": "python3 -B .cursor/hooks/fi-hook-to-otlp/emit.py cursor afterAgentThought 2>/dev/null || true",
3737
"timeout": 10
3838
}
3939
],
4040
"afterAgentResponse": [
4141
{
42-
"command": "python3 .cursor/hooks/fi-hook-to-otlp/emit.py cursor afterAgentResponse",
42+
"command": "python3 -B .cursor/hooks/fi-hook-to-otlp/emit.py cursor afterAgentResponse 2>/dev/null || true",
4343
"timeout": 10
4444
}
4545
],
4646
"preCompact": [
4747
{
48-
"command": "python3 .cursor/hooks/fi-hook-to-otlp/emit.py cursor preCompact",
48+
"command": "python3 -B .cursor/hooks/fi-hook-to-otlp/emit.py cursor preCompact 2>/dev/null || true",
4949
"timeout": 10
5050
}
5151
],
5252
"stop": [
5353
{
54-
"command": "python3 .cursor/hooks/fi-hook-to-otlp/emit.py cursor stop",
54+
"command": "python3 -B .cursor/hooks/fi-hook-to-otlp/emit.py cursor stop 2>/dev/null || true",
5555
"timeout": 10
5656
}
5757
],
5858
"sessionEnd": [
5959
{
60-
"command": "python3 .cursor/hooks/fi-hook-to-otlp/emit.py cursor sessionEnd",
60+
"command": "python3 -B .cursor/hooks/fi-hook-to-otlp/emit.py cursor sessionEnd 2>/dev/null || true",
6161
"timeout": 10
6262
}
6363
]

‎examples/coding-agents/cursor/hooks.user.json‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -3,61 +3,61 @@
33
"hooks": {
44
"sessionStart": [
55
{
6-
"command": "python3 ./hooks/fi-hook-to-otlp/emit.py cursor sessionStart",
6+
"command": "python3 -B ./hooks/fi-hook-to-otlp/emit.py cursor sessionStart 2>/dev/null || true",
77
"timeout": 10
88
}
99
],
1010
"beforeSubmitPrompt": [
1111
{
12-
"command": "python3 ./hooks/fi-hook-to-otlp/emit.py cursor beforeSubmitPrompt",
12+
"command": "python3 -B ./hooks/fi-hook-to-otlp/emit.py cursor beforeSubmitPrompt 2>/dev/null || true",
1313
"timeout": 10
1414
}
1515
],
1616
"postToolUse": [
1717
{
18-
"command": "python3 ./hooks/fi-hook-to-otlp/emit.py cursor postToolUse",
18+
"command": "python3 -B ./hooks/fi-hook-to-otlp/emit.py cursor postToolUse 2>/dev/null || true",
1919
"timeout": 10
2020
}
2121
],
2222
"postToolUseFailure": [
2323
{
24-
"command": "python3 ./hooks/fi-hook-to-otlp/emit.py cursor postToolUseFailure",
24+
"command": "python3 -B ./hooks/fi-hook-to-otlp/emit.py cursor postToolUseFailure 2>/dev/null || true",
2525
"timeout": 10
2626
}
2727
],
2828
"subagentStop": [
2929
{
30-
"command": "python3 ./hooks/fi-hook-to-otlp/emit.py cursor subagentStop",
30+
"command": "python3 -B ./hooks/fi-hook-to-otlp/emit.py cursor subagentStop 2>/dev/null || true",
3131
"timeout": 10
3232
}
3333
],
3434
"afterAgentThought": [
3535
{
36-
"command": "python3 ./hooks/fi-hook-to-otlp/emit.py cursor afterAgentThought",
36+
"command": "python3 -B ./hooks/fi-hook-to-otlp/emit.py cursor afterAgentThought 2>/dev/null || true",
3737
"timeout": 10
3838
}
3939
],
4040
"afterAgentResponse": [
4141
{
42-
"command": "python3 ./hooks/fi-hook-to-otlp/emit.py cursor afterAgentResponse",
42+
"command": "python3 -B ./hooks/fi-hook-to-otlp/emit.py cursor afterAgentResponse 2>/dev/null || true",
4343
"timeout": 10
4444
}
4545
],
4646
"preCompact": [
4747
{
48-
"command": "python3 ./hooks/fi-hook-to-otlp/emit.py cursor preCompact",
48+
"command": "python3 -B ./hooks/fi-hook-to-otlp/emit.py cursor preCompact 2>/dev/null || true",
4949
"timeout": 10
5050
}
5151
],
5252
"stop": [
5353
{
54-
"command": "python3 ./hooks/fi-hook-to-otlp/emit.py cursor stop",
54+
"command": "python3 -B ./hooks/fi-hook-to-otlp/emit.py cursor stop 2>/dev/null || true",
5555
"timeout": 10
5656
}
5757
],
5858
"sessionEnd": [
5959
{
60-
"command": "python3 ./hooks/fi-hook-to-otlp/emit.py cursor sessionEnd",
60+
"command": "python3 -B ./hooks/fi-hook-to-otlp/emit.py cursor sessionEnd 2>/dev/null || true",
6161
"timeout": 10
6262
}
6363
]

‎examples/coding-agents/cursor/run_e2e.sh‎

Lines changed: 22 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,15 @@
22
# Drive the real emitter with Cursor hook payloads into a Future AGI collector.
33
#
44
# FI_API_KEY=... FI_SECRET_KEY=... FI_BASE_URL=http://localhost:14338 \
5-
# FI_PROJECT_NAME=cursor-e2e ./run_e2e.sh [fixture.jsonl]
5+
# FI_PROJECT_NAME=cursor-e2e ./run_e2e.sh [fixture.jsonl] [replay.py args...]
66
#
77
# Default input is the documented-shape session in
88
# ../hook-to-otlp/tests/fixtures/cursor/session.jsonl. Each line runs
99
# emit.py as its own process, exactly as Cursor runs a hook command. Every
10-
# run gets a fresh conversation id, printed at the end with its trace id.
10+
# run replaces the fixture's conversation_id and generation_id with fresh
11+
# UUIDs (Cursor's own id shape, so suffixed generation ids such as
12+
# "<id>-0-ab12" still pair up), printed at the end with the trace id.
13+
# Extra arguments go to replay.py (for example --replace MARKER=my-marker).
1114
# Set FI_HOOK_CAPTURE_CONTENT=1 to exercise the content opt-in.
1215
# REPLAY_SLEEP (default 1s) spaces the hooks out so the fixture's reported
1316
# tool durations fit inside the turn, as they would in a real session.
@@ -16,15 +19,25 @@ set -euo pipefail
1619
HERE="$(cd "$(dirname "$0")" && pwd)"
1720
EMITTER="$HERE/../hook-to-otlp"
1821
FIXTURE="${1:-$EMITTER/tests/fixtures/cursor/session.jsonl}"
22+
shift || true
1923
: "${FI_API_KEY:?set FI_API_KEY}" "${FI_SECRET_KEY:?set FI_SECRET_KEY}"
2024
export FI_PROJECT_NAME="${FI_PROJECT_NAME:-cursor-e2e}"
2125

22-
RUN_ID="cursor-e2e-$(date +%Y%m%d%H%M%S)-$$"
23-
python3 "$EMITTER/replay.py" cursor "$FIXTURE" \
24-
--replace "fixture-conv-0001=$RUN_ID" \
25-
--replace "fixture-gen-0001=$RUN_ID-gen-1" \
26-
--sleep "${REPLAY_SLEEP:-1}"
26+
# The fixture's own ids (first record), and fresh UUIDs to replace them with.
27+
read -r SRC_CONV SRC_GEN CONV GEN < <(python3 -B - "$FIXTURE" <<'PY'
28+
import json, re, sys, uuid
29+
payload = json.loads(open(sys.argv[1], encoding="utf-8").readline())["payload"]
30+
conv = payload.get("conversation_id") or payload.get("session_id")
31+
gen = re.sub(r"-\d+-[a-z0-9]{4}$", "", str(payload.get("generation_id") or "-"))
32+
print(conv, gen, uuid.uuid4(), uuid.uuid4())
33+
PY
34+
)
2735

28-
TRACE_ID="$(cd "$EMITTER" && python3 -c 'import sys, emit; print(emit.trace_id("cursor", sys.argv[1]))' "$RUN_ID")"
29-
echo "conversation_id=$RUN_ID"
36+
REPLACE=(--replace "$SRC_CONV=$CONV")
37+
if [ "$SRC_GEN" != "-" ]; then REPLACE+=(--replace "$SRC_GEN=$GEN"); fi
38+
python3 -B "$EMITTER/replay.py" cursor "$FIXTURE" "${REPLACE[@]}" \
39+
--sleep "${REPLAY_SLEEP:-1}" ${@+"$@"}
40+
41+
TRACE_ID="$(cd "$EMITTER" && python3 -B -c 'import sys, emit; print(emit.trace_id("cursor", sys.argv[1]))' "$CONV")"
42+
echo "conversation_id=$CONV"
3043
echo "trace_id=$TRACE_ID"

‎examples/coding-agents/hook-to-otlp/README.md‎

Lines changed: 35 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,28 @@ echo '{"conversation_id":"c1","generation_id":"g1","tool_name":"Shell","duration
2424

2525
`python3 emit.py <app> [<event>] [--env-file PATH]` reads one JSON object on
2626
stdin, prints what the host expects on stdout (`{}` unless the adapter says
27-
otherwise), and always exits 0. The network send happens in a detached child
28-
process so the host is not kept waiting.
27+
otherwise), and always exits 0. On macOS and Linux the network send happens in a
28+
detached child process so the host is not kept waiting. Windows has no fork: the
29+
send is inline (default timeout 3 s) and state files are not locked.
30+
31+
### Registering the hook (canonical guarded form)
32+
33+
Every app ships its hook commands in this form, so a missing emitter, a missing
34+
`python3`, or a crash can never return exit code 2 (which many hosts treat as
35+
"block") and never prints a decision:
36+
37+
```bash
38+
python3 -B <path-to>/emit.py <app> <EventName> 2>/dev/null || true
39+
```
40+
41+
`|| true` makes every failure exit 0 with empty stdout; `2>/dev/null` keeps Python's
42+
own error text out of host logs (the emitter never writes to stderr); `-B` keeps
43+
`__pycache__` out of the customer's repo. Pass the event name explicitly. Do not add
44+
`echo` fallbacks (a second JSON object is invalid output). The form needs a POSIX shell;
45+
document the equivalent on hosts whose hook runner is not one. Add a config test like
46+
`tests/test_cursor_hooks_config.py`: run every shipped command through `sh -c` with the
47+
emitter missing, with `python3` missing, and installed, and assert exit 0 plus the
48+
expected (or empty) stdout.
2949

3050
| Variable | Default | Meaning |
3151
| --- | --- | --- |
@@ -35,9 +55,9 @@ process so the host is not kept waiting.
3555
| `FI_OTLP_ENDPOINT` | none | Full traces URL; overrides `FI_BASE_URL`. |
3656
| `FI_HOOK_CAPTURE_CONTENT` | off | `1` exports prompts, tool input/output, model text, error text. |
3757
| `FI_HOOK_MAX_CONTENT_CHARS` | `4096` | Per-field cap when content is on. |
38-
| `FI_HOOK_TIMEOUT` | `10` | HTTP timeout in seconds (the send runs in a detached process, so the host never waits on it). |
58+
| `FI_HOOK_TIMEOUT` | `10` (`3` without `fork`, i.e. Windows) | HTTP timeout in seconds. On macOS/Linux the send runs in a detached process, so the host never waits on it; on Windows it is inline. |
3959
| `FI_HOOK_SYNC` | off | `1` sends inline instead of in a detached child (tests, debugging). |
40-
| `FI_HOOK_STATE_DIR` | `$TMPDIR/fi-hook-to-otlp-<uid>` | Per-session state files (0600, removed at session end, swept after 24 h). |
60+
| `FI_HOOK_STATE_DIR` | `$TMPDIR/fi-hook-to-otlp-<uid>` | Per-session state files (0600, removed at session end, swept after 24 h). With content on they also hold the content of spans that have not ended yet (for example the open turn's prompt) and of up to 8 turns closed as incomplete; completed turns keep no content. |
4161
| `FI_HOOK_LOG_FILE` | none | One line per hook: event, span count, HTTP status. No content, no keys. |
4262
| `FI_HOOK_DUMP_FILE` | none | Appends each OTLP/JSON body exactly as sent (privacy checks). |
4363
| `FI_HOOK_DISABLED` | off | `1` turns the hook into a no-op. |
@@ -57,7 +77,10 @@ process so the host is not kept waiting.
5777
- Trace id = `sha256("trace", app, session_id)[:32]`; span ids are derived from
5878
`(app, session_id, scope, key)`, so retries of the same hook overwrite rather than duplicate.
5979
- A span's start is the matching START hook if one was seen, else `end - duration_ms`
60-
from the payload, else the hook time. A turn opens on the first event that names it.
80+
from the payload, else the hook time, never earlier than the root's start once the
81+
root has been sent. A turn opens on the first event that names it.
82+
- A tool/subagent/llm/event span without `turn_id` goes under the open turn and gets
83+
`coding_agent.turn.inferred=true`; with no open turn it goes under the session.
6184
- A turn end closes still-open children of that turn (`coding_agent.incomplete=true`);
6285
a session end closes everything and deletes the state file.
6386
- One turn is open per session: a turn START closes any other open turn (and its
@@ -66,7 +89,10 @@ process so the host is not kept waiting.
6689
- Every span carries `session.id`, `gen_ai.conversation.id`, `coding_agent.app`,
6790
`coding_agent.scope`, `coding_agent.hook.event`, and `coding_agent.turn.id` when known.
6891
Tool spans add `gen_ai.tool.name` and `gen_ai.tool.call.id`; session/turn/llm/subagent
69-
spans add `llm.model_name` when the payload names a model.
92+
spans add `llm.model_name` when the payload names a model (the root uses the last model
93+
reported by a session, turn or llm event).
94+
- Opted-in content keeps paths but replaces the user name in home-directory paths with
95+
`<user>` (`/Users/<user>/...`, `/home/<user>/...`, `C:\Users\<user>\...`).
7096

7197
## Writing an adapter
7298

@@ -119,7 +145,9 @@ input=None, output=None, error_message=None)`:
119145
`<app>.*`. Never emails, file paths, transcript paths, or text bodies.
120146

121147
Do not wire the emitter to hooks whose output decides whether the agent may act
122-
(permission hooks): the emitter observes, it does not approve.
148+
(permission hooks): the emitter observes, it does not approve. If an app requires an
149+
answer on such a hook, `respond()` must not approve; return `""` (print nothing) when
150+
the app treats no output as "no decision", as the Cursor adapter does.
123151

124152
Add `tests/fixtures/<app>/session.jsonl` (`{"event": ..., "payload": ...}` per line,
125153
shaped exactly like the vendor docs) and `tests/test_<app>_adapter.py`. The Cursor

‎examples/coding-agents/hook-to-otlp/adapters/cursor.py‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@
99
Mapped events (all non-permission hooks, so the emitter never decides
1010
whether Cursor may run something):
1111
12-
sessionStart -> session start (root span exported, re-exported later)
12+
sessionStart -> session start (nothing exported until a child span is sent)
1313
beforeSubmitPrompt -> turn start prompt = content
1414
postToolUse -> tool span start = end - duration
1515
postToolUseFailure -> tool span, ERROR status message = failure_type
@@ -51,8 +51,12 @@
5151
DISPLAY_NAME = "Cursor"
5252
SERVICE_NAME = "cursor"
5353

54-
# Cursor blocks permission hooks on invalid output; this emitter is not
55-
# meant to be wired to them, and answers neutrally if it is.
54+
# The emitter is not registered on these (it observes, it never decides).
55+
# If it is wired to one by mistake it prints nothing: Cursor treats a hook
56+
# with no output as failed and lets the action through (fail-open unless the
57+
# hook sets failClosed), the same as a missing emitter. It never answers
58+
# "allow" (that could approve an action) and never prints "{}" (invalid for a
59+
# permission hook, which blocks the action).
5660
PERMISSION_HOOKS = {
5761
"preToolUse", "beforeShellExecution", "beforeMCPExecution",
5862
"beforeReadFile", "beforeTabFileRead", "subagentStart",
@@ -67,7 +71,7 @@ def respond(event: str, payload: Dict[str, Any]) -> str:
6771
if event == "beforeSubmitPrompt":
6872
return '{"continue": true}'
6973
if event in PERMISSION_HOOKS:
70-
return '{"permission": "allow"}'
74+
return ""
7175
return "{}"
7276

7377

@@ -237,7 +241,8 @@ def parse(event: str, payload: Dict[str, Any]) -> List[SpanEvent]:
237241
modified = payload.get("modified_files")
238242
return [SpanEvent(
239243
END, SUBAGENT, sid,
240-
key=_digest(subagent_type, payload.get("task"), payload.get("description")),
244+
key=_digest(subagent_type, turn, payload.get("duration_ms"),
245+
payload.get("task"), payload.get("description")),
241246
turn_id=turn,
242247
name=f"Subagent: {subagent_type}",
243248
duration_ms=number(payload.get("duration_ms")),

0 commit comments

Comments
 (0)