Kancalar

Kancalar, Codex için bir genişletilebilirlik çerçevesidir. Kendi betiklerinizi ajan döngüsüne eklemenize ve aşağıdakiler gibi özellikleri etkinleştirmenize olanak tanır:

• Sohbeti özel bir günlük kaydı/analiz motoruna gönderme
• API key değerlerinin 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ı uygulamak üzere özel bir doğrulama denetimi çalıştırma
• Belirli bir dizindeyken istemleri özelleştirme

Dikkate alınması gereken çalışma zamanı davranışları:

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

Kancalar, bir konuşmanın farklı noktalarında çalışır:

Codex kancaları nerede arar?

Codex, etkin yapılandırma katmanlarının yanındaki kancaları şu biçimlerden biriyle keşfeder:

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

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

Uygulamada en yararlı dört konum şunlardır:

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

Birden fazla kanca kaynağı varsa Codex, eşleşen tüm kancaları yükler. Daha yüksek öncelikli yapılandırma katmanları, daha düşük öncelikli kancaları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österimi tercih edin.

Codex, etkin eklentilerle paketlenmiş kancaları da keşfedebilir. Eklentiyle paketlenmiş kancalar diğer kanca kaynaklarıyla birlikte yüklenir ve yönetilmeyen diğer kancalarla aynı güven incelemesi akışını kullanır.

Projeye yerel kancalar yalnızca projenin .codex/ katmanı güvenilir olduğunda yüklenir. Codex, güvenilmeyen projelerde de kullanıcı ve sistem kancalarını kendi etkin yapılandırma katmanlarından yükler.

Kancaları inceleme ve güvenilir olarak işaretleme

Codex, hangilerinin çalışabileceğine karar vermeden önce yapılandırılmış kancaları listeler. Yönetilmeyen bir komut kancasının çalışabilmesi için Codex, tam kanca tanımını inceleyip güvenilir olarak işaretlemenizi gerektirir. Codex güveni kancanın güncel karmasıyla ilişkilendirerek kaydeder; bu nedenle yeni veya değiştirilmiş kancalar inceleme için işaretlenir ve güvenilir olarak işaretlenene kadar atlanır.

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

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

Kanca kaynaklarını Codex dışında zaten denetleyen tek seferlik otomasyonlarda, o çağrı için kalıcı kanca güveni gerektirmeden etkin kancaları çalıştırmak üzere --dangerously-bypass-hook-trust iletin.

Yapılandırma biçimi

Kancalar üç düzeyde düzenlenir:

• PreToolUse, PostToolUse, PreCompact, SubagentStart veya Stop gibi bir kanca 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 kanca 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 veridir. Hangi kancaların çalışacağını değiştirmez.
• timeout saniye cinsindendir.
• timeout belirtilmezse Codex çoğu kanca için 600 saniye kullanır.
  • SessionEnd 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 yerine daha kısa bir önizlemeyi göndermeden önce bir komut kancasının modele ne kadar additionalContext gönderebileceğini belirler. Büyük kanca çı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'de command_windows veya commandWindows kullanın.
• async seçeneği ayrıştırılır ancak eşzamansız komut kancaları henüz desteklenmez.
• Şu anda yalnızca type: "command" işleyicileri çalışır. 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 kancalarda .codex/hooks/... gibi göreli bir yol kullanmak yerine git kökünden çözümlemeyi tercih edin. Codex bir alt dizinden başlatılabilir; git kökünü temel alan bir yol, kancanın 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"

Kancaları kapatma

Kancalar varsayılan olarak etkindir. Bunları config.toml içinde kapatmak için şunu ayarlayı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 kancaları aynı şekilde zorunlu olarak kapatabilir.

requirements.toml kaynaklı yönetilen kancalar

Kuruluş tarafından yönetilen gereksinimler, kancaları [hooks] altında satır içi olarak da tanımlayabilir. Bu yöntem, yöneticilerin gerçek betikleri MDM veya başka bir cihaz yönetim sistemi aracılığıyla sunarken kanca yapılandırmasını zorunlu kılmak istediği durumlarda kullanışlıdır. Kancaları yerel olarak devre dışı bırakan kullanıcılar için bile yönetilen kancaları zorunlu kılmak üzere [hooks] ile birlikte requirements.toml içinde [features].hooks = true değerini sabitleyin. Yönetici tarafından yönetilen kancalara izin vermeye devam ederken kullanıcı, proje, oturum ve eklenti kancalarını yok saymak için allow_managed_hooks_only = true ayarını yapı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 kancalara ilişkin notlar:

• managed_dir, macOS ve Linux'ta kullanılır.
• windows_managed_dir, Windows'ta kullanılır.
• Codex, managed_dir içindeki betikleri dağıtmaz; kuruluş araçlarınızın bunları ayrıca yüklemesi ve güncellemesi gerekir.
• Yönetilen kanca komutları, yapılandırılmış yönetilen dizin altındaki mutlak betik yollarını kullanmalıdır.
• allow_managed_hooks_only = true; kullanıcı, proje, oturum ve eklenti kaynaklarındaki kancaları atlar ancak requirements.toml ve diğer yönetilen yapılandırma katmanlarındaki yönetilen kancaları yüklemeye devam eder.

Eklentiyle paketlenmiş kancalar

Bir eklenti etkinleştirildiğinde Codex, o eklentideki yaşam döngüsü kancalarını kullanıcı, proje ve yönetilen kancalarla birlikte yükleyebilir.

Codex varsayılan olarak eklenti kökü içinde hooks/hooks.json arar. Bir eklenti manifesti, .codex-plugin/plugin.json içinde bir hooks girdisiyle bu varsayılanı geçersiz kılabilir. Manifest girdisi; ./ önekli bir yol, ./ önekli yollardan oluşan bir dizi, satır içi bir kanca nesnesi veya satır içi kanca nesnelerinden oluşan bir dizi olabilir.

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

Manifest kanca 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 kancaları ş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 kancalarıyla uyumluluk için CLAUDE_PLUGIN_ROOT ve CLAUDE_PLUGIN_DATA değerlerini de ayarlar.

Eklenti kancaları, diğer kancalarla aynı olay şemasını kullanır. Bir eklentiyi yüklemek veya etkinleştirmek, kancalarını otomatik olarak güvenilir yapmaz; siz güncel kanca tanımını inceleyip güvenilir olarak işaretleyene kadar Codex, eklentiyle paketlenmiş kancaları atlar.

Eşleştirici kalıpları

matcher alanı, kancaların ne zaman tetikleneceğini filtreleyen bir regex dizesidir. Desteklenen bir olayın her gerçekleşmesini eşleştirmek için "*" veya "" kullanın ya da matcher alanını tamamen kaldırın.

Yalnızca bazı güncel Codex olayları matcher alanını 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, kabuk ve MCP çağrılarından daha fazlasını gözlemleyebilir. Çoğu yerel işlev aracı aynı kanca yolunu kullanır; böylece araç adlarını eşleştirebilir, JSON bağımsız değişkenlerini inceleyebilir ve PreToolUse için çağrıyı engelleyebilir veya yeniden yazabilirsiniz.

write_stdin, mevcut bir birleşik yürütme oturumuna yönelik aktarımdır. Girdi gönderdiğinde veya daha önce PreToolUse aşamasından geçmiş bir komutu yokladığında PreToolUse olayını yeniden çalıştırmaz.

Bazı özel araç yolları varsayılan kanca yolunu kullanmamayı seçebilir. Araç kancalarını eksiksiz bir yaptırım sınırı değil, yararlı bir koruyucu önlem olarak değerlendirin.

Ortak girdi alanları

Her komut kancası, stdin üzerinden tek bir JSON nesnesi alır.

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

Tur kapsamındaki kancalar, olaya özgü tablolarında turn_id alanını Codex'e özgü bir uzantı olarak listeler.

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

transcript_path kolaylık sağlamak için bir sohbet dökümüne işaret eder ancak döküm biçimi, kancalar için kararlı bir arabirim 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 kancaya ö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ı vermeden 0 ile çıkmak başarı sayılır ve Codex devam eder.

PreToolUse ve PermissionRequest, systemMessage alanını destekler ancak continue, stopReason ve suppressOutput şu anda bu olaylar için desteklenmez. Bir PreToolUse kancası desteklenmeyen bu alanlardan birini döndürürse Codex, bu kanca çalıştırmasını başarısız olarak işaretler, hatayı bildirir ve araç çağrısına devam eder.

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

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

Codex varsayılan olarak modelin görebildiği her kanca çıktı iletisini yaklaşık 2.500 token ile sınırlar. Bir kanca daha fazlasını döndürürse Codex tam metni <temp_dir>/hook_outputs/<session_id>/<uuid>.txt altına kaydeder ve modele kayıtlı dosyanın yoluyla birlikte baş ve son bölümlerden oluşan bir önizleme sunar. Bu davranışa taşırma denir: Codex, büyük boyutlu çıktıyı diskte saklar ve bunun yerine modelin görebileceğ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 kancasında, yaklaşık token eşiğini özelleştirmek için işleyicide additionalContextLimit ayarını yapın:

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

