phasegate 0.335.0 → 0.340.0

package/docs/guide/grok-integration.md

@@ -0,0 +1,26 @@
+# Grok Build Integration
+
+<!-- @work-item-id WI-385 -->
+
+Phasegate uses Grok Build's Claude-compatible project hook scanner. It manages `.claude/settings.json` as the single hook source and deliberately does not create `.grok/hooks`, avoiding duplicate invocation.
+
+Minimum supported runtime: the hook-capable Grok CLI 1.0.0 series, which is the series used to verify this integration. If hooks appear to be silently inactive, run `grok inspect` and confirm the project hook is loaded and trusted in `/hooks`.
+
+## Setup
+
+```bash
+npx phasegate install --agent grok --with-husky --apply
+npx phasegate doctor --agent grok
+```
+
+The managed PreToolUse entries collectively match `Bash|Write|Edit|apply_patch`; each Phasegate command has an explicit 30-second timeout. Grok otherwise defaults a hook to 5 seconds and fails open when the hook times out or crashes, so the distributed timeout gives Phasegate enough time to inspect a write while L2 pre-commit remains the backstop. `run_terminal_command`, `search_replace`, `write`, and `apply_patch` camelCase payloads are normalized to the existing Bash/Write/Edit/patch pipeline. Grok truncates tool input at 128 KB; a truncated command or patch is denied because the full target set cannot be proven. A direct tool with a complete path can still be checked.
+
+## Result contract
+
+- Deny writes top-level `{ "decision": "deny", "reason": ... }` and Claude-compatible `hookSpecificOutput` to stdout, writes the reason to stderr, and exits 2.
+- Allow exits 0 with empty stdout and does not override permission.
+- Agent/model fields and the selected install target are not authorization inputs.
+
+## Trust and residual risk
+
+Project hooks can be skipped before trust is approved, and Phasegate cannot inspect Grok's external trust state. Run `grok inspect`, open `/hooks`, and approve with `--trust` or `/hooks-trust`. Keep L2 pre-commit and CI enabled because timeout/crash remains fail-open even with the explicit 30-second limit. The canonical path key for every future Grok `write` variant remains runtime-controlled; unknown supported-write shapes fail closed rather than silently allowing.

package/docs/guide/hooks-integration.md

@@ -6,17 +6,28 @@ Phasegate integrates natively with Claude Code through its hooks system. This en
 
 For new or existing projects, prefer `npx phasegate install --dry-run` followed by `npx phasegate install --apply` so existing hook JSON is merged instead of replaced. Manual editing is still possible, but then `phasegate doctor` may report missing managed targets until the expected PhaseGate entries, skill links, Husky scripts, CI workflow, and manifest are present. See [Setup Artifacts](setup-artifacts.md). <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 -->
 
-Add the following to `.claude/settings.json`:
+### Manual hook configuration
+
+If structured install is unavailable, use the same packaged commands and timeout as the distributed `.claude/settings.json`:
 
 ```jsonc
 {
   "hooks": {
     "PreToolUse": [
+      {
+        "matcher": "Bash|apply_patch",
+        "hooks": [{
+          "type": "command",
+          "command": "npx phasegate hook pre-tool-use",
+          "timeout": 30
+        }]
+      },
       {
         "matcher": "Write|Edit",
         "hooks": [{
           "type": "command",
-          "command": "npx tsx scripts/harness/agent-integration/presentation/pre-tool-use-hook.ts"
+          "command": "npx phasegate hook pre-tool-use",
+          "timeout": 30
         }]
       }
     ],
@@ -25,7 +36,7 @@ Add the following to `.claude/settings.json`:
         "matcher": "Write|Edit",
         "hooks": [{
           "type": "command",
-          "command": "npx tsx scripts/harness/agent-integration/presentation/post-tool-use-hook.ts"
+          "command": "npx phasegate hook post-tool-use"
         }]
       }
     ],
@@ -34,7 +45,7 @@ Add the following to `.claude/settings.json`:
         "matcher": "",
         "hooks": [{
           "type": "command",
-          "command": "npx tsx scripts/harness/agent-integration/presentation/stop-hook.ts"
+          "command": "npx phasegate hook stop"
         }]
       }
     ]
@@ -42,6 +53,18 @@ Add the following to `.claude/settings.json`:
 }
 ```
 
