polydeukes 0.8.0 → 0.9.0

package/dist/covenant/shell-mod.d.ts

@@ -4,7 +4,7 @@
  * Analyzes the command-line strings of *shell* tool calls (names and arg keys are injected
  * values, never source literals) per simple command: the fixed detection rules catch writes
  * to a protected path, undecidable structures (opaque mentions, opaque write targets) fail
- * closed, the read-only allowlist absolves proven reads, and every other protected-path
+ * closed, read-only proof absolves safe reads, and every other protected-path
  * mention breaks — "mention + unproven = block". It judges only its own axis: a non-shell
  * tool call is upheld, since the tool axis belongs to the self-mod meta-covenant and
  * run-all co-existence depends on that boundary.
@@ -18,7 +18,7 @@ import type { CovenantRegistration, MetaCovenantRegistration } from './dispatch.
  * `protectedPaths` are literal path strings; `shellToolNames` are the tool names whose
  * calls carry shell lines; `commandArgNames` are the `args` keys those lines live under;
  * `readOnlyCommands` are allowlist entries — space-separated word sequences (`'cat'`,
- * `'git diff'`). Empty-string entries in every list are ignored (an unguarded `''` would
+ * `'git status'`). Empty-string entries in every list are ignored (an unguarded `''` would
  * match every path / tool / arg / command).
  */
 export type ShellModificationSpec = {
@@ -38,6 +38,16 @@ export type ShellModificationSpec = {
  * redirect-free truncating write. `git status`/`git grep` reject `--output`, so they stay.
  */
 export declare const DEFAULT_READ_ONLY_COMMANDS: string[];
+/**
+ * True when a configured allowlist has the same effective entries as the shipped default.
+ * Conditional readers belong to that default contract and stay disabled for replacements.
+ */
+export declare function usesDefaultReadOnlyCommands(commands: string[]): boolean;
+/**
+ * Prove the finite argument-sensitive readers that cannot be represented by a leading-word
+ * allowlist. Every word must be transparent because these readers inspect their later words.
+ */
+export declare function matchesConditionalReadOnlyCommand(command: SimpleCommand): boolean;
 /**
  * True when the command's leading words match the allowlist entry's word sequence. Exported
  * so the transcript judge's allowlist clause absolves reads by this exact comparison instead
@@ -59,8 +69,9 @@ export declare function judgeShellModification(input: CovenantInput, spec: Shell
 /**
  * `ShellModRegistrationSpec` — the assembly values baked into the registration. The call
  * set is not among them: the dispatcher supplies it to the judge at call time.
- * `readOnlyCommands` REPLACES {@link DEFAULT_READ_ONLY_COMMANDS} when given — no merge,
- * since an assembly wanting to extend the default spreads the constant.
+ * `readOnlyCommands` REPLACES {@link DEFAULT_READ_ONLY_COMMANDS} when given — no merge.
+ * Any replacement, including a superset made by spreading the default, disables the finite
+ * argument-sensitive readers because their proof belongs to the exact shipped default.
  */
 export type ShellModRegistrationSpec = {
     protectedPaths: string[];

package/dist/covenant/shell-mod.js

@@ -4,7 +4,7 @@
  * Analyzes the command-line strings of *shell* tool calls (names and arg keys are injected
  * values, never source literals) per simple command: the fixed detection rules catch writes
  * to a protected path, undecidable structures (opaque mentions, opaque write targets) fail
- * closed, the read-only allowlist absolves proven reads, and every other protected-path
+ * closed, read-only proof absolves safe reads, and every other protected-path
  * mention breaks — "mention + unproven = block". It judges only its own axis: a non-shell
  * tool call is upheld, since the tool axis belongs to the self-mod meta-covenant and
  * run-all co-existence depends on that boundary.
@@ -39,6 +39,58 @@ export const DEFAULT_READ_ONLY_COMMANDS = [
     'git status',
     'git grep',
 ];
+const FIND_WRITE_OR_EXECUTE_ACTIONS = new Set([
+    '-delete',
+    '-exec',
+    '-execdir',
+    '-ok',
+    '-okdir',
+    '-fprint',
+    '-fprint0',
+    '-fprintf',
+    '-fls',
+]);
+function normalizedReadOnlyCommands(commands) {
+    return [
+        ...new Set(commands
+            .map((entry) => entry
+            .split(/\s+/)
+            .filter((word) => word !== '')
+            .join(' '))
+            .filter((entry) => entry !== '')),
+    ].sort();
+}
+/**
+ * True when a configured allowlist has the same effective entries as the shipped default.
+ * Conditional readers belong to that default contract and stay disabled for replacements.
+ */
+export function usesDefaultReadOnlyCommands(commands) {
+    const configured = normalizedReadOnlyCommands(commands);
+    const shipped = normalizedReadOnlyCommands(DEFAULT_READ_ONLY_COMMANDS);
+    return (configured.length === shipped.length && configured.every((entry, i) => entry === shipped[i]));
+}
+/**
+ * Prove the finite argument-sensitive readers that cannot be represented by a leading-word
+ * allowlist. Every word must be transparent because these readers inspect their later words.
+ */
+export function matchesConditionalReadOnlyCommand(command) {
+    if (command.words.length === 0 || command.words.some((word) => word.opaque))
+        return false;
+    const name = commandBasename(command.words[0]);
+    if (name === 'git')
+        return command.words[1]?.text === 'ls-files';
+    if (name === 'find') {
+        return !command.words.some((word) => FIND_WRITE_OR_EXECUTE_ACTIONS.has(word.text));
+    }
+    if (name !== 'sed')
+        return false;
+    const script = command.words[2]?.text;
+    return (command.words[1]?.text === '-n' &&
+        script !== undefined &&
+        /^\d+(?:,\d+)?p$/.test(script) &&
+        command.words.length > 3 &&
+        command.words.slice(3).every((word) => !word.text.startsWith('-')));
+}
 // The rule set is fixed, not injectable: dropping a rule from an assembly would be a
 // detection hole, and no consumer needs a subset.
 const MUTATION_RULES = [redirectWriteRule, teeRule, sedInPlaceRule];
@@ -65,9 +117,9 @@ export function matchesReadOnlyEntry(command, entry) {
  * Judge one simple command. Returns the break reason, or null when the command contributes
  * to uphold. The clause order below is normative: each clause exists to be reached before
  * the next one can absolve. `lineFullyRead` is false when the line carried a span the
- * tokenizer could not read, which withholds the allowlist clause.
+ * tokenizer could not read, which withholds read-only proof.
  */
-function judgeCommand(command, protectedPaths, readOnlyEntries, lineFullyRead) {
+function judgeCommand(command, protectedPaths, readOnlyEntries, conditionalReadersEnabled, lineFullyRead) {
     // (a) Precise rules: a detected mutation whose target carries a protected path breaks.
     for (const rule of MUTATION_RULES) {
         for (const target of rule.detect(command)) {
@@ -100,16 +152,18 @@ function judgeCommand(command, protectedPaths, readOnlyEntries, lineFullyRead) {
     if (command.redirects.some((r) => r.operator.includes('>') && r.target.opaque)) {
         return `opaque redirect target alongside protected path ${mentioned}`;
     }
-    // (e) Read-only allowlist: a proven read absolves the mention — but a nested shell
-    // (`eval`/`sh -c …`) re-parses its string args, so it can never be proven read-only even
-    // if it was injected into the allowlist. Its mention falls through to the backstop. A line
+    // (e) Read-only proof: the allowlist or a finite argument-sensitive reader absolves the
+    // mention. A nested shell (`eval`/`sh -c …`) re-parses its string args, so it can never be
+    // proven read-only even if it was injected into the allowlist. Its mention falls through
+    // to the backstop. A line
     // carrying an unread span is refused the same way: what the scanner never read could be
     // anything, so no head vouches for it.
     const first = command.words[0];
     const firstBasename = first !== undefined ? commandBasename(first) : '';
     if (lineFullyRead &&
         !isNestedShellCommand(firstBasename) &&
-        readOnlyEntries.some((entry) => matchesReadOnlyEntry(command, entry))) {
+        (readOnlyEntries.some((entry) => matchesReadOnlyEntry(command, entry)) ||
+            (conditionalReadersEnabled && matchesConditionalReadOnlyCommand(command)))) {
         return null;
     }
     // (f) Backstop — mention + unproven = block.
@@ -133,6 +187,7 @@ export function judgeShellModification(input, spec) {
     const readOnlyEntries = spec.readOnlyCommands
         .map((entry) => entry.split(/\s+/).filter((word) => word !== ''))
         .filter((entry) => entry.length > 0);
+    const conditionalReadersEnabled = usesDefaultReadOnlyCommands(spec.readOnlyCommands);
     for (const call of input.toolCalls) {
         if (!shellToolNames.includes(call.name)) {
             continue;
@@ -167,7 +222,7 @@ export function judgeShellModification(input, spec) {
                 }
             }
             for (const command of commands) {
-                const reason = judgeCommand(command, protectedPaths, readOnlyEntries, unread.length === 0);
+                const reason = judgeCommand(command, protectedPaths, readOnlyEntries, conditionalReadersEnabled, unread.length === 0);
                 if (reason !== null)
                     return { upheld: false, reason };
             }

package/dist/covenant/transcript-mod.js

@@ -13,7 +13,7 @@ import { isNestedShellCommand, tokenizeCommandLine } from './bash-line.js';
 import { pathCandidates, pathSegments, provenChangePath, resolveDotSegments, someStringValue, untokenizableLineCandidates, } from './mention.js';
 import { commandBasename, redirectWriteRule, sedInPlaceRule, teeRule } from './mutation-rules.js';
 import { outcomeFromVerdict, UNJUDGEABLE_OUTCOME } from './run-covenant.js';
-import { DEFAULT_READ_ONLY_COMMANDS, matchesReadOnlyEntry } from './shell-mod.js';
+import { DEFAULT_READ_ONLY_COMMANDS, matchesConditionalReadOnlyCommand, matchesReadOnlyEntry, usesDefaultReadOnlyCommands, } from './shell-mod.js';
 // The rule set is fixed, assembled exactly as shell-mod assembles it: dropping one would be
 // a detection hole, and the two judges must not diverge on what counts as a write.
 const MUTATION_RULES = [redirectWriteRule, teeRule, sedInPlaceRule];
@@ -55,6 +55,7 @@ function resolveTranscript(spec) {
         readOnlyEntries: spec.readOnlyCommands
             .map((entry) => entry.split(/\s+/).filter((word) => word !== ''))
             .filter((entry) => entry.length > 0),
+        conditionalReadersEnabled: usesDefaultReadOnlyCommands(spec.readOnlyCommands),
     };
 }
 /**
@@ -96,7 +97,7 @@ function argsNameTranscript(value, transcript) {
  * it has to break before the allowlist gets a chance to absolve it. The letters skip `(c)`
  * because this ladder has no opaque-mention clause, matching the shell ladder's numbering
  * rather than closing the gap. `lineFullyRead` is false when the line carried a span the
- * tokenizer could not read, which withholds the allowlist clause.
+ * tokenizer could not read, which withholds read-only proof.
  */
 function judgeCommand(command, transcript, lineFullyRead) {
     // (a) Precise rules: a detected mutation whose target is the transcript breaks.
@@ -118,15 +119,17 @@ function judgeCommand(command, transcript, lineFullyRead) {
     if (command.redirects.some((r) => r.operator.includes('>') && r.target.opaque)) {
         return `opaque redirect target alongside the session transcript ${transcript.path}`;
     }
-    // (e) Read-only allowlist: a proven read absolves the mention, in every spelling — but a
-    // nested shell (`eval`/`sh -c …`) re-parses its string args, so it is never provably a read.
+    // (e) Read-only proof: the allowlist or a finite argument-sensitive reader absolves the
+    // mention in every spelling. A nested shell (`eval`/`sh -c …`) re-parses its string args,
+    // so it is never provably a read.
     // A line carrying an unread span is refused the same way: reading the session is free, but
     // only on a line we finished reading.
     const first = command.words[0];
     const firstBasename = first !== undefined ? commandBasename(first) : '';
     if (lineFullyRead &&
         !isNestedShellCommand(firstBasename) &&
-        transcript.readOnlyEntries.some((entry) => matchesReadOnlyEntry(command, entry))) {
+        (transcript.readOnlyEntries.some((entry) => matchesReadOnlyEntry(command, entry)) ||
+            (transcript.conditionalReadersEnabled && matchesConditionalReadOnlyCommand(command)))) {
         return null;
     }
     // (f) Backstop — mention + unproven = block.

package/dist/docs/how-to/connect-surfaces.ko.md

@@ -56,23 +56,35 @@ Codex에서 개발할 때 씁니다.
    제공합니다. 먼저 `pdks init`으로 초기 파일을 만든 뒤 Codex 등록 산출물을 씁니다.
 3. Codex에서 `/hooks`로 생성된 훅을 승인합니다. 승인하기 전까지는 훅을 건너뜁니다.
 
-Codex 프로젝트에는 `.codex/hooks/covenant-pretooluse.mjs` 위임자와 `.codex/hooks.json`의 항목이
-생깁니다. 이 JSON은 덮어쓰지 않고 병합합니다. 다른 이벤트, 다른 matcher, 설치기가 모르는 키는
-그대로 둡니다. 초기 설정은 기본적으로 `.codex/hooks`를 보호합니다.
+Codex 프로젝트에는 `.codex/hooks/covenant-pretooluse.mjs` 위임자와 `.codex/hooks.json`의
+`PreToolUse`, `UserPromptSubmit`, `PostToolUse`, `SessionEnd` 항목이 생깁니다. 이 JSON은
+덮어쓰지 않고 병합합니다. 사용자 항목, 같은 항목의 다른 handler, 다른 이벤트, 설치기가 모르는
+키는 그대로 둡니다. 초기 설정은 기본적으로 `.codex/hooks`를 보호합니다.
 
 **승인은 선택이 아닙니다.** Codex는 훅 정의의 해시로 신뢰를 기록하므로, 새로 쓴 훅은 검토
 대상으로 표시되고 누군가 승인하기 전까지 건너뛰어집니다. 그때까지는 아무것도 판정되지
 않습니다. `init`은 실행할 때마다 바이트가 같은 명령 문자열을 쓰므로, 다시 설치해도 이미 받은
 승인이 무효가 되지 않습니다.
 
-Codex는 모든 파일 편집을 `apply_patch` 하나로 정규화하고, 경로 인자가 아니라 패치 텍스트를
+Codex는 훅에 도달하는 모든 파일 편집을 `apply_patch` 하나로 정규화하고, 경로 인자가 아니라 패치 텍스트를
 보냅니다. `Edit`과 `Write`는 훅 파일에 적을 수 있는 matcher 별칭이며 도구 이름으로 도착하지
 않습니다. 패치 하나가 여러 파일을 건드리면 파일마다 IR 원소 하나가 실리고, 그중 하나라도
 차단되면 호출 전체가 차단됩니다.
 
-Codex에는 대화 기록 채널이 없어서 세션 증인(witness) 밸브가 읽을 사람 메시지가 없습니다.
-의도한 편집이 차단되면 자신의 터미널에서 수행하세요. 세션 어댑터를 한 프로젝트에 둘 이상
-설치하면 호출마다 판정기가 두 번 실행될 수 있습니다.
+**승인된 훅도 Code Mode는 덮지 못합니다.** codex-cli 0.154에서 Code Mode `exec` 호출과 그
+JavaScript 안에 중첩된 도구 호출은 `PreToolUse`에 도달하지 않으므로
+([openai/codex#23411](https://github.com/openai/codex/issues/23411)), 그 경로로 이루어진 편집은
+`/hooks`에 훅이 Active로 표시되는 동안에도 판정되지도 기록되지도 않습니다. `init`이 이 사실을
+`note:` 줄로 출력하고, [패키지 레퍼런스](../reference/packages/adapter-codex.ko.md#limits)가
+다른 선언된 한계와 함께 나열합니다.
+
+Codex의 대화 기록 형식은 계속 불안정하므로 해석하지 않습니다. 대신 `UserPromptSubmit`이
+시각을 붙인 사람 메시지를, `PostToolUse`가 완료된 도구 호출을 `.polydeukes/codex-sessions/`
+아래의 어댑터 소유 파일에 기록하고 `SessionEnd`가 지웁니다. 의도한 차단을 풀려면 설정된 증인
+토큰을 첫 줄에 단독으로 보낸 뒤 호출을 다시 시도합니다. 복구 메시지가
+`UserPromptSubmit` 증거가 없다고 알리면 재시도가 증인 밸브에 닿지 못하므로 자신의 터미널을
+사용합니다. 세션 어댑터를 한 프로젝트에 둘 이상 설치하면 호출마다 판정기가 두 번 실행될 수
+있습니다.
 
 <a id="change-set-surface"></a>
 ## 변경 집합 표면

package/dist/docs/how-to/connect-surfaces.md

@@ -58,24 +58,36 @@ Use this when the project is developed in Codex.
    runs `pdks init` for the scaffold, then writes the Codex registration artifacts.
 3. Approve the generated hook with `/hooks` in Codex. Until you do, it is skipped.
 
-A Codex tree gets a delegator at `.codex/hooks/covenant-pretooluse.mjs` and an entry in
-`.codex/hooks.json`. That JSON is merged, not overwritten: other events, other matchers, and
-keys the installer does not know stay where they are. The scaffold config protects
-`.codex/hooks` by default.
+A Codex tree gets a delegator at `.codex/hooks/covenant-pretooluse.mjs` and entries for
+`PreToolUse`, `UserPromptSubmit`, `PostToolUse`, and `SessionEnd` in `.codex/hooks.json`.
+That JSON is merged, not overwritten: user entries, sibling handlers, other events, and keys
+the installer does not know stay where they are. The scaffold config protects `.codex/hooks`
+by default.
 
 **Approval is not optional.** Codex records trust against the hash of a hook's definition, so a
 newly written hook is listed for review and skipped until someone approves it — until then
 nothing is judged. `init` writes a byte-identical command string on every run, so a re-install
 does not invalidate an approval you already gave.
 
-Codex normalises every file edit into one tool, `apply_patch`, and sends the patch text rather
-than a path argument. `Edit` and `Write` are matcher aliases you may write in the hooks file;
-they never arrive as the tool name. One patch that touches several files carries one IR element
-per file, and any one of them blocking blocks the whole call.
-
-Codex supplies no transcript channel, so the session witness valve has no human message to read.
-For an intentional blocked edit, use your own terminal. Installing more than one session adapter
-in one project can run the judge twice per call.
+Codex normalises every file edit that reaches the hook into one tool, `apply_patch`, and sends
+the patch text rather than a path argument. `Edit` and `Write` are matcher aliases you may
+write in the hooks file; they never arrive as the tool name. One patch that touches several
+files carries one IR element per file, and any one of them blocking blocks the whole call.
+
+**An approved hook does not cover Code Mode.** In codex-cli 0.154 a Code Mode `exec` dispatch,
+and the tool calls nested in its JavaScript, do not reach `PreToolUse`
+([openai/codex#23411](https://github.com/openai/codex/issues/23411)), so an edit made that way
+is neither judged nor logged even while `/hooks` shows the hook Active. `init` prints this as a
+`note:` line; the [package reference](../reference/packages/adapter-codex.md#limits)
+lists it with the other declared limits.
+
+Codex's transcript format remains unstable and is never parsed. Instead, `UserPromptSubmit`
+records timestamped human messages and `PostToolUse` records completed tool calls in an
+adapter-owned file under `.polydeukes/codex-sessions/`; `SessionEnd` removes it. To release an
+intentional block, send the configured witness token alone on the first line, then retry the
+call. If the recovery message says no `UserPromptSubmit` evidence was recorded, use your own
+terminal because the retry cannot reach the witness valve. Installing more than one session
+adapter in one project can run the judge twice per call.
 
 
 <a id="change-set-surface"></a>