> ## 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 prompt

> Records what a terminal chat's Claude Code session waits on its person for, from its PermissionRequest hook, and answers the prompt. A permission prompt asks to run one tool call: the machine bridge holds the hook open for hold_seconds while Aether shows it and notifies the person, who answers from Aether or in the terminal, whichever comes first. A question (AskUserQuestion, or the plan ExitPlanMode asks to approve) is answered in the terminal alone; Aether shows it.

Use this tool when you need to:
- Show a permission request Claude Code holds open in the terminal, and notify its person
- Show that a terminal chat waits on a question in the terminal

Examples:
- PUT /computers/{computerID}/terminal-chats/{sessionID}/prompts/{promptID} {"kind": "permission", "tool_name": "Bash", "tool_input": {"command": "git push origin main"}, "input_shortened": false, "hold_seconds": 3000}

Hints:
- promptID is the bridge's own id of the prompt: reporting it again answers the same prompt, its hold unmoved, and notifies nobody twice. A prompt of the id that asks something else is refused with 409 terminal_chat_prompt_differs.
- The prompt expires hold_seconds from the first report: the hook then answers no decision, and the prompt stays in the terminal alone.
- A prompt of a turn the bridge runs itself carries run_id, the run's delivery_id (reportTerminalChatRun): no terminal answers it, so Aether shows its question as answerable too, and the bridge denies it when its hold ends unanswered and closes it expired. A run the chat holds none of is refused with 422.
- tool_input holds at most 64 KiB as Postgres stores it, each key once and no NUL character: a longer input is refused with 422. Shorten its strings and set input_shortened. A body the API cannot read, a number past a double's range included, is refused with 400.
- decisions, on a permission prompt, names what it offers beside allow and deny: an allow that adds, for the agent's session alone, allow rules the agent itself suggested for the request's own tool, the one kind Aether offers. A person's answer that picks one reads with decision_id. Any other kind, an id allow or deny or named twice, more than 8 decisions or rules, a rule of another tool, or rules whose text holds a link, an address or a domain or runs over 200 characters, is refused whole with 422 prompt_decisions_refused (a value the schema does not take with 422 validation_failed). A report of the same id with other decisions asks something else.
- Wait for the answer with getTerminalChatPrompt and close the prompt with closeTerminalChatPrompt.
- 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 PUT /computers/{computerID}/terminal-chats/{sessionID}/prompts/{promptID}
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}/prompts/{promptID}:
    put:
      tags:
        - computers
      summary: Report a terminal chat's prompt
      description: >-
        Records what a terminal chat's Claude Code session waits on its person
        for, from its PermissionRequest hook, and answers the prompt. A
        permission prompt asks to run one tool call: the machine bridge holds
        the hook open for hold_seconds while Aether shows it and notifies the
        person, who answers from Aether or in the terminal, whichever comes
        first. A question (AskUserQuestion, or the plan ExitPlanMode asks to
        approve) is answered in the terminal alone; Aether shows it.


        Use this tool when you need to:

        - Show a permission request Claude Code holds open in the terminal, and
        notify its person

        - Show that a terminal chat waits on a question in the terminal


        Examples:

        - PUT
        /computers/{computerID}/terminal-chats/{sessionID}/prompts/{promptID}
        {"kind": "permission", "tool_name": "Bash", "tool_input": {"command":
        "git push origin main"}, "input_shortened": false, "hold_seconds": 3000}


        Hints:

        - promptID is the bridge's own id of the prompt: reporting it again
        answers the same prompt, its hold unmoved, and notifies nobody twice. A
        prompt of the id that asks something else is refused with 409
        terminal_chat_prompt_differs.

        - The prompt expires hold_seconds from the first report: the hook then
        answers no decision, and the prompt stays in the terminal alone.

        - A prompt of a turn the bridge runs itself carries run_id, the run's
        delivery_id (reportTerminalChatRun): no terminal answers it, so Aether
        shows its question as answerable too, and the bridge denies it when its
        hold ends unanswered and closes it expired. A run the chat holds none of
        is refused with 422.

        - tool_input holds at most 64 KiB as Postgres stores it, each key once
        and no NUL character: a longer input is refused with 422. Shorten its
        strings and set input_shortened. A body the API cannot read, a number
        past a double's range included, is refused with 400.

        - decisions, on a permission prompt, names what it offers beside allow
        and deny: an allow that adds, for the agent's session alone, allow rules
        the agent itself suggested for the request's own tool, the one kind
        Aether offers. A person's answer that picks one reads with decision_id.
        Any other kind, an id allow or deny or named twice, more than 8
        decisions or rules, a rule of another tool, or rules whose text holds a
        link, an address or a domain or runs over 200 characters, is refused
        whole with 422 prompt_decisions_refused (a value the schema does not
        take with 422 validation_failed). A report of the same id with other
        decisions asks something else.

        - Wait for the answer with getTerminalChatPrompt and close the prompt
        with closeTerminalChatPrompt.

        - 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: openTerminalChatPrompt
      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
        - in: path
          name: promptID
          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:
                decisions:
                  description: >-
                    permission only: what the request offers beside allow and
                    deny, which every permission request offers, from what the
                    agent itself suggested. Absent when it offers nothing else.
                    Each adds, for the agent's session alone, allow rules the
                    agent suggested for the request's own tool; the bridge names
                    no change of mode, no folder and no write to a settings
                    file. A report naming anything else, an id twice, an id
                    allow or deny, or rules whose text holds a link, an address
                    or a domain or runs over 200 characters, is refused whole
                    with 422 prompt_decisions_refused.
                  items:
                    additionalProperties: false
                    properties:
                      behavior:
                        enum:
                          - allow
                        type: string
                      destination:
                        description: >-
                          The rules hold for the agent's session alone, and are
                          written to no settings file.
                        enum:
                          - session
                        type: string
                      id:
                        description: >-
                          Names the decision in the answer; neither allow nor
                          deny.
                        pattern: ^[a-z][a-z0-9_]{0,63}$
                        type: string
                      rules:
                        items:
                          additionalProperties: false
                          properties:
                            rule_content:
                              description: >-
                                What of the tool the rule matches, as Claude
                                Code writes a rule's content (npm test *);
                                absent for the whole tool.
                              maxLength: 200
                              minLength: 1
                              type: string
                              x-aether-string-length-unit: unicode-code-point
                            tool_name:
                              description: The request's own tool.
                              maxLength: 200
                              minLength: 1
                              type: string
                              x-aether-string-length-unit: unicode-code-point
                          required:
                            - tool_name
                          type: object
                        maxItems: 8
                        minItems: 1
                        type: array
                      type:
                        enum:
                          - add_rules
                        type: string
                    required:
                      - id
                      - type
                      - behavior
                      - destination
                      - rules
                    type: object
                  maxItems: 8
                  minItems: 1
                  type: array
                hold_seconds:
                  description: >-
                    How long from now the bridge holds the hook open, in
                    seconds: the prompt expires then.
                  maximum: 7200
                  minimum: 1
                  type: integer
                input_shortened:
                  description: >-
                    The bridge cut the input's longest strings to fit it in 64
                    KiB.
                  type: boolean
                kind:
                  description: >-
                    permission asks to run a tool call, answerable from Aether;
                    question asks in the terminal alone (AskUserQuestion,
                    ExitPlanMode), or, a run's, from Aether alone.
                  enum:
                    - permission
                    - question
                  type: string
                run_id:
                  description: >-
                    The run whose hooks reported the prompt
                    (reportTerminalChatRun's delivery_id): no terminal answers
                    it, so Aether shows a question of it as answerable too.
                    Absent for a terminal's.
                  format: uuid
                  type: string
                tool_input:
                  additionalProperties: true
                  description: >-
                    The tool call's input, as Claude Code asked to run it: at
                    most 64 KiB as Postgres stores it, each key once.
                  properties: {}
                  type: object
                tool_name:
                  description: >-
                    The Claude Code tool the prompt is about: Bash, Edit, an MCP
                    tool.
                  maxLength: 200
                  minLength: 1
                  type: string
                  x-aether-string-length-unit: unicode-code-point
              required:
                - kind
                - tool_name
                - tool_input
                - input_shortened
                - hold_seconds
              type: object
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TerminalChatPrompt'
          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
        '409':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ComputersErrorResponse'
          description: Conflict
        '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:
    TerminalChatPrompt:
      additionalProperties: false
      properties:
        chat_id:
          format: uuid
          type: string
        expires_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        input_shortened:
          type: boolean
        kind:
          enum:
            - permission
            - question
          type: string
        requested_at:
          format: date-time
          type: string
        state:
          $ref: '#/components/schemas/TerminalChatPromptState'
        tool_input:
          additionalProperties: true
          description: >-
            The tool call's input, as Claude Code asked to run it: at most 64
            KiB as Postgres stores it, each key once.
          properties: {}
          type: object
        tool_name:
          description: 'The Claude Code tool the prompt is about: Bash, Edit, an MCP tool.'
          maxLength: 200
          minLength: 1
          type: string
          x-aether-string-length-unit: unicode-code-point
      required:
        - id
        - chat_id
        - kind
        - tool_name
        - tool_input
        - input_shortened
        - requested_at
        - expires_at
        - state
      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
    TerminalChatPromptState:
      discriminator:
        mapping:
          answered: '#/components/schemas/TerminalChatPromptAnswered'
          answered_from_aether: '#/components/schemas/TerminalChatPromptAnsweredFromAether'
          answered_in_terminal: '#/components/schemas/TerminalChatPromptAnsweredInTerminal'
          expired: '#/components/schemas/TerminalChatPromptExpired'
          open: '#/components/schemas/TerminalChatPromptOpen'
          stopped: '#/components/schemas/TerminalChatPromptStopped'
        propertyName: kind
      oneOf:
        - $ref: '#/components/schemas/TerminalChatPromptOpen'
        - $ref: '#/components/schemas/TerminalChatPromptAnswered'
        - $ref: '#/components/schemas/TerminalChatPromptAnsweredFromAether'
        - $ref: '#/components/schemas/TerminalChatPromptAnsweredInTerminal'
        - $ref: '#/components/schemas/TerminalChatPromptStopped'
        - $ref: '#/components/schemas/TerminalChatPromptExpired'
    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
    TerminalChatPromptAnswered:
      additionalProperties: false
      description: Answered from Aether, on its way to the hook.
      properties:
        answer:
          $ref: '#/components/schemas/TerminalChatPromptAnswer'
        kind:
          enum:
            - answered
          type: string
      required:
        - kind
        - answer
      type: object
    TerminalChatPromptAnsweredFromAether:
      additionalProperties: false
      description: The answer from Aether reached Claude Code.
      properties:
        answer:
          $ref: '#/components/schemas/TerminalChatPromptAnswer'
        kind:
          enum:
            - answered_from_aether
          type: string
      required:
        - kind
        - answer
      type: object
    TerminalChatPromptAnsweredInTerminal:
      additionalProperties: false
      description: >-
        The terminal answered first; late_answer is an answer from Aether Claude
        Code never got, null when there was none.
      properties:
        kind:
          enum:
            - answered_in_terminal
          type: string
        late_answer:
          anyOf:
            - $ref: '#/components/schemas/TerminalChatPromptAnswer'
            - type: 'null'
      required:
        - kind
        - late_answer
      type: object
    TerminalChatPromptExpired:
      additionalProperties: false
      description: >-
        The hold ended first and the prompt stays in the terminal, or, a run's,
        was denied; late_answer is an answer from Aether that did not reach the
        hook in time, null when there was none.
      properties:
        kind:
          enum:
            - expired
          type: string
        late_answer:
          anyOf:
            - $ref: '#/components/schemas/TerminalChatPromptAnswer'
            - type: 'null'
      required:
        - kind
        - late_answer
      type: object
    TerminalChatPromptOpen:
      additionalProperties: false
      description: >-
        Waiting on the person, in Aether and in the terminal; a run's, in Aether
        alone.
      properties:
        kind:
          enum:
            - open
          type: string
      required:
        - kind
      type: object
    TerminalChatPromptStopped:
      additionalProperties: false
      description: >-
        A stop from Aether ended the turn first: Claude Code denied the tool
        call and stopped. late_answer is an answer from Aether Claude Code never
        got, null when there was none.
      properties:
        kind:
          enum:
            - stopped
          type: string
        late_answer:
          anyOf:
            - $ref: '#/components/schemas/TerminalChatPromptAnswer'
            - type: 'null'
      required:
        - kind
        - late_answer
      type: object
    TerminalChatPromptAnswer:
      additionalProperties: false
      properties:
        answered_at:
          format: date-time
          type: string
        answers:
          additionalProperties:
            maxLength: 2000
            minLength: 1
            type: string
            x-aether-string-length-unit: unicode-code-point
          description: >-
            The answer to each question of a run's AskUserQuestion, keyed by the
            question, when it was answered so; absent otherwise.
          type: object
        decision:
          description: allow lets the tool call run; deny refuses it.
          enum:
            - allow
            - deny
          type: string
        decision_id:
          description: >-
            The decision the request was opened with that an allow picked: the
            bridge adds its rules for the session alone, from what it holds of
            the request. Absent on a plain allow, on a denial, and on every
            answer to a request opened with no decisions.
          pattern: ^[a-z][a-z0-9_]{0,63}$
          type: string
        reason:
          description: >-
            What a denial tells Claude; null for an approval and for a denial
            that gave none.
          maxLength: 2000
          minLength: 1
          type:
            - string
            - 'null'
          x-aether-string-length-unit: unicode-code-point
      required:
        - decision
        - reason
        - answered_at
      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.