Thread Items

These are the items a Job Session Object carries: every agent step the worker observes becomes one thread item, posted via post_session_thread_item. The content array carries a brief human-readable rendering; metadata carries the structured detail.

General shape

content:
  - type: text                       # content-item type (text | json | image later)
    text: <brief human-readable rendering>
metadata:
  type: text | tool_call | tool_result | thinking | status | turn_end | pending_prompt |
        pending_prompt_resolved | artifacts_published | policy_applied | policy_denied
  # plus type-specific fields below

content[].type and metadata.type are in different scopes — content-item shape vs. event shape — and don’t collide. Consumers (renderers, exporters, the future native widget) dispatch on metadata.type. The presence of metadata.type is the distinguishing mark vs. plain user-posted items, which have no metadata.type set.

Item types (per-thread)

`text`

The agent’s user-facing text output.

content:
  - type: text
    text: |
      Looks like the issue is in `parseToken` — it doesn't handle the new prefix.
metadata:
  type: text

A text item carries no metadata beyond type — the full output is content[0].text. If an item exceeds the budget, the generic truncation path excerpts content[0].text and sets metadata.truncated (see the truncation rules below); there is no separate full-text copy for text items.

`tool_call`

The agent invoked a tool. Posted before the result so live tailing shows the call landing.

content:
  - type: text
    text: "Bash → npm test"
metadata:
  type: tool_call
  tool:
    name: Bash
    invocation_id: tu_01J...
    input:
      command: npm test
      description: Run the test suite

`tool_result`

The tool’s result for the matching invocation_id.

content:
  - type: text
    text: "→ ✓ src/parser.test.ts (12 ok) (3 lines)"
metadata:
  type: tool_result
  tool:
    invocation_id: tu_01J...
    is_error: false
    output: |
      ✓ src/parser.test.ts (12 ok)
      Test Files  1 passed (1)
      ...

A tool_result carries no tool name — renderers fold a tool_call / tool_result pair by invocation_id and take the name from the tool_call. The brief is → <first output line> (N lines).

`thinking`

Internal reasoning blocks (Claude Code). The brief content.text shows the first ~120 characters; the full reasoning is in metadata.text.

content:
  - type: text
    text: "[thinking] Considering the user's request and looking at the parser code..."
metadata:
  type: thinking
  text: "Considering the user's request and looking at the parser code, the prefix handling..."
  full_text_length: 1842

`status`

Progress / status pings (e.g. “Compacting context”). Carries a machine-readable token.

content:
  - type: text
    text: "Compacting context..."
metadata:
  type: status
  status: compacting_context
  detail: "Reducing 38k → 12k tokens"

`turn_end`

Marker that the agent has finished its current turn. Useful for renderers to draw a turn separator and for monitoring.

content:
  - type: text
    text: "Turn complete"
metadata:
  type: turn_end
  stats:
    input_tokens: 12480
    input_tokens_cached: 9600
    output_tokens: 1322
    duration_ms: 8421

input_tokens is the total input the model processed this turn (cached + uncached); input_tokens_cached is the portion served from the prompt cache. Both adapters (Claude Code and Codex) report the same breakdown.

`pending_prompt` and `pending_prompt_resolved`

Used for the interactive-prompt round-trip. See Interactive prompts.

`artifacts_published`

Posted once per turn on a thread whose envelope carries an artifacts block (see Job Session Object → Artifacts) — even when nothing was published, so an empty outbox is visible rather than indistinguishable from the feature being off. Posted after the outbox is walked and every publishable file in it is uploaded, immediately before that turn’s turn_end item — so anything reacting to turn_end always sees a complete artifact set.

content:
  - type: text
    text: "Published 3 artifact(s), skipped 1"
metadata:
  type: artifacts_published
  aliases:                                                                             # capped at 100
    - projects/p1/items/i1/runs/1/artifacts/docs/plan.md
    - projects/p1/items/i1/runs/1/artifacts/src/parser.py
  skipped:                                                                              # capped at 100
    - { path: out.bin, reason: binary }
  counts: { published: 3, skipped: 1 }

Both lists are capped at 100 entries because a thread item is capped at 350 KB and a large outbox would otherwise overflow it; counts always reports the true totals regardless of the cap. skipped[].reason is one of binary, too_large, invalid_alias, unreadable, or upload_failed. A source that resolves outside work_folder is checked twice, at two different times, because the outbox is a directory inside the agent’s own writable workspace and the worker cannot assume it stays put for the length of a turn:

Caught at activation, before the first turn runs — the worker sets its in-memory artifacts spec to None instead of proceeding, and publishing is off for the thread’s entire current activation. No artifacts_published item is posted at all, for any turn, until the thread is next re-activated with a corrected source. An outbox_invalid warning lands in the worker’s log instead.
Caught at publish time — the activation-time check passed against the filesystem as it stood then, but the outbox path is re-resolved live on every publish, and the agent had the whole turn to rewrite it (for example, replacing the outbox directory with a symlink pointing outside work_folder). When that re-resolution lands outside the workspace, the artifacts_published item for that turn is posted, with aliases: [], skipped: [], and metadata.error set to the resolution failure.

Neither check is redundant with the other: the second one exists precisely because the first can’t see what happens during the turn it’s meant to guard, and a use-time re-check is the correct design for a directory an untrusted agent can rewrite. This item is an audit record, not the discovery mechanism. Find published artifacts by listing the session with prefix=<artifacts.prefix>, exactly as any other client would — never by reading this item.

`policy_applied`

Posted once before each turn on a guarded thread, naming the rule set in force. Doubles as an enforcement acknowledgement: its presence is what tells a reader this turn actually ran gated, rather than against a worker version too old to know about policy at all.

content:
  - type: text
    text: "Policy in force: 3 rule(s), default allow"
metadata:
  type: policy_applied
  rules:
    - { id: confine_writes, origin: worker, action: deny }
    - { id: never_force_push, origin: worker, action: deny }
    - { id: destructive_git, origin: thread, action: deny }
  default: allow

rules lists every rule in evaluation order — the worker’s own first, then the thread’s own — each tagged origin: worker | thread.

`policy_denied`

Posted once for every tool call a guarded policy denied.

content:
  - type: text
    text: "Blocked by policy rule 'confine_writes': /etc/passwd"
metadata:
  type: policy_denied
  rule: confine_writes
  effect: write
  detail: /etc/passwd

detail is the denied call’s command or path, whichever the matched rule’s effect uses; when neither is populated — a codex file-change call, for instance, which carries no path at all (see Job Session Object → Policy and guarded permissions) — it falls back to the tool or call name instead.

Self-filter

Every item the worker posts carries the worker’s user_id (because BlobHub stamps the calling user on every post). The worker filters out items where user_id == self.user_id when consuming a thread — they are echoes of its own emissions and must not be re-fed to the agent. This has a documented consequence: a human posting from the same user account is also filtered. See Reference.

350 KB truncation

The worker enforces a 350 KB budget (350_000 bytes) on each serialized thread item and truncates large payloads before posting.

1. Always write the full untruncated payload to
   jobs/{job_id}/threads/{alias}/logs/thread.log before posting.
2. Build the candidate item dict (content + metadata).
3. budget = 350 KB
   if json.dumps(item) <= budget: post; done.
4. Identify the largest truncatable string fields, in order:
     metadata.tool.output, metadata.tool.input,
     metadata.text, content[0].text
   For each, replace with: <head 4 KB> + "…[truncated <N> bytes; see <local-log-path>]…" + <tail 2 KB>.
   Set metadata.truncated = true.
   Append the field name to metadata.truncated_fields.
   Set metadata.local_log = "<job_id>/threads/{alias}/logs/thread.log".
5. If still > budget after truncating all fields above, drop them entirely (keep markers + field list).
6. If still > budget (very rare), transition the thread to failed with THREAD_ITEM_TOO_LARGE.

After truncation, a posted item looks like:

content:
  - type: text
    text: "→ added 1452 packages in 38s (4210 lines)"
metadata:
  type: tool_result
  truncated: true
  truncated_fields: [tool.output]
  local_log: session_agent_harness-ses_01J.../threads/my-feature-x/logs/thread.log
  tool:
    invocation_id: tu_01J...
    is_error: false
    output: |
      <first 4 KB>
      …[truncated 412992 bytes; see <local-log-path>]…
      <last 2 KB>

The local_log field is relative to the profile’s own jobs/ directory. The full untruncated payload is always recoverable from the worker’s local disk.

Overview

Specification

General shape

Item types (per-thread)

`text`

`tool_call`

`tool_result`

`thinking`

`status`

`turn_end`

`pending_prompt` and `pending_prompt_resolved`

`artifacts_published`

`policy_applied`

`policy_denied`

Self-filter

350 KB truncation

See also

​General shape

​Item types (per-thread)

​text

​tool_call

​tool_result

​thinking

​status

​turn_end

​pending_prompt and pending_prompt_resolved

​artifacts_published

​policy_applied

​policy_denied

​Self-filter

​350 KB truncation

​See also

General shape

Item types (per-thread)

`text`

`tool_call`

`tool_result`

`thinking`

`status`

`turn_end`

`pending_prompt` and `pending_prompt_resolved`

`artifacts_published`

`policy_applied`

`policy_denied`

Self-filter

350 KB truncation

See also