Varsayılan 2500 token eşiğini kullanmak için additionalContextLimit alanını belirtmeyin. Farklı bir eşik seçmek için pozitif bir tam sayı, işleyicinin eksiksiz ek bağlamı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 ayarını 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.

Büyük boyutlu çıktılar diske yazılabildiğinden kanca çıktısında gizli bilgiler veya diğer hassas verileri döndürmekten kaçının.

Kancalar

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 kancaya ö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 kancaları 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 kancanın ek bağlamını sonraki bir kullanıcı turunu bekletmek yerine hemen devam eden isteğe iletir. Kanca 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 işlemler için komut çalıştırmanıza olanak tanır. Hâlâ açık olan bir konuşmayı arşivlediğinizde veya sildiğinizde, Codex normal şekilde kapandığında ya da bir konuşma 30 dakika boyunca etkin olmadığında ve bağlı hiçbir istemcide açık bulunmadığında ana iş parçacığı için çalışır. Alt ajanlar için çalışmaz.

Bir konuşmadan ayrılmak veya thread/unsubscribe çağrısı yapmak oturumu hemen sonlandırmadığından SessionEnd anında çalışmaz. Kancanız çalışırken oturum dökümünü okumaya devam edebilir.

Bu olayda matcher, reason değerini filtreler. Şimdilik reason her zaman other değerindedir. Her SessionEnd olayında çalıştırmak için matcher alanını kaldırabilir 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 kancaları bilgilendirme amaçlıdır. Çıktıları Codex'i yönlendirmez veya iş parçacığını açık tutmaz. Bir komut zaman aşımına uğrarsa ya da hatayla çıkarsa Codex bunu kanca 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 alanını ve şu kancaya ö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 yapılan dosya düzenlemelerini, MCP araç çağrılarını ve diğer yerel işlev araçlarını durdurabilir. Desteklenen yollar ve istisnalar için Araç kapsamı bölümüne bakın.

matcher, tool_name 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; kanca girdisi yine 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 kancaya ö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örebileceğ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, yeni bağımsız değişkenler nesnesidir. updatedInput değerini yalnızca permissionDecision: "allow" ile 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, kanca çalıştırmasını başarısız olarak işaretler, hatayı bildirir ve araç çağrısına devam eder.

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 ya da karar vermeyerek normal onay isteminin devam etmesini sağlayabilir. Onay gerektirmeyen komutlar için çalışmaz.

matcher, tool_name ve eşleştirici takma adlarına uygulanır. Güncel standart değerler arasında Bash, apply_patch ve mcp__server__tool gibi MCP araç adları bulunur; apply_patch ayrıca Edit ve Write değerlerini de eşleştirir.

Ortak girdi alanlarına ek alanlar:

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

Bazı araç girdileri insanların okuyabileceği bir açıklama içerebilir ancak her araç için 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."
    }
  }
}

Eşleşen birden fazla kanca karar döndürürse herhangi bir deny kararı önceliklidir. Aksi durumda bir allow, onay istemini göstermeden isteğin devam etmesini sağlar. Eşleşen hiçbir kanca 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ırdan farklı durumla çıkan komutlardan sonra da çalışır. Ç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 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; kanca girdisi yine tool_name: "apply_patch" bildirir.

Ortak girdi alanlarına ek alanlar:

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

stdout üzerindeki JSON, systemMessage alanını ve şu kancaya ö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 olay için decision: "block" tamamlanmış Bash komutunu geri almaz. Codex bunun yerine geri bildirimi kaydeder, araç sonucunu bu geri bildirimle değiştirir ve kancanın sağladığı iletiden modeli devam ettirir.

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

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

updatedMCPToolOutput ve suppressOutput ayrıştırılır ancak henüz desteklenmez. Codex kanca çalıştırmasını başarısız olarak işaretler, hatayı bildirir ve araç sonucunun normal şekilde işlenmesine devam eder.

Kod modundan gelen araç çağrıları

Bir model kod modunu kullanarak JavaScript'ten bir araç çağırdığında kanca kararları o 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 alanına 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 kancası 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 alanına 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 kancası continue: false döndürürse Codex sıkıştırdıktan 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 kancaya ö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 devam 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 devam kararlarından önceliklidir.

Stop

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 devam etmesini sağlamak 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 devam nedenini stderr üzerine yazabilirsiniz.

Bu olay için decision: "block" turu reddetmez. Bunun yerine Codex'e devam etmesini söyler ve reason değerinizi istem metni olarak kullanan, yeni bir kullanıcı istemi gibi davranan yeni bir devam 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 devam kararlarından önceliklidir.

Şemalar

Tam güncel aktarım biçimine ihtiyacınız varsa Codex GitHub deposundaki oluşturulmuş şemalara bakın.

Düz metin takma adları

• string | null