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

# Report a terminal chat's status

> Records what a terminal chat's machine bridge observes of it: the status its Claude Code hooks report (running from a prompt to the end of its turn, needs_you while a permission request is open, idle otherwise), that its session's file is gone from the computer, or where its session is open. Answers the chat.

Use this tool when you need to:
- Report a terminal chat's status from its hooks, as the machine bridge does
- Report that a session file the bridge shipped is gone from the computer, so the chat is read-only history
- Report whether a terminal Aether can write to holds the session

Examples:
- PATCH /computers/{computerID}/terminal-chats/{sessionID} {"status": "running", "observed_at": "2026-11-07T10:00:00.120Z"}
- PATCH /computers/{computerID}/terminal-chats/{sessionID} {"session_gone": true, "observed_at": "2026-11-07T10:00:00.120Z"}
- PATCH /computers/{computerID}/terminal-chats/{sessionID} {"open_in": "terminal", "observed_at": "2026-11-07T10:00:00.120Z"}

Hints:
- A report is status, session_gone or open_in, exactly one: a body with two, or none, is refused with 422.
- open_in is terminal while a terminal Aether can write to holds the session, null while none does: the chat reads what the agent supports in a terminal, or as a run. Report it for each session after every connect, which clears it for the computer's sessions, and again whenever it changes, in order: the latest report stands. A report that arrived before a connect writes nothing after it.
- observed_at is when the bridge observed the status, or the file gone, on the computer's clock. A status observed before the chat's current status began changes nothing, so a retried report is harmless; a Stop that reports background work still running is reported running from the Stop.
- session_gone keeps the chat's status as it was and sets its session_gone_at, unless a status observed after it says the file was there; one already set keeps its first time. A status observed no earlier than it, or a range of the session's files, means the file is back and clears it.
- The session file closes a turn its hooks did not end (Escape in the terminal, a prompt a hook blocked, a manual /compact, a permission Claude denied itself): its reader sets the chat idle from the turn's end.
- A session the computer holds no chat of for the caller (ensureTerminalChat creates it), or a computer that is not theirs, is refused with 404 not_found.
- Only the grant of the caller's coding agent's bridge calls it, the machine bridge on the computer: a session or an API key is refused with 403 credential_kind_not_admitted.
- The call presents the computer's own secret, which aether setup keeps on it, in the Aether-Computer-Secret header. A computer that has none is refused with 403 computer_needs_setup: update the aether CLI there and run aether setup. A call that presents no secret, or another, is refused with 403 computer_set_up_elsewhere.



## OpenAPI

````yaml api-reference/openapi.json PATCH /computers/{computerID}/terminal-chats/{sessionID}
openapi: 3.1.0
info:
  title: Aether API
  version: 0.1.0
servers:
  - url: https://api.runaether.dev
security:
  - bearerAuth: []