+## Runtime coverage matrix
+
+<!-- @work-item-id WI-385 -->
+
+| Runtime payload | Managed source | Pre-edit deny output | Coverage boundary |
+|---|---|---|---|
+| Claude / Codex flat snake_case | `.claude/settings.json` / `.codex/hooks.json` | empty stdout, stderr, exit 2 | Existing contract unchanged |
+| Grok flat camelCase | Claude-compatible `.claude/settings.json` | top-level deny plus `hookSpecificOutput`, stderr, exit 2 | Trust must be checked with `grok inspect` / `/hooks` |
+| Antigravity nested `toolCall` | named `.agents/hooks.json` | top-level `decision` / `reason`, stderr, exit 2 | Hard block supported for `agy` CLI only |
+
+All allow paths keep stdout empty and do not override runtime permission. Malformed, ambiguous, truncated command/patch, or supported write tools without extractable targets fail closed. L2 pre-commit and CI remain the backstops for untrusted/skipped hooks, Antigravity IDE/desktop, and unverified timeout/crash behavior.
+
 ## Hook Behaviors
 
 ### Responsibility Separation (important)

package/docs/guide/installation.md

@@ -36,7 +36,7 @@ npm install
 npx phasegate init --name <project-name>
 ```
 
-This deploys 29 skills to `skills/`, creates the agent-facing skill links (for example `.claude/skills/` or `.codex/skills/`), and generates `phasegate.config.json`.
+This deploys 29 skills to `skills/`, creates the selected agent-facing skill links (`.claude/skills/`, `.codex/skills/`, or `.agents/skills/`), and generates `phasegate.config.json`.
 
 `init` is the legacy-compatible bootstrap path for new projects. It also runs the structured install path for the selected agent target so `CLAUDE.md` and/or `AGENTS.md` receive a PhaseGate managed section. Use `install` when the project may already have hooks, package scripts, or CI files that should be preserved. <!-- @work-item-id WI-174 -->
 
@@ -56,7 +56,9 @@ npx phasegate install --apply
 npx phasegate doctor
 ```
 
-`install --dry-run` reports whether each target will be created, merged, skipped, or refused. `install --apply` performs the merge, adds package scripts and the `phasegate` devDependency, deploys selected bundled skills to root `skills/`, creates `.claude/skills` and `.codex/skills` links, writes `CLAUDE.md` / `AGENTS.md` managed sections for selected agent targets, writes `.github/workflows/phasegate-aidlc-gate.yml` when CI is enabled, and records managed entries in `.phasegate/manifest.json`. Husky hook targets (`.husky/*`) and the GitHub Actions target are opt-in, matching `init` and `setup:agent`: pass `--with-husky` and/or `--with-ci` to include them — without these flags `install` does not touch `.husky/` or `.github/workflows/`. <!-- @work-item-id WI-316 --> Existing skills catalogs are merged: PhaseGate refreshes only bundled skill directories selected by `--skills core|all` and preserves user-owned skills. See [Setup Artifacts](setup-artifacts.md) for the full managed target, generated artifact, runtime state, legacy artifact, and user-level setting inventory. <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 --> <!-- @work-item-id WI-174 --> <!-- @work-item-id WI-216 -->
+`install --dry-run` reports whether each target will be created, merged, skipped, or refused. `install --apply` performs the merge, adds package scripts and the `phasegate` devDependency, deploys selected bundled skills to root `skills/`, creates the selected `.claude/skills`, `.codex/skills`, and `.agents/skills` links, writes `CLAUDE.md` / `AGENTS.md` managed sections for selected agent targets, writes `.github/workflows/phasegate-aidlc-gate.yml` when CI is enabled, and records managed entries in `.phasegate/manifest.json`. Husky hook targets (`.husky/*`) and the GitHub Actions target are opt-in, matching `init` and `setup:agent`: pass `--with-husky` and/or `--with-ci` to include them — without these flags `install` does not touch `.husky/` or `.github/workflows/`. <!-- @work-item-id WI-316 --> Existing skills catalogs are merged: PhaseGate refreshes only bundled skill directories selected by `--skills core|all` and preserves user-owned skills. See [Setup Artifacts](setup-artifacts.md) for the full managed target, generated artifact, runtime state, legacy artifact, and user-level setting inventory. <!-- @work-item-id WI-152 --> <!-- @work-item-id WI-169 --> <!-- @work-item-id WI-174 --> <!-- @work-item-id WI-216 -->
+
+Agent targets are `claude | codex | both | grok | antigravity | all`. `both` is backward-compatible Claude + Codex. Grok shares `.claude/settings.json` and `.claude/skills`, receives `AGENTS.md` without Claude-only `CLAUDE.md`, and does not receive `.grok/hooks`. Antigravity receives `.agents/hooks.json`, `.agents/skills`, and `AGENTS.md`. `all` installs Claude, Codex, and Antigravity surfaces, with Grok covered once by the Claude-compatible hook. <!-- @work-item-id WI-385 -->
 
 For personal evaluation inside a team-owned repository:
 

