agent/codex
2
0
Fork 0
mirror of https://github.com/pchuan98/codex.git synced 2026-07-01 00:31:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

Add PermissionRequest hooks support (#17563)

Browse Source 
## Why

We need `PermissionRequest` hook support!

Also addresses:
- https://github.com/openai/codex/issues/16301
- run a script on Hook to do things like play a sound to draw attention
but actually no-op so user can still approve
- can omit the `decision` object from output or just have the script
exit 0 and print nothing
- https://github.com/openai/codex/issues/15311
  - let the script approve/deny on its own
  - external UI what will run on Hook and relay decision back to codex


## Reviewer Note

There's a lot of plumbing for the new hook, key files to review are:
- New hook added in `codex-rs/hooks/src/events/permission_request.rs`
- Wiring for network approvals
`codex-rs/core/src/tools/network_approval.rs`
- Wiring for tool orchestrator `codex-rs/core/src/tools/orchestrator.rs`
- Wiring for execve
`codex-rs/core/src/tools/runtimes/shell/unix_escalation.rs`

## What

- Wires shell, unified exec, and network approval prompts into the
`PermissionRequest` hook flow.
- Lets hooks allow or deny approval prompts; quiet or invalid hooks fall
back to the normal approval path.
- Uses `tool_input.description` for user-facing context when it helps:
  - shell / `exec_command`: the request justification, when present
  - network approvals: `network-access <domain>`
- Uses `tool_name: Bash` for shell, unified exec, and network approval
permission-request hooks.
- For network approvals, passes the originating command in
`tool_input.command` when there is a single owning call; otherwise falls
back to the synthetic `network-access ...` command.

<details>
<summary>Example `PermissionRequest` hook input for a shell
approval</summary>

```json
{
  "session_id": "<session-id>",
  "turn_id": "<turn-id>",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/path/to/cwd",
  "hook_event_name": "PermissionRequest",
  "model": "gpt-5",
  "permission_mode": "default",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -f /tmp/example"
  }
}
```

</details>

<details>
<summary>Example `PermissionRequest` hook input for an escalated
`exec_command` request</summary>

```json
{
  "session_id": "<session-id>",
  "turn_id": "<turn-id>",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/path/to/cwd",
  "hook_event_name": "PermissionRequest",
  "model": "gpt-5",
  "permission_mode": "default",
  "tool_name": "Bash",
  "tool_input": {
    "command": "cp /tmp/source.json /Users/alice/export/source.json",
    "description": "Need to copy a generated file outside the workspace"
  }
}
```

</details>

<details>
<summary>Example `PermissionRequest` hook input for a network
approval</summary>

```json
{
  "session_id": "<session-id>",
  "turn_id": "<turn-id>",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/path/to/cwd",
  "hook_event_name": "PermissionRequest",
  "model": "gpt-5",
  "permission_mode": "default",
  "tool_name": "Bash",
  "tool_input": {
    "command": "curl http://codex-network-test.invalid",
    "description": "network-access http://codex-network-test.invalid"
  }
}
```

</details>

## Follow-ups

- Implement the `PermissionRequest` semantics for `updatedInput`,
`updatedPermissions`, `interrupt`, and suggestions /
`permission_suggestions`
- Add `PermissionRequest` support for the `request_permissions` tool
path

---------

Co-authored-by: Codex <noreply@openai.com>
This commit is contained in:
Abhinav
2026-04-17 07:45:47 -07:00
committed by GitHub
Unverified
parent d0047de7cb
commit 8494e5bd7b
43 changed files with 1821 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
codex-rs/hooks/src/engine/config.rs
+2
View File
@@ -10,6 +10,8 @@ pub(crate) struct HooksFile {
pub(crate) struct HookEvents {
#[serde(rename = "PreToolUse", default)]
pub pre_tool_use: Vec<MatcherGroup>,
#[serde(rename = "PermissionRequest", default)]
pub permission_request: Vec<MatcherGroup>,
#[serde(rename = "PostToolUse", default)]
pub post_tool_use: Vec<MatcherGroup>,
#[serde(rename = "SessionStart", default)]
codex-rs/hooks/src/engine/discovery.rs
+5
View File
@@ -65,6 +65,7 @@ pub(crate) fn discover_handlers(config_layer_stack: Option<&ConfigLayerStack>) -
let super::config::HookEvents {
pre_tool_use,
permission_request,
post_tool_use,
session_start,
user_prompt_submit,
@@ -76,6 +77,10 @@ pub(crate) fn discover_handlers(config_layer_stack: Option<&ConfigLayerStack>) -
codex_protocol::protocol::HookEventName::PreToolUse,
pre_tool_use,
),
(
codex_protocol::protocol::HookEventName::PermissionRequest,
permission_request,
),
(
codex_protocol::protocol::HookEventName::PostToolUse,
post_tool_use,
codex-rs/hooks/src/engine/dispatcher.rs
+2
View File
@@ -32,6 +32,7 @@ pub(crate) fn select_handlers(
.filter(|handler| handler.event_name == event_name)
.filter(|handler| match event_name {
HookEventName::PreToolUse
| HookEventName::PermissionRequest
| HookEventName::PostToolUse
| HookEventName::SessionStart => {
matches_matcher(handler.matcher.as_deref(), matcher_input)
@@ -111,6 +112,7 @@ fn scope_for_event(event_name: HookEventName) -> HookScope {
match event_name {
HookEventName::SessionStart => HookScope::Thread,
HookEventName::PreToolUse
| HookEventName::PermissionRequest
| HookEventName::PostToolUse
| HookEventName::UserPromptSubmit
| HookEventName::Stop => HookScope::Turn,
codex-rs/hooks/src/engine/mod.rs
+17
View File
@@ -10,6 +10,8 @@ use codex_protocol::protocol::HookRunSummary;
use codex_protocol::protocol::HookSource;
use codex_utils_absolute_path::AbsolutePathBuf;
use crate::events::permission_request::PermissionRequestOutcome;
use crate::events::permission_request::PermissionRequestRequest;
use crate::events::post_tool_use::PostToolUseOutcome;
use crate::events::post_tool_use::PostToolUseRequest;
use crate::events::pre_tool_use::PreToolUseOutcome;
@@ -52,6 +54,7 @@ impl ConfiguredHandler {
fn event_name_label(&self) -> &'static str {
match self.event_name {
codex_protocol::protocol::HookEventName::PreToolUse => "pre-tool-use",
codex_protocol::protocol::HookEventName::PermissionRequest => "permission-request",
codex_protocol::protocol::HookEventName::PostToolUse => "post-tool-use",
codex_protocol::protocol::HookEventName::SessionStart => "session-start",
codex_protocol::protocol::HookEventName::UserPromptSubmit => "user-prompt-submit",
@@ -105,6 +108,13 @@ impl ClaudeHooksEngine {
crate::events::pre_tool_use::preview(&self.handlers, request)
}
pub(crate) fn preview_permission_request(
&self,
request: &PermissionRequestRequest,
) -> Vec<HookRunSummary> {
crate::events::permission_request::preview(&self.handlers, request)
}
pub(crate) fn preview_post_tool_use(
&self,
request: &PostToolUseRequest,
@@ -124,6 +134,13 @@ impl ClaudeHooksEngine {
crate::events::pre_tool_use::run(&self.handlers, &self.shell, request).await
}
pub(crate) async fn run_permission_request(
&self,
request: PermissionRequestRequest,
) -> PermissionRequestOutcome {
crate::events::permission_request::run(&self.handlers, &self.shell, request).await
}
pub(crate) async fn run_post_tool_use(
&self,
request: PostToolUseRequest,
codex-rs/hooks/src/engine/output_parser.rs
+158
View File
@@ -19,6 +19,19 @@ pub(crate) struct PreToolUseOutput {
pub invalid_reason: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum PermissionRequestDecision {
Allow,
Deny { message: String },
}
#[derive(Debug, Clone)]
pub(crate) struct PermissionRequestOutput {
pub universal: UniversalOutput,
pub decision: Option<PermissionRequestDecision>,
pub invalid_reason: Option<String>,
}
#[derive(Debug, Clone)]
pub(crate) struct PostToolUseOutput {
pub universal: UniversalOutput,
@@ -48,6 +61,9 @@ pub(crate) struct StopOutput {
use crate::schema::BlockDecisionWire;
use crate::schema::HookUniversalOutputWire;
use crate::schema::PermissionRequestBehaviorWire;
use crate::schema::PermissionRequestCommandOutputWire;
use crate::schema::PermissionRequestDecisionWire;
use crate::schema::PostToolUseCommandOutputWire;
use crate::schema::PreToolUseCommandOutputWire;
use crate::schema::PreToolUseDecisionWire;
@@ -115,6 +131,29 @@ pub(crate) fn parse_pre_tool_use(stdout: &str) -> Option<PreToolUseOutput> {
})
}
pub(crate) fn parse_permission_request(stdout: &str) -> Option<PermissionRequestOutput> {
let wire: PermissionRequestCommandOutputWire = parse_json(stdout)?;
let universal = UniversalOutput::from(wire.universal);
let hook_specific_output = wire.hook_specific_output.as_ref();
let decision = hook_specific_output.and_then(|output| output.decision.as_ref());
let invalid_reason = unsupported_permission_request_universal(&universal).or_else(|| {
hook_specific_output.and_then(|output| {
unsupported_permission_request_hook_specific_output(output.decision.as_ref())
})
});
let decision = if invalid_reason.is_none() {
decision.map(permission_request_decision)
} else {
None
};
Some(PermissionRequestOutput {
universal,
decision,
invalid_reason,
})
}
pub(crate) fn parse_post_tool_use(stdout: &str) -> Option<PostToolUseOutput> {
let wire: PostToolUseCommandOutputWire = parse_json(stdout)?;
let universal = UniversalOutput::from(wire.universal);
@@ -235,6 +274,18 @@ fn unsupported_pre_tool_use_universal(universal: &UniversalOutput) -> Option<Str
}
}
fn unsupported_permission_request_universal(universal: &UniversalOutput) -> Option<String> {
if !universal.continue_processing {
Some("PermissionRequest hook returned unsupported continue:false".to_string())
} else if universal.stop_reason.is_some() {
Some("PermissionRequest hook returned unsupported stopReason".to_string())
} else if universal.suppress_output {
Some("PermissionRequest hook returned unsupported suppressOutput".to_string())
} else {
None
}
}
fn unsupported_post_tool_use_universal(universal: &UniversalOutput) -> Option<String> {
if universal.suppress_output {
Some("PostToolUse hook returned unsupported suppressOutput".to_string())
@@ -243,6 +294,36 @@ fn unsupported_post_tool_use_universal(universal: &UniversalOutput) -> Option<St
}
}
fn unsupported_permission_request_hook_specific_output(
decision: Option<&PermissionRequestDecisionWire>,
) -> Option<String> {
let decision = decision?;
if decision.updated_input.is_some() {
Some("PermissionRequest hook returned unsupported updatedInput".to_string())
} else if decision.updated_permissions.is_some() {
Some("PermissionRequest hook returned unsupported updatedPermissions".to_string())
} else if decision.interrupt {
Some("PermissionRequest hook returned unsupported interrupt:true".to_string())
} else {
None
}
}
fn permission_request_decision(
decision: &PermissionRequestDecisionWire,
) -> PermissionRequestDecision {
match decision.behavior {
PermissionRequestBehaviorWire::Allow => PermissionRequestDecision::Allow,
PermissionRequestBehaviorWire::Deny => PermissionRequestDecision::Deny {
message: decision
.message
.as_deref()
.and_then(trimmed_reason)
.unwrap_or_else(|| "PermissionRequest hook denied approval".to_string()),
},
}
}
fn unsupported_post_tool_use_hook_specific_output(
output: &crate::schema::PostToolUseHookSpecificOutputWire,
) -> Option<String> {
@@ -334,3 +415,80 @@ fn trimmed_reason(reason: &str) -> Option<String> {
Some(trimmed.to_string())
}
}
#[cfg(test)]
mod tests {
use pretty_assertions::assert_eq;
use serde_json::json;
use super::parse_permission_request;
#[test]
fn permission_request_rejects_reserved_updated_input_field() {
let parsed = parse_permission_request(
&json!({
"continue": true,
"hookSpecificOutput": {
"hookEventName": "PermissionRequest",
"decision": {
"behavior": "allow",
"updatedInput": {}
}
}
})
.to_string(),
)
.expect("permission request hook output should parse");
assert_eq!(
parsed.invalid_reason,
Some("PermissionRequest hook returned unsupported updatedInput".to_string())
);
}
#[test]
fn permission_request_rejects_reserved_updated_permissions_field() {
let parsed = parse_permission_request(
&json!({
"continue": true,
"hookSpecificOutput": {
"hookEventName": "PermissionRequest",
"decision": {
"behavior": "allow",
"updatedPermissions": {}
}
}
})
.to_string(),
)
.expect("permission request hook output should parse");
assert_eq!(
parsed.invalid_reason,
Some("PermissionRequest hook returned unsupported updatedPermissions".to_string())
);
}
#[test]
fn permission_request_rejects_reserved_interrupt_field() {
let parsed = parse_permission_request(
&json!({
"continue": true,
"hookSpecificOutput": {
"hookEventName": "PermissionRequest",
"decision": {
"behavior": "allow",
"interrupt": true
}
}
})
.to_string(),
)
.expect("permission request hook output should parse");
assert_eq!(
parsed.invalid_reason,
Some("PermissionRequest hook returned unsupported interrupt:true".to_string())
);
}
}
codex-rs/hooks/src/engine/schema_loader.rs
+12
View File
@@ -6,6 +6,8 @@ use serde_json::Value;
pub(crate) struct GeneratedHookSchemas {
pub post_tool_use_command_input: Value,
pub post_tool_use_command_output: Value,
pub permission_request_command_input: Value,
pub permission_request_command_output: Value,
pub pre_tool_use_command_input: Value,
pub pre_tool_use_command_output: Value,
pub session_start_command_input: Value,
@@ -27,6 +29,14 @@ pub(crate) fn generated_hook_schemas() -> &'static GeneratedHookSchemas {
"post-tool-use.command.output",
include_str!("../../schema/generated/post-tool-use.command.output.schema.json"),
),
permission_request_command_input: parse_json_schema(
"permission-request.command.input",
include_str!("../../schema/generated/permission-request.command.input.schema.json"),
),
permission_request_command_output: parse_json_schema(
"permission-request.command.output",
include_str!("../../schema/generated/permission-request.command.output.schema.json"),
),
pre_tool_use_command_input: parse_json_schema(
"pre-tool-use.command.input",
include_str!("../../schema/generated/pre-tool-use.command.input.schema.json"),
@@ -78,6 +88,8 @@ mod tests {
assert_eq!(schemas.post_tool_use_command_input["type"], "object");
assert_eq!(schemas.post_tool_use_command_output["type"], "object");
assert_eq!(schemas.permission_request_command_input["type"], "object");
assert_eq!(schemas.permission_request_command_output["type"], "object");
assert_eq!(schemas.pre_tool_use_command_input["type"], "object");
assert_eq!(schemas.pre_tool_use_command_output["type"], "object");
assert_eq!(schemas.session_start_command_input["type"], "object");
codex-rs/hooks/src/events/common.rs
+4 -3
View File
@@ -100,9 +100,10 @@ pub(crate) fn matcher_pattern_for_event(
matcher: Option<&str>,
) -> Option<&str> {
match event_name {
HookEventName::PreToolUse | HookEventName::PostToolUse | HookEventName::SessionStart => {
matcher
}
HookEventName::PreToolUse
| HookEventName::PermissionRequest
| HookEventName::PostToolUse
| HookEventName::SessionStart => matcher,
HookEventName::UserPromptSubmit | HookEventName::Stop => None,
}
}
codex-rs/hooks/src/events/mod.rs
+1
View File
@@ -1,4 +1,5 @@
pub(crate) mod common;
pub mod permission_request;
pub mod post_tool_use;
pub mod pre_tool_use;
pub mod session_start;
codex-rs/hooks/src/events/permission_request.rs
+331
View File
@@ -0,0 +1,331 @@
//! Permission-request hook execution.
//!
//! This event runs in the approval path, before guardian or user approval UI is
//! shown. Unlike `pre_tool_use`, handlers do not rewrite tool input or block by
//! stopping execution outright; instead they can return a concrete allow/deny
//! decision, or decline to decide and let the normal approval flow continue.
//!
//! The event also mirrors the rest of the hook system's lifecycle:
//!
//! 1. Preview matching handlers so the UI can render pending hook rows.
//! 2. Execute every matching handler in precedence order.
//! 3. Parse each handler into transcript-visible output plus an optional
//! decision.
//! 4. Fold the decisions conservatively: any deny wins, otherwise the last
//! allow wins, otherwise there is no hook verdict.
use std::path::PathBuf;
use super::common;
use crate::engine::CommandShell;
use crate::engine::ConfiguredHandler;
use crate::engine::command_runner::CommandRunResult;
use crate::engine::dispatcher;
use crate::engine::output_parser;
use crate::schema::PermissionRequestCommandInput;
use crate::schema::PermissionRequestToolInput;
use codex_protocol::ThreadId;
use codex_protocol::protocol::HookCompletedEvent;
use codex_protocol::protocol::HookEventName;
use codex_protocol::protocol::HookOutputEntry;
use codex_protocol::protocol::HookOutputEntryKind;
use codex_protocol::protocol::HookRunStatus;
use codex_protocol::protocol::HookRunSummary;
#[derive(Debug, Clone)]
pub struct PermissionRequestRequest {
pub session_id: ThreadId,
pub turn_id: String,
pub cwd: PathBuf,
pub transcript_path: Option<PathBuf>,
pub model: String,
pub permission_mode: String,
pub tool_name: String,
pub run_id_suffix: String,
pub command: String,
pub description: Option<String>,
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum PermissionRequestDecision {
Allow,
Deny { message: String },
}
#[derive(Debug)]
pub struct PermissionRequestOutcome {
pub hook_events: Vec<HookCompletedEvent>,
pub decision: Option<PermissionRequestDecision>,
}
#[derive(Debug, Default, PartialEq, Eq)]
struct PermissionRequestHandlerData {
decision: Option<PermissionRequestDecision>,
}
pub(crate) fn preview(
handlers: &[ConfiguredHandler],
request: &PermissionRequestRequest,
) -> Vec<HookRunSummary> {
dispatcher::select_handlers(
handlers,
HookEventName::PermissionRequest,
Some(&request.tool_name),
)
.into_iter()
.map(|handler| {
common::hook_run_for_tool_use(
dispatcher::running_summary(&handler),
&request.run_id_suffix,
)
})
.collect()
}
pub(crate) async fn run(
handlers: &[ConfiguredHandler],
shell: &CommandShell,
request: PermissionRequestRequest,
) -> PermissionRequestOutcome {
let matched = dispatcher::select_handlers(
handlers,
HookEventName::PermissionRequest,
Some(&request.tool_name),
);
if matched.is_empty() {
return PermissionRequestOutcome {
hook_events: Vec::new(),
decision: None,
};
}
let input_json = match serde_json::to_string(&build_command_input(&request)) {
Ok(input_json) => input_json,
Err(error) => {
let hook_events = common::serialization_failure_hook_events_for_tool_use(
matched,
Some(request.turn_id.clone()),
format!("failed to serialize permission request hook input: {error}"),
&request.run_id_suffix,
);
return PermissionRequestOutcome {
hook_events,
decision: None,
};
}
};
let results = dispatcher::execute_handlers(
shell,
matched,
input_json,
request.cwd.as_path(),
Some(request.turn_id.clone()),
parse_completed,
)
.await;
// Preserve the most specific matching allow, but treat any deny as final so
// broader policy layers cannot accidentally overrule a more specific block.
let decision = resolve_permission_request_decision(
results
.iter()
.filter_map(|result| result.data.decision.as_ref()),
);
PermissionRequestOutcome {
hook_events: results
.into_iter()
.map(|result| {
common::hook_completed_for_tool_use(result.completed, &request.run_id_suffix)
})
.collect(),
decision,
}
}
/// Resolve matching hook decisions conservatively: any deny wins immediately;
/// otherwise keep the highest-precedence allow so more specific handlers
/// override broader ones.
fn resolve_permission_request_decision<'a>(
decisions: impl IntoIterator<Item = &'a PermissionRequestDecision>,
) -> Option<PermissionRequestDecision> {
let mut resolved_allow = None;
for decision in decisions {
match decision {
PermissionRequestDecision::Allow => {
resolved_allow = Some(PermissionRequestDecision::Allow);
}
PermissionRequestDecision::Deny { message } => {
return Some(PermissionRequestDecision::Deny {
message: message.clone(),
});
}
}
}
resolved_allow
}
fn build_command_input(request: &PermissionRequestRequest) -> PermissionRequestCommandInput {
PermissionRequestCommandInput {
session_id: request.session_id.to_string(),
turn_id: request.turn_id.clone(),
transcript_path: crate::schema::NullableString::from_path(request.transcript_path.clone()),
cwd: request.cwd.display().to_string(),
hook_event_name: "PermissionRequest".to_string(),
model: request.model.clone(),
permission_mode: request.permission_mode.clone(),
tool_name: request.tool_name.clone(),
tool_input: PermissionRequestToolInput {
command: request.command.clone(),
description: request.description.clone(),
},
}
}
fn parse_completed(
handler: &ConfiguredHandler,
run_result: CommandRunResult,
turn_id: Option<String>,
) -> dispatcher::ParsedHandler<PermissionRequestHandlerData> {
let mut entries = Vec::new();
let mut status = HookRunStatus::Completed;
let mut decision = None;
match run_result.error.as_deref() {
Some(error) => {
status = HookRunStatus::Failed;
entries.push(HookOutputEntry {
kind: HookOutputEntryKind::Error,
text: error.to_string(),
});
}
None => match run_result.exit_code {
Some(0) => {
let trimmed_stdout = run_result.stdout.trim();
if trimmed_stdout.is_empty() {
} else if let Some(parsed) =
output_parser::parse_permission_request(&run_result.stdout)
{
if let Some(system_message) = parsed.universal.system_message {
entries.push(HookOutputEntry {
kind: HookOutputEntryKind::Warning,
text: system_message,
});
}
if let Some(invalid_reason) = parsed.invalid_reason {
status = HookRunStatus::Failed;
entries.push(HookOutputEntry {
kind: HookOutputEntryKind::Error,
text: invalid_reason,
});
} else if let Some(parsed_decision) = parsed.decision {
match parsed_decision {
output_parser::PermissionRequestDecision::Allow => {
decision = Some(PermissionRequestDecision::Allow);
}
output_parser::PermissionRequestDecision::Deny { message } => {
status = HookRunStatus::Blocked;
entries.push(HookOutputEntry {
kind: HookOutputEntryKind::Feedback,
text: message.clone(),
});
decision = Some(PermissionRequestDecision::Deny { message });
}
}
}
} else if trimmed_stdout.starts_with('{') || trimmed_stdout.starts_with('[') {
status = HookRunStatus::Failed;
entries.push(HookOutputEntry {
kind: HookOutputEntryKind::Error,
text: "hook returned invalid permission-request JSON output".to_string(),
});
}
}
Some(2) => {
if let Some(message) = common::trimmed_non_empty(&run_result.stderr) {
status = HookRunStatus::Blocked;
entries.push(HookOutputEntry {
kind: HookOutputEntryKind::Feedback,
text: message.clone(),
});
decision = Some(PermissionRequestDecision::Deny { message });
} else {
status = HookRunStatus::Failed;
entries.push(HookOutputEntry {
kind: HookOutputEntryKind::Error,
text: "PermissionRequest hook exited with code 2 but did not write a denial reason to stderr".to_string(),
});
}
}
Some(exit_code) => {
status = HookRunStatus::Failed;
entries.push(HookOutputEntry {
kind: HookOutputEntryKind::Error,
text: format!("hook exited with code {exit_code}"),
});
}
None => {
status = HookRunStatus::Failed;
entries.push(HookOutputEntry {
kind: HookOutputEntryKind::Error,
text: "hook exited without a status code".to_string(),
});
}
},
}
let completed = HookCompletedEvent {
turn_id,
run: dispatcher::completed_summary(handler, &run_result, status, entries),
};
dispatcher::ParsedHandler {
completed,
data: PermissionRequestHandlerData { decision },
}
}
#[cfg(test)]
mod tests {
use pretty_assertions::assert_eq;
use super::PermissionRequestDecision;
use super::resolve_permission_request_decision;
#[test]
fn permission_request_deny_overrides_earlier_allow() {
let decisions = [
PermissionRequestDecision::Allow,
PermissionRequestDecision::Deny {
message: "repo deny".to_string(),
},
];
assert_eq!(
resolve_permission_request_decision(decisions.iter()),
Some(PermissionRequestDecision::Deny {
message: "repo deny".to_string(),
})
);
}
#[test]
fn permission_request_returns_allow_when_no_handler_denies() {
let decisions = [
PermissionRequestDecision::Allow,
PermissionRequestDecision::Allow,
];
assert_eq!(
resolve_permission_request_decision(decisions.iter()),
Some(PermissionRequestDecision::Allow)
);
}
#[test]
fn permission_request_returns_none_when_no_handler_decides() {
let decisions = Vec::<PermissionRequestDecision>::new();
assert_eq!(resolve_permission_request_decision(decisions.iter()), None);
}
}
codex-rs/hooks/src/lib.rs
+3
View File
@@ -5,6 +5,9 @@ mod registry;
mod schema;
mod types;
pub use events::permission_request::PermissionRequestDecision;
pub use events::permission_request::PermissionRequestOutcome;
pub use events::permission_request::PermissionRequestRequest;
pub use events::post_tool_use::PostToolUseOutcome;
pub use events::post_tool_use::PostToolUseRequest;
pub use events::pre_tool_use::PreToolUseOutcome;
codex-rs/hooks/src/registry.rs
+16
View File
@@ -3,6 +3,8 @@ use tokio::process::Command;
use crate::engine::ClaudeHooksEngine;
use crate::engine::CommandShell;
use crate::events::permission_request::PermissionRequestOutcome;
use crate::events::permission_request::PermissionRequestRequest;
use crate::events::post_tool_use::PostToolUseOutcome;
use crate::events::post_tool_use::PostToolUseRequest;
use crate::events::pre_tool_use::PreToolUseOutcome;
@@ -103,6 +105,13 @@ impl Hooks {
self.engine.preview_pre_tool_use(request)
}
pub fn preview_permission_request(
&self,
request: &PermissionRequestRequest,
) -> Vec<codex_protocol::protocol::HookRunSummary> {
self.engine.preview_permission_request(request)
}
pub fn preview_post_tool_use(
&self,
request: &PostToolUseRequest,
@@ -122,6 +131,13 @@ impl Hooks {
self.engine.run_pre_tool_use(request).await
}
pub async fn run_permission_request(
&self,
request: PermissionRequestRequest,
) -> PermissionRequestOutcome {
self.engine.run_permission_request(request).await
}
pub async fn run_post_tool_use(&self, request: PostToolUseRequest) -> PostToolUseOutcome {
self.engine.run_post_tool_use(request).await
}
codex-rs/hooks/src/schema.rs
+123 -1
View File
@@ -15,6 +15,8 @@ use std::path::PathBuf;
const GENERATED_DIR: &str = "generated";
const POST_TOOL_USE_INPUT_FIXTURE: &str = "post-tool-use.command.input.schema.json";
const POST_TOOL_USE_OUTPUT_FIXTURE: &str = "post-tool-use.command.output.schema.json";
const PERMISSION_REQUEST_INPUT_FIXTURE: &str = "permission-request.command.input.schema.json";
const PERMISSION_REQUEST_OUTPUT_FIXTURE: &str = "permission-request.command.output.schema.json";
const PRE_TOOL_USE_INPUT_FIXTURE: &str = "pre-tool-use.command.input.schema.json";
const PRE_TOOL_USE_OUTPUT_FIXTURE: &str = "pre-tool-use.command.output.schema.json";
const SESSION_START_INPUT_FIXTURE: &str = "session-start.command.input.schema.json";
@@ -69,6 +71,8 @@ pub(crate) struct HookUniversalOutputWire {
pub(crate) enum HookEventNameWire {
#[serde(rename = "PreToolUse")]
PreToolUse,
#[serde(rename = "PermissionRequest")]
PermissionRequest,
#[serde(rename = "PostToolUse")]
PostToolUse,
#[serde(rename = "SessionStart")]
@@ -109,6 +113,58 @@ pub(crate) struct PostToolUseCommandOutputWire {
pub hook_specific_output: Option<PostToolUseHookSpecificOutputWire>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[serde(deny_unknown_fields)]
#[schemars(rename = "permission-request.command.output")]
pub(crate) struct PermissionRequestCommandOutputWire {
#[serde(flatten)]
pub universal: HookUniversalOutputWire,
#[serde(default)]
pub hook_specific_output: Option<PermissionRequestHookSpecificOutputWire>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[serde(deny_unknown_fields)]
pub(crate) struct PermissionRequestHookSpecificOutputWire {
pub hook_event_name: HookEventNameWire,
#[serde(default)]
pub decision: Option<PermissionRequestDecisionWire>,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[serde(deny_unknown_fields)]
pub(crate) struct PermissionRequestDecisionWire {
pub behavior: PermissionRequestBehaviorWire,
/// Reserved for a future input-rewrite capability.
///
/// PermissionRequest hooks currently fail closed if this field is present.
#[serde(default)]
pub updated_input: Option<Value>,
/// Reserved for a future permission-rewrite capability.
///
/// PermissionRequest hooks currently fail closed if this field is present.
#[serde(default)]
pub updated_permissions: Option<Value>,
#[serde(default)]
pub message: Option<String>,
/// Reserved for future short-circuiting semantics.
///
/// PermissionRequest hooks currently fail closed if this field is `true`.
#[serde(default)]
pub interrupt: bool,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq)]
pub(crate) enum PermissionRequestBehaviorWire {
#[serde(rename = "allow")]
Allow,
#[serde(rename = "deny")]
Deny,
}
#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[serde(deny_unknown_fields)]
@@ -181,6 +237,34 @@ pub(crate) struct PreToolUseCommandInput {
pub tool_use_id: String,
}
#[derive(Debug, Clone, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[serde(deny_unknown_fields)]
pub(crate) struct PermissionRequestToolInput {
pub command: String,
#[serde(skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
}
#[derive(Debug, Clone, Serialize, JsonSchema)]
#[serde(deny_unknown_fields)]
#[schemars(rename = "permission-request.command.input")]
pub(crate) struct PermissionRequestCommandInput {
pub session_id: String,
/// Codex extension: expose the active turn id to internal turn-scoped hooks.
pub turn_id: String,
pub transcript_path: NullableString,
pub cwd: String,
#[schemars(schema_with = "permission_request_hook_event_name_schema")]
pub hook_event_name: String,
pub model: String,
#[schemars(schema_with = "permission_mode_schema")]
pub permission_mode: String,
#[schemars(schema_with = "permission_request_tool_name_schema")]
pub tool_name: String,
pub tool_input: PermissionRequestToolInput,
}
#[derive(Debug, Clone, Serialize, JsonSchema)]
#[serde(rename_all = "camelCase")]
#[serde(deny_unknown_fields)]
@@ -358,6 +442,14 @@ pub fn write_schema_fixtures(schema_root: &Path) -> anyhow::Result<()> {
&generated_dir.join(POST_TOOL_USE_OUTPUT_FIXTURE),
schema_json::<PostToolUseCommandOutputWire>()?,
)?;
write_schema(
&generated_dir.join(PERMISSION_REQUEST_INPUT_FIXTURE),
schema_json::<PermissionRequestCommandInput>()?,
)?;
write_schema(
&generated_dir.join(PERMISSION_REQUEST_OUTPUT_FIXTURE),
schema_json::<PermissionRequestCommandOutputWire>()?,
)?;
write_schema(
&generated_dir.join(PRE_TOOL_USE_INPUT_FIXTURE),
schema_json::<PreToolUseCommandInput>()?,
@@ -461,10 +553,18 @@ fn pre_tool_use_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
string_const_schema("PreToolUse")
}
fn permission_request_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
string_const_schema("PermissionRequest")
}
fn pre_tool_use_tool_name_schema(_gen: &mut SchemaGenerator) -> Schema {
string_const_schema("Bash")
}
fn permission_request_tool_name_schema(_gen: &mut SchemaGenerator) -> Schema {
string_const_schema("Bash")
}
fn user_prompt_submit_hook_event_name_schema(_gen: &mut SchemaGenerator) -> Schema {
string_const_schema("UserPromptSubmit")
}
@@ -516,10 +616,13 @@ fn default_continue() -> bool {
#[cfg(test)]
mod tests {
use super::PERMISSION_REQUEST_INPUT_FIXTURE;
use super::PERMISSION_REQUEST_OUTPUT_FIXTURE;
use super::POST_TOOL_USE_INPUT_FIXTURE;
use super::POST_TOOL_USE_OUTPUT_FIXTURE;
use super::PRE_TOOL_USE_INPUT_FIXTURE;
use super::PRE_TOOL_USE_OUTPUT_FIXTURE;
use super::PermissionRequestCommandInput;
use super::PostToolUseCommandInput;
use super::PreToolUseCommandInput;
use super::SESSION_START_INPUT_FIXTURE;
@@ -544,6 +647,12 @@ mod tests {
POST_TOOL_USE_OUTPUT_FIXTURE => {
include_str!("../schema/generated/post-tool-use.command.output.schema.json")
}
PERMISSION_REQUEST_INPUT_FIXTURE => {
include_str!("../schema/generated/permission-request.command.input.schema.json")
}
PERMISSION_REQUEST_OUTPUT_FIXTURE => {
include_str!("../schema/generated/permission-request.command.output.schema.json")
}
PRE_TOOL_USE_INPUT_FIXTURE => {
include_str!("../schema/generated/pre-tool-use.command.input.schema.json")
}
@@ -585,6 +694,8 @@ mod tests {
for fixture in [
POST_TOOL_USE_INPUT_FIXTURE,
POST_TOOL_USE_OUTPUT_FIXTURE,
PERMISSION_REQUEST_INPUT_FIXTURE,
PERMISSION_REQUEST_OUTPUT_FIXTURE,
PRE_TOOL_USE_INPUT_FIXTURE,
PRE_TOOL_USE_OUTPUT_FIXTURE,
SESSION_START_INPUT_FIXTURE,
@@ -615,6 +726,11 @@ mod tests {
.expect("serialize post tool use input schema"),
)
.expect("parse post tool use input schema");
let permission_request: Value = serde_json::from_slice(
&schema_json::<PermissionRequestCommandInput>()
.expect("serialize permission request input schema"),
)
.expect("parse permission request input schema");
let user_prompt_submit: Value = serde_json::from_slice(
&schema_json::<UserPromptSubmitCommandInput>()
.expect("serialize user prompt submit input schema"),
@@ -625,7 +741,13 @@ mod tests {
)
.expect("parse stop input schema");
for schema in [&pre_tool_use, &post_tool_use, &user_prompt_submit, &stop] {
for schema in [
&pre_tool_use,
&permission_request,
&post_tool_use,
&user_prompt_submit,
&stop,
] {
assert_eq!(schema["properties"]["turn_id"]["type"], "string");
assert!(
schema["required"]