paths:
  /computers/{computerID}/terminal-chats/{sessionID}:
    patch:
      tags:
        - computers
      summary: Report a terminal chat's status
      description: >-
        Records what a terminal chat's machine bridge observes of it: the status
        its Claude Code hooks report (running from a prompt to the end of its
        turn, needs_you while a permission request is open, idle otherwise),
        that its session's file is gone from the computer, or where its session
        is open. Answers the chat.


        Use this tool when you need to:

        - Report a terminal chat's status from its hooks, as the machine bridge
        does

        - Report that a session file the bridge shipped is gone from the
        computer, so the chat is read-only history

        - Report whether a terminal Aether can write to holds the session


        Examples:

        - PATCH /computers/{computerID}/terminal-chats/{sessionID} {"status":
        "running", "observed_at": "2026-11-07T10:00:00.120Z"}

        - PATCH /computers/{computerID}/terminal-chats/{sessionID}
        {"session_gone": true, "observed_at": "2026-11-07T10:00:00.120Z"}

        - PATCH /computers/{computerID}/terminal-chats/{sessionID} {"open_in":
        "terminal", "observed_at": "2026-11-07T10:00:00.120Z"}


        Hints:

        - A report is status, session_gone or open_in, exactly one: a body with
        two, or none, is refused with 422.

        - open_in is terminal while a terminal Aether can write to holds the
        session, null while none does: the chat reads what the agent supports in
        a terminal, or as a run. Report it for each session after every connect,
        which clears it for the computer's sessions, and again whenever it
        changes, in order: the latest report stands. A report that arrived
        before a connect writes nothing after it.

        - observed_at is when the bridge observed the status, or the file gone,
        on the computer's clock. A status observed before the chat's current
        status began changes nothing, so a retried report is harmless; a Stop
        that reports background work still running is reported running from the
        Stop.

        - session_gone keeps the chat's status as it was and sets its
        session_gone_at, unless a status observed after it says the file was
        there; one already set keeps its first time. A status observed no
        earlier than it, or a range of the session's files, means the file is
        back and clears it.

        - The session file closes a turn its hooks did not end (Escape in the
        terminal, a prompt a hook blocked, a manual /compact, a permission
        Claude denied itself): its reader sets the chat idle from the turn's
        end.

        - A session the computer holds no chat of for the caller
        (ensureTerminalChat creates it), or a computer that is not theirs, is
        refused with 404 not_found.

        - Only the grant of the caller's coding agent's bridge calls it, the
        machine bridge on the computer: a session or an API key is refused with
        403 credential_kind_not_admitted.

        - The call presents the computer's own secret, which aether setup keeps
        on it, in the Aether-Computer-Secret header. A computer that has none is
        refused with 403 computer_needs_setup: update the aether CLI there and
        run aether setup. A call that presents no secret, or another, is refused
        with 403 computer_set_up_elsewhere.
      operationId: patchTerminalChat
      parameters:
        - in: path
          name: computerID
          required: true
          schema:
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            type: string
        - in: path
          name: sessionID
          required: true
          schema:
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
            type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                observed_at:
                  description: >-
                    When the machine bridge observed the status, the file gone,
                    or where the session is open, on the computer's clock.
                  format: date-time
                  type: string
                open_in:
                  description: >-
                    Where the session is open: terminal while a terminal Aether
                    can write to holds it, null while none does. Sent alone;
                    absent is no report.
                  enum:
                    - terminal
                  type:
                    - string
                    - 'null'
                session_gone:
                  description: >-
                    true: the session file the bridge shipped is gone from the
                    computer, so the chat is read-only history. Sent alone;
                    false is no report.
                  type: boolean
                status:
                  description: The status the chat's hooks report. Sent alone.
                  enum:
                    - running
                    - needs_you
                    - idle
                  type: string
              required:
                - observed_at
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputerTerminalChat'
          description: OK
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unauthorized
        '403':
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/ComputersErrorResponse'
                  - $ref: '#/components/schemas/OrgAuthorizationErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Not Found
        '410':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Gone
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Unprocessable Entity
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Internal Server Error
components:
  schemas:
    ComputerTerminalChat:
      additionalProperties: false
      description: >-
        A terminal chat as its computer's machine bridge reads it: its id, its
        task, its status and whether its session's file is gone.
      properties:
        id:
          format: uuid
          type: string
        session_gone_at:
          description: >-
            When the computer's machine bridge found the session's file gone
            from the computer, on its clock: Claude Code can no longer resume
            the session there, so the chat is read-only history. Null while the
            file is there, and always from a machine bridge too old to report
            it.
          format: date-time
          type:
            - string
            - 'null'
        status:
          description: >-
            running from a prompt to the end of its turn, needs_you while a
            permission request is open, idle otherwise.
          enum:
            - running
            - needs_you
            - idle
          type: string
        task_id:
          format: uuid
          type: string
      required:
        - id
        - task_id
        - status
        - session_gone_at
      type: object
    ComputersErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - account_deleting
            - aether_inference_unserved
            - agent_pr_blocked
            - agent_pr_pending
            - agent_profile_changed
            - agent_starts_off
            - agent_starts_on_from_computer_only
            - agent_uses_own_sign_in
            - answer_on_its_way
            - app_identity_missing
            - attachments_unsupported
            - attribution_unavailable
            - bad_gateway
            - bad_request
            - base_branch_unusable
            - branch_exists
            - caller_inactive
            - chat_archived
            - chat_being_forked
            - chat_moved
            - chat_not_removable
            - chat_settings_fixed
            - chats_not_addable
            - checkout_not_archivable
            - cli_upgrade_required
            - client_outdated
            - computer_cli_outdated
            - computer_needs_fresh_sign_in
            - computer_needs_setup
            - computer_registered_to_another_person
            - computer_set_up_elsewhere
            - computer_starts_no_agents
            - computer_starts_no_forks
            - computer_task_start_moved
            - computer_unreachable
            - conflict
            - connection_creator_only
            - connection_harness_mismatch
            - connection_not_held
            - contents_write_required
            - continuation_failed
            - continuation_unavailable
            - control_forbidden
            - credential_kind_not_admitted
            - credential_named_file
            - detached_head
            - download_unsupported
            - embeddings_unavailable
            - feature_unsupported
            - file_references_unsupported
            - fix_not_requested
            - fix_requests_unrecorded
            - forbidden
            - fork_branch_delete_unsupported
            - fork_forbidden
            - fork_in_progress
            - fork_unsupported
            - gateway_timeout
            - github_failed
            - github_identity_required
            - github_push_access_required
            - gone
            - handed_branch_protected
            - head_moved
            - html_render_nul_byte
            - html_render_too_large
            - idempotency_key_conflict
            - idempotency_key_reused
            - idle_compaction_not_pending
            - idle_compaction_skipped
            - inference_proxy_unavailable
            - insufficient_credits
            - insufficient_inference_balance
            - interaction_mode_unsupported
            - internal_error
            - invalid_request
            - last_queued_message
            - live_protocol_unsupported
            - main_chat_permanent
            - mcp_server_not_connected
            - merge_when_ready_requires_pr_review
            - message_not_queued
            - message_not_waiting
            - method_not_allowed
            - mode_forbidden
            - name_follows_session
            - no_checkout_on_computer
            - no_checkpoint_yet
            - no_commit
            - no_dispatch_target
            - no_main_chat
            - no_origin
            - no_work_tree_folder
            - not_acceptable
            - not_found
            - not_implemented
            - onboarding_already_completed
            - onboarding_requirements_missing
            - open_in_terminal
            - org_id_required
            - org_role_insufficient
            - org_suspended
            - payment_required
            - pending_input_answered
            - permission_prompt_open
            - pr_automation_unsupported
            - pr_review_actor_required
            - pr_review_connection_spent
            - pr_review_publish_forbidden
            - precondition_failed
            - project_has_no_repository
            - project_not_a_choice
            - project_required
            - prompt_decisions_refused
            - pull_request_closed
            - pull_request_mirror_failed
            - pull_request_not_mirrored
            - push_failed
            - question_answers
            - question_shortened
            - queue_for_later_unsupported
            - queued_stop_requires_discard
            - rate_limited
            - reasoning_effort_fixed
            - remote_changes_on_from_computer_only
            - repository_not_connected
            - request_canceled
            - request_expired
            - request_timeout
            - request_too_large
            - review_name_follows_pull_request
            - sandbox_deleted
            - sandbox_failed
            - sandbox_needs_message
            - service_unavailable
            - session_file_generation
            - session_file_hole
            - session_file_missing
            - session_file_range_differs
            - session_gone
            - session_not_started_by_aether
            - slash_commands_unsupported
            - stack_cycle
            - stack_too_large
            - stack_two_parents
            - stale_execution
            - stale_or_indeterminate
            - stale_pending_input
            - start_cancelled
            - stream_delivery_gap
            - stream_event_conflict
            - task_archived
            - task_awaiting_message
            - task_awaiting_tool_response
            - task_backed_by_work_tree
            - task_connection_disconnected
            - task_creator_deleted
            - task_has_no_branch
            - task_has_no_repository
            - task_ineligible
            - task_not_accepting_messages
            - task_not_pinnable
            - task_not_started
            - task_settings_changed
            - task_start_failed
            - task_start_pending
            - teleport_unavailable
            - terminal_chat
            - terminal_chat_continuation_refused
            - terminal_chat_prompt_closed_otherwise
            - terminal_chat_prompt_differs
            - terminal_chat_prompt_not_answered
            - terminal_chat_removed
            - terminal_chat_run_moved
            - terminal_question
            - too_large
            - too_many_live_connections
            - too_many_waiting_messages
            - turn_running
            - unauthenticated
            - unsigned_aether_head
            - unsigned_commit
            - unsupported_changes
            - unsupported_media_type
            - untyped_error
            - user_suspended
            - validation_failed
            - work_tree_repository_differs
            - workspace_git_unavailable
            - workspace_gone
            - workspace_outdated
            - workspace_rejected
            - workspace_start_failed
          minLength: 1
          type: string
        error:
          minLength: 1
          type: string
        errors:
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type: array
      required:
        - error
        - code
      type: object
    OrgAuthorizationErrorResponse:
      additionalProperties: false
      properties:
        code:
          enum:
            - org_membership_required
            - org_role_insufficient
            - org_suspended
            - account_deleting
            - agent_host_route_not_allowed
            - credential_kind_not_admitted
            - grant_scope_insufficient
          type: string
        error:
          minLength: 1
          type: string
      required:
        - error
        - code
      type: object
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: >-
            Where the error occurred, e.g. 'body.items[3].tags' or
            'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http

````

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