> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Report agent activity

> **Prototype (AG-285).** Reports activity observed by an agent runtime on a developer's machine - today, Claude Code hook events.

This is **telemetry from cooperating machines, not attestation**. Opal can only see what a configured, consenting client chooses to send, cannot verify that a fleet is configured at all, and has no way to detect a machine that is reporting nothing. Absence of activity for an agent therefore means "nothing was reported", never "the agent did nothing".

The request body is either a batch envelope (`{"events": [...]}`), a bare JSON array of events, or a single raw Claude Code hook payload - the last so a hook can POST here directly with no relay in between.

The bearer token establishes the **organization** and nothing finer. No field in the payload is treated as an identity claim Opal trusts: the actor headers below are used for best-effort attribution and display only. Events that cannot be attributed to an agent are retained and surfaced as unattributed activity rather than dropped.



## OpenAPI

````yaml https://app.opal.dev/openapi.yaml post /agent-activity
openapi: 3.1.0
info:
  contact:
    email: hello@opal.dev
    name: Opal Team
    url: https://www.opal.dev/
  description: >-
    The Opal API is a RESTful API that allows you to interact with the Opal
    Security platform programmatically.
  title: Opal API
  version: '1.0'
servers:
  - description: Production
    url: https://api.opal.dev/v1
security: []
tags:
  - name: access-rules
    description: Operations related to access rules
  - name: agent-activity
    description: Operations related to agent activity telemetry
  - name: apps
    description: Operations related to apps
  - name: bundles
    description: Operations related to bundles
  - name: campaigns
    description: Operations related to access review campaigns
  - name: configuration-templates
    description: Operations related to configuration templates
  - name: delegations
    description: Operations related to request reviewer delegations
  - name: event-streams
    description: Operations related to event streaming connections
  - name: events
    description: Operations related to events
  - name: groups
    description: Operations related to groups
  - name: group-bindings
    description: Operations related to group bindings
  - name: idp-group-mappings
    description: Operations related to IDP group mappings
  - name: message-channels
    description: Operations related to message channels
  - name: non-human-identities
    description: Operations related to non-human identities
  - name: on-call-schedules
    description: Operations related to on-call schedules
  - name: opal-queries
    description: Operations related to OpalQuery
  - name: opal-scripts
    description: Operations related to OpalScripts
  - name: owners
    description: Operations related to owners
  - name: requests
    description: Operations related to requests
  - name: resources
    description: Operations related to resources
  - name: role-assignments
    description: >-
      Operations related to role assignments (general grants between an entity
      and a principal)
  - name: paladin
    description: Operations related to Paladin
  - name: service-users
    description: Operations related to service users (non-human identities owned by a team)
  - name: sessions
    description: Operations related to sessions
  - name: tags
    description: Operations related to tags
  - name: tokens
    description: Operations related to API tokens
  - name: uars
    description: Operations related to UARs. Deprecated in favor of the `campaigns` API.
  - name: users
    description: Operations related to users
