@threadcrumbs/common 0.1.2 → 0.1.4

package/lib/tool-kinds.mjs

@@ -0,0 +1,256 @@
+export const TOOL_KINDS = Object.freeze([
+  'read',
+  'search',
+  'edit',
+  'delete',
+  'move',
+  'execute',
+  'think',
+  'fetch',
+  'agent',
+  'plan',
+  'communicate',
+  'switch_mode',
+  'other',
+])
+
+const NAMES = {
+  read: [
+    'read', 'notebookread', 'read_file', 'read_many_files', 'view', 'view_file', 'view_file_outline', 'view_code_item',
+    'view_image', 'todoread', 'cat',
+  ],
+  search: [
+    'grep', 'glob', 'ls', 'list', 'list_dir', 'list_directory', 'search_file_content', 'search_files', 'grep_search',
+    'find_by_name', 'codesearch', 'file_search', 'codebase_search',
+  ],
+  edit: [
+    'edit', 'multiedit', 'write', 'notebookedit', 'apply_patch', 'applypatch', 'patch', 'create', 'write_file', 'replace',
+    'str_replace', 'strreplace', 'write_to_file', 'replace_file_content', 'multi_replace_file_content', 'search_replace',
+  ],
+  delete: ['delete', 'delete_file'],
+  move: ['move', 'move_file', 'rename', 'rename_file'],
+  execute: [
+    'bash', 'powershell', 'shell', 'exec_command', 'write_stdin', 'run_shell_command', 'run_command', 'terminal',
+    'execute_code', 'process', 'bashoutput', 'killshell', 'command_status', 'send_command_input', 'local_shell',
+  ],
+  think: ['think', 'save_memory', 'memory', 'report_intent'],
+  fetch: [
+    'webfetch', 'websearch', 'web_fetch', 'web_search', 'google_web_search', 'web_extract', 'read_url_content',
+    'search_web', 'fetch',
+  ],
+  agent: ['agent', 'task', 'spawn_agent', 'wait_agent', 'send_input', 'delegate_task', 'subagent'],
+  plan: ['todowrite', 'todo_write', 'update_plan', 'write_todos', 'todo', 'todo_list', 'task_boundary'],
+  communicate: ['askuserquestion', 'ask_user', 'request_user_input', 'request_permissions', 'question', 'clarify', 'notify_user'],
+  switch_mode: ['enterplanmode', 'exitplanmode', 'switch_mode'],
+}
+
+const KIND_OF = new Map(Object.entries(NAMES).flatMap(([kind, names]) => names.map((name) => [name, kind])))
+
+const PREFIXES = [
+  [/^browser_/, 'fetch'],
+  [/^web_/, 'fetch'],
+]
+
+const normalize = (name) => String(name || '').trim().toLowerCase().replace(/[\s-]+/g, '_')
+
+export function mcpServer(name) {
+  return /^mcp__(.+?)__./.exec(String(name || ''))?.[1] || null
+}
+
+export function nameKind(name) {
+  if (mcpServer(name)) return 'other'
+  const key = normalize(name)
+  return KIND_OF.get(key) || PREFIXES.find(([re]) => re.test(key))?.[1] || 'other'
+}
+
+const READS = /^(cat|head|tail|less|more|bat|nl|wc|type|get-content|gc)$/
+const SEARCHES = /^(rg|grep|egrep|fgrep|ag|ack|findstr|select-string|sls|ls|dir|tree|fd|get-childitem|gci)$/
+const DELETES = /^(rm|rmdir|del|erase|remove-item|ri)$/
+const MOVES = /^(mv|move|move-item|rename-item|ren)$/
+const FILTERS = /^(head|tail|sort|uniq|wc|cut|tr|grep|rg|findstr|select-string|sls|select-object|select|measure-object|measure|sort-object|less|more|cat|nl)$/
+const GIT_KINDS = { show: 'read', diff: 'read', log: 'read', status: 'read', blame: 'read', grep: 'search', 'ls-files': 'search', rm: 'delete', mv: 'move' }
+const QUIET_TARGET = /^(\/dev\/null|\$null|nul)$/i
+
+function splitCommand(command) {
+  const steps = [{ words: [], piped: false }]
+  let word = ''
+  let quote = ''
+  let unsafe = false
+  const pushWord = () => {
+    if (word) steps.at(-1).words.push(word)
+    word = ''
+  }
+  const pushStep = (join) => {
+    pushWord()
+    steps.push({ words: [], piped: join === 'pipe' })
+  }
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i]
+    const next = command[i + 1]
+    if (quote === "'") {
+      if (c === "'") quote = ''
+      else word += c
+      continue
+    }
+    if (c === '`' || (c === '$' && next === '(')) unsafe = true
+    if (quote === '"') {
+      if (c === '"') quote = ''
+      else if (c === '\\' && next) word += command[++i]
+      else word += c
+      continue
+    }
+    if (c === "'" || c === '"') {
+      quote = c
+      continue
+    }
+    if (c === '\\' && next && next !== '\n') {
+      word += command[++i]
+      continue
+    }
+    if ((c === '<' || c === '>') && next === '(') {
+      unsafe = true
+      continue
+    }
+    if (c === '<') {
+      pushWord()
+      continue
+    }
+    if (c === '>') {
+      if (/^\d*$/.test(word)) word = ''
+      else pushWord()
+      const rest = /^>?(&\d|\s*([^\s;&|<>]+))?/.exec(command.slice(i + 1))
+      if (!rest[1]?.startsWith('&') && !QUIET_TARGET.test(rest[2] || '')) unsafe = true
+      i += rest[0].length
+      continue
+    }
+    if (c === '&' && next === '&') {
+      pushStep('and')
+      i++
+      continue
+    }
+    if (c === '|' && next === '|') {
+      pushStep('or')
+      i++
+      continue
+    }
+    if (c === '|') {
+      pushStep('pipe')
+      continue
+    }
+    if (c === ';' || c === '\n') {
+      pushStep('then')
+      continue
+    }
+    if (c === '&') {
+      unsafe = true
+      continue
+    }
+    if (/\s/.test(c)) {
+      pushWord()
+      continue
+    }
+    word += c
+  }
+  pushWord()
+  if (quote) unsafe = true
+  return { steps: steps.filter((s) => s.words.length), unsafe }
+}
+
+const SED_ADDRESS = String.raw`(?:\d+(?:~\d+)?|\$|\/(?:[^\/\\]|\\.)*\/[IM]*)`
+const SED_PRINT = new RegExp(String.raw`^(?:${SED_ADDRESS}(?:,(?:${SED_ADDRESS}|[+~]\d+))?)?\s*!?\s*p$`)
+const SED_FLAGS = /^(-[nEruzs]+|--(quiet|silent|regexp-extended|separate|unbuffered|null-data|posix|debug|sandbox))$/
+
+function sedOnlyPrints(args) {
+  const scripts = []
+  let script = null
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '-e' || arg === '--expression') scripts.push(args[++i] ?? '')
+    else if (arg.startsWith('--expression=')) scripts.push(arg.slice('--expression='.length))
+    else if (SED_FLAGS.test(arg)) continue
+    else if (arg.startsWith('-') && arg !== '-') return false
+    else if (!scripts.length && script == null) script = arg
+  }
+  if (script != null) scripts.push(script)
+  const parts = scripts.flatMap((s) => s.split(';')).map((s) => s.trim()).filter(Boolean)
+  return parts.length > 0 && parts.every((part) => SED_PRINT.test(part))
+}
+
+function positionals(args, valued) {
+  const out = []
+  for (let i = 0; i < args.length; i++) {
+    if (valued.test(args[i])) i++
+    else if (args[i] === '-' || !args[i].startsWith('-')) out.push(args[i])
+  }
+  return out
+}
+
+const WRITES_OR_RUNS = {
+  find: (args) => args.some((a) => /^-(exec|execdir|ok|okdir|delete|fprint|fprint0|fprintf|fls)$/.test(a)),
+  fd: (args) => args.some((a) => /^--exec(-batch)?(=|$)/.test(a) || /^-[^-]*[xX]/.test(a)),
+  rg: (args) => args.some((a) => /^--pre(=|$)/.test(a)),
+  tree: (args) => args.some((a) => /^-o/.test(a) || a === '-R'),
+  less: (args) => args.some((a) => /^-[oO]|^--(log-file|LOG-FILE)(=|$)/.test(a)),
+  sort: (args) => args.some((a) => /^-[^-]*o/.test(a) || /^--output(=|$)/.test(a)),
+  uniq: (args) => positionals(args, /^-[fsw]$/).length > 1,
+}
+
+function gitArgs(args) {
+  let i = 0
+  while (i < args.length) {
+    if (args[i] === '-C') i += 2
+    else if (args[i] === '--no-pager') i++
+    else break
+  }
+  return args.slice(i)
+}
+
+function stepKind(words) {
+  const [first, ...args] = words
+  const verb = first.toLowerCase().replace(/\.exe$/, '')
+  if (verb === 'git') {
+    const [sub, ...rest] = gitArgs(args)
+    return rest.some((a) => a.startsWith('--output')) ? null : GIT_KINDS[String(sub || '').toLowerCase()] || null
+  }
+  if (verb === 'sed') return sedOnlyPrints(args) ? 'read' : null
+  if (WRITES_OR_RUNS[verb]?.(args)) return null
+  if (verb === 'find') return 'search'
+  if (READS.test(verb)) return 'read'
+  if (SEARCHES.test(verb)) return 'search'
+  if (DELETES.test(verb)) return 'delete'
+  if (MOVES.test(verb)) return 'move'
+  return null
+}
+
+function isFilter(words) {
+  const [first, ...args] = words
+  const verb = first.toLowerCase()
+  return FILTERS.test(verb) && !WRITES_OR_RUNS[verb]?.(args)
+}
+
+export function shellKind(command) {
+  const source = String(command || '').trim()
+  if (!source) return 'execute'
+  const { steps, unsafe } = splitCommand(source)
+  if (unsafe || !steps.length) return 'execute'
+  const kinds = []
+  for (const { words, piped } of steps) {
+    if (piped) {
+      if (!isFilter(words)) return 'execute'
+      continue
+    }
+    if (/^(cd|pushd|popd|set-location|sl|chdir)$/i.test(words[0])) continue
+    const kind = stepKind(words)
+    if (!kind) return 'execute'
+    kinds.push(kind)
+  }
+  if (!kinds.length) return 'execute'
+  return kinds.every((k) => k === kinds[0]) ? kinds[0] : 'execute'
+}
+
+export function toolKind(name, command = null) {
+  const kind = nameKind(name)
+  const server = mcpServer(name)
+  if (kind !== 'execute' || command == null) return { kind, server }
+  return { kind: shellKind(command), server }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threadcrumbs/common",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "type": "module",
   "description": "Code the Threadcrumbs apps share, starting with the readers for each coding-agent harness.",
   "license": "SEE LICENSE IN LICENSE.md",

package/telemetry/HARNESS-NOTES.md

@@ -0,0 +1,246 @@
+# Harness notes
+
+What each harness saves of its reasoning and replies, what hooks it offers to other programs,
+and how much of its context it keeps free for compacting. The readers use the first two; the
+hooks are for apps that answer or message agents, whose code stays out of these readers.
+
+Each section says which version was checked and when. Formats change between versions, so
+recheck a fact before relying on it again.
+
+## Claude Code
+
+Checked against Claude Code 2.1.287 to 2.1.317 and its docs, 2026-11-08.
+
+- **Thoughts:** `thinking` blocks in assistant records, timed by the record's `timestamp`.
+  Claude 5 models usually write them with no text, only a `signature` that holds the encrypted
+  reasoning: the API's `thinking.display` defaults to `omitted` for them, and `updates` also
+  leaves the reasoning empty. Text is there only when the API returned a summary. The record's
+  `thinkingDisplay` field (`summarized`, `updates`, or absent) isn't documented.
+  `redacted_thinking` blocks hold no text either.
+- **Replies:** `text` blocks in assistant records. Each content block is its own record, and the
+  blocks of one reply share `message.id`.
+- **What a request held:** recent versions write it into the transcript. None of it is
+  documented. The attachments below were seen from 2.1.287 and `api-request-shape` from 2.1.301:
+  - `api-request-shape`: the system prompt's text and every tool definition loaded, written
+    again when the set changes (`shapeHash`).
+  - Attachments: `instructions` (memory files, with path, type, and text), `skill_listing`
+    (skill names and the listing's text), `deferred_tools_delta` (deferred tool names, with MCP
+    tools as `mcp__<server>__<tool>`), `mcp_instructions_delta` (server names and their
+    instructions), and `agent_listing_delta` (custom agents). After a compaction they're written
+    again, marked `isInitial`.
+- **`/context`:** the docs don't say its output reaches the transcript, and no transcript with
+  it has been checked. The 2.1.319 changelog mentions a table form that Claude reads.
+- **Kept free for compacting:** about 33,000 tokens by default. The docs say 1M-window models
+  compact at about 967K. The `autoCompactWindow` setting, `CLAUDE_CODE_AUTO_COMPACT_WINDOW`,
+  `--autocompact`, and `/autocompact` change it.
+- **Hooks:** 33 events, each a command or `type: "http"` with `url`, `headers`, `timeout`, and
+  `onFailure`.
+  - Answering a permission request: a `PermissionRequest` hook returns
+    `hookSpecificOutput.decision.behavior`, `allow` or `deny`. Deny rules still win.
+  - A message when a turn ends: a `Stop` hook returns `decision: "block"` with a `reason`, and
+    the agent carries on with it.
+  - Hooks fire in the CLI, the IDE extensions, and the desktop app; cloud sessions don't read
+    local settings. They're set in user, project, or local settings, and edits are picked up
+    without a restart.
+- **Sources:** <https://code.claude.com/docs/en/hooks>,
+  <https://code.claude.com/docs/en/model-config>,
+  <https://platform.claude.com/docs/en/build-with-claude/thinking>.
+
+## Codex
+
+Checked against Codex 0.166 rollouts and openai/codex `main`, 2026-11-08. Rollouts come in two
+modes, `paginated` and the older default; the records below are in both.
+
+- **Thoughts:** `response_item` of type `reasoning`: `summary` is a list of `summary_text`
+  parts, timed by the record's `timestamp`. A summary can be empty. `encrypted_content` is the
+  full reasoning, encrypted. `content` holds raw reasoning only for models that return it.
+  Copies to skip: `event_msg` `agent_reasoning` (older mode) and `item_completed` with a
+  `Reasoning` item (paginated mode), which adds start and end times.
+- **Replies:** `response_item` of type `message` with role `assistant`: `content` is a list of
+  `output_text` parts, and `phase` is `commentary` or `final_answer`. Copies to skip:
+  `agent_message`, `item_completed` with an `AgentMessage` item, and
+  `task_complete.last_agent_message`.
+- **What a request held:** `session_meta.base_instructions` and the `developer` messages are the
+  system prompt; a user message starting `# AGENTS.md instructions` carries AGENTS.md;
+  `additional_tools` items list the MCP and app tools by namespace. Built-in tool definitions
+  aren't written.
+- **Kept free for compacting:** Codex compacts at 90% of the model's window, and rollouts report
+  95% of it as `model_context_window`, so compaction comes at about 94.7% of the reported window.
+  `model_auto_compact_token_limit` can only lower it. (`codex-rs/protocol/src/openai_models.rs`)
+- **Hooks:** on by default, set in `~/.codex/hooks.json`, `[hooks]` in `config.toml`, a trusted
+  project's `.codex/`, or plugins. A hook is a command (JSON on stdin and stdout, exit 2 blocks)
+  or an MCP tool call, and must be trusted in `/hooks`; a changed hook must be trusted again.
+  - Events: SessionStart, SessionEnd, SubagentStart, SubagentStop, UserPromptSubmit,
+    PreToolUse, PermissionRequest, PostToolUse, PreCompact, PostCompact, Stop, Interrupt,
+    PreModelRequest, PostModelRequest.
+  - Answering a permission request: `PermissionRequest` returns
+    `hookSpecificOutput.decision.behavior`, `allow` or `deny`, with a `message`.
+  - A message when a turn ends: `Stop` returns `decision: "block"` with a `reason`, which becomes
+    the next prompt.
+  - The older `notify` setting runs a command once a turn ends, with the thread, turn, and last
+    reply as JSON; it can't answer.
+  - Whether editing `hooks.json` takes effect without a restart isn't documented.
+- **Sources:** `codex-rs/protocol/src/models.rs`, `codex-rs/protocol/src/protocol.rs`,
+  `codex-rs/hooks/`, <https://learn.chatgpt.com/docs/hooks>.
+
+## Gemini CLI
+
+Not read yet. Checked against google-gemini/gemini-cli `main`, 2026-11-08.
+
+- **Thoughts:** chats are `~/.gemini/tmp/<project>/chats/session-<time>-<id>.jsonl`. A record
+  with `type: "gemini"` has `thoughts: [{ subject, description, timestamp }]`, the API's thought
+  summaries. They're stamped when the reply finishes, so their time is about the reply's.
+- **Replies:** the same record's `content`, timed by its `timestamp`. Other lines are `$set`,
+  `$rewindTo`, and `$patch`.
+- **Kept free for compacting:** Gemini CLI compresses at 50% of the model's limit
+  (`model.compressionThreshold`) and keeps the newest 30%.
+- **Hooks:** set under `hooks` in settings (project, `~/.gemini`, system, or extensions), as
+  commands only, on by default. Events: BeforeTool, AfterTool, BeforeAgent, AfterAgent,
+  BeforeModel, AfterModel, BeforeToolSelection, SessionStart, SessionEnd, Notification,
+  PreCompress.
+  - Answering a permission request: no. BeforeTool can deny or ask, but `allow` doesn't skip the
+    prompt.
+  - A message when a turn ends: AfterAgent returns `decision: "deny"` with a `reason`, sent as a
+    new prompt.
+- **Sources:** `packages/core/src/services/chatRecordingService.ts`,
+  `packages/core/src/services/chatCompressionService.ts`, `packages/core/src/hooks/types.ts`.
+
+## Copilot CLI
+
+Not read yet. Checked against the github/copilot-sdk event types and GitHub's docs, 2026-11-08.
+
+- **Thoughts:** `~/.copilot/session-state/<id>/events.jsonl`, one `{ type, data, id, parentId,
+  timestamp }` per line. `assistant.message` has `data.reasoningText` beside an encrypted copy
+  (`reasoningOpaque`, or `encryptedContent` for OpenAI models). The SDK also defines
+  `assistant.reasoning` events. Whether the text is full reasoning or a summary isn't documented.
+- **Replies:** `assistant.message` `data.content`, empty on steps that only call tools.
+- **Kept free for compacting:** background compaction starts at about 80% of the window and the
+  CLI waits for it at about 95%, so about 20% is kept free.
+- **Hooks:** set in `~/.copilot/hooks/*.json`, `.github/hooks/*.json`, or `hooks` in settings,
+  as a command, `http` (HTTPS only; localhost needs `COPILOT_HOOK_ALLOW_LOCALHOST=1`), or a
+  prompt at session start. A hook that times out (30 seconds) lets things go on.
+  - Answering a permission request: `permissionRequest` returns `behavior`, `allow` or `deny`.
+  - A message when a turn ends: `agentStop` returns `decision: "block"` with a `reason`, which
+    becomes the next prompt, at most 8 times in a row.
+- **Sources:** <https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-hooks-reference>,
+  `nodejs/src/types.ts` and `session-events.ts` in github/copilot-sdk.
+
+## Cursor
+
+Checked against Cursor's docs and staff answers on its forum, 2026-11-08. Not checked on an
+install.
+
+- **Thoughts:** not saved apart from the reply. Agent transcripts write the thinking and the reply
+  into one `text` block on purpose, so they can't be told apart. The `afterAgentThought` hook
+  gets the thinking, in the IDE only.
+- **Replies:** `{ role: "assistant", message: { content: [...] } }` with `text` and `tool_use`
+  blocks. Replies and tool calls carry no time and no tool results; only prompts have a
+  `<timestamp>` tag. Newer transcripts don't write `turn_ended`.
+- **Kept free for compacting:** not documented. The `preCompact` hook is told the context's use,
+  size, and window when it fires.
+- **Hooks:** `hooks.json` in `~/.cursor/`, a project's `.cursor/`, or enterprise settings,
+  reloaded when saved. Each hook is a command, with JSON on stdin and stdout, and every payload
+  includes `transcript_path`.
+  - Answering a permission request: `beforeShellExecution`, `beforeMCPExecution`, and
+    `preToolUse` return `permission`, `allow`, `deny`, or `ask` (`ask` isn't enforced in
+    `preToolUse`).
+  - A message when a turn ends: `stop` and `subagentStop` return `followup_message`, which Cursor
+    sends on its own, up to `loop_limit` (5) times.
+  - Others: `sessionStart`, `sessionEnd`, `postToolUse`, `afterAgentResponse`, `preCompact`.
+- **Sources:** <https://cursor.com/docs/agent/hooks>, Cursor forum threads 161788 (2026-05-28)
+  and 166592 (2026-07-26).
+
+## Antigravity CLI
+
+Checked against Antigravity's docs and open-source tools that parse its files, 2026-11-08. Not
+checked on an install, and its own format isn't documented.
+
+- **Thoughts:** `PLANNER_RESPONSE` steps carry an optional `thinking` string, timed by
+  `created_at`. Whether it's the full thinking or a summary isn't known.
+- **Replies:** the same steps' `content`. `transcript.jsonl` cuts long fields and lists them in
+  `truncated_fields`; `transcript_full.jsonl` keeps them whole.
+- **Kept free for compacting:** not documented. `CHECKPOINT` steps seem to mark compactions.
+- **Hooks:** `.agents/hooks.json` in a project, `~/.gemini/config/hooks.json`, or a plugin's
+  `hooks.json`. Commands only, with camelCase JSON on stdin and stdout and a 30-second timeout.
+  - Answering a permission request: `PreToolUse` returns `decision`: `allow`, `deny`, `ask`, or
+    a stronger form such as `auto_approve`.
+  - A message when a turn ends: `Stop` returns `decision: "continue"` with a `reason`, added as a
+    system message.
+  - Others: `SessionStart`, `PostToolUse`, `PreInvocation`, `PostInvocation`. Payloads include
+    `transcriptPath`.
+- **Sources:** <https://antigravity.google/docs/hooks?tab=cli>, Heeler issue 644 and
+  cli-sessionr pull request 17 for the step fields.
+
+## Hermes
+
+Checked against NousResearch/hermes-agent at commit `0b82ddc`, 2026-11-08.
+
+- **Thoughts:** the `messages` table's `reasoning` column, the raw reasoning text for providers
+  that return it, or `reasoning_content`. A reply that is only reasoning has empty `content`.
+  `reasoning_details` and `codex_reasoning_items` are JSON that holds the providers' encrypted
+  state. Timed by the row's `timestamp`, in epoch seconds.
+- **Replies:** an assistant row's `content`, with `finish_reason` and `timestamp`. A reply through
+  the Responses API can sit in `codex_message_items` instead.
+- **Kept free for compacting:** it compacts at 50% of the window, raised to 75% for windows
+  under 512K, so most models keep 25% free (`context_compressor.py`).
+- **Hooks:** shell hooks in a `hooks:` block in `config.yaml`, in Claude Code's JSON format,
+  registered when the CLI or gateway starts and allowed once on first use.
+  - Answering a permission request: not through hooks. `pre_approval_request` and
+    `post_approval_response` only observe. Approvals can be answered through
+    `POST /v1/runs/{id}/approval` on its API server, ACP, or a messaging gateway's `/approve`.
+  - A message when a turn ends: `pre_verify` can return `{ "action": "continue", "message" }`,
+    but only on turns that edited code, at most 3 times. `POST /api/sessions/{id}/chat` runs a
+    new turn.
+  - Others: `on_session_start`, `post_llm_call`, `post_compaction`, `subagent_stop`,
+    `on_stream_delta`.
+- **Sources:** `hermes_state_common.py`, `context_compressor.py`, and the `hooks.md`,
+  `session-storage.md`, and `api-server.md` docs in NousResearch/hermes-agent.
+
+## OpenCode
+
+Checked against anomalyco/opencode (formerly sst/opencode) at tag `v1.19.5` for 1.x and `dev`
+commit `ff4a652` for 2.x, 2026-11-08.
+
+- **Thoughts:**
+  - 1.x: a `part` row with `{ type: "reasoning", text, metadata, time: { start, end } }`. The
+    text is written once the reasoning ends, so it's empty while the model is thinking.
+    `metadata` holds the provider's signature or encrypted copy.
+  - 2.x: a `{ type: "reasoning", text, native, time }` part, filled in when the reasoning ends.
+    `native` holds the provider's data for replaying it.
+- **Replies:**
+  - 1.x: `part` rows with `{ type: "text", text, synthetic, ignored, time }`, written empty when
+    the text starts and filled when it ends. `synthetic` and `ignored` parts weren't written by
+    the model.
+  - 2.x: `{ type: "text", text, native }` parts with no time of their own; the assistant
+    message's time stands for them. Parts get their own `session_part` rows only when
+    `experimental.part_rows` is on, which it isn't by default; otherwise they're in the
+    message's `data.content`.
+- **Kept free for compacting:**
+  - 1.x: `compaction.reserved` tokens, by default the smaller of 20,000 and the model's largest
+    output (`session/overflow.ts`).
+  - 2.x: 15% of the window, or 16,000 tokens if that's more. `compaction.buffer` changes it, as
+    tokens or a share such as `"20%"` (`compaction.ts`).
+- **Hooks:** plugins, in JavaScript or TypeScript, and the HTTP server the TUI starts.
+  - 1.x plugins: `event` gets every event, `tool.execute.before` and `tool.execute.after` wrap
+    calls, and `permission.ask` is declared but no call to it was found.
+  - 2.x plugins: `ctx.permission.hook("evaluate")` can allow, ask, or deny;
+    `ctx.session.prompt` sends a message to steer or queue; config folders reload on their own.
+  - Server: `GET /event` streams events; `POST /session/:id/permissions/:permissionID` answers a
+    permission request (1.x), or `POST /api/session/:sessionID/permission/:requestID/reply`
+    (2.x); `POST /session/:id/prompt_async` sends a prompt.
+- **Sources:** `packages/schema/src/v1/session.ts`, `session-message.ts`, `processor.ts`,
+  `compaction.ts`, `packages/plugin/src/index.ts`, <https://opencode.ai/docs/server>.
+
+## Kilo Code
+
+Checked against Kilo-Org/kilocode at commit `b6a49d0` (CLI 7.8.28), 2026-11-08.
+
+- **Thoughts and replies:** the same `part` rows as OpenCode 1.x. Kilo has no 2.x tables.
+- **Kept free for compacting:** OpenCode 1.x's rule, and `compaction.threshold_percent` can set
+  a lower share of the window (`kilocode/session/overflow.ts`).
+- **Hooks:** plugins in `~/.config/kilo/plugin/` and a project's `.kilo/plugin/`, loaded at
+  startup, with events such as `session.idle`, `permission.asked`, and `message.part.updated`.
+  Its server answers permission requests at `POST /permission/:requestID/reply` and questions at
+  `POST /question/:requestID/reply`.
+- **Sources:** `packages/schema/src/v1/session.ts`, `kilocode/session/overflow.ts`, and the
+  plugins page in `kilo-docs`.