Hook'lar

Hook'lar, Codex için bir genişletilebilirlik çerçevesidir. Ajan döngüsü sırasında betikler veya MCP araçları çalıştırmanıza olanak tanıyarak aşağıdaki gibi özellikleri mümkün kılar:

• Sohbeti özel bir günlük kaydı/analiz motoruna gönderme
• API anahtarlarının yanlışlıkla yapıştırılmasını engellemek için ekibinizin istemlerini tarama
• Kalıcı anıları otomatik olarak oluşturmak için sohbetleri özetleme
• Bir sohbet turu durduğunda standartları zorunlu kılan özel bir doğrulama denetimi çalıştırma
• Belirli bir dizindeyken istemleri özelleştirme

Göz önünde bulundurulması gereken çalışma zamanı davranışları:

• Birden fazla dosyadaki eşleşen hook'ların tümü çalışır.
• Aynı olay için eşleşen birden fazla komut hook'u eşzamanlı olarak başlatılır; dolayısıyla bir hook, eşleşen başka bir hook'un başlamasını engelleyemez.
• Yönetilmeyen hook'lar çalıştırılmadan önce incelenmeli ve güvenilir olarak işaretlenmelidir.

Hook'lar bir konuşmanın farklı noktalarında çalışır:

Codex hook'ları nerede arar?

Codex, etkin yapılandırma katmanlarının yanında bulunan şu iki biçimdeki hook'ları keşfeder:

• hooks.json
• config.toml içindeki satır içi [hooks] tabloları

Yüklü eklentiler de yaşam döngüsü yapılandırmasını kendi eklenti manifestleri veya varsayılan bir hooks/hooks.json dosyası aracılığıyla paketleyebilir. Eklenti paketleme kuralları için Eklenti oluşturma bölümüne bakın.

Uygulamada en kullanışlı dört konum şunlardır:

• ~/.codex/hooks.json
• ~/.codex/config.toml
• <repo>/.codex/hooks.json
• <repo>/.codex/config.toml

Birden fazla hook kaynağı varsa Codex, eşleşen hook'ların tümünü yükler. Daha yüksek öncelikli yapılandırma katmanları, daha düşük öncelikli hook'ların yerini almaz. Tek bir katman hem hooks.json hem de satır içi [hooks] içeriyorsa Codex bunları birleştirir ve başlangıçta uyarı verir. Her katmanda tek bir gösterim biçimini tercih edin.

Codex, etkin eklentilerle paketlenmiş hook'ları da keşfedebilir. Eklentiyle paketlenmiş hook'lar diğer hook kaynaklarıyla birlikte yüklenir ve yönetilmeyen diğer hook'larla aynı güven inceleme akışını kullanır.

Projeye yerel hook'lar yalnızca projenin .codex/ katmanına güvenildiğinde yüklenir. Güvenilmeyen projelerde Codex, kullanıcı ve sistem hook'larını kendi etkin yapılandırma katmanlarından yüklemeye devam eder.

Hook'ları inceleme ve güvenilir olarak işaretleme

Codex, hangilerinin çalışabileceğine karar vermeden önce yapılandırılmış hook'ları listeler. Bir yönetilmeyen hook çalışmadan önce Codex, tam hook tanımını inceleyip güvenilir olarak işaretlemenizi gerektirir. Codex güven kaydını hook'un geçerli karmasıyla ilişkilendirir; bu nedenle yeni veya değiştirilmiş hook'lar, güvenilir olarak işaretlenene kadar incelenecek olarak işaretlenir ve atlanır.

Hook kaynaklarını incelemek, yeni ya da değiştirilmiş hook'ları gözden geçirmek, hook'ları güvenilir olarak işaretlemek veya yönetilmeyen hook'ları tek tek devre dışı bırakmak için CLI'da /hooks kullanın. Hook'ların başlangıçta incelenmesi gerekiyorsa Codex, /hooks açmanızı söyleyen bir uyarı yazdırır.

Sistem, MDM, bulut veya requirements.toml kaynaklarından gelen yönetilen hook'lar yönetilen olarak işaretlenir, ilke gereği güvenilir kabul edilir ve kullanıcı hook tarayıcısından devre dışı bırakılamaz.

Hook kaynaklarını Codex dışında zaten doğrulayan tek seferlik otomasyonlarda, kalıcı hook güveni gerektirmeden etkin hook'ları çalıştırmak için --dangerously-bypass-hook-trust iletin.

Yapılandırma biçimi

Hook'lar üç düzeyde düzenlenir:

• PreToolUse, PostToolUse, PreCompact, SubagentStart veya Stop gibi bir hook olayı
• Olayın ne zaman eşleşeceğine karar veren bir eşleştirici grubu
• Eşleştirici grubu eşleştiğinde çalışan bir veya daha fazla hook işleyicisi

{
  "description": "Optional lifecycle hooks for this workspace.",
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_start.py",
            "statusMessage": "Loading session notes",
            "additionalContextLimit": 5000
          }
        ]
      }
    ],
    "SessionEnd": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/session_end.py",
            "timeout": 3
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py\"",
            "statusMessage": "Checking Bash command"
          }
        ]
      }
    ],
    "PermissionRequest": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/permission_request.py\"",
            "statusMessage": "Checking approval request"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py\"",
            "statusMessage": "Reviewing Bash output"
          }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/user_prompt_submit_data_flywheel.py\""
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/bin/python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/stop_continue.py\"",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Notlar:

• description, bir hooks.json dosyası için isteğe bağlı üst düzey meta verilerdir. Hangi hook'ların çalışacağını değiştirmez.
• timeout saniye cinsindendir.
• timeout belirtilmezse Codex çoğu hook için 600 saniye kullanır.
  • SessionEnd ve Interrupt varsayılan olarak 1 saniye kullanır ve 3 saniyeye kadar destekler.
• statusMessage isteğe bağlıdır.
• additionalContextLimit, Codex tam metni diske kaydedip bunun yerine daha kısa bir önizleme göndermeden önce bir komut hook'unun modele ne kadar additionalContext gönderebileceğini belirler. Büyük hook çıktısı bölümüne bakın.
• commandWindows yalnızca Windows'a özgü, isteğe bağlı bir komut geçersiz kılma ayarıdır. TOML'da command_windows veya commandWindows kullanın.
• Bir komut hook'unu arka planda çalıştırmak için async değerini true olarak ayarlayın.
• command ve mcp_tool işleyicileri desteklenir. prompt ve agent işleyicileri ayrıştırılır ancak atlanır.
• Komutlar, çalışma dizini olarak oturumun cwd değerini kullanır.
• Depoya yerel hook'larda .codex/hooks/... gibi göreli bir yol kullanmak yerine yolu git kökünden çözümlemeyi tercih edin. Codex bir alt dizinden başlatılabilir; git kökünü temel alan bir yol, hook konumunu sabit tutar.

config.toml içindeki eşdeğer satır içi TOML:

[[hooks.SessionStart]]
matcher = "^compact$"

[[hooks.SessionStart.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/session_start.py"'
additionalContextLimit = 5000

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/pre_tool_use_policy.py"'
timeout = 30
statusMessage = "Checking Bash command"

[[hooks.PostToolUse]]
matcher = "^Bash$"

[[hooks.PostToolUse.hooks]]
type = "command"
command = '/usr/bin/python3 "$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_review.py"'
timeout = 30
statusMessage = "Reviewing Bash output"

MCP aracı hook'ları

Bir MCP aracı hook'u, bir yaşam döngüsü olayının zaten bağlı olan bir MCP sunucusundaki aracı çağırmasına olanak tanır. Yapılandırılmış argümanları doğrudan araca gönderir ve bir komut hook'uyla aynı güven incelemesini ve çıktı sözleşmesini kullanır.

Bir MCP aracı hook'unu yapılandırma

Bu hook, Codex dosyaları yazdıktan veya düzenledikten sonra her yamayı taramasını scanner MCP sunucusundan ister:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "mcp_tool",
            "server": "scanner",
            "tool": "scan_patch",
            "input": { "patch": "${tool_input.command}" },
            "timeout": 30,
            "statusMessage": "Scanning edited files"
          }
        ]
      }
    ]
  }
}

Hook olayından argümanları genişletme

Hook olayından noktalı bir alanı okumak için ${field.nested} kullanın. Bir değerin tamamını dolduran yer tutucu, JSON türünü korur. Daha büyük bir dizenin içindeki yer tutucu metin olarak işlenir. Codex nesneleri ve dizileri özyinelemeli olarak genişletir.

{"tool_input":{"file_path":"src/main.rs","count":3}} içeren bir olay için şu argüman şablonu:

{
  "path": "${tool_input.file_path}",
  "count": "${tool_input.count}",
  "message": "Scanning ${tool_input.file_path}"
}

şuna dönüşür:

{
  "path": "src/main.rs",
  "count": 3,
  "message": "Scanning src/main.rs"
}

Yürütme ve yaşam döngüsü