package/docs/guide/setup-artifacts.md

@@ -14,7 +14,7 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 
 | Class | Examples | Owner | Lifecycle |
 |---|---|---|---|
-| Managed target | `phasegate.config.json`, `.claude/settings.json`, `.codex/hooks.json`, `CLAUDE.md`, `AGENTS.md`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, root `skills/` bundled skill bodies, `.claude/skills`, `.codex/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block, real runtime artifact, shared skill body, or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
+| Managed target | `phasegate.config.json`, `.claude/settings.json`, `.codex/hooks.json`, `.agents/hooks.json`, `CLAUDE.md`, `AGENTS.md`, `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`, `.github/workflows/phasegate-aidlc-gate.yml`, root `skills/` bundled skill bodies, `.claude/skills`, `.codex/skills`, `.agents/skills`, `package.json` PhaseGate scripts/devDependency | PhaseGate managed block, real runtime artifact, shared skill body, or symlink plus user content | Created or merged by `install`, refreshed by `reconcile`, removed or reversed by `uninstall` |
 | Configuration | `phasegate.config.json`, `package.json` | User owned, PhaseGate assisted | Created by `init` or project install when absent; `install` may merge scripts/devDependency into `package.json` |
 | Generated artifact | `.phasegate/manifest.json`, `.phasegate/backups/*`, `.phasegate/uninstalled-*.json`, `.phasegate/baseline.json` | PhaseGate | Written by lifecycle commands and validators; safe to regenerate only through the owning command |
 | Runtime state/report | `.phasegate/hook-skip-events.jsonl`, explicit `doctor --report-out <path>` output, `reports/regression/*`, resolved `reporting.outputDir` reports | PhaseGate command output | Produced while hooks, doctor, and validation commands run |
@@ -26,11 +26,11 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 
 `install --apply` and `reconcile --apply` manage only explicit targets. The current structured lifecycle covers:
 
-- Agent hook JSON: `.claude/settings.json`, `.codex/hooks.json`
+- Agent hook JSON: `.claude/settings.json`, `.codex/hooks.json`, `.agents/hooks.json`
 - Agent context files: `CLAUDE.md` and `AGENTS.md` managed sections. `AGENT.md` singular is not a PhaseGate managed target; treat it as user-owned content or migrate it manually. <!-- @work-item-id WI-174 -->
 - Husky scripts when requested: `.husky/pre-commit`, `.husky/commit-msg`, `.husky/pre-push`
 - CI workflow when requested: `.github/workflows/phasegate-aidlc-gate.yml`
-- Agent skill links: `.claude/skills`, `.codex/skills`
+- Agent skill links: `.claude/skills`, `.codex/skills`, `.agents/skills`
 - Project shared bundled skills: selected `skills/<name>/` directories plus `skills/.harness-version`
 - Project config: `phasegate.config.json` when absent, so installed agent hooks have a discoverable runtime config
 - Package metadata: PhaseGate scripts and `devDependencies.phasegate` in `package.json`
@@ -48,7 +48,7 @@ If `.claude/*` or `.codex/*` already exists and is not a PhaseGate-managed perso
 
 Personal agent context is also placed only where the runtime will read it. Claude Code uses `.claude/CLAUDE.md`. Codex uses root `AGENTS.md` when PhaseGate can create or manage it locally; if a team `AGENTS.md` already exists, PhaseGate leaves it unchanged and doctor reports `codex-context-missing` instead of creating `AGENTS.override.md`. <!-- @work-item-id WI-215 -->
 
-Project install uses a different topology: selected bundled skills are deployed once to root `skills/`, and `.claude/skills` / `.codex/skills` point to that shared target. Existing root `skills/` is also a mergeable catalog: selected bundled skill directories are refreshed, selection-excluded or user-owned skills are not removed, and uninstall deletes only manifest-managed bundled skills plus metadata. If an older project install has the links but an empty `skills/` target, `phasegate doctor` reports the selected agent skill check and `phasegate reconcile --apply` repairs the shared skill bodies. <!-- @work-item-id WI-210 --> <!-- @work-item-id WI-216 -->
+Project install uses a different topology: selected bundled skills are deployed once to root `skills/`, and `.claude/skills` / `.codex/skills` / `.agents/skills` point to that shared target. Existing root `skills/` is also a mergeable catalog: selected bundled skill directories are refreshed, selection-excluded or user-owned skills are not removed, and uninstall deletes only manifest-managed bundled skills plus metadata. If an older project install has the links but an empty `skills/` target, `phasegate doctor` reports the selected agent skill check and `phasegate reconcile --apply` repairs the shared skill bodies. <!-- @work-item-id WI-210 --> <!-- @work-item-id WI-216 -->
 
 ## Doctor Findings
 

package/docs/guide/skills-overview.md

@@ -1,6 +1,6 @@
 # Skills Overview
 
-Phasegate provides 29 skills covering the full AIDLC (AI-Driven Development Life Cycle). `npx phasegate init` and project `npx phasegate install` deploy skill bodies to root `skills/` and expose them to enabled agents through `.claude/skills/` / `.codex/skills/` links. Personal install instead writes real local-only per-agent skill directories. <!-- @work-item-id WI-210 -->
+Phasegate provides 29 skills covering the full AIDLC (AI-Driven Development Life Cycle). `npx phasegate init` and project `npx phasegate install` deploy skill bodies to root `skills/` and expose them to enabled agents through `.claude/skills/`, `.codex/skills/`, or `.agents/skills/` links. Personal install instead writes real local-only per-agent skill directories. <!-- @work-item-id WI-210 --> <!-- @work-item-id WI-385 -->
 
 Bundled `SKILL.md` files include `languages: [typescript]` frontmatter so PhaseGate can distinguish current TypeScript-oriented guidance from future language-specific skill variants. The metadata is advisory for applicability and does not prevent non-TypeScript projects from installing the catalog. <!-- @work-item-id WI-212 -->
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.335.0",
+  "version": "0.340.0",
   "packageManager": "pnpm@10.30.1",
   "description": "Phasegate — AI-agnostic quality defense toolkit. Enforces structural integrity between design intent and code.",
   "license": "MIT",

package/scripts/harness/agent-integration/application/dto/handle-pre-tool-use-dto.ts

@@ -26,7 +26,7 @@ export interface HandlePreToolUseOutput {
   phaseGateBlockers?: string[];
   storyReflectionBlockers?: string[];
   storyReflectionWarnings?: string[];
-  fullModeRejectionRule?: 'MIXED_CHANGES' | 'NEW_DOMAIN' | 'API_CONTRACT';
+  fullModeRejectionRule?: 'CATEGORY_NOT_ALLOWED' | 'MIXED_CHANGES' | 'NEW_DOMAIN' | 'API_CONTRACT';
   fullModeDominantCategory?: string;
   nextAction?: string;
   // Quick Mode が write を許可した際に dominant カテゴリを presentation 層に伝える。

package/scripts/harness/agent-integration/application/dto/normalized-pre-tool-use-request.ts

@@ -0,0 +1,32 @@
+/**
+ * @unit agent-integration
+ * @layer application
+ * @work-item-id WI-385
+ */
+
+export type PayloadShape = "FLAT_SNAKE_CASE" | "FLAT_CAMEL_CASE" | "NESTED_TOOL_CALL";
+
+export type HookResponseProfile = "LEGACY_EXIT_ONLY" | "COMPATIBILITY_DENY_ENVELOPE" | "TOP_LEVEL_DENY_ENVELOPE";
+
+export interface CanonicalPreToolUseInput {
+  readonly path?: string;
+  readonly file_path?: string;
+  readonly paths?: readonly string[];
+  readonly command?: string;
+  readonly content?: string;
+  readonly old_string?: string;
+  readonly new_string?: string;
+}
+
+export interface NormalizedPreToolUseRequest {
+  readonly shape: PayloadShape;
+  readonly responseProfile: HookResponseProfile;
+  readonly cwd?: string;
+  readonly toolName: string;
+  readonly toolInput: CanonicalPreToolUseInput;
+  readonly inputTruncated: boolean;
+}
+
+export type PreToolUseNormalizationResult =
+  | { readonly ok: true; readonly request: NormalizedPreToolUseRequest }
+  | { readonly ok: false; readonly reason: string; readonly responseProfile?: HookResponseProfile };

