core/core-agent-ide
8
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
core-agent-ide/codex-rs/app-server-protocol/schema/json/v2
History
Andrei Eternal 6fef421654
[hooks] userpromptsubmit - hook before user's prompt is executed (#14626) 
- this allows blocking the user's prompts from executing, and also
prevents them from entering history
- handles the edge case where you can both prevent the user's prompt AND
add n amount of additionalContexts
- refactors some old code into common.rs where hooks overlap
functionality
- refactors additionalContext being previously added to user messages,
instead we use developer messages for them
- handles queued messages correctly

Sample hook for testing - if you write "[block-user-submit]" this hook
will stop the thread:

example run
```
› sup


• Running UserPromptSubmit hook: reading the observatory notes

UserPromptSubmit hook (completed)
  warning: wizard-tower UserPromptSubmit demo inspected: sup
  hook context: Wizard Tower UserPromptSubmit demo fired. For this reply only, include the exact
phrase 'observatory lanterns lit' exactly once near the end.

• Just riding the cosmic wave and ready to help, my friend. What are we building today? observatory
  lanterns lit


› and [block-user-submit]


• Running UserPromptSubmit hook: reading the observatory notes

UserPromptSubmit hook (stopped)
  warning: wizard-tower UserPromptSubmit demo blocked the prompt on purpose.
  stop: Wizard Tower demo block: remove [block-user-submit] to continue.
```

.codex/config.toml
```
[features]
codex_hooks = true
```

.codex/hooks.json
```
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 .codex/hooks/user_prompt_submit_demo.py",
            "timeoutSec": 10,
            "statusMessage": "reading the observatory notes"
          }
        ]
      }
    ]
  }
}
```