• Hook'lar mevcut bir MCP bağlantısını kullanır. Sunucuları başlatmaz veya yeniden bağlamazlar.
• Araç engelleme kararı döndürdüğünde bir hook işlemi engelleyebilir. Hatalar, eksik sunucular ve kullanılamayan araçlar işlemi engellemez.
• MCP aracı hook'ları eşzamanlı çalışır. Araç onayı istemez veya başka hook'ları tetiklemezler.
• Hook ya da sunucu zaman aşımlarından daha kısa olanı uygulanır. MCP bilgi isteme yanıtını bekleyerek geçirilen süre, zaman aşımından sayılmaz.
• SessionStart hook'ları bir MCP sunucusu hazır olmadan önce çalışabilir. Böyle bir durumda oturumu engellemezler.
• SessionEnd, MCP aracı hook'larını desteklemez.

Hook'ları kapatma

Hook'lar varsayılan olarak etkindir. Bunları config.toml içinde kapatmak için şu ayarı yapın:

[features]
hooks = false

Standart özellik anahtarı olarak hooks kullanın. codex_hooks, kullanımdan kaldırılmış bir takma ad olarak çalışmaya devam eder. Yöneticiler, requirements.toml içinde [features].hooks = false kullanarak hook'ları aynı şekilde zorunlu olarak kapatabilir.

requirements.toml kaynaklı yönetilen hook'lar

Kuruluş tarafından yönetilen gereksinimler, hook'ları [hooks] altında satır içinde de tanımlayabilir. Bu, yöneticiler hook yapılandırmasını zorunlu kılarken gerçek betikleri MDM veya başka bir cihaz yönetim sistemi üzerinden sağlamak istediğinde kullanışlıdır. Hook'ları yerel olarak devre dışı bırakmış kullanıcılar için bile yönetilen hook'ları zorunlu kılmak üzere [features].hooks = true değerini requirements.toml içinde [hooks] ile birlikte sabitleyin. Yönetici tarafından yönetilen hook'lara izin vermeyi sürdürürken kullanıcı, proje, oturum ve eklenti hook'larını yok saymak için allow_managed_hooks_only = true değerini ayarlayın.

allow_managed_hooks_only = true

[features]
hooks = true

[hooks]
managed_dir = "/enterprise/hooks"
windows_managed_dir = 'C:\enterprise\hooks'

[[hooks.PreToolUse]]
matcher = "^Bash$"

[[hooks.PreToolUse.hooks]]
type = "command"
command = "python3 /enterprise/hooks/pre_tool_use_policy.py"
command_windows = 'py -3 C:\enterprise\hooks\pre_tool_use_policy.py'
timeout = 30
statusMessage = "Checking managed Bash command"

Yönetilen hook'lara ilişkin notlar:

• macOS ve Linux'ta managed_dir kullanılır.
• Windows'ta windows_managed_dir kullanılır.
• Codex, managed_dir içindeki betikleri dağıtmaz; kuruluş araçlarınız bunları ayrı olarak yüklemeli ve güncellemelidir.
• Yönetilen hook komutları, yapılandırılmış yönetilen dizinin altındaki mutlak betik yollarını kullanmalıdır.
• allow_managed_hooks_only = true; kullanıcı, proje, oturum ve eklenti kaynaklarından gelen hook'ları atlar ancak requirements.toml ile diğer yönetilen yapılandırma katmanlarından gelen yönetilen hook'ları yüklemeyi sürdürür.

Eklentiyle paketlenmiş hook'lar

Bir eklenti etkinleştirildiğinde Codex, bu eklentideki yaşam döngüsü hook'larını kullanıcı, proje ve yönetilen hook'larla birlikte yükleyebilir.

Codex varsayılan olarak eklenti kökünün içinde hooks/hooks.json arar. Bir eklenti manifesti, .codex-plugin/plugin.json içindeki bir hooks girdisiyle bu varsayılanı geçersiz kılabilir. Manifest girdisi; ./ ön ekli bir yol, ./ ön ekli yollar dizisi, satır içi bir hook nesnesi veya satır içi hook nesneleri dizisi olabilir.

{
  "name": "repo-policy",
  "hooks": "./hooks/hooks.json"
}

Manifest hook yolları eklenti köküne göre çözümlenir ve bu kökün içinde kalmalıdır. Bir manifest hooks tanımlıyorsa Codex, varsayılan hooks/hooks.json yerine bu manifest girdilerini kullanır.

Eklenti hook komutları şu ortam değişkenlerini alır:

• PLUGIN_ROOT, yüklü eklenti kökünü gösteren Codex'e özgü bir uzantıdır.
• PLUGIN_DATA, eklentinin yazılabilir veri dizinini gösteren Codex'e özgü bir uzantıdır.
• Codex, mevcut eklenti hook'larıyla uyumluluk için CLAUDE_PLUGIN_ROOT ve CLAUDE_PLUGIN_DATA değerlerini de ayarlar.

Eklenti hook'ları diğer hook'larla aynı olay şemasını kullanır. Bir eklentiyi yüklemek veya etkinleştirmek, hook'larını otomatik olarak güvenilir kılmaz; Codex, geçerli hook tanımını inceleyip güvenilir olarak işaretleyene kadar eklentiyle paketlenmiş hook'ları atlar.

Eşleştirici kalıpları

matcher alanı, hook'ların ne zaman tetikleneceğini filtreleyen bir regex dizesidir. Desteklenen bir olayın her oluşumuyla eşleşmek için "*", "" kullanın veya matcher değerini tamamen belirtmeyin.

Yalnızca bazı mevcut Codex olayları matcher değerini dikkate alır:

*apply_patch için matcher değerleri Edit veya Write da kullanabilir.

Örnekler:

• Bash
• ^apply_patch$
• Edit|Write
• mcp__filesystem__read_file
• mcp__filesystem__.*
• startup|resume|clear|compact
• manual|auto

Araç kapsamı

PreToolUse ve PostToolUse yalnızca kabuk ve MCP çağrılarını değil, daha fazlasını gözlemleyebilir. Çoğu yerel işlev aracı aynı hook yolunu kullanır; böylece araç adlarıyla eşleştirme yapabilir, JSON argümanlarını inceleyebilir ve PreToolUse için çağrıyı engelleyebilir veya yeniden yazabilirsiniz.

write_stdin, mevcut bir birleşik exec oturumunun aktarım mekanizmasıdır. Girdi gönderirken veya PreToolUse aşamasından zaten geçmiş bir komutu yoklarken PreToolUse işlemini yeniden çalıştırmaz.

Bazı özel araç yolları varsayılan hook yolunun dışında kalmayı seçebilir. Araç hook'larını eksiksiz bir yaptırım sınırı olarak değil, yararlı bir koruma önlemi olarak değerlendirin.

Ortak girdi alanları

Her komut hook'u stdin üzerinden tek bir JSON nesnesi alır.

Genellikle kullanacağınız ortak alanlar şunlardır:

Tur kapsamındaki hook'lar, olaya özgü tablolarında turn_id değerini Codex'e özgü bir uzantı olarak listeler.

SessionStart, PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, SubagentStart, SubagentStop, Stop ve Interrupt ayrıca geçerli izin modunu default, acceptEdits, plan, dontAsk veya bypassPermissions olarak açıklayan permission_mode değerini içerir.

transcript_path kolaylık sağlamak amacıyla bir sohbet dökümünü gösterir, ancak döküm biçimi hook'lar için kararlı bir arayüz değildir ve zaman içinde değişebilir.

Tam aktarım biçimine ihtiyacınız varsa Şemalar bölümüne bakın.

Ortak çıktı alanları

SessionStart, PreCompact, PostCompact, UserPromptSubmit, SubagentStop ve Stop şu ortak JSON alanlarını destekler. SubagentStart, systemMessage ve hook'a özgü bağlam için aynı biçimi kabul eder; ancak continue: false alt ajanı durdurmaz:

{
  "continue": true,
  "stopReason": "optional",
  "systemMessage": "optional",
  "suppressOutput": false
}

Çıktı olmadan 0 ile çıkılması başarılı kabul edilir ve Codex devam eder.

PreToolUse ve PermissionRequest, systemMessage değerini destekler; ancak continue, stopReason ve suppressOutput şu anda bu olaylar için desteklenmez. Bir PreToolUse hook'u bu desteklenmeyen alanlardan birini döndürürse Codex, söz konusu hook çalıştırmasını başarısız olarak işaretler, hatayı bildirir ve araç çağrısını sürdürür.

PostToolUse; systemMessage, continue: false ve stopReason değerlerini destekler. suppressOutput ayrıştırılır ancak şu anda bu olay için desteklenmez.

Büyük hook çıktısı

Codex varsayılan olarak modelin görebildiği her hook çıktı mesajını yaklaşık 2.500 token ile sınırlar. Bir hook daha fazlasını döndürürse Codex tam metni <temp_dir>/hook_outputs/<session_id>/<uuid>.txt altına kaydeder ve modele, kaydedilen dosyanın yoluyla birlikte baş ve son kısımları içeren bir önizleme sunar. Bu davranışa taşırma denir: Codex, aşırı büyük çıktıyı diskte depolar ve bunun yerine modelin görebildiği daha kısa bir önizleme koyar. Dosya yazılamazsa model yine de kısaltılmış bir önizleme alır.