package/scripts/harness/agent-integration/application/usecases/handle-pre-tool-use-usecase.ts

@@ -278,7 +278,7 @@ export class HandlePreToolUseUseCase {
     blockedFilePath: string | undefined,
     result: {
       requiresFullMode: boolean;
-      rejectionRule?: "MIXED_CHANGES" | "NEW_DOMAIN" | "API_CONTRACT";
+      rejectionRule?: "CATEGORY_NOT_ALLOWED" | "MIXED_CHANGES" | "NEW_DOMAIN" | "API_CONTRACT";
       rejectionReason?: string;
       dominantCategory?: string;
     },
@@ -581,7 +581,7 @@ export class HandlePreToolUseUseCase {
       // WI-363: .husky/ 配下は L0 runtime の実施点。Quick Mode でも書き換えさせない。
       pattern: /(?:^|\/)\.husky\//,
       message: (fp) =>
-        `保護ファイルへの書き込みがブロックされました: ${fp}\n.husky/ 配下は L0 runtime（pre-commit / commit-msg / pre-push）の実施点であり、Quick Mode でも変更できません。\n未導入 hook の配置は npx phasegate setup:agent --apply --with-husky を使用してください。\n意図的に手編集する場合は phasegate.config.json の protectedFiles.exclude に対象パターンを明示してください。`,
+        `保護ファイルへの書き込みがブロックされました: ${fp}\n.husky/ 配下は L0 runtime（pre-commit / commit-msg / pre-push）の実施点であり、Quick Mode でも変更できません。\n未導入 hook の配置は npx phasegate setup:agent --apply --with-husky を使用してください。\n意図的な手編集が必要な場合は、agent セッション外で人間が変更し、通常の検証を実行してください。`,
     },
   ];
 