.codex/hooks/user_prompt_submit_demo.py
```
#!/usr/bin/env python3

import json
import sys
from pathlib import Path


def prompt_from_payload(payload: dict) -> str:
    prompt = payload.get("prompt")
    if isinstance(prompt, str) and prompt.strip():
        return prompt.strip()

    event = payload.get("event")
    if isinstance(event, dict):
        user_prompt = event.get("user_prompt")
        if isinstance(user_prompt, str):
            return user_prompt.strip()

    return ""


def main() -> int:
    payload = json.load(sys.stdin)
    prompt = prompt_from_payload(payload)
    cwd = Path(payload.get("cwd", ".")).name or "wizard-tower"

    if "[block-user-submit]" in prompt:
        print(
            json.dumps(
                {
                    "systemMessage": (
                        f"{cwd} UserPromptSubmit demo blocked the prompt on purpose."
                    ),
                    "decision": "block",
                    "reason": (
                        "Wizard Tower demo block: remove [block-user-submit] to continue."
                    ),
                }
            )
        )
        return 0

    prompt_preview = prompt or "(empty prompt)"
    if len(prompt_preview) > 80:
        prompt_preview = f"{prompt_preview[:77]}..."

    print(
        json.dumps(
            {
                "systemMessage": (
                    f"{cwd} UserPromptSubmit demo inspected: {prompt_preview}"
                ),
                "hookSpecificOutput": {
                    "hookEventName": "UserPromptSubmit",
                    "additionalContext": (
                        "Wizard Tower UserPromptSubmit demo fired. "
                        "For this reply only, include the exact phrase "
                        "'observatory lanterns lit' exactly once near the end."
                    ),
                },
            }
        )
    )
    return 0


if __name__ == "__main__":
    raise SystemExit(main())
```
2026-03-17 22:09:22 -07:00
..
AccountLoginCompletedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
AccountRateLimitsUpdatedNotification.json feat: support multiple rate limits (#11260) 2026-02-10 20:09:31 -08:00
AccountUpdatedNotification.json [codex] include plan type in account updates (#13181) 2026-03-01 13:43:37 -08:00
AgentMessageDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
AppListUpdatedNotification.json add @plugin mentions (#13510) 2026-03-06 00:03:39 +00:00
AppsListParams.json [apps] Add thread_id param to optionally load thread config for apps feature check. (#11279) 2026-02-09 23:10:26 -08:00
AppsListResponse.json add @plugin mentions (#13510) 2026-03-06 00:03:39 +00:00
CancelLoginAccountParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
CancelLoginAccountResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
CommandExecOutputDeltaNotification.json app-server: Add streaming and tty/pty capabilities to command/exec (#13640) 2026-03-06 17:30:17 -08:00
CommandExecParams.json app-server: Add streaming and tty/pty capabilities to command/exec (#13640) 2026-03-06 17:30:17 -08:00
CommandExecResizeParams.json app-server: Add streaming and tty/pty capabilities to command/exec (#13640) 2026-03-06 17:30:17 -08:00
CommandExecResizeResponse.json app-server: Add streaming and tty/pty capabilities to command/exec (#13640) 2026-03-06 17:30:17 -08:00
CommandExecResponse.json app-server: Add streaming and tty/pty capabilities to command/exec (#13640) 2026-03-06 17:30:17 -08:00
CommandExecTerminateParams.json app-server: Add streaming and tty/pty capabilities to command/exec (#13640) 2026-03-06 17:30:17 -08:00
CommandExecTerminateResponse.json app-server: Add streaming and tty/pty capabilities to command/exec (#13640) 2026-03-06 17:30:17 -08:00
CommandExecutionOutputDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
CommandExecWriteParams.json app-server: Add streaming and tty/pty capabilities to command/exec (#13640) 2026-03-06 17:30:17 -08:00
CommandExecWriteResponse.json app-server: Add streaming and tty/pty capabilities to command/exec (#13640) 2026-03-06 17:30:17 -08:00
ConfigBatchWriteParams.json [app-server] Support hot-reload user config when batch writing config. (#13839) 2026-03-08 17:38:01 -07:00
ConfigReadParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ConfigReadResponse.json Add Smart Approvals guardian review across core, app-server, and TUI (#13860) 2026-03-13 15:27:00 -07:00
ConfigRequirementsReadResponse.json Rename reject approval policy to granular (#14516) 2026-03-12 16:38:04 -07:00
ConfigValueWriteParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ConfigWarningNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ConfigWriteResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ContextCompactedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
DeprecationNoticeNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ErrorNotification.json change model cap to server overload (#11388) 2026-02-11 17:16:27 -08:00
ExperimentalFeatureListParams.json [app-server] Add a method to list experimental features. (#10721) 2026-02-05 20:04:01 +00:00
ExperimentalFeatureListResponse.json Add stage field for experimental flags. (#10793) 2026-02-05 23:31:04 +00:00
ExternalAgentConfigDetectParams.json Support external agent config detect and import (#12660) 2026-02-25 02:11:51 -08:00
ExternalAgentConfigDetectResponse.json Support external agent config detect and import (#12660) 2026-02-25 02:11:51 -08:00
ExternalAgentConfigImportParams.json Support external agent config detect and import (#12660) 2026-02-25 02:11:51 -08:00
ExternalAgentConfigImportResponse.json Support external agent config detect and import (#12660) 2026-02-25 02:11:51 -08:00
FeedbackUploadParams.json Add ability to attach extra files to feedback (#12370) 2026-02-20 22:26:14 +00:00
FeedbackUploadResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
FileChangeOutputDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
FsCopyParams.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsCopyResponse.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsCreateDirectoryParams.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsCreateDirectoryResponse.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsGetMetadataParams.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsGetMetadataResponse.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsReadDirectoryParams.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsReadDirectoryResponse.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsReadFileParams.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsReadFileResponse.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsRemoveParams.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsRemoveResponse.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsWriteFileParams.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
FsWriteFileResponse.json app-server: add v2 filesystem APIs (#14245) 2026-03-13 14:42:20 -07:00
GetAccountParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
GetAccountRateLimitsResponse.json feat: support multiple rate limits (#11260) 2026-02-10 20:09:31 -08:00
GetAccountResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
HookCompletedNotification.json [hooks] userpromptsubmit - hook before user's prompt is executed (#14626) 2026-03-17 22:09:22 -07:00
HookStartedNotification.json [hooks] userpromptsubmit - hook before user's prompt is executed (#14626) 2026-03-17 22:09:22 -07:00
ItemCompletedNotification.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ItemGuardianApprovalReviewCompletedNotification.json Add Smart Approvals guardian review across core, app-server, and TUI (#13860) 2026-03-13 15:27:00 -07:00
ItemGuardianApprovalReviewStartedNotification.json Add Smart Approvals guardian review across core, app-server, and TUI (#13860) 2026-03-13 15:27:00 -07:00
ItemStartedNotification.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ListMcpServerStatusParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ListMcpServerStatusResponse.json feat: replace custom mcp-types crate with equivalents from rmcp (#10349) 2026-02-02 17:41:55 -08:00
LoginAccountParams.json fix(app-server): for external auth, replace id_token with chatgpt_acc… (#11240) 2026-02-09 20:48:58 -08:00
LoginAccountResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
LogoutAccountResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
McpServerOauthLoginCompletedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
McpServerOauthLoginParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
McpServerOauthLoginResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
McpServerRefreshResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
McpToolCallProgressNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ModelListParams.json fix: send unfiltered models over model/list (#11793) 2026-02-13 16:26:32 -08:00
ModelListResponse.json Add model availability NUX metadata (#12972) 2026-02-26 22:02:57 -08:00
ModelReroutedNotification.json Feat: add model reroute notification (#12001) 2026-02-17 11:02:23 -08:00
PlanDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
PluginInstallParams.json feat: support remote_sync for plugin install/uninstall. (#14878) 2026-03-16 21:37:27 -07:00
PluginInstallResponse.json feat: add plugin/read. (#14445) 2026-03-12 16:52:21 -07:00
PluginListParams.json feat: Allow sync with remote plugin status. (#14176) 2026-03-11 12:33:08 -07:00
PluginListResponse.json fix: align marketplace display name with existing interface conventions (#14886) 2026-03-16 21:52:19 -07:00
PluginReadParams.json feat: add plugin/read. (#14445) 2026-03-12 16:52:21 -07:00
PluginReadResponse.json make defaultPrompt an array, keep backcompat (#14649) 2026-03-14 06:13:51 +00:00
PluginUninstallParams.json feat: support remote_sync for plugin install/uninstall. (#14878) 2026-03-16 21:37:27 -07:00
PluginUninstallResponse.json chore: plugin/uninstall endpoint (#14111) 2026-03-09 12:40:25 -07:00
RawResponseItemCompletedNotification.json generate an internal json schema for RolloutLine (#14434) 2026-03-17 11:19:42 -07:00
ReasoningSummaryPartAddedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ReasoningSummaryTextDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ReasoningTextDeltaNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ReviewStartParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ReviewStartResponse.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ServerRequestResolvedNotification.json app-server: Replay pending item requests on thread/resume (#12560) 2026-02-27 12:45:59 -08:00
SkillsChangedNotification.json feat(app-server): add a skills/changed v2 notification (#13414) 2026-03-03 17:01:00 -08:00
SkillsConfigWriteParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
SkillsConfigWriteResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
SkillsListParams.json feat: extend skills/list to support additional roots. (#10835) 2026-02-09 13:30:38 -08:00
SkillsListResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TerminalInteractionNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadArchivedNotification.json app-server: Emit thread archive/unarchive notifications (#12030) 2026-02-17 14:53:58 -08:00
ThreadArchiveParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadArchiveResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadClosedNotification.json feat(app-server): thread/unsubscribe API (#10954) 2026-02-25 13:14:30 -08:00
ThreadCompactStartParams.json Add thread/compact v2 (#10445) 2026-02-03 18:15:55 -08:00
ThreadCompactStartResponse.json Add thread/compact v2 (#10445) 2026-02-03 18:15:55 -08:00
ThreadForkParams.json Add Smart Approvals guardian review across core, app-server, and TUI (#13860) 2026-03-13 15:27:00 -07:00
ThreadForkResponse.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ThreadListParams.json feat: add search term to thread list (#12578) 2026-02-25 09:59:41 +00:00
ThreadListResponse.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ThreadLoadedListParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadLoadedListResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadMetadataUpdateParams.json Add thread metadata update endpoint to app server (#13280) 2026-03-03 15:56:11 -08:00
ThreadMetadataUpdateResponse.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ThreadNameUpdatedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadReadParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadReadResponse.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ThreadRealtimeClosedNotification.json Add app-server v2 thread realtime API (#12715) 2026-02-25 09:59:10 -08:00
ThreadRealtimeErrorNotification.json Add app-server v2 thread realtime API (#12715) 2026-02-25 09:59:10 -08:00
ThreadRealtimeItemAddedNotification.json Add app-server v2 thread realtime API (#12715) 2026-02-25 09:59:10 -08:00
ThreadRealtimeOutputAudioDeltaNotification.json [stack 2/4] Align main realtime v2 wire and runtime flow (#14830) 2026-03-16 21:38:07 -07:00
ThreadRealtimeStartedNotification.json Gate realtime audio interruption logic to v2 (#14984) 2026-03-17 15:24:37 -07:00
ThreadResumeParams.json generate an internal json schema for RolloutLine (#14434) 2026-03-17 11:19:42 -07:00
ThreadResumeResponse.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ThreadRollbackParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadRollbackResponse.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ThreadSetNameParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadSetNameResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadStartedNotification.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ThreadStartParams.json dynamic tool calls: add param exposeToContext to optionally hide tool (#14501) 2026-03-14 01:58:43 -07:00
ThreadStartResponse.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ThreadStatusChangedNotification.json app-server: expose loaded thread status via read/list and notifications (#11786) 2026-02-18 15:20:03 -08:00
ThreadTokenUsageUpdatedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadUnarchivedNotification.json app-server: Emit thread archive/unarchive notifications (#12030) 2026-02-17 14:53:58 -08:00
ThreadUnarchiveParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
ThreadUnarchiveResponse.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
ThreadUnsubscribeParams.json feat(app-server): thread/unsubscribe API (#10954) 2026-02-25 13:14:30 -08:00
ThreadUnsubscribeResponse.json feat(app-server): thread/unsubscribe API (#10954) 2026-02-25 13:14:30 -08:00
TurnCompletedNotification.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
TurnDiffUpdatedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnInterruptParams.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnInterruptResponse.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnPlanUpdatedNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00
TurnStartedNotification.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
TurnStartParams.json Add Smart Approvals guardian review across core, app-server, and TUI (#13860) 2026-03-13 15:27:00 -07:00
TurnStartResponse.json feat: make interrupt state not final for multi-agents (#13850) 2026-03-16 16:39:40 +00:00
TurnSteerParams.json feat(app-server): turn/steer API (#10821) 2026-02-06 00:35:04 +00:00
TurnSteerResponse.json feat(app-server): turn/steer API (#10821) 2026-02-06 00:35:04 +00:00
WindowsSandboxSetupCompletedNotification.json app-server support for Windows sandbox setup. (#12025) 2026-02-18 13:03:16 -08:00
WindowsSandboxSetupStartParams.json app-server: include experimental skill metadata in exec approval requests (#13929) 2026-03-08 18:07:46 -07:00
WindowsSandboxSetupStartResponse.json app-server support for Windows sandbox setup. (#12025) 2026-02-18 13:03:16 -08:00
WindowsWorldWritableWarningNotification.json feat: vendor app-server protocol schema fixtures (#10371) 2026-02-01 23:38:43 -08:00