additionalContext döndüren herhangi bir komut hook'unda yaklaşık token eşiğini özelleştirmek için işleyicide additionalContextLimit değerini ayarlayın:

{
  "type": "command",
  "command": "python3 ~/.codex/hooks/session_start.py",
  "additionalContextLimit": 5000
}

Varsayılan 2500 token eşiğini kullanmak için additionalContextLimit değerini belirtmeyin. Farklı bir eşik seçmek için pozitif bir tam sayı, işleyicinin ek bağlamının tamamını doğrudan modele iletmek içinse 0 kullanın. Codex, eşleşen her işleyiciyi bağımsız olarak değerlendirir. Ek bağlam üretemeyen olaylarda Codex, additionalContextLimit değerini yok sayar ve bir yapılandırma uyarısı bildirir.

Ayar yalnızca additionalContext için geçerlidir. Araç geri bildirimi ve devam istemleri varsayılan sınırı korur.

Aşırı büyük çıktılar diske yazılabileceğinden hook çıktısında gizli bilgiler veya başka hassas veriler döndürmekten kaçının.

Hook'ları arka planda çalıştırma

Codex varsayılan olarak, hook'u tetikleyen işleme devam etmeden önce bir komut hook'unun tamamlanmasını bekler. Codex devam ederken komut hook'unu arka planda çalıştırmak için async değerini true olarak ayarlayın.

Arka plan hook'unu yapılandırma

hooks.json içindeki bir komut işleyicisine "async": true ekleyin:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.codex/hooks/post_tool_use.py",
            "async": true,
            "timeout": 120
          }
        ]
      }
    ]
  }
}

config.toml içindeki satır içi bir hook için async = true değerini ayarlayın:

[[hooks.PostToolUse]]
matcher = "Bash"

[[hooks.PostToolUse.hooks]]
type = "command"
command = "python3 ~/.codex/hooks/post_tool_use.py"
async = true
timeout = 120

Arka plan hook'ları, eşzamanlı komut hook'larıyla aynı girdiyi, eşleştiriciyi, güven incelemesini, zaman aşımını ve büyük çıktı işleme yöntemini kullanır. Diğer komut hook'larında olduğu gibi timeout saniye cinsinden ölçülür ve varsayılanı 600 değeridir. Interrupt hook'ları, arka planda çalıştıklarında da bir saniyelik varsayılan ve üç saniyelik azami süre kullanır.

Arka plan hook'ları nasıl çalışır?

Bir arka plan hook'u tamamlandığında Codex, desteklenen bilgilendirici çıktıyı konuşmadaki bir sonraki güvenli noktada iletir:

• Bir tur etkinse Codex, mevcut model isteğinin ve araç çağrılarının tamamlanmasını bekler; ardından çıktıyı o turdaki bir sonraki model isteğine sunar.
• Etkin bir tur yoksa Codex bir sonraki kullanıcı turunu bekler. Bir arka plan hook'unun tamamlanması yeni bir tur başlatmaz.

Eşzamanlı hook ile aynı olaya özgü JSON çıktısını kullanın. Codex, modelin bağlamına additionalContext ekler ve systemMessage değerini uyarı olarak gösterir.

Sınırlamalar

• Codex, oturum başına en fazla sekiz arka plan hook'unu eşzamanlı çalıştırır. Ek hook'lar, çalışmakta olan bir hook tamamlanana kadar bekler.
• Eşleşen her çağrı bağımsız olarak çalışır ve arka plan hook'ları başladıklarından farklı bir sırada tamamlanabilir.
• Oturum sona erdiğinde Codex tamamlanmamış arka plan hook'larını iptal eder ve henüz iletilmemiş çıktıyı atar.
• SessionEnd hook'ları her zaman eşzamanlı çalışır.

Hook'lar

SessionStart

Bu olay için matcher, source değerine uygulanır.

Ortak girdi alanlarına ek alanlar:

stdout üzerindeki düz metin, ek geliştirici bağlamı olarak eklenir.

stdout üzerindeki JSON, Ortak çıktı alanlarını ve şu hook'a özgü biçimi destekler:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Load the workspace conventions before editing."
  }
}

Bu additionalContext metni ek geliştirici bağlamı olarak eklenir.