paths:
  /agent-activity:
    post:
      tags:
        - agent-activity
      summary: Report agent activity
      description: >-
        **Prototype (AG-285).** Reports activity observed by an agent runtime on
        a developer's machine - today, Claude Code hook events.


        This is **telemetry from cooperating machines, not attestation**. Opal
        can only see what a configured, consenting client chooses to send,
        cannot verify that a fleet is configured at all, and has no way to
        detect a machine that is reporting nothing. Absence of activity for an
        agent therefore means "nothing was reported", never "the agent did
        nothing".


        The request body is either a batch envelope (`{"events": [...]}`), a
        bare JSON array of events, or a single raw Claude Code hook payload -
        the last so a hook can POST here directly with no relay in between.


        The bearer token establishes the **organization** and nothing finer. No
        field in the payload is treated as an identity claim Opal trusts: the
        actor headers below are used for best-effort attribution and display
        only. Events that cannot be attributed to an agent are retained and
        surfaced as unattributed activity rather than dropped.
      operationId: reportAgentActivity
      parameters:
        - description: >-
            The identity the reporting client claims this activity belongs to -
            an email or an Anthropic user id. **Unverified**: a Claude Code hook
            payload contains no user identity, so this has to be injected by
            whoever deploys the hook (via the http handler's `headers` map and
            `allowedEnvVars` interpolation), and whoever controls the machine
            controls the header. Used only when the API key itself does not
            identify a developer. When the email belongs to a person in the
            organization, that person is recorded as who the activity was
            reported for (always as a claim), and the activity is attributed to
            the one Claude agent they own, if they own exactly one. The API
            key's own email is never treated this way: a key belongs to whoever
            created it, which with a shared key is not who is at the keyboard.
            Omitting it is valid. When an event's `opal_reported` object carries
            other emails, Opal also tries them, in the order `configured_email`,
            `claude_account_email`, `git_email`, after this header and skipping
            any that repeat it. The first one that resolves to an agent wins.
          explode: false
          in: header
          name: X-Opal-Actor
          required: false
          schema:
            type: string
          style: simple
        - description: >-
            The name of the machine that sent this request, as that machine
            reports it (`hostname -s`). **Unverified**: two machines can share a
            name, and whoever controls the machine controls the header. Stored
            with each event, so a reader can tell which machine reported it.
            When an event's own `opal_reported.hostname` names a different
            machine, this header wins and the body's value is kept beside it.
            Omitting it is valid.
          explode: false
          in: header
          name: X-Opal-Host
          required: false
          schema:
            type: string
          style: simple
        - description: >-
            `1` when the sender collects conversation content: the prompt of a
            `UserPromptSubmit` event, the `tool_response` of a `PostToolUse`
            event and the `last_assistant_message` of a `Stop` or `SubagentStop`
            event. Without it (or an event's own `opal_content`) those fields
            are read and discarded, as before. An `http` hook sets it in its
            `headers` map, because it cannot change the payload. Opal stores the
            content only when the organization stores content as well.
          explode: false
          in: header
          name: X-Opal-Content
          required: false
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentActivityIngestRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentActivityIngestResult'
          description: >-
            A per-batch accounting of what was accepted, stored, and attributed.
            An organization that has agent activity turned off gets a 200 with
            an empty body for every body shape, so a sender does not keep the
            events and try again.
        '400':
          description: >-
            The body was unparseable, empty, or carried more events than one
            request may.
        '413':
          description: The request body exceeded the maximum accepted size.
      security:
        - BearerAuth: []
components:
  schemas:
    AgentActivityIngestRequest:
      description: >-
        # AgentActivityIngestRequest Object

        ### Description

        A batch of agent activity events.


        Three body shapes are accepted: this envelope (`{"events": [...]}`), a
        bare JSON

        array of `AgentActivityEvent`, and a single `AgentActivityEvent` object.
        The last

        exists so a Claude Code hook can POST here directly, since a hook sends
        one bare

        payload per event and cannot wrap it.
      properties:
        events:
          items:
            $ref: '#/components/schemas/AgentActivityEvent'
          type: array
      type: object
      additionalProperties: true
    AgentActivityIngestResult:
      description: >-
        # AgentActivityIngestResult Object

        ### Description

        What one ingest request actually did.


        `received` and `stored` differ when a delivery was retried and
        deduplicated.

        `attributed` and `unattributed` sum to `received` rather than to
        `stored`, because

        attribution happens before deduplication. Unattributed events are kept,
        not dropped:

        activity Opal cannot tie to a governed agent is itself a governance
        finding.
      properties:
        received:
          description: Events parsed out of the request body.
          type: integer
        stored:
          description: >-
            Rows actually written. Lower than `received` when a retried delivery
            was deduplicated on `tool_use_id`.
          type: integer
        attributed:
          description: Events that resolved to an agent in this organization.
          type: integer
        unattributed:
          description: >-
            Events that resolved to no agent, and are therefore visible only in
            the unattributed activity list. A persistently high value means the
            reporting clients are not sending an identity Opal can resolve.
          type: integer
      required:
        - received
        - stored
        - attributed
        - unattributed
      type: object
    AgentActivityEvent:
      description: >-
        # AgentActivityEvent Object

        ### Description

        One activity event reported by an agent runtime. Today this is a Claude
        Code hook

        payload, posted either by the hook itself or by a relay that batches
        them.


        Only the fields below are read; everything else in the payload is parsed
        and

        **discarded**, never persisted. That includes `transcript_path` /
        `scratchpad_dir`

        (absolute paths on an employee's own laptop, which Opal cannot govern
        and should not

        be accumulating).


        `prompt`, `tool_response` and `last_assistant_message` (the conversation
        content) are

        stored only when the sender collects them (`opal_content` on the event,
        or the

        `X-Opal-Content` header) and the organization stores content. Secrets in
        the shapes

        Opal recognizes are masked and each text is cut to the organization's
        limit before

        it is written. Otherwise they are discarded too.


        `tool_input` IS now read and stored. It was previously discarded pending
        a

        data-handling decision; that decision has since been made, and without
        arguments

        no policy can name what a call acted on - a rule about a file path, a
        command

        family or a web domain refers to something that exists only inside
        `tool_input`.
      properties:
        hook_event_name:
          description: >-
            Which hook fired, e.g. `PostToolUse`, `PreToolUse`,
            `PermissionDenied`. Required; an event with no name cannot be
            interpreted and is rejected.
          type: string
        tool_input:
          description: >-
            The call's arguments, as the runtime sent them. Server-defined for
            an MCP tool;

            a fixed shape per built-in (`command` for Bash, `file_path` for
            Edit, `url` for

            WebFetch).


            Stored as sent, and separately reduced to a normalized target the
            activity feed

            and policy can match on. The stored copy is the record of fact; the
            derived

            target is recomputed whenever the extractor improves.


            Capped before storage. A capped payload is no longer valid JSON, so
            the row

            records that it was capped rather than leaving each reader to
            discover it by

            failing to parse.
          type: object
          additionalProperties: true
        session_id:
          description: The agent session this event belongs to. Opaque to Opal.
          type: string
        prompt_id:
          description: >-
            Groups every tool call made under one user instruction, so a run can
            be read back as the instruction that caused it rather than as
            unrelated rows.
          type: string
        agent_id:
          description: >-
            Set only when the call came from an autonomous subagent rather than
            the session a person is typing into. Stored as `subagent_id` -
            Opal's own `agent_id` already means something else.
          type: string
        agent_type:
          description: >-
            The subagent's type, e.g. `general-purpose`. Set alongside
            `agent_id`.
          type: string
        permission_mode:
          description: >-
            The session's permission mode, e.g. `default`, `acceptEdits`,
            `bypassPermissions`. A session running `bypassPermissions` had no
            approval gate in front of any tool call it made.
          type: string
        actor_email:
          description: >-
            The identity the sender reports for this specific event.
            **Unverified**, the same as `X-Opal-Actor`, and used only when
            neither the API key nor that header identified a developer. An
            `http` hook cannot populate this; a `command`-type hook or a relay
            can (`$USER`, a hostname, `git config user.email`), which is why it
            is per-event rather than per-request - a relay can batch several
            developers.
          type: string
        opal_reported:
          $ref: '#/components/schemas/AgentActivityOpalReported'
        duration_ms:
          description: >-
            How long the tool call took to run, in milliseconds, as Claude Code
            measured it. Claude Code's documentation says it leaves out time
            spent in permission prompts and in `PreToolUse` hooks. It is sent
            with `PostToolUse` and `PostToolUseFailure` only; it is ignored on
            any other event. **Unverified.** Stored only when it is a number
            from 0 to 86400000 (24 hours), rounded to a whole millisecond; any
            other value is dropped and the event is stored without it. A value
            of the wrong type never rejects the event or the batch it came in.
          x-go-type: json.RawMessage
        transcript_path:
          description: >-
            Read at ingest **only** to parse an operating-system username out
            of, as the last-resort attribution step, and then discarded. The
            path itself is never stored: it is an absolute path on an employee's
            laptop and Opal has no business accumulating those.
          type: string
        tool_name:
          description: >-
            The tool invoked, for tool-scoped events. Empty for session-level
            events.


            An MCP tool is named `mcp__<server>__<tool>`. The whole string is
            stored as sent,

            and the server and the tool are also stored in their own fields (see
            `mcp_server`).
          type: string
        mcp_server:
          $ref: '#/components/schemas/AgentActivityMcpServer'
        opal_mcp_server:
          $ref: '#/components/schemas/AgentActivityOpalMcpServer'
        tool_use_id:
          description: >-
            The tool invocation's id, used together with `hook_event_name` to
            deduplicate a retried delivery. Absent on events that carry none,
            which are stored at-least-once unless they are a prompt or the end
            of a turn with `session_id` and `prompt_id`, or carry
            `opal_event_id`.
          type: string
        opal_event_id:
          description: >-
            An id Opal's hook kit gives each event it holds for sending, so that
            a retried delivery of an event without a `tool_use_id` (a prompt,
            the end of a turn) is stored once. Used only for an event that has
            no `tool_use_id` and is not a tool-call event, and only when it is 8
            to 64 letters, digits and dashes; otherwise ignored.
          type: string
        cwd:
          description: The working directory the agent was operating in.
          type: string
        timestamp:
          description: >-
            When the client says the event occurred (RFC 3339). Clamped
            server-side to a window around receipt, because a client-controlled
            sort key is otherwise a way to pin rows to the top of every list.
            Defaults to receipt time when absent or unparseable.
          format: date-time
          type: string
        prompt:
          description: >-
            The text a person submitted (`UserPromptSubmit`), a string. Stored
            only as described

            above. Read whatever its type, so that a change in its shape cannot
            make Opal refuse

            the event.
        tool_response:
          description: >-
            What the tool returned (`PostToolUse`), in the tool's own shape, or
            as text when the

            sender already converted it. Stored only as described above, as
            text: every image

            is replaced by a placeholder that names its type and size.
        last_assistant_message:
          description: >-
            The text of the model's final message in the turn (`Stop`,
            `SubagentStop`), a string.

            Stored only as described above, and only when
            `opal_content.assistant_text` is absent.

            Read whatever its type, like `prompt`.
        opal_content:
          $ref: '#/components/schemas/AgentActivityContentReport'
      required:
        - hook_event_name
      type: object
      additionalProperties: true
    AgentActivityOpalReported:
      description: >-
        # AgentActivityOpalReported Object

        ### Description

        What the sending machine says about who and what it is, added by the
        Opal hook

        script. Every field is optional and **unverified**: whoever controls the
        machine

        controls them. They can disagree, and Opal keeps every one that is
        present, each cut

        to a fixed length (254 characters for an email, 64 for `os_user`, 255
        for

        `hostname`) with control characters removed.


        The emails are also tried, in the order below and after the
        `X-Opal-Actor` header,

        to find the agent, so a person without a git email can still match
        through their

        Claude account.
      properties:
        configured_email:
          description: An email set by an administrator, an MDM profile or the installer.
          type: string
        claude_account_email:
          description: The email of the account Claude Code is signed in with.
          type: string
        git_email:
          description: The machine's global `git config user.email`.
          type: string
        os_user:
          description: The operating-system username. Not used to find an agent.
          type: string
        hostname:
          description: >-
            The machine's name. The `X-Opal-Host` header wins when it names a
            different machine.
          type: string
      type: object
    AgentActivityMcpServer:
      description: >-
        # AgentActivityMcpServer Object

        ### Description

        The MCP server behind a tool call, as Claude Code reports it. Claude
        Code v2.1.274 and

        later adds this object to the hook input of an MCP tool call; an older
        client does not

        send it, and it is never present for a built-in tool such as `Bash`.


        When `name` is present it is stored as the call's server. When this
        object is absent,

        the server is read from `tool_name` instead: the part after the `mcp__`
        prefix and

        before the next `__`. The tool is always read from `tool_name`.


        `name` is stored as the call's server. `source` says where the server's
        definition came

        from (`plugin`, `sdk`, or a configuration scope such as `user` or
        `project`) and is

        stored as sent, cut to 64 characters. Neither field is an identity:
        `name` is whatever

        the user called the server in their own configuration, and `source` is
        what the machine

        said.
      properties:
        name:
          description: The server's name.
          type: string
        source:
          description: >-
            Where the server's definition came from, such as `plugin`, `sdk`,
            `user` or `project`. Stored as sent, cut to 64 characters.
          type: string
      type: object
    AgentActivityOpalMcpServer:
      description: >-
        # AgentActivityOpalMcpServer Object

        ### Description

        Where the MCP server behind a tool call connects, as the Opal hook kit
        read it from the

        developer's own Claude Code configuration. Claude Code's hook payload
        names the server

        but not where it connects, so the kit adds this for an
        `mcp__<server>__<tool>` call when

        it finds the server in the configuration.


        Opal uses it to identify the server in the organization's MCP server
        registry: by its

        URL, or by the hash of its command. The URL is stored without its query,
        fragment or

        user name and password.
      properties:
        url:
          description: The server's URL, for an `http` or `sse` server.
          type: string
        transport:
          description: '`http`, `sse` or `stdio`.'
          type: string
        command_hash:
          description: >-
            For a `stdio` server, a SHA-256 of its command's shape, in hex.
            Arguments that can hold a secret are replaced before hashing, and
            the command itself is never sent.
          type: string
        scope:
          description: >-
            The configuration the server was found in, such as `user`,
            `project`, `local`, `managed` or `plugin`.
          type: string
      type: object
    AgentActivityContentReport:
      description: >-
        # AgentActivityContentReport Object

        ### Description

        What Opal's hook kit adds to an event when it collects conversation
        content. Its

        presence means the sender collects content, like the `X-Opal-Content`
        header. The kit

        has already masked secrets in the texts and cut them to its own limit.
      properties:
        assistant_text:
          description: >-
            Every text the model wrote in the turn, read from the session's
            transcript (`Stop`, `SubagentStop`). Preferred over
            `last_assistant_message`, which holds only the final message.
          type: string
        thinking:
          description: >-
            The model's thinking in the turn, when the transcript holds it as
            plain text.
          type: string
        images:
          $ref: '#/components/schemas/AgentActivityImages'
        truncated:
          description: >-
            The fields the kit cut (`prompt`, `tool_response`, `assistant_text`,
            `last_assistant_message`, `thinking`), each with its size in bytes
            before the cut. A prompt or a tool result keeps its start; a turn's
            text and thinking keep their end. Sizes are stored up to 2147483647.
          additionalProperties:
            type: integer
          type: object
      type: object
    AgentActivityImages:
      description: >-
        # AgentActivityImages Object

        ### Description

        The images attached to a prompt or returned by a tool. Only their number
        and size are

        sent; the images themselves are not.
      properties:
        count:
          type: integer
        bytes:
          format: int64
          type: integer
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.