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

# session.stop()



## OpenAPI

````yaml /api-reference/openapi.json post /sessions/{id}/stop
openapi: 3.1.0
info:
  title: paddock API
  version: 1.0.0
  description: >-
    The paddock API. Send an API key, or a session token on its own session, as
    a bearer token.
servers:
  - url: https://api.paddock.build/v1
security:
  - bearer: []
paths:
  /sessions/{id}/stop:
    post:
      summary: session.stop()
      operationId: stopSession
      parameters:
        - $ref: '#/components/parameters/SessionId'
      responses:
        '202':
          description: The stored stop.requested event
          headers:
            Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Event'
        default:
          $ref: '#/components/responses/Error'
components:
  parameters:
    SessionId:
      name: id
      in: path
      required: true
      description: The session's ID
      schema:
        type: string
        pattern: ^ses_[0-7][0-9a-hjkmnp-tv-z]{25}$
  headers:
    RequestId:
      description: The request's ID, for support and logs
      schema:
        type: string
  schemas:
    Event:
      description: 'An event of an agent''s log: the envelope and one event type.'
      allOf:
        - $ref: '#/components/schemas/EventEnvelope'
        - $ref: '#/components/schemas/EventBody'
    EventEnvelope:
      description: The envelope every event has.
      type: object
      required:
        - seq
        - agentId
        - sessionId
        - turnId
        - createdAt
      properties:
        seq:
          $ref: '#/components/schemas/Seq'
        agentId:
          type: string
          pattern: ^agt_[0-7][0-9a-hjkmnp-tv-z]{25}$
        sessionId:
          type:
            - string
            - 'null'
          pattern: ^ses_[0-7][0-9a-hjkmnp-tv-z]{25}$
        turnId:
          type:
            - string
            - 'null'
          pattern: ^trn_[0-7][0-9a-hjkmnp-tv-z]{25}$
        createdAt:
          $ref: '#/components/schemas/Timestamp'
    EventBody:
      oneOf:
        - $ref: '#/components/schemas/MessageEvent'
        - $ref: '#/components/schemas/TurnStartedEvent'
        - $ref: '#/components/schemas/TurnEndedEvent'
        - $ref: '#/components/schemas/StopRequestedEvent'
        - $ref: '#/components/schemas/AgentUnavailableEvent'
        - $ref: '#/components/schemas/AgentAvailableEvent'
        - $ref: '#/components/schemas/DaemonOutdatedEvent'
        - $ref: '#/components/schemas/SessionStatusEvent'
        - $ref: '#/components/schemas/ConfigAppliedEvent'
      discriminator:
        propertyName: type
        mapping:
          message: '#/components/schemas/MessageEvent'
          turn.started: '#/components/schemas/TurnStartedEvent'
          turn.ended: '#/components/schemas/TurnEndedEvent'
          stop.requested: '#/components/schemas/StopRequestedEvent'
          agent.unavailable: '#/components/schemas/AgentUnavailableEvent'
          agent.available: '#/components/schemas/AgentAvailableEvent'
          daemon.outdated: '#/components/schemas/DaemonOutdatedEvent'
          session.status: '#/components/schemas/SessionStatusEvent'
          config.applied: '#/components/schemas/ConfigAppliedEvent'
    ErrorBody:
      description: The body of every non-2xx response.
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorObject'
    Seq:
      description: A position in an agent's event log.
      type: integer
      minimum: 0
      maximum: 9007199254740991
    Timestamp:
      description: RFC 3339 in UTC with milliseconds.
      type: string
      format: date-time
      pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}\.[0-9]{3}Z$
      x-go-type: wire.Timestamp
      x-go-type-import:
        path: github.com/wenfengwang/paddock/internal/wire
    MessageEvent:
      type: object
      required:
        - type
        - message
      properties:
        type:
          const: message
        message:
          $ref: '#/components/schemas/StoredMessage'
    TurnStartedEvent:
      type: object
      required:
        - type
        - turn
      properties:
        type:
          const: turn.started
        turn:
          $ref: '#/components/schemas/TurnStarted'
    TurnEndedEvent:
      type: object
      required:
        - type
        - turn
      properties:
        type:
          const: turn.ended
        turn:
          $ref: '#/components/schemas/TurnEnded'
    StopRequestedEvent:
      type: object
      required:
        - type
      properties:
        type:
          const: stop.requested
    AgentUnavailableEvent:
      type: object
      required:
        - type
        - agent
      properties:
        type:
          const: agent.unavailable
        agent:
          $ref: '#/components/schemas/AgentUnavailable'
    AgentAvailableEvent:
      type: object
      required:
        - type
      properties:
        type:
          const: agent.available
    DaemonOutdatedEvent:
      type: object
      required:
        - type
        - daemon
      properties:
        type:
          const: daemon.outdated
        daemon:
          $ref: '#/components/schemas/DaemonOutdated'
    SessionStatusEvent:
      type: object
      required:
        - type
        - status
      properties:
        type:
          const: session.status
          x-enum-varnames:
            - SessionStatusEventType
        status:
          $ref: '#/components/schemas/HarnessStatus'
    ConfigAppliedEvent:
      type: object
      required:
        - type
        - config
      properties:
        type:
          const: config.applied
        config:
          $ref: '#/components/schemas/ConfigApplied'
    ErrorObject:
      type: object
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode'
        message:
          type: string
        details:
          type: object
    StoredMessage:
      description: 'A message as an event holds it: every kind but streaming.'
      allOf:
        - $ref: '#/components/schemas/Message'
        - not:
            type: object
            required:
              - kind
            properties:
              kind:
                const: streaming
    TurnStarted:
      type: object
      required:
        - origin
        - inputSeqs
        - attempt
      properties:
        origin:
          $ref: '#/components/schemas/TurnOrigin'
        inputSeqs:
          type: array
          items:
            $ref: '#/components/schemas/Seq'
        attempt:
          type: integer
          minimum: 1
    TurnEnded:
      type: object
      required:
        - outcome
        - error
        - retry
        - usage
        - timing
      properties:
        outcome:
          $ref: '#/components/schemas/TurnOutcome'
        error:
          oneOf:
            - $ref: '#/components/schemas/TurnError'
            - type: 'null'
        retry:
          oneOf:
            - $ref: '#/components/schemas/RetryAt'
            - $ref: '#/components/schemas/RetryGiveUp'
            - type: 'null'
        usage:
          oneOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
        timing:
          description: >-
            Where the turn's time went, as Turn.timing reports it; null when
            none was measured.
          oneOf:
            - $ref: '#/components/schemas/TurnTiming'
            - type: 'null'
    AgentUnavailable:
      type: object
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/TurnError'
    DaemonOutdated:
      type: object
      required:
        - version
        - required
      properties:
        version:
          type: string
        required:
          type: string
    HarnessStatus:
      description: >-
        The harness's internal state at the end of a turn: Context, Plugins,
        Skills, MCP, Subagents, and Workflows.
      type: object
      required:
        - harness
        - takenAt
        - context
        - plugins
        - skills
        - mcp
        - subagents
        - workflows
      properties:
        harness:
          type: string
          enum:
            - claude-code
            - codex
        takenAt:
          $ref: '#/components/schemas/Timestamp'
        context:
          $ref: '#/components/schemas/ContextStatus'
        plugins:
          type: array
          items:
            $ref: '#/components/schemas/HarnessEntry'
        skills:
          type: array
          items:
            $ref: '#/components/schemas/HarnessEntry'
        mcp:
          type: array
          items:
            $ref: '#/components/schemas/HarnessMcpServer'
        subagents:
          $ref: '#/components/schemas/HarnessSubagents'
        workflows:
          description: null on Codex, which has no workflows
          oneOf:
            - $ref: '#/components/schemas/HarnessWorkflows'
            - type: 'null'
    ConfigApplied:
      description: One application of the agent's configuration to a session's harness.
      type: object
      required:
        - generation
        - changes
      properties:
        generation:
          description: The agent generation the session's harness now runs.
          type: integer
          minimum: 1
        changes:
          type: array
          items:
            $ref: '#/components/schemas/ConfigChange'
    ErrorCode:
      type: string
      enum:
        - invalid_request
        - unauthorized
        - forbidden
        - not_found
        - conflict
        - payload_too_large
        - unsupported
        - unavailable
        - internal
    Message:
      description: >-
        id and parentToolUseId joined with a MessageBody. Its position belongs
        to the event that holds it.
      allOf:
        - type: object
          required:
            - id
            - parentToolUseId
          properties:
            id:
              type: string
              pattern: ^msg_[0-7][0-9a-hjkmnp-tv-z]{25}$
            parentToolUseId:
              type:
                - string
                - 'null'
        - $ref: '#/components/schemas/MessageBody'
    TurnOrigin:
      description: >-
        user: started over waiting messages; harness: started by the harness on
        its own, with no inputs, never retried.
      type: string
      enum:
        - user
        - harness
    TurnOutcome:
      type: string
      enum:
        - completed
        - stopped
        - failed
    TurnError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          $ref: '#/components/schemas/TurnErrorCode'
        message:
          type: string
    RetryAt:
      description: paddock will retry the failed turn at this time.
      type: object
      required:
        - at
      properties:
        at:
          $ref: '#/components/schemas/Timestamp'
    RetryGiveUp:
      description: paddock gave up retrying; waiting messages at or below heldSeq are held.
      type: object
      required:
        - giveUp
        - heldSeq
      properties:
        giveUp:
          const: true
        heldSeq:
          $ref: '#/components/schemas/Seq'
    Usage:
      description: The turn's model usage.
      type: object
      required:
        - inputTokens
        - outputTokens
        - cacheReadTokens
        - cacheWriteTokens
      properties:
        inputTokens:
          type: integer
          minimum: 0
        outputTokens:
          type: integer
          minimum: 0
        cacheReadTokens:
          type: integer
          minimum: 0
        cacheWriteTokens:
          type: integer
          minimum: 0
    TurnTiming:
      description: >-
        Where a turn's time went, as phases on the turn's own timeline, in
        milliseconds.
      type: object
      required:
        - totalMs
        - phases
      properties:
        totalMs:
          description: The turn's start to its end.
          type: integer
          minimum: 0
        phases:
          description: In order of startMs.
          type: array
          items:
            $ref: '#/components/schemas/TimingPhase'
    ContextStatus:
      description: >-
        The context window's fill, as Claude Code's /context shows it or as
        Codex reports it.
      type: object
      required:
        - model
        - windowTokens
        - modelWindowTokens
        - usedTokens
        - percent
        - estimated
        - autoCompactTokens
        - autoCompactEnabled
        - categories
        - mcpTools
        - agents
        - memoryFiles
        - skills
        - instructionFiles
        - lastRequest
        - totalTokens
      properties:
        model:
          type: string
        windowTokens:
          description: The window usage is measured against.
          type: integer
          minimum: 0
        modelWindowTokens:
          description: >-
            The model's window when windowTokens is the usable share of it
            (Codex); null when not reported.
          type:
            - integer
            - 'null'
          minimum: 0
        usedTokens:
          description: Tokens in the context window now.
          type: integer
          minimum: 0
        percent:
          description: usedTokens of windowTokens.
          type: number
          minimum: 0
        estimated:
          description: >-
            The harness estimated the counts locally instead of counting them
            with the model endpoint.
          type: boolean
        autoCompactTokens:
          description: The fill at which the harness compacts; null when not reported.
          type:
            - integer
            - 'null'
          minimum: 0
        autoCompactEnabled:
          type:
            - boolean
            - 'null'
        categories:
          description: null when not reported (Codex).
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ContextCategory'
        mcpTools:
          description: Each with its server in group; null when not reported.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ContextItem'
        agents:
          description: Custom agents with their source; null when not reported.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ContextItem'
        memoryFiles:
          description: With type and path; null when not reported.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ContextItem'
        skills:
          description: With their source; null when not reported.
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/ContextItem'
        instructionFiles:
          description: Instruction files loaded, such as AGENTS.md.
          type: array
          items:
            type: string
        lastRequest:
          description: The last model request; null when not reported.
          oneOf:
            - $ref: '#/components/schemas/TokenCount'
            - type: 'null'
        totalTokens:
          description: The conversation's tokens so far; null when not reported.
          type:
            - integer
            - 'null'
          minimum: 0
    HarnessEntry:
      description: >-
        A plugin, skill, MCP server, subagent, or workflow definition the
        harness knows.
      type: object
      required:
        - name
        - description
        - scope
        - plugin
        - state
        - error
      properties:
        name:
          type: string
        description:
          type: string
        scope:
          description: Where the harness found the entry.
          type: string
          enum:
            - home
            - project
            - plugin
            - builtin
        plugin:
          description: The contributing plugin when scope is plugin.
          type:
            - string
            - 'null'
        state:
          type: string
          enum:
            - loaded
            - starting
            - error
        error:
          description: The harness's message when state is error.
          type:
            - string
            - 'null'
    HarnessMcpServer:
      allOf:
        - $ref: '#/components/schemas/HarnessEntry'
        - type: object
          required:
            - tools
          properties:
            tools:
              description: The tool names the server offers.
              type: array
              items:
                type: string
    HarnessSubagents:
      type: object
      required:
        - definitions
        - runs
      properties:
        definitions:
          type: array
          items:
            $ref: '#/components/schemas/HarnessEntry'
        runs:
          type: array
          items:
            $ref: '#/components/schemas/SubagentRun'
    HarnessWorkflows:
      type: object
      required:
        - definitions
        - runs
      properties:
        definitions:
          type: array
          items:
            $ref: '#/components/schemas/HarnessEntry'
        runs:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowRun'
    ConfigChange:
      type: object
      required:
        - kind
        - name
        - action
        - how
        - version
        - error
        - warnings
      properties:
        kind:
          type: string
          enum:
            - model
            - mcp
            - marketplaces
            - plugins
            - env
            - permissions
        name:
          description: The entry or variable; null for model and permissions.
          type:
            - string
            - 'null'
        action:
          type: string
          enum:
            - added
            - changed
            - removed
            - refreshed
        how:
          description: 'start: done before the harness process started.'
          type: string
          enum:
            - hot
            - start
        version:
          description: The plugin version or marketplace commit the harness reported.
          type:
            - string
            - 'null'
        error:
          description: The command's or the harness's message when it failed.
          type:
            - string
            - 'null'
        warnings:
          type: array
          items:
            type: string
    MessageBody:
      oneOf:
        - $ref: '#/components/schemas/UserBody'
        - $ref: '#/components/schemas/AssistantBody'
        - $ref: '#/components/schemas/ReasoningBody'
        - $ref: '#/components/schemas/ToolCallBody'
        - $ref: '#/components/schemas/ToolResultBody'
        - $ref: '#/components/schemas/UnknownBody'
        - $ref: '#/components/schemas/StreamingBody'
      discriminator:
        propertyName: kind
        mapping:
          user: '#/components/schemas/UserBody'
          assistant: '#/components/schemas/AssistantBody'
          reasoning: '#/components/schemas/ReasoningBody'
          tool_call: '#/components/schemas/ToolCallBody'
          tool_result: '#/components/schemas/ToolResultBody'
          unknown: '#/components/schemas/UnknownBody'
          streaming: '#/components/schemas/StreamingBody'
    TurnErrorCode:
      type: string
      enum:
        - harness_error
        - watchdog_timeout
        - model_unavailable
        - model_auth
        - context_too_long
        - conversation_lost
        - sandbox_unavailable
        - internal
    TimingPhase:
      type: object
      required:
        - kind
        - startMs
        - durationMs
        - messageId
      properties:
        kind:
          $ref: '#/components/schemas/TimingPhaseKind'
        startMs:
          description: >-
            From the turn's start; negative for sandbox and daemon, which
            precede it.
          type: integer
        durationMs:
          description: null only for a tool call without a result when the turn ended.
          oneOf:
            - type: integer
              minimum: 0
            - type: 'null'
        messageId:
          description: >-
            reasoning, tool, and reply: the reasoning, tool_call, or assistant
            message.
          oneOf:
            - type: string
              pattern: ^msg_[0-7][0-9a-hjkmnp-tv-z]{25}$
            - type: 'null'
    ContextCategory:
      type: object
      required:
        - name
        - kind
        - tokens
        - percent
      properties:
        name:
          description: The harness's label.
          type: string
        kind:
          type: string
          enum:
            - used
            - deferred
            - buffer
            - free
        tokens:
          type: integer
          minimum: 0
        percent:
          description: Of windowTokens.
          type: number
          minimum: 0
    ContextItem:
      type: object
      required:
        - name
        - group
        - source
        - type
        - path
        - tokens
        - deferred
      properties:
        name:
          type: string
        group:
          type:
            - string
            - 'null'
        source:
          type:
            - string
            - 'null'
        type:
          type:
            - string
            - 'null'
        path:
          type:
            - string
            - 'null'
        tokens:
          type: integer
          minimum: 0
        deferred:
          type: boolean
    TokenCount:
      type: object
      required:
        - input
        - cachedInput
        - output
        - reasoning
        - total
      properties:
        input:
          type: integer
          minimum: 0
        cachedInput:
          type: integer
          minimum: 0
        output:
          type: integer
          minimum: 0
        reasoning:
          type: integer
          minimum: 0
        total:
          type: integer
          minimum: 0
    SubagentRun:
      type: object
      required:
        - id
        - type
        - description
        - state
        - background
        - startedAt
        - endedAt
        - tokens
        - toolUses
        - lastTool
      properties:
        id:
          description: The harness's task or thread ID.
          type: string
        type:
          description: The definition it runs.
          type: string
        description:
          type: string
        state:
          $ref: '#/components/schemas/RunState'
        background:
          type: boolean
        startedAt:
          $ref: '#/components/schemas/Timestamp'
        endedAt:
          description: null while running
          oneOf:
            - $ref: '#/components/schemas/Timestamp'
            - type: 'null'
        tokens:
          type: integer
          minimum: 0
        toolUses:
          type: integer
          minimum: 0
        lastTool:
          type:
            - string
            - 'null'
    WorkflowRun:
      type: object
      required:
        - id
        - name
        - state
        - phase
        - agents
        - agentsDone
        - tokens
        - startedAt
        - endedAt
      properties:
        id:
          type: string
        name:
          type: string
        state:
          $ref: '#/components/schemas/RunState'
        phase:
          description: The current or last phase's title.
          type:
            - string
            - 'null'
        agents:
          description: Agents started so far.
          type: integer
          minimum: 0
        agentsDone:
          type: integer
          minimum: 0
        tokens:
          type: integer
          minimum: 0
        startedAt:
          $ref: '#/components/schemas/Timestamp'
        endedAt:
          description: null while running
          oneOf:
            - $ref: '#/components/schemas/Timestamp'
            - type: 'null'
    UserBody:
      type: object
      required:
        - kind
        - text
      properties:
        kind:
          const: user
        text:
          type: string
    AssistantBody:
      type: object
      required:
        - kind
        - text
      properties:
        kind:
          const: assistant
        text:
          type: string
    ReasoningBody:
      type: object
      required:
        - kind
        - text
      properties:
        kind:
          const: reasoning
        text:
          type: string
    ToolCallBody:
      type: object
      required:
        - kind
        - toolCall
      properties:
        kind:
          const: tool_call
        toolCall:
          $ref: '#/components/schemas/ToolCall'
    ToolResultBody:
      type: object
      required:
        - kind
        - toolResult
      properties:
        kind:
          const: tool_result
        toolResult:
          $ref: '#/components/schemas/ToolResult'
    UnknownBody:
      description: An item the core maps to no known kind.
      type: object
      required:
        - kind
        - harness
        - type
        - raw
      properties:
        kind:
          const: unknown
        harness:
          $ref: '#/components/schemas/Harness'
        type:
          type: string
        raw: {}
    StreamingBody:
      description: 'Live only: the whole text of an assistant message generated so far.'
      type: object
      required:
        - kind
        - text
      properties:
        kind:
          const: streaming
        text:
          type: string
    TimingPhaseKind:
      type: string
      enum:
        - sandbox
        - daemon
        - harness
        - first_token
        - reasoning
        - tool
        - reply
    RunState:
      type: string
      enum:
        - running
        - completed
        - failed
        - stopped
    ToolCall:
      type: object
      required:
        - callId
        - tool
        - rawName
        - input
      properties:
        callId:
          type: string
        tool:
          $ref: '#/components/schemas/ToolName'
        rawName:
          type: string
        input:
          $ref: '#/components/schemas/ToolInput'
    ToolResult:
      type: object
      required:
        - callId
        - tool
        - isError
        - output
      properties:
        callId:
          type: string
        tool:
          $ref: '#/components/schemas/ToolName'
        isError:
          type: boolean
        output:
          $ref: '#/components/schemas/ToolOutput'
    Harness:
      type: string
      enum:
        - claude-code
        - codex
        - pi
    ToolName:
      type: string
      enum:
        - shell
        - file_read
        - file_write
        - file_edit
        - file_patch
        - glob
        - grep
        - web_fetch
        - web_search
        - mcp
        - subagent
        - skill
        - unknown
    ToolInput:
      description: A tool call's input; type equals the tool name.
      oneOf:
        - $ref: '#/components/schemas/ShellInput'
        - $ref: '#/components/schemas/FileReadInput'
        - $ref: '#/components/schemas/FileWriteInput'
        - $ref: '#/components/schemas/FileEditInput'
        - $ref: '#/components/schemas/FilePatchInput'
        - $ref: '#/components/schemas/GlobInput'
        - $ref: '#/components/schemas/GrepInput'
        - $ref: '#/components/schemas/WebFetchInput'
        - $ref: '#/components/schemas/WebSearchInput'
        - $ref: '#/components/schemas/McpInput'
        - $ref: '#/components/schemas/SubagentInput'
        - $ref: '#/components/schemas/SkillInput'
        - $ref: '#/components/schemas/UnknownInput'
      discriminator:
        propertyName: type
        mapping:
          shell: '#/components/schemas/ShellInput'
          file_read: '#/components/schemas/FileReadInput'
          file_write: '#/components/schemas/FileWriteInput'
          file_edit: '#/components/schemas/FileEditInput'
          file_patch: '#/components/schemas/FilePatchInput'
          glob: '#/components/schemas/GlobInput'
          grep: '#/components/schemas/GrepInput'
          web_fetch: '#/components/schemas/WebFetchInput'
          web_search: '#/components/schemas/WebSearchInput'
          mcp: '#/components/schemas/McpInput'
          subagent: '#/components/schemas/SubagentInput'
          skill: '#/components/schemas/SkillInput'
          unknown: '#/components/schemas/UnknownInput'
    ToolOutput:
      description: A tool result's output; type equals the tool name.
      oneOf:
        - $ref: '#/components/schemas/ShellOutput'
        - $ref: '#/components/schemas/FileReadOutput'
        - $ref: '#/components/schemas/FileWriteOutput'
        - $ref: '#/components/schemas/FileEditOutput'
        - $ref: '#/components/schemas/FilePatchOutput'
        - $ref: '#/components/schemas/GlobOutput'
        - $ref: '#/components/schemas/GrepOutput'
        - $ref: '#/components/schemas/WebFetchOutput'
        - $ref: '#/components/schemas/WebSearchOutput'
        - $ref: '#/components/schemas/McpOutput'
        - $ref: '#/components/schemas/SubagentOutput'
        - $ref: '#/components/schemas/SkillOutput'
        - $ref: '#/components/schemas/UnknownOutput'
      discriminator:
        propertyName: type
        mapping:
          shell: '#/components/schemas/ShellOutput'
          file_read: '#/components/schemas/FileReadOutput'
          file_write: '#/components/schemas/FileWriteOutput'
          file_edit: '#/components/schemas/FileEditOutput'
          file_patch: '#/components/schemas/FilePatchOutput'
          glob: '#/components/schemas/GlobOutput'
          grep: '#/components/schemas/GrepOutput'
          web_fetch: '#/components/schemas/WebFetchOutput'
          web_search: '#/components/schemas/WebSearchOutput'
          mcp: '#/components/schemas/McpOutput'
          subagent: '#/components/schemas/SubagentOutput'
          skill: '#/components/schemas/SkillOutput'
          unknown: '#/components/schemas/UnknownOutput'
    ShellInput:
      type: object
      required:
        - type
        - command
        - description
        - timeoutMs
      properties:
        type:
          const: shell
        command:
          type: string
        description:
          type: string
        timeoutMs:
          type: integer
    FileReadInput:
      type: object
      required:
        - type
        - path
        - offset
        - limit
      properties:
        type:
          const: file_read
        path:
          type: string
        offset:
          type: integer
        limit:
          type: integer
    FileWriteInput:
      type: object
      required:
        - type
        - path
        - content
      properties:
        type:
          const: file_write
        path:
          type: string
        content:
          type: string
    FileEditInput:
      type: object
      required:
        - type
        - path
        - oldString
        - newString
        - replaceAll
      properties:
        type:
          const: file_edit
        path:
          type: string
        oldString:
          type: string
        newString:
          type: string
        replaceAll:
          type: boolean
    FilePatchInput:
      type: object
      required:
        - type
        - changes
      properties:
        type:
          const: file_patch
        changes:
          type: array
          items:
            $ref: '#/components/schemas/FileChange'
    GlobInput:
      type: object
      required:
        - type
        - pattern
        - path
      properties:
        type:
          const: glob
        pattern:
          type: string
        path:
          type: string
    GrepInput:
      type: object
      required:
        - type
        - pattern
        - path
        - glob
      properties:
        type:
          const: grep
        pattern:
          type: string
        path:
          type: string
        glob:
          type: string
    WebFetchInput:
      type: object
      required:
        - type
        - url
        - prompt
      properties:
        type:
          const: web_fetch
        url:
          type: string
        prompt:
          type: string
    WebSearchInput:
      type: object
      required:
        - type
        - query
      properties:
        type:
          const: web_search
        query:
          type: string
    McpInput:
      type: object
      required:
        - type
        - server
        - tool
        - arguments
      properties:
        type:
          const: mcp
        server:
          type: string
        tool:
          type: string
        arguments:
          description: The tool's arguments, as the harness reported them.
    SubagentInput:
      type: object
      required:
        - type
        - description
        - prompt
        - subagentType
      properties:
        type:
          const: subagent
        description:
          type: string
        prompt:
          type: string
        subagentType:
          type: string
          description: >-
            The core's SubagentInput.Type; renamed because type is the
            discriminator.
    SkillInput:
      type: object
      required:
        - type
        - name
        - args
      properties:
        type:
          const: skill
        name:
          type: string
          description: The skill the harness runs, such as frontend-design:frontend-design.
        args:
          type: string
          description: The skill's arguments; empty when the call has none.
    UnknownInput:
      type: object
      required:
        - type
        - raw
      properties:
        type:
          const: unknown
        raw:
          description: The harness's original JSON for the call.
    ShellOutput:
      type: object
      required:
        - type
        - output
        - exitCode
      properties:
        type:
          const: shell
        output:
          type: string
        exitCode:
          type:
            - integer
            - 'null'
    FileReadOutput:
      type: object
      required:
        - type
        - content
      properties:
        type:
          const: file_read
        content:
          type: string
    FileWriteOutput:
      type: object
      required:
        - type
        - text
      properties:
        type:
          const: file_write
        text:
          type: string
    FileEditOutput:
      type: object
      required:
        - type
        - text
      properties:
        type:
          const: file_edit
        text:
          type: string
    FilePatchOutput:
      type: object
      required:
        - type
        - text
      properties:
        type:
          const: file_patch
        text:
          type: string
    GlobOutput:
      type: object
      required:
        - type
        - text
      properties:
        type:
          const: glob
        text:
          type: string
    GrepOutput:
      type: object
      required:
        - type
        - text
      properties:
        type:
          const: grep
        text:
          type: string
    WebFetchOutput:
      type: object
      required:
        - type
        - text
      properties:
        type:
          const: web_fetch
        text:
          type: string
    WebSearchOutput:
      type: object
      required:
        - type
        - text
      properties:
        type:
          const: web_search
        text:
          type: string
    McpOutput:
      type: object
      required:
        - type
        - content
      properties:
        type:
          const: mcp
        content:
          description: The tool's result content, as the harness reported it.
    SubagentOutput:
      type: object
      required:
        - type
        - text
      properties:
        type:
          const: subagent
        text:
          type: string
    SkillOutput:
      type: object
      required:
        - type
        - text
      properties:
        type:
          const: skill
        text:
          type: string
    UnknownOutput:
      type: object
      required:
        - type
        - raw
      properties:
        type:
          const: unknown
        raw:
          description: The harness's original JSON for the result.
    FileChange:
      type: object
      required:
        - path
        - kind
        - diff
      properties:
        path:
          type: string
        kind:
          type: string
          enum:
            - add
            - delete
            - update
        diff:
          type: string
  responses:
    Error:
      description: Every non-2xx response
      headers:
        Request-Id:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorBody'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: An API key, or a session token on its own session

````

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