Codex bir kök oturumu sıkıştırdıktan sonra source: "compact" ile eşleşen SessionStart hook'ları bir sonraki model isteğinden önce çalışır. Bu, bir turun ortasında otomatik sıkıştırma gerçekleştiğinde de geçerlidir: Codex, hook'un ek bağlamını daha sonraki bir kullanıcı turunu beklemek yerine doğrudan devam isteğine iletir. Hook continue: false döndürürse Codex, başka bir model isteği göndermeden turu sonlandırır.

SessionEnd

SessionEnd, bir oturum sona erdiğinde son notları kaydetmek veya dosyaları temizlemek gibi amaçlarla bir komut çalıştırmanıza olanak tanır. Hâlâ açık bir konuşmayı arşivlediğinizde veya sildiğinizde, Codex normal biçimde kapandığında ya da bir konuşma 30 dakika boyunca boşta kaldığında ve hiçbir bağlı istemcide açık olmadığında ana iş parçacığı için çalışır. Alt ajanlar için çalışmaz.

Bir konuşmadan başka bir konuşmaya geçmek veya thread/unsubscribe çağırmak oturumu hemen sonlandırmaz; dolayısıyla SessionEnd hemen çalışmaz. Hook'unuz çalışırken oturum dökümünü okumaya devam edebilir.

Bu olay için matcher, reason değerini filtreler. Şimdilik reason her zaman other değeridir. Her SessionEnd olayında çalıştırmak için matcher değerini belirtmeyebilir veya other kullanabilirsiniz.

Ortak girdi alanlarına ek alanlar:

Örneğin bir SessionEnd komutu şunu alır:

{
  "session_id": "thr_123",
  "transcript_path": "/workspace/.codex/rollout.jsonl",
  "cwd": "/workspace",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}

SessionEnd hook'ları, async değeri true olsa bile her zaman eşzamanlı çalışır. Bunlar danışma amaçlıdır; dolayısıyla çıktıları Codex'i yönlendirmez veya iş parçacığını açık tutmaz. Bir komut zaman aşımına uğrarsa veya hatayla çıkarsa Codex bunu hook hatası olarak bildirir.

SubagentStart

Bu olay için matcher, agent_type değerine uygulanır.

Ortak girdi alanlarına ek alanlar:

stdout üzerindeki düz metin, alt ajan için ek geliştirici bağlamı olarak eklenir.

stdout üzerindeki JSON, systemMessage değerini ve şu hook'a özgü biçimi destekler:

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Review the repository test conventions first."
  }
}

Bu additionalContext metni, alt ajan için ek geliştirici bağlamı olarak eklenir. continue: false uyumluluk amacıyla ayrıştırılır ancak alt ajanın başlamasını engellemez.

PreToolUse

PreToolUse; Bash'i, apply_patch üzerinden gerçekleştirilen dosya düzenlemelerini, MCP araç çağrılarını ve diğer yerel işlev araçlarını yakalayabilir. Desteklenen yollar ve istisnalar için Araç kapsamı bölümüne bakın.

matcher, tool_name değerine ve eşleştirici takma adlarına uygulanır. apply_patch üzerinden yapılan dosya düzenlemelerinde matcher değerleri apply_patch, Edit veya Write kullanabilir; hook girdisi yine de tool_name: "apply_patch" bildirir.

Ortak girdi alanlarına ek alanlar:

stdout üzerindeki düz metin yok sayılır.

stdout üzerindeki JSON, systemMessage kullanabilir. Desteklenen bir araç çağrısını reddetmek için şu hook'a özgü biçimi döndürün:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Destructive command blocked by hook."
  }
}

Codex şu eski engelleme biçimini de kabul eder:

{
  "decision": "block",
  "reason": "Destructive command blocked by hook."
}

Ayrıca 2 çıkış kodunu kullanabilir ve engelleme nedenini stderr üzerine yazabilirsiniz.

Engellemeden modelin görebildiği bağlam eklemek için hookSpecificOutput.additionalContext döndürün:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "additionalContext": "The pending command touches generated files."
  }
}

Desteklenen bir araç çağrısını engellemeden yeniden yazmak için updatedInput ile birlikte permissionDecision: "allow" döndürün:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "updatedInput": {
      "command": "echo rewritten"
    }
  }
}

Bash komutları ve apply_patch için updatedInput, dize türünde bir command alanı içermelidir. MCP ve diğer yerel işlev araçlarında updatedInput, yerine geçen argüman nesnesidir. updatedInput değerini yalnızca permissionDecision: "allow" ile birlikte döndürün; diğer updatedInput biçimleri hata olarak bildirilir.