package/scripts/harness/agent-integration/domain/ports/full-mode-requirement-query-port.ts

@@ -1,15 +1,17 @@
 // @unit agent-integration
 // @layer domain
+// @work-item-id WI-384
 
 export interface FullModeRequirementQueryResult {
   readonly requiresFullMode: boolean;
-  readonly rejectionRule?: 'MIXED_CHANGES' | 'NEW_DOMAIN' | 'API_CONTRACT';
+  readonly rejectionRule?: 'CATEGORY_NOT_ALLOWED' | 'MIXED_CHANGES' | 'NEW_DOMAIN' | 'API_CONTRACT';
   readonly rejectionReason?: string;
   readonly dominantCategory?: string;
 }
 
 export interface FullModeTargetChange {
   readonly filePath: string;
+  readonly changeKind?: 'CREATE' | 'MODIFY' | 'DELETE';
   readonly beforeContent?: string | null;
   readonly afterContent?: string | null;
 }

package/scripts/harness/agent-integration/domain/services/apply-patch-write-target-extractor.ts

@@ -0,0 +1,98 @@
+/**
+ * @layer domain
+ * @unit agent-integration
+ * @work-item-id WI-384
+ *
+ * Codex apply_patch の raw patch から書き込み対象と変更種別を抽出する。
+ */
+
+export type PatchChangeKind = "CREATE" | "MODIFY" | "DELETE";
+
+export interface PatchWriteTarget {
+  readonly filePath: string;
+  readonly changeKind: PatchChangeKind;
+}
+
+const APPLY_PATCH_BEGIN_SOURCE = String.raw`\*\*\*\s+Begin\s+Patch`;
+const APPLY_PATCH_END_SOURCE = String.raw`\*\*\*\s+End\s+Patch`;
+const APPLY_PATCH_FILE_LINE_SOURCE = String.raw`^\*\*\*\s+(Update|Add|Delete)\s+File:\s*(.+?)\s*$`;
+const APPLY_PATCH_MOVE_LINE_SOURCE = String.raw`^\*\*\*\s+Move\s+to:\s*(.+?)\s*$`;
+
+const CHANGE_KIND_BY_DIRECTIVE = Object.freeze({
+  Add: "CREATE",
+  Update: "MODIFY",
+  Delete: "DELETE",
+} as const satisfies Readonly<Record<string, PatchChangeKind>>);
+
+const EMPTY_TARGETS: readonly PatchWriteTarget[] = Object.freeze([]);
+
+export class ApplyPatchWriteTargetExtractor {
+  extract(rawPatch: string): readonly PatchWriteTarget[] {
+    if (typeof rawPatch !== "string" || rawPatch.length === 0) {
+      return EMPTY_TARGETS;
+    }
+
+    const beginGlobal = new RegExp(APPLY_PATCH_BEGIN_SOURCE, "g");
+    const beginStarts: number[] = [];
+    let match = beginGlobal.exec(rawPatch);
+    while (match !== null) {
+      beginStarts.push(match.index + match[0].length);
+      match = beginGlobal.exec(rawPatch);
+    }
+    if (beginStarts.length === 0) {
+      return EMPTY_TARGETS;
+    }
+
+    const endGlobal = new RegExp(APPLY_PATCH_END_SOURCE, "g");
+    const endStarts: number[] = [];
+    match = endGlobal.exec(rawPatch);
+    while (match !== null) {
+      endStarts.push(match.index);
+      match = endGlobal.exec(rawPatch);
+    }
+
+    const targets: PatchWriteTarget[] = [];
+    const seen = new Set<string>();
+    for (let index = 0; index < beginStarts.length; index += 1) {
+      const start = beginStarts[index];
+      const nextBegin = index + 1 < beginStarts.length ? beginStarts[index + 1] : rawPatch.length;
+      const endInRange = endStarts.find((candidate) => candidate > start && candidate <= nextBegin);
+      const body = rawPatch.slice(start, endInRange ?? nextBegin);
+      let acceptsMoveDestination = false;
+
+      for (const line of body.split(/\r?\n/)) {
+        const fileMatch = new RegExp(APPLY_PATCH_FILE_LINE_SOURCE).exec(line);
+        if (fileMatch !== null) {
+          const directive = fileMatch[1] as keyof typeof CHANGE_KIND_BY_DIRECTIVE;
+          const filePath = fileMatch[2].trim();
+          acceptsMoveDestination = directive === "Update";
+          if (filePath.length === 0) continue;
+          const changeKind = CHANGE_KIND_BY_DIRECTIVE[directive];
+          this.appendTarget(targets, seen, filePath, changeKind);
+          continue;
+        }
+
+        const moveMatch = acceptsMoveDestination ? new RegExp(APPLY_PATCH_MOVE_LINE_SOURCE).exec(line) : null;
+        acceptsMoveDestination = false;
+        if (moveMatch === null) continue;
+        const filePath = moveMatch[1].trim();
+        if (filePath.length === 0) continue;
+        this.appendTarget(targets, seen, filePath, "CREATE");
+      }
+    }
+
+    return targets.length === 0 ? EMPTY_TARGETS : Object.freeze(targets);
+  }
+
+  private appendTarget(
+    targets: PatchWriteTarget[],
+    seen: Set<string>,
+    filePath: string,
+    changeKind: PatchChangeKind,
+  ): void {
+    const key = `${changeKind}\u0000${filePath}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    targets.push(Object.freeze({ filePath, changeKind }));
+  }
+}

package/scripts/harness/agent-integration/domain/services/bash-write-target-extractor.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit agent-integration
+ * @work-item-id WI-384
  *
  * BashWriteTargetExtractor ドメインサービス
  *
@@ -25,6 +26,8 @@
  *     `*** Update|Add|Delete File: <path>` 行) — Codex CLI 対応 (ISSUE-013 Wave 1)
  */
 
+import { ApplyPatchWriteTargetExtractor } from './apply-patch-write-target-extractor.js';
+
 /** 引数トークン (値とクォート種別) */
 type Token = {
   readonly value: string;
@@ -508,62 +511,13 @@ function extractFromCommandString(command: string): string[] {
     }
   }
   // ネスト内の apply_patch heredoc も拾う
-  for (const p of extractApplyPatchTargets(command)) {
-    collected.push(p);
+  const patchExtractor = new ApplyPatchWriteTargetExtractor();
+  for (const target of patchExtractor.extract(command)) {
+    collected.push(target.filePath);
   }
   return collected;
 }
 
-/** apply_patch ブロック境界マーカー (Begin/End) */
-const APPLY_PATCH_BEGIN_SOURCE = String.raw`\*\*\*\s+Begin\s+Patch`;
-const APPLY_PATCH_END_SOURCE = String.raw`\*\*\*\s+End\s+Patch`;
-/** ブロック内のファイル行: `*** (Update|Add|Delete) File: <path>` */
-const APPLY_PATCH_FILE_LINE_SOURCE = String.raw`^\s*\*\*\*\s+(?:Update|Add|Delete)\s+File:\s*(.+?)\s*$`;
-
-/**
- * apply_patch ヒアドキュメント構文から対象ファイルパスを抽出する。
- *
- * Codex CLI 等が採用する unified-diff 風パッチフォーマット:
- *   *** Begin Patch
- *   *** Update File: <path>
- *   *** Add File: <path>
- *   *** Delete File: <path>
- *   *** End Patch
- *
- * `*** End Patch` が欠けている場合は command 末尾までをブロックとして扱う
- * (保護側に倒す — phase-gate の取りこぼしよりも誤検出のほうが許容される)。
- */
-function extractApplyPatchTargets(command: string): string[] {
-  const beginGlobal = new RegExp(APPLY_PATCH_BEGIN_SOURCE, 'g');
-  const beginStarts: number[] = [];
-  let m: RegExpExecArray | null;
-  while ((m = beginGlobal.exec(command)) !== null) {
-    beginStarts.push(m.index + m[0].length);
-  }
-  if (beginStarts.length === 0) return [];
-
-  const endGlobal = new RegExp(APPLY_PATCH_END_SOURCE, 'g');
-  const endStarts: number[] = [];
-  while ((m = endGlobal.exec(command)) !== null) {
-    endStarts.push(m.index);
-  }
-
-  const results: string[] = [];
-  for (let i = 0; i < beginStarts.length; i += 1) {
-    const start = beginStarts[i];
-    const nextBegin = i + 1 < beginStarts.length ? beginStarts[i + 1] : command.length;
-    const endInRange = endStarts.find((e) => e > start && e <= nextBegin);
-    const end = endInRange ?? nextBegin;
-    const body = command.slice(start, end);
-
-    const fileRegex = new RegExp(APPLY_PATCH_FILE_LINE_SOURCE, 'gm');
-    while ((m = fileRegex.exec(body)) !== null) {
-      results.push(m[1]);
-    }
-  }
-  return results;
-}
-
 export class BashWriteTargetExtractor {
   /**
    * Bash コマンド文字列から書き込み先ファイルパスを抽出する。

package/scripts/harness/agent-integration/domain/value-objects/hook-translation-result.ts

@@ -18,7 +18,7 @@ export interface BlockMetadata {
   readonly scopeLevel?: 1 | 2 | 3;
   readonly unitId?: string;
   readonly storyId?: string;
-  readonly fullModeRejectionRule?: 'MIXED_CHANGES' | 'NEW_DOMAIN' | 'API_CONTRACT';
+  readonly fullModeRejectionRule?: 'CATEGORY_NOT_ALLOWED' | 'MIXED_CHANGES' | 'NEW_DOMAIN' | 'API_CONTRACT';
   readonly fullModeRejectionReason?: string;
   readonly fullModeDominantCategory?: string;
 }

package/scripts/harness/agent-integration/domain/value-objects/protected-file-list.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit agent-integration
+ * @work-item-id WI-390
  *
  * ProtectedFileList 値オブジェクト
  * 変更をブロックすべきファイルのパターンリスト
@@ -14,13 +15,15 @@ export class ProtectedFileListEmptyError extends Error {
   }
 }
 
-/** デフォルトの保護対象ファイルパターン */
-const DEFAULT_PATTERNS = [
-  'biome.json',
-  '.biome.json',
-  'tsconfig.json',
-  'package.json',
-  'package-lock.json',
+/**
+ * 設定から除外できない agent trust roots。
+ * これらを protectedFiles.exclude で解除できると、防御機構そのものを agent が
+ * 無効化してから書き換えられるため、通常の保護対象とは別の集合で保持する。
+ */
+const NON_EXCLUDABLE_PATTERNS = [
+  'phasegate.config.json',
+  '.phasegate-local/phasegate.config.json',
+  '**/phasegate.config.json',
   // baseline.json は grandfather 判定の信頼基盤。手動追記による protected file の
   // grandfather bypass を防ぐため、書き込み自体を保護対象とする。
   '.phasegate/baseline.json',
@@ -30,8 +33,24 @@ const DEFAULT_PATTERNS = [
   // 入ったため、防御機構そのものの書き換えを protected file として明示的に止める。
   '.husky/**',
   '**/.husky/**',
+  // Root agent instructions determine the permissions and operating procedure
+  // used by coding agents, so direct agent writes must remain blocked.
+  'CLAUDE.md',
+  'AGENTS.md',
+  'GEMINI.md',
+];
+
+/** 利用者設定で除外可能な通常のデフォルト保護対象。 */
+const EXCLUDABLE_DEFAULT_PATTERNS = [
+  'biome.json',
+  '.biome.json',
+  'tsconfig.json',
+  'package.json',
+  'package-lock.json',
 ];
 
+const DEFAULT_PATTERNS = [...NON_EXCLUDABLE_PATTERNS, ...EXCLUDABLE_DEFAULT_PATTERNS];
+
 /**
  * glob パターンのシンプルなマッチング実装
  * micromatch なしで基本的な glob をサポート
@@ -79,23 +98,21 @@ export class ProtectedFileList {
   }
 
   static createWithExclusions(exclusions: string[]): ProtectedFileList {
-    const filtered = DEFAULT_PATTERNS.filter((p) => !exclusions.includes(p));
-    if (filtered.length === 0) {
-      return new ProtectedFileList([...DEFAULT_PATTERNS]);
-    }
-    return new ProtectedFileList(filtered);
+    const excludable = EXCLUDABLE_DEFAULT_PATTERNS.filter((p) => !exclusions.includes(p));
+    return new ProtectedFileList([...NON_EXCLUDABLE_PATTERNS, ...excludable]);
   }
 
   static createWithAdditionalAndExclusions(
     additionalPatterns: string[],
     exclusions: string[],
   ): ProtectedFileList {
-    const base = DEFAULT_PATTERNS.filter((p) => !exclusions.includes(p));
-    const allPatterns = [...base, ...additionalPatterns];
-    if (allPatterns.length === 0) {
-      return new ProtectedFileList([...DEFAULT_PATTERNS]);
-    }
-    return new ProtectedFileList(allPatterns);
+    const excludableDefaults = EXCLUDABLE_DEFAULT_PATTERNS.filter((p) => !exclusions.includes(p));
+    const excludableAdditional = additionalPatterns.filter((p) => !exclusions.includes(p));
+    return new ProtectedFileList([
+      ...NON_EXCLUDABLE_PATTERNS,
+      ...excludableDefaults,
+      ...excludableAdditional,
+    ]);
   }
 
   matches(filePath: string): boolean {

package/scripts/harness/agent-integration/presentation/phasegate-status-context.ts

@@ -243,7 +243,7 @@ export function buildSessionStartContext(status: PhasegateStatus): string {
     "",
     "- Do NOT write to protected files without going through `/quick-implementor` skill.",
     '- Do NOT create/structurally modify source files under units listed as "blocked" below — the required design docs (logical_design.md / domain_model.md) are missing, and pre-tool-use hooks will block writes.',
-    "- Prefer the native `apply_patch` tool for edits, BUT note that Codex's apply_patch bypasses pre-edit hooks. Violations surface at pre-commit time.",
+    "- Native `apply_patch` edits are phase-gated at PreToolUse; the Codex matcher is `Bash|apply_patch`. L2 pre-commit remains the backstop for skipped or untrusted hooks.",
     "",
   ];
 

package/scripts/harness/agent-integration/presentation/post-tool-use-hook.ts

@@ -3,6 +3,7 @@
  * @unit agent-integration
  * @work-item-id WI-208
  * @work-item-id WI-323
+ * @work-item-id WI-384
  *
  * PostToolUse Hook Adapter
  * Claude Code の PostToolUse Hook エントリポイント