Structured agent session logging (JSONL) with secret scrubbing

[itscooleric]

Problem

There is zero structured logging of agent activity. Once a session ends there's no record of what tools the agent called, what decisions it made, or what it cost. We can't audit, replay, or measure agent performance.

Proposed approach

Emit structured events to /home/clide/.clide/logs/<session_id>/events.jsonl:

Event types

Session envelope:

{"event":"session_start","session_id":"clide-<ulid>","repo":"itscooleric/clem","model":"claude-opus-4-5","started_at":"...","schema_version":1}

{"event":"session_end","session_id":"clide-<ulid>","outcome":"success","total_turns":42,"total_tokens_in":15000,"total_tokens_out":8000,"estimated_cost_usd":0.35,"files_changed":["src/foo.py"],"schema_version":1}

Tool calls:

{"event":"tool_call","ts":"...","session_id":"clide-<ulid>","turn":7,"tool":"bash","input":{"command":"pytest tests/ -v"},"exit_code":0,"duration_ms":4211,"schema_version":1}

Reasoning checkpoints:

{"event":"reasoning","ts":"...","session_id":"clide-<ulid>","type":"plan","content":"...","schema_version":1}

Secret scrubbing (required — formerly C-5)

All tool inputs must be scrubbed before writing to disk:

• Redact values matching [A-Z_]{3,}=\S+ heuristic (env var assignments)
• Explicit blocklist: GH_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY, CLAUDE_CODE_OAUTH_TOKEN, TTYD_PASS
• Scrub before write, never after

Implementation approach

Prerequisite spike: Verify if Claude CLI supports --output-format stream-json or similar structured output flag. If yes (Option B), parse the stream directly. If no, write a thin Python shim that wraps the agent CLI and intercepts tool calls (Option A).

Must work for both Claude and Codex CLIs — the logging mechanism should be agent-agnostic or have pluggable adapters.

Schema

Include schema_version: 1 on every event from day one. This is non-negotiable — we'll regret changing the format without versioning.

Acceptance criteria

• events.jsonl written per session with all event types above
• Secret scrubbing applied to all tool inputs before write
• schema_version field on every event
• Works for Claude CLI sessions
• Works for Codex CLI sessions (or has a clear adapter path)
• Session ID follows agreed convention (see X-1 / session_id convention)

Size

M — this is the keystone of agent observability. Everything else in v4 depends on it.

Dependencies

• X-1: Session ID convention should be agreed before this starts (XS effort)

Source: workspace/notes/research/ai_agent_logging.md, final_observability_ticket_plan.md (C-3 + C-5)

[itscooleric]

Update: structured logging spike completed (2026-03-15)

Spike result: Claude Code's --output-format stream-json

Verified that claude -p --output-format stream-json --verbose produces structured JSONL with:

• type: "system" init event (model, tools, session_id, version, permissions)
• type: "assistant" messages (thinking blocks, text content, tool calls, token usage)
• type: "result" summary (duration_ms, total_cost_usd, num_turns, stop_reason, per-model usage breakdown)

Limitation: --output-format only works with --print (non-interactive mode).

Native session logs (interactive mode)

For interactive sessions, Claude Code saves full conversation JSONL at ~/.claude/projects/<project>/<uuid>.jsonl with user messages, assistant responses (including thinking + tool_use), and tool_results.

Updated session-logger.sh to harvest these after session end — see #42 comment for details. The session_end event now includes claude_session_id and has_conversation=true when the log is captured.

Remaining work for this ticket

• Parse the harvested conversation.jsonl to emit structured events (tool_call, reasoning) into events.jsonl
• Extract token/cost from Claude's conversation data into session_end event
• Codex CLI adapter (separate agent, different output format)
• Secret scrubbing on conversation.jsonl content (Claude Code may log env var values in tool outputs)

[itscooleric]

Shipped in PR #80 (session-logger.sh with JSONL events + secret scrubbing)

[itscooleric]

Remaining #41 scope (post v4)

Session envelope logging is done and working. Three items remain from the original spec:

1. Parse conversation.jsonl → structured events in events.jsonl (M)

Currently events.jsonl only has session_start / session_end events. The original spec called for tool_call and reasoning events parsed from Claude Code's native conversation.jsonl.

Approach: Post-process conversation.jsonl at session end (in the cleanup handler of session-logger.sh). Walk the JSONL, emit:

• tool_call events (tool name, input summary, exit code, duration)
• reasoning events (plan checkpoints — optional, lower priority)

Python script alongside token-cost.py — same pattern, called from cleanup.

Blocker: None — conversation.jsonl format is stable.
Size: M (parsing logic + schema additions)

2. Codex CLI adapter (S)

Session-logger already wraps Codex (codex() in .bashrc), but conversation harvesting is Claude-specific (searches ~/.claude/projects/). Codex stores conversations differently.

Approach: Add a harvest_codex() function in session-logger.sh that finds Codex's conversation file (need to investigate Codex's output format and file locations).

Blocker: Need to determine where Codex CLI stores its conversation logs (or if it has a --output flag). Low priority until Codex sees more use.
Size: S once format is known

3. Secret scrubbing on conversation.jsonl content (S)

scrub_secrets() exists and runs on session-start command. But the copied conversation.jsonl may contain secret values in tool output (e.g., if an agent ran env or echo $GH_TOKEN).

Approach: Pipe conversation.jsonl through scrub_secrets() at copy time (both in the watcher and final cleanup copy). The function already handles the blocklist + heuristic pattern.

Blocker: None
Size: S

Priority order

1. Secret scrubbing on conversation.jsonl (S, security) — should do first
2. Structured event parsing (M, enables Clem viewer features)
3. Codex adapter (S, low urgency until Codex usage increases)