permissionDecision: "ask", eski decision: "approve", continue: false, stopReason ve suppressOutput ayrıştırılır ancak henüz desteklenmez. Codex, hook çalıştırmasını başarısız olarak işaretler, hatayı bildirir ve araç çağrısını sürdürür.

PermissionRequest

PermissionRequest, Codex bir kabuk yetki yükseltmesi veya yönetilen ağ onayı gibi bir işlem için onay istemek üzereyken çalışır. İsteğe izin verebilir, isteği reddedebilir veya karar vermeyerek normal onay isteminin devam etmesini sağlayabilir. Onay gerektirmeyen komutlar için çalışmaz.

matcher, tool_name değerine ve eşleştirici takma adlarına uygulanır. Geçerli standart değerler arasında Bash, apply_patch ve mcp__server__tool gibi MCP araç adları bulunur; apply_patch ayrıca Edit ve Write ile eşleşir.

Ortak girdi alanlarına ek alanlar:

stdout üzerindeki düz metin yok sayılır.

Bazı araç girdileri insan tarafından okunabilir bir açıklama içerebilir; ancak her araçta tool_input.description alanının bulunacağına güvenmeyin.

İsteği onaylamak için şunu döndürün:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow"
    }
  }
}

İsteği reddetmek için şunu döndürün:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "deny",
      "message": "Blocked by repository policy."
    }
  }
}

Birden fazla eşleşen hook karar döndürürse herhangi bir deny kararı önceliklidir. Aksi takdirde bir allow, onay istemini göstermeden isteğin ilerlemesini sağlar. Eşleşen hiçbir hook karar vermezse Codex normal onay akışını kullanır.

PermissionRequest için updatedInput, updatedPermissions veya interrupt döndürmeyin; bu alanlar gelecekteki davranışlar için ayrılmıştır ve şu anda güvenli biçimde başarısız olur.

PostToolUse

PostToolUse; Bash, apply_patch, MCP araç çağrıları ve diğer yerel işlev araçları dâhil olmak üzere desteklenen araçlar çıktı ürettikten sonra çalışır. Bash için sıfır olmayan durum koduyla çıkan komutlardan sonra da çalışır. Daha önce çalışmış bir aracın yan etkilerini geri alamaz. Desteklenen yollar ve istisnalar için Araç kapsamı bölümüne bakın.

matcher, tool_name değerine ve eşleştirici takma adlarına uygulanır. apply_patch üzerinden yapılan dosya düzenlemelerinde matcher değerleri apply_patch, Edit veya Write kullanabilir; hook girdisi yine de tool_name: "apply_patch" bildirir.

Ortak girdi alanlarına ek alanlar:

stdout üzerindeki düz metin yok sayılır.

stdout üzerindeki JSON, systemMessage değerini ve şu hook'a özgü biçimi kullanabilir:

{
  "decision": "block",
  "reason": "The Bash output needs review before continuing.",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "The command updated generated files."
  }
}

Bu additionalContext metni ek geliştirici bağlamı olarak eklenir.

Bu olayda decision: "block", tamamlanmış Bash komutunu geri almaz. Bunun yerine Codex geri bildirimi kaydeder, araç sonucunu bu geri bildirimle değiştirir ve modeli hook tarafından sağlanan mesajdan devam ettirir.

Ayrıca 2 çıkış kodunu kullanabilir ve geri bildirim nedenini stderr üzerine yazabilirsiniz.

Komut zaten çalıştıktan sonra özgün araç sonucunun normal işlenmesini durdurmak için continue: false döndürün. Codex, araç sonucunu geri bildiriminiz veya durdurma metninizle değiştirip buradan devam eder.

updatedMCPToolOutput ve suppressOutput ayrıştırılır ancak henüz desteklenmez. Codex, hook çalıştırmasını başarısız olarak işaretler, hatayı bildirir ve araç sonucunu normal şekilde işlemeyi sürdürür.

Kod modundaki araç çağrıları

Bir model kod modunu kullanarak JavaScript'ten araç çağırdığında hook kararları bu iç içe çağrıya uygulanır. PreToolUse, aracı çalışmadan önce durdurabilir veya girdisini yeniden yazabilir. Engelleyen bir PostToolUse, aracın yan etkilerini geri alamaz ancak özgün sonucun çalışan betiğe ulaşmasını engelleyebilir.

PreCompact

PreCompact, Codex sohbeti sıkıştırmadan önce çalışır. matcher, değerleri manual ve auto olan trigger değerine uygulanır.

Ortak girdi alanlarına ek alanlar:

stdout üzerindeki düz metin yok sayılır.

stdout üzerindeki JSON, Ortak çıktı alanlarını destekler. Eşleşen bir PreCompact hook'u continue: false döndürürse Codex sıkıştırmadan önce durur.

PostCompact

PostCompact, Codex sohbeti sıkıştırdıktan sonra çalışır. matcher, değerleri manual ve auto olan trigger değerine uygulanır.

Ortak girdi alanlarına ek alanlar:

stdout üzerindeki düz metin yok sayılır.

stdout üzerindeki JSON, Ortak çıktı alanlarını destekler. Eşleşen bir PostCompact hook'u continue: false döndürürse Codex sıkıştırmadan sonra durur.

UserPromptSubmit

matcher şu anda bu olay için kullanılmaz.

Ortak girdi alanlarına ek alanlar:

stdout üzerindeki düz metin, ek geliştirici bağlamı olarak eklenir.

stdout üzerindeki JSON, Ortak çıktı alanlarını ve şu hook'a özgü biçimi destekler:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Ask for a clearer reproduction before editing files."
  }
}

Bu additionalContext metni ek geliştirici bağlamı olarak eklenir.

İstemi engellemek için şunu döndürün:

{
  "decision": "block",
  "reason": "Ask for confirmation before doing that."
}

Ayrıca 2 çıkış kodunu kullanabilir ve engelleme nedenini stderr üzerine yazabilirsiniz.

SubagentStop

Bu olay için matcher, agent_type değerine uygulanır.

Ortak girdi alanlarına ek alanlar:

SubagentStop, 0 ile çıktığında stdout üzerinde JSON bekler. Düz metin çıktısı bu olay için geçersizdir.

stdout üzerindeki JSON, Ortak çıktı alanlarını destekler. Codex'ten alt ajan akışını sürdürmesini istemek için şunu döndürün:

{
  "decision": "block",
  "reason": "Run one more focused pass inside the subagent."
}

Ayrıca 2 çıkış kodunu kullanabilir ve sürdürme nedenini stderr üzerine yazabilirsiniz.

Eşleşen herhangi bir SubagentStop kancası continue: false döndürürse bu, eşleşen diğer SubagentStop kancalarının sürdürme kararlarından öncelikli olur.

Durdurma

matcher şu anda bu olay için kullanılmaz.

Ortak girdi alanlarına ek alanlar:

Stop, 0 ile çıktığında stdout üzerinde JSON bekler. Düz metin çıktısı bu olay için geçersizdir.

stdout üzerindeki JSON, Ortak çıktı alanlarını destekler. Codex'in çalışmayı sürdürmesi için şunu döndürün:

{
  "decision": "block",
  "reason": "Run one more pass over the failing tests."
}

Ayrıca 2 çıkış kodunu kullanabilir ve sürdürme nedenini stderr üzerine yazabilirsiniz.

Bu olayda decision: "block" turu reddetmez. Bunun yerine Codex'e çalışmayı sürdürmesini bildirir ve reason değerinizi istem metni olarak kullanan, yeni bir kullanıcı istemi işlevi gören yeni bir sürdürme istemini otomatik olarak oluşturur.

Eşleşen herhangi bir Stop kancası continue: false döndürürse bu, eşleşen diğer Stop kancalarının sürdürme kararlarından öncelikli olur.

Kesintiye uğratma

Interrupt, ana iş parçacığındaki etkin bir turu kesintiye uğrattığınızda çalışır. Bunu kesintiyi kaydetmek veya bir kancanın başlattığı çalışmayı temizlemek için kullanın. Boştaki iş parçacıkları ya da alt ajanlar için çalışmaz ve yapılandırılmış matcher yok sayılır.

Ortak girdi alanlarına ek olarak olay, kesintiye uğratılan turun kimliği olan turn_id ile permission_mode alanlarını içerir.

Komut kancalarının varsayılan zaman aşımı bir saniyedir. Yapılandırılan zaman aşımları bir ile üç saniye arasında sınırlandırılır. Kanca çıktısı kesintiyi engelleyemez veya turu yeniden başlatamaz. Çıktı vermeden 0 ile çıkın ya da bir uyarı göstermek için isteğe bağlı bir systemMessage içeren JSON döndürün. Düz metin çıktısı bu olay için geçersizdir.

{ "systemMessage": "Saved the interrupted turn to the local audit log." }

Şemalar

Geçerli kablo biçiminin tam hâline ihtiyacınız varsa Codex GitHub deposundaki oluşturulmuş şemalara bakın.

Düz metin diğer adları

• string | null