phasegate 0.160.11 → 0.160.12

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.160.12] - 2026-05-20
+
+### Added
+
+- **WI-206 — hook-visible Full Mode sessions** — adds `phasegate session begin/end` for TTL-scoped Full Mode authorization, lets PreToolUse allow matching unit/category edits through `.phasegate/session.json`, updates `/story-implementor` to use the session route, and improves full-mode block guidance so users are not sent to a guide-only route.
+
 ## [0.160.11] - 2026-05-17
 
 ### Fixed

package/README.md

@@ -135,7 +135,7 @@ npx phasegate reconcile --apply
 
 ```bash
 npx phasegate init --name my-project --agent codex --with-husky
-codex features enable codex_hooks
+codex features enable hooks
 ```
 
 Use `--agent both` for projects that use Claude Code and Codex together. Codex native `apply_patch` currently cannot be intercepted before the edit, so those violations are caught at pre-commit; Bash-based writes are blocked before execution.
@@ -482,12 +482,12 @@ Phasegate also integrates with [OpenAI Codex CLI](https://developers.openai.com/
 npx phasegate init --name my-project --agent codex --with-husky
 
 # 2. Enable the Codex CLI feature flag manually on your machine
-codex features enable codex_hooks
+codex features enable hooks
 ```
 
 For dual-agent projects (Claude + Codex), use `--agent both`.
 
-`init` sets up files inside the project. The Codex CLI user-level setting (`codex_hooks`) remains an explicit manual step.
+`init` sets up files inside the project. The Codex CLI user-level hooks feature remains an explicit manual step.
 
 ### Coverage and known limitation
 

package/docs/guide/cli-reference.md

@@ -29,6 +29,7 @@ Command names in this document are split into three surfaces:
 | `reconcile --dry-run` / `--apply` | Update PhaseGate-managed files to current package templates and refresh manifest hashes; `--force` allows managed-file replacement with backup. |
 | `setup:agent` | Agent-readable setup planner and optional apply path. Options: `--intent <minimal\|recommended\|strict\|ci-only\|agent-hooks\|retrofit>`, `--agent <claude\|codex\|both>`, `--workflow <standard\|strict>`, `--with-husky`, `--with-ci`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-172 --> |
 | `config:plan` | Agent-readable configuration change planner. Options: `--intent <l4-strict\|codex-hooks\|ci-fail-on-warning\|baseline-reset\|quick-mode-strict\|quick-mode-relax\|retrofit-bootstrap\|planning-mode-relax>`, `--dry-run`, `--apply`, `--json`. <!-- @work-item-id WI-173 --> <!-- @work-item-id WI-201 --> <!-- @work-item-id WI-204 --> |
+| `session begin` / `session end` | Hook-visible Full Mode session manager. Use `session begin --mode full --unit <unit> --work-item <WI-XXX> --reason <text> --duration <ttl>` before implementation that must touch Quick Mode disallowed categories, and `session end --work-item <WI-XXX>` after completion. <!-- @work-item-id WI-206 --> |
 | `update-skills` | Compatibility alias for `reconcile`; use `reconcile` for new automation. |
 | `scaffold-wi <unit> <type>` | Create `docs/inception/{unit}/WI-XXX/description.md` using the next free WI number. |
 | `emit-agent-rules` | Print the AGENTS.md / CLAUDE.md WI workflow rules block. |

package/docs/guide/codex-integration.md

@@ -11,7 +11,7 @@ Phasegate supports [OpenAI Codex CLI](https://developers.openai.com/codex/cli) t
 npx phasegate init --name my-project --agent codex --with-husky
 
 # 2. Enable the Codex CLI feature flag manually
-codex features enable codex_hooks
+codex features enable hooks
 ```
 
 For dual-agent projects (Claude + Codex), use `--agent both`.
@@ -19,7 +19,7 @@ For dual-agent projects (Claude + Codex), use `--agent both`.
 Responsibility split:
 
 - `phasegate init --agent codex` sets up **project-local artifacts** such as `phasegate.config.json`, `skills/`, `.codex/hooks.json`, and `.codex/skills`
-- `codex features enable codex_hooks` updates the **Codex CLI user environment** and is intentionally left as a manual step
+- `codex features enable hooks` updates the **Codex CLI user environment** and is intentionally left as a manual step
 
 ### Manual setup
 
@@ -31,7 +31,7 @@ Add to `~/.codex/config.toml` (or project `.codex/config.toml`):
 
 ```toml
 [features]
-codex_hooks = true
+hooks = true
 ```
 
 #### 2. Install Phasegate hooks
@@ -148,7 +148,7 @@ Codex documents that the newer `unified_exec` mechanism has incomplete intercept
 
 ### Hooks don't seem to run
 
-- Verify `codex_hooks = true` is set in `config.toml`
+- Verify `hooks = true` is set in `config.toml`
 - Verify `.codex/hooks.json` is in the project root or `~/.codex/`
 - Run `codex --version` to ensure you're on a version that supports hooks
 

package/docs/guide/installation.md

@@ -43,7 +43,7 @@ This deploys 30 skills to `skills/`, creates the agent-facing skill links (for e
 For Codex, project initialization stops at the project boundary. After `npx phasegate init --agent codex`, enable the Codex CLI feature flag manually:
 
 ```bash
-codex features enable codex_hooks
+codex features enable hooks
 ```
 
 ### Existing Projects

package/docs/guide/quick-vs-full-mode.md

@@ -62,6 +62,15 @@ Even when you launch `/quick-implementor`, the harness re-checks whether the in-
 
 Introduced in v0.63.0 (ISSUE-006 Story A — config-driven flags + `check-change-category` CLI) and wired into the hook in v0.64.0 (Story B). Each flag can be flipped to `false` only when a project intentionally accepts the risk of merging that category of change without the design ceremony — e.g. early-stage prototypes where new domain files churn freely.
 
+When the escalation is intentional, do not widen `quickMode.allowedCategories` by hand. Start a hook-visible Full Mode session for the approved Unit/WI before the implementation step, then end it after completion:
+
+```bash
+npx phasegate session begin --mode full --unit <unit> --work-item <WI-XXX> --reason "story-implementor Phase 2" --duration 1h
+npx phasegate session end --work-item <WI-XXX>
+```
+
+The PreToolUse hook validates `.phasegate/session.json` by TTL, unit, and dominant category. The `/story-implementor` skill is still the design/TDD guide; the session marker is the authorization the hook can actually observe. <!-- @work-item-id WI-206 -->
+
 ### Dry-running the classifier
 
 Use `check-change-category` to evaluate an arbitrary file list without actually starting an implementation:

package/docs/guide/recipes.md

@@ -29,7 +29,7 @@ Use this when a repository already has meaningful history or custom automation.
 ```bash
 npx phasegate setup:agent --intent agent-hooks --agent both --with-husky --dry-run --json
 npx phasegate install --agent both --apply
-codex features enable codex_hooks
+codex features enable hooks
 npx phasegate doctor --json
 ```
 

package/docs/guide/setup-artifacts.md

@@ -15,7 +15,7 @@ PhaseGate setup is more than `phasegate.config.json`. A healthy installation is
 | 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 |
 | Legacy artifact | `.harness-hooks.yml`, old Fuse hook files, `.harness/session-state.json`, `.harness/context-priority.json`, `.harness/reports` fallback | Compatibility only | Not required for current install lifecycle unless a project intentionally keeps an archived integration |
-| User-level setting | Codex CLI `codex_hooks` feature flag | User machine | Must be enabled manually with `codex features enable codex_hooks`; project commands do not modify it |
+| User-level setting | Codex CLI `hooks` feature flag | User machine | Must be enabled manually with `codex features enable hooks`; project commands do not modify it |
 
 ## Managed Targets
 

package/docs/guide/troubleshooting.md

@@ -42,7 +42,7 @@ Check both project and user-level state:
 
 ```bash
 npx phasegate doctor --json
-codex features enable codex_hooks
+codex features enable hooks
 npx phasegate phasegate:status --json
 ```
 

package/docs/templates/agent-context/AGENTS.md.template.md

@@ -32,7 +32,7 @@
 
 ### Codex Notes
 
-- Enable native hook execution with `codex features enable codex_hooks` when Codex hooks are installed.
+- Enable native hook execution with `codex features enable hooks` when Codex hooks are installed.
 - Keep local-only Codex settings outside repository-managed targets unless PhaseGate explicitly reports them as managed.
 <!-- phasegate:managed-section:end -->
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "phasegate",
-  "version": "0.160.11",
+  "version": "0.160.12",
   "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

@@ -30,4 +30,9 @@ export interface HandlePreToolUseOutput {
   quickModeAllowed?: {
     dominantCategory?: string;
   };
+  fullModeSessionAllowed?: {
+    workItemId?: string;
+    unit?: string;
+    expiresAt?: string;
+  };
 }

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

@@ -3,6 +3,8 @@
  * @unit agent-integration
  * @story H11-02
  * @work-item-id WI-201
+ * @work-item-id WI-202 / WI-204
+ * @work-item-id WI-206
  *
  * HandlePreToolUseUseCase
  * PreToolUse Hook処理のオーケストレーション
@@ -14,6 +16,10 @@ import type {
 } from "../../domain/ports/baseline-grandfather-query-port.js";
 import type { ConfigQueryPort } from "../../domain/ports/config-query-port.js";
 import type { ErrorGuidance, ErrorGuidanceQueryPort } from "../../domain/ports/error-guidance-query-port.js";
+import type {
+  FullModeSessionQueryPort,
+  FullModeSessionQueryResult,
+} from "../../domain/ports/full-mode-session-query-port.js";
 import type { FullModeRequirementQueryPort } from "../../domain/ports/full-mode-requirement-query-port.js";
 import type { PhaseGateQueryPort } from "../../domain/ports/phase-gate-query-port.js";
 import type { StoryReflectionQueryPort } from "../../domain/ports/story-reflection-query-port.js";
@@ -31,6 +37,7 @@ export interface HandlePreToolUseUseCasePorts {
   baselineGrandfatherQueryPort?: BaselineGrandfatherQueryPort;
   grandfatherLogger?: (reason: string, targetFilePaths: readonly string[]) => void;
   errorGuidanceQueryPort?: ErrorGuidanceQueryPort;
+  fullModeSessionQueryPort?: FullModeSessionQueryPort;
 }
 
 export class HandlePreToolUseInputValidationError extends Error {
@@ -56,6 +63,7 @@ export class HandlePreToolUseUseCase {
   private readonly fullModeRequirementQueryPort?: FullModeRequirementQueryPort;
   private readonly baselineGrandfatherQueryPort?: BaselineGrandfatherQueryPort;
   private readonly errorGuidanceQueryPort?: ErrorGuidanceQueryPort;
+  private readonly fullModeSessionQueryPort?: FullModeSessionQueryPort;
   private readonly grandfatherLogger: (reason: string, targetFilePaths: readonly string[]) => void;
 
   constructor(ports: HandlePreToolUseUseCasePorts) {
@@ -65,6 +73,7 @@ export class HandlePreToolUseUseCase {
     this.fullModeRequirementQueryPort = ports.fullModeRequirementQueryPort;
     this.baselineGrandfatherQueryPort = ports.baselineGrandfatherQueryPort;
     this.errorGuidanceQueryPort = ports.errorGuidanceQueryPort;
+    this.fullModeSessionQueryPort = ports.fullModeSessionQueryPort;
     this.grandfatherLogger =
       ports.grandfatherLogger ??
       ((reason, paths) => process.stderr.write(`[baseline] grandfather skip (${reason}): ${paths.join(", ")}\n`));
@@ -149,12 +158,27 @@ export class HandlePreToolUseUseCase {
           input.targetChanges,
         );
         if (fullModeResult.requiresFullMode) {
+          const unitIdForGuidance = this.deriveUnitIdFromPaths(input.targetFilePaths);
+          const sessionResult = await this.checkFullModeSession(
+            input.targetFilePaths,
+            unitIdForGuidance,
+            fullModeResult.dominantCategory,
+          );
+          if (sessionResult.allowed) {
+            return {
+              shouldBlock: false,
+              fullModeSessionAllowed: {
+                workItemId: sessionResult.workItemId,
+                unit: sessionResult.unit,
+                expiresAt: sessionResult.expiresAt,
+              },
+            };
+          }
           // ISSUE-021: 当該Unitの必須設計文書が揃っている場合は full mode block を bypass
           //（hook がスキルコンテキストを参照できない構造的ギャップへの対処）
           const bypassedByDesignDocs = await this.isFullModeBypassedByDesignDocs(input.targetFilePaths);
           if (!bypassedByDesignDocs) {
             const guidance = await this.resolveGuidance("L2-001");
-            const unitIdForGuidance = this.deriveUnitIdFromPaths(input.targetFilePaths);
             return HandlePreToolUseUseCase.buildFullModeRequiredBlockOutput(
               input.targetFilePaths[0],
               fullModeResult,
@@ -227,6 +251,25 @@ export class HandlePreToolUseUseCase {
     }
   }
 
+  private async checkFullModeSession(
+    targetFilePaths: readonly string[],
+    unitId: string | undefined,
+    dominantCategory: string | undefined,
+  ): Promise<FullModeSessionQueryResult> {
+    if (this.fullModeSessionQueryPort === undefined) {
+      return { active: false, allowed: false };
+    }
+    try {
+      return await this.fullModeSessionQueryPort.check({
+        targetFilePaths,
+        unitId,
+        dominantCategory,
+      });
+    } catch {
+      return { active: false, allowed: false };
+    }
+  }
+
   private static buildFullModeRequiredBlockOutput(
     blockedFilePath: string | undefined,
     result: {
@@ -304,6 +347,12 @@ export class HandlePreToolUseUseCase {
     }
     const suggestedSkill = guidance?.suggestedSkill ?? "/story-implementor";
     lines.push(`次のアクション: ${suggestedSkill} スキルを使用して設計フェーズから開始してください。`);
+    if (unitId !== undefined && unitId !== "") {
+      lines.push(
+        `  実装フェーズ開始時: phasegate session begin --mode full --unit ${unitId} --work-item <WI-XXX> --reason "<reason>" --duration 1h`,
+      );
+      lines.push("  実装完了時: phasegate session end --work-item <WI-XXX>");
+    }
     HandlePreToolUseUseCase.appendGuidanceLines(lines, guidance, unitId);
 
     return {

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

@@ -0,0 +1,22 @@
+// @unit agent-integration
+// @layer domain
+// @work-item-id WI-206
+
+export interface FullModeSessionQueryInput {
+  readonly targetFilePaths: readonly string[];
+  readonly unitId?: string;
+  readonly dominantCategory?: string;
+}
+
+export interface FullModeSessionQueryResult {
+  readonly active: boolean;
+  readonly allowed: boolean;
+  readonly reason?: string;
+  readonly workItemId?: string;
+  readonly unit?: string;
+  readonly expiresAt?: string;
+}
+
+export interface FullModeSessionQueryPort {
+  check(input: FullModeSessionQueryInput): Promise<FullModeSessionQueryResult>;
+}

package/scripts/harness/agent-integration/infrastructure/adapters/file-system-full-mode-session-query-adapter.ts

@@ -0,0 +1,119 @@
+// @unit agent-integration
+// @layer infrastructure
+// @work-item-id WI-206
+
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+
+import type {
+  FullModeSessionQueryInput,
+  FullModeSessionQueryPort,
+  FullModeSessionQueryResult,
+} from '../../domain/ports/full-mode-session-query-port.js';
+import type { ConfigQueryPort } from '../../domain/ports/config-query-port.js';
+import { WriteTargetScope } from '../../domain/value-objects/write-target-scope.js';
+
+interface FullModeSessionDocument {
+  readonly mode?: unknown;
+  readonly unit?: unknown;
+  readonly workItemId?: unknown;
+  readonly allowedCategories?: unknown;
+  readonly reason?: unknown;
+  readonly startedAt?: unknown;
+  readonly expiresAt?: unknown;
+}
+
+export class FileSystemFullModeSessionQueryAdapter implements FullModeSessionQueryPort {
+  constructor(
+    private readonly options: {
+      readonly rootDir: string;
+      readonly configQueryPort: ConfigQueryPort;
+      readonly now?: () => Date;
+    },
+  ) {}
+
+  async check(input: FullModeSessionQueryInput): Promise<FullModeSessionQueryResult> {
+    let document: FullModeSessionDocument;
+    try {
+      const raw = await fs.readFile(path.join(this.options.rootDir, '.phasegate', 'session.json'), 'utf8');
+      document = JSON.parse(raw) as FullModeSessionDocument;
+    } catch {
+      return { active: false, allowed: false, reason: 'session marker not found or unreadable' };
+    }
+
+    if (document.mode !== 'full') {
+      return { active: false, allowed: false, reason: 'session mode is not full' };
+    }
+    if (typeof document.unit !== 'string' || document.unit === '') {
+      return { active: true, allowed: false, reason: 'session unit is missing' };
+    }
+    if (typeof document.workItemId !== 'string' || !/^WI-\d+$/.test(document.workItemId)) {
+      return { active: true, allowed: false, reason: 'session work item is invalid' };
+    }
+    if (typeof document.expiresAt !== 'string' || Number.isNaN(Date.parse(document.expiresAt))) {
+      return { active: true, allowed: false, reason: 'session expiry is invalid' };
+    }
+    if ((this.options.now?.() ?? new Date()).getTime() >= Date.parse(document.expiresAt)) {
+      return {
+        active: true,
+        allowed: false,
+        reason: 'session expired',
+        workItemId: document.workItemId,
+        unit: document.unit,
+        expiresAt: document.expiresAt,
+      };
+    }
+    if (!Array.isArray(document.allowedCategories) || document.allowedCategories.some((value) => typeof value !== 'string')) {
+      return { active: true, allowed: false, reason: 'session allowedCategories is invalid' };
+    }
+    if (input.dominantCategory === undefined || !document.allowedCategories.includes(input.dominantCategory)) {
+      return {
+        active: true,
+        allowed: false,
+        reason: `category ${input.dominantCategory ?? '<unknown>'} is not allowed by session`,
+        workItemId: document.workItemId,
+        unit: document.unit,
+        expiresAt: document.expiresAt,
+      };
+    }
+    if (input.unitId === undefined || input.unitId !== document.unit) {
+      return {
+        active: true,
+        allowed: false,
+        reason: `target unit ${input.unitId ?? '<unknown>'} does not match session unit ${document.unit}`,
+        workItemId: document.workItemId,
+        unit: document.unit,
+        expiresAt: document.expiresAt,
+      };
+    }
+    if (!this.allTargetPathsBelongToUnit(input.targetFilePaths, document.unit)) {
+      return {
+        active: true,
+        allowed: false,
+        reason: `one or more target paths are outside session unit ${document.unit}`,
+        workItemId: document.workItemId,
+        unit: document.unit,
+        expiresAt: document.expiresAt,
+      };
+    }
+
+    return {
+      active: true,
+      allowed: true,
+      workItemId: document.workItemId,
+      unit: document.unit,
+      expiresAt: document.expiresAt,
+    };
+  }
+
+  private allTargetPathsBelongToUnit(targetFilePaths: readonly string[], unit: string): boolean {
+    const projectPaths = this.options.configQueryPort.getProjectPaths();
+    for (const targetFilePath of targetFilePaths) {
+      const scope = WriteTargetScope.fromPath(targetFilePath, projectPaths);
+      if (scope?.unitId !== undefined && scope.unitId !== unit) {
+        return false;
+      }
+    }
+    return true;
+  }
+}

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

@@ -1,6 +1,8 @@
 /**
  * @layer presentation
  * @unit agent-integration
+ * @work-item-id WI-202 / WI-204
+ * @work-item-id WI-206
  *
  * PreToolUse Hook Adapter
  * Claude Code の PreToolUse Hook エントリポイント
@@ -15,6 +17,7 @@ import { FileSystemStoryReflectionQueryAdapter } from '../infrastructure/adapter
 import { QuickModeFullModeRequirementAdapter } from '../infrastructure/adapters/quick-mode-full-mode-requirement-adapter.js';
 import { CiGovernanceBaselineGrandfatherAdapter } from '../infrastructure/adapters/ci-governance-baseline-grandfather-adapter.js';
 import { HarnessErrorGuidanceAdapter } from '../infrastructure/adapters/harness-error-guidance-adapter.js';
+import { FileSystemFullModeSessionQueryAdapter } from '../infrastructure/adapters/file-system-full-mode-session-query-adapter.js';
 import { createQuickModeCompositionRoot } from '../../quick-mode/composition-root.js';
 import * as path from 'node:path';
 import * as fs from 'node:fs/promises';
@@ -152,6 +155,10 @@ async function main(): Promise<void> {
     const errorGuidanceQueryPort = new HarnessErrorGuidanceAdapter({
       rootDir: path.dirname(configPath),
     });
+    const fullModeSessionQueryPort = new FileSystemFullModeSessionQueryAdapter({
+      rootDir: path.dirname(configPath),
+      configQueryPort,
+    });
     const useCase = new HandlePreToolUseUseCase({
       configQueryPort,
       phaseGateQueryPort,
@@ -159,6 +166,7 @@ async function main(): Promise<void> {
       fullModeRequirementQueryPort,
       baselineGrandfatherQueryPort,
       errorGuidanceQueryPort,
+      fullModeSessionQueryPort,
     });
 
     const callerSkill = input.caller_skill ?? process.env.PHASEGATE_CALLER_SKILL;
@@ -183,6 +191,12 @@ async function main(): Promise<void> {
       const suffix = cat !== undefined && cat !== '' ? `, category=${cat}` : '';
       process.stderr.write(`phasegate: write allowed (Quick Mode${suffix})\n`);
     }
+    if (output.fullModeSessionAllowed !== undefined) {
+      const session = output.fullModeSessionAllowed;
+      const workItem = session.workItemId !== undefined ? `, workItem=${session.workItemId}` : '';
+      const unit = session.unit !== undefined ? `, unit=${session.unit}` : '';
+      process.stderr.write(`phasegate: write allowed (Full Mode session${workItem}${unit})\n`);
+    }
 
     process.exit(0);
   } catch (error) {

package/scripts/harness/main.ts

@@ -14,6 +14,9 @@
  * @work-item-id WI-197
  * @work-item-id WI-200
  * @work-item-id WI-201
+ * @work-item-id WI-202 / WI-204
+ * @work-item-id WI-205
+ * @work-item-id WI-206
  *
  * Phasegate CLI エントリポイント。
  * 各Unitの Composition Root からハンドラーを取得し、コマンドに応じてディスパッチする。
@@ -27,6 +30,7 @@ import {
   readdir as fsReaddir,
   readlink as fsReadlink,
   rename as fsRename,
+  rm as fsRm,
   writeFile as fsWriteFile,
 } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
@@ -180,6 +184,7 @@ Commands:
   migrate                      Migrate phasegate.config.json (--schema v3, --config <path>)
   migrate work-items           Migrate legacy inception work item directories (--dry-run|--apply)
   work-items:status            Report or apply derived WI frontmatter status (--dry-run|--apply, --id, --fail-on-stale, --json)
+  session begin|end            Manage hook-visible Full Mode sessions
 
   render-errors                Render harness errors (--format human|agent|ci)
   validate-fix                 Validate fix examples (--code <code>)
@@ -223,6 +228,8 @@ Gate semantics:
   ci:check-repetition          Check error repetition (--code <errorCode>, --reset, --json)
   baseline                     Create retrofit baseline snapshot (--dry-run, --force, --paths <glob,glob,...>, --json)
   scaffold-design              Scaffold a design doc (--unit <id>, --phase <logical|domain|uiux|unit-test|it-test>, --dry-run|--apply, --force, --json)
+  session begin                Start a Full Mode session (--mode full, --unit, --work-item, --reason, --duration)
+  session end                  End a Full Mode session (--work-item)
 
   skill:execute-tdd-cycle      Execute TDD cycle (--unit, --story, --desc, --phase RED|GREEN|REFACTOR, --passed)
   skill:check-coverage         Check coverage (--story <storyId>, --json)
@@ -476,6 +483,109 @@ function validateKnownFlags(args: readonly string[], known: readonly string[]):
   return null;
 }
 
+const FULL_MODE_SESSION_ALLOWED_CATEGORIES = Object.freeze([
+  "domain",
+  "application",
+  "infrastructure",
+  "presentation",
+  "config",
+]);
+
+interface FullModeSessionFile {
+  readonly mode: "full";
+  readonly unit: string;
+  readonly workItemId: string;
+  readonly allowedCategories: readonly string[];
+  readonly reason: string;
+  readonly startedAt: string;
+  readonly expiresAt: string;
+}
+
+function parseSessionDurationMs(raw: string | undefined): number {
+  const value = raw ?? "1h";
+  const match = value.match(/^(\d+)(s|m|h)$/);
+  if (match === null) {
+    throw new Error("Invalid --duration. Use values like 30m, 1h, or 3600s.");
+  }
+  const amount = Number(match[1]);
+  if (!Number.isSafeInteger(amount) || amount <= 0) {
+    throw new Error("Invalid --duration. Duration must be a positive integer.");
+  }
+  const unit = match[2];
+  const multiplier = unit === "s" ? 1_000 : unit === "m" ? 60_000 : 3_600_000;
+  return amount * multiplier;
+}
+
+function validateWorkItemId(value: string | undefined): string {
+  if (value === undefined || !/^WI-\d+$/.test(value)) {
+    throw new Error("--work-item must be a WI id such as WI-206.");
+  }
+  return value;
+}
+
+function validateSessionUnit(value: string | undefined): string {
+  if (value === undefined || !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value)) {
+    throw new Error("--unit must be a non-empty unit id.");
+  }
+  return value;
+}
+
+async function readFullModeSession(sessionPath: string): Promise<FullModeSessionFile | null> {
+  try {
+    return JSON.parse(await fsReadFile(sessionPath, "utf8")) as FullModeSessionFile;
+  } catch {
+    return null;
+  }
+}
+
+async function beginFullModeSession(rootDir: string, args: readonly string[]): Promise<FullModeSessionFile> {
+  if ((parseFlag(args, "--mode") ?? "full") !== "full") {
+    throw new Error("--mode must be full.");
+  }
+  const unit = validateSessionUnit(parseFlag(args, "--unit"));
+  const workItemId = validateWorkItemId(parseFlag(args, "--work-item"));
+  const reason = parseFlag(args, "--reason");
+  if (reason === undefined || reason.trim() === "") {
+    throw new Error("--reason is required.");
+  }
+  const startedAt = new Date();
+  const expiresAt = new Date(startedAt.getTime() + parseSessionDurationMs(parseFlag(args, "--duration")));
+  const session: FullModeSessionFile = {
+    mode: "full",
+    unit,
+    workItemId,
+    allowedCategories: FULL_MODE_SESSION_ALLOWED_CATEGORIES,
+    reason,
+    startedAt: startedAt.toISOString(),
+    expiresAt: expiresAt.toISOString(),
+  };
+  const phasegateDir = join(rootDir, ".phasegate");
+  await fsMkdir(phasegateDir, { recursive: true });
+  await fsWriteFile(join(phasegateDir, "session.json"), `${JSON.stringify(session, null, 2)}\n`, "utf8");
+  return session;
+}
+
+async function endFullModeSession(
+  rootDir: string,
+  args: readonly string[],
+): Promise<{ removed: boolean; session: FullModeSessionFile | null }> {
+  const sessionPath = join(rootDir, ".phasegate", "session.json");
+  const session = await readFullModeSession(sessionPath);
+  const requestedWorkItemId = parseFlag(args, "--work-item");
+  if (requestedWorkItemId !== undefined && session?.workItemId !== requestedWorkItemId) {
+    throw new Error(`Active session work item is ${session?.workItemId ?? "<none>"}, not ${requestedWorkItemId}.`);
+  }
+  try {
+    await fsRm(sessionPath);
+    return { removed: true, session };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return { removed: false, session: null };
+    }
+    throw error;
+  }
+}
+
 const SUBCOMMAND_HELP: Record<string, string> = {
   init: `Usage: phasegate init [options]
 
@@ -663,6 +773,22 @@ Options:
   --force                    Overwrite an existing target when applying.
   --json                     Output machine-readable JSON.
   --help, -h                 Show this help`,
+  session: `Usage: phasegate session <begin|end> [options]
+
+Manage hook-visible Full Mode sessions.
+
+Begin options:
+  --mode full                Required session mode.
+  --unit <id>                Unit id allowed by the session.
+  --work-item <WI-XXX>       Work item authorizing the session.
+  --reason <text>            Human-readable reason for audit.
+  --duration <ttl>           TTL such as 30m, 1h, or 3600s. Default: 1h.
+  --json                     Output machine-readable JSON.
+
+End options:
+  --work-item <WI-XXX>       Optional safety check before removing the session.
+  --json                     Output machine-readable JSON.
+  --help, -h                 Show this help`,
   "ci:generate-template": `Usage: phasegate ci:generate-template [options]
 
 Generates a CI template configuration.
@@ -1002,7 +1128,7 @@ function buildSetupCompleteness(input: {
   ];
 
   const externalActions: string[] = [];
-  if (includeCodex) externalActions.push("Run codex features enable codex_hooks if Codex hooks are not enabled for the user.");
+  if (includeCodex) externalActions.push("Run codex features enable hooks if Codex hooks are not enabled for the user.");
   if (input.withCi) externalActions.push("Trigger or inspect the first GitHub Actions PhaseGate workflow run.");
   if (input.intent === "strict") externalActions.push("Confirm team policy accepts strict local and CI enforcement.");
   entries.push({
@@ -1108,7 +1234,7 @@ function buildAgentReadiness(input: {
         "setup:agent will create or refresh the AGENTS.md PhaseGate managed section.",
         "setup:agent will deploy bundled skills for Codex.",
       ],
-      nextAction: "Run setup:agent --agent codex --apply, then enable codex_hooks at user level if needed.",
+      nextAction: "Run setup:agent --agent codex --apply, then enable hooks at user level if needed.",
       risk: "Codex user-level hook feature enablement remains a manual external check.",
     }),
     setupReadinessEntry({
@@ -1338,8 +1464,8 @@ async function buildConfigChangePlan(rootDir: string, intent: ConfigChangeIntent
     "codex-hooks": {
       targets: [".codex/hooks.json", "AGENTS.md", ".codex/skills"],
       managedTargets: [".codex/hooks.json", "AGENTS.md", ".codex/skills"],
-      externalActions: [{ id: "codex-hooks-feature", label: "Enable Codex user-level hooks feature.", command: "codex features enable codex_hooks", blocking: true }],
-      commands: ["phasegate install --agent codex --apply", "codex features enable codex_hooks"],
+      externalActions: [{ id: "codex-hooks-feature", label: "Enable Codex user-level hooks feature.", command: "codex features enable hooks", blocking: true }],
+      commands: ["phasegate install --agent codex --apply", "codex features enable hooks"],
       validations: ["phasegate doctor --json", "phasegate phasegate:status --json"],
       risks: ["Codex apply_patch writes still require the pre-commit backstop for full coverage."],
     },
@@ -1830,7 +1956,7 @@ async function main(): Promise<void> {
           console.log("  3. Edit .claude/scripts/hook-config.json to set target directories");
         }
         if (deployCodex) {
-          console.log(`  ${deployClaude ? "4" : "3"}. Enable Codex hooks: codex features enable codex_hooks`);
+          console.log(`  ${deployClaude ? "4" : "3"}. Enable Codex hooks: codex features enable hooks`);
           console.log(
             `  ${deployClaude ? "5" : "4"}. (Recommended) Install pre-commit backstop: rerun with --with-husky or set up husky manually`,
           );
@@ -2081,6 +2207,61 @@ async function main(): Promise<void> {
         break;
       }
 
+      case "session": {
+        const subcommand = args[1];
+        const knownFlags = ["--mode", "--unit", "--work-item", "--reason", "--duration", "--json"];
+        const flagError = validateKnownFlags(args.slice(2), knownFlags);
+        if (flagError) {
+          console.error(flagError);
+          process.exit(2);
+        }
+        if (subcommand === "begin") {
+          try {
+            const session = await beginFullModeSession(rootDir, args);
+            if (json) {
+              console.log(JSON.stringify({ ok: true, sessionPath: ".phasegate/session.json", session }, null, 2));
+            } else {
+              console.log(
+                `Full Mode session started: ${session.workItemId} unit=${session.unit} expiresAt=${session.expiresAt}`,
+              );
+            }
+            process.exit(0);
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (json) {
+              console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+            } else {
+              console.error(`Error: ${message}`);
+            }
+            process.exit(2);
+          }
+        }
+        if (subcommand === "end") {
+          try {
+            const result = await endFullModeSession(rootDir, args);
+            if (json) {
+              console.log(JSON.stringify({ ok: true, ...result }, null, 2));
+            } else if (result.removed) {
+              console.log(`Full Mode session ended: ${result.session?.workItemId ?? "<unknown>"}`);
+            } else {
+              console.log("No Full Mode session was active.");
+            }
+            process.exit(0);
+          } catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (json) {
+              console.log(JSON.stringify({ ok: false, error: message }, null, 2));
+            } else {
+              console.error(`Error: ${message}`);
+            }
+            process.exit(2);
+          }
+        }
+        console.error("Error: session subcommand must be begin or end.");
+        process.exit(2);
+        break;
+      }
+
       case "uninstall": {
         const KNOWN_UNINSTALL_FLAGS = ["--dry-run", "--apply", "--force", "--json"];
         const flagError = validateKnownFlags(args, KNOWN_UNINSTALL_FLAGS);

package/scripts/harness/quick-mode/domain/services/quick-mode-judgment-engine.ts

@@ -1,6 +1,7 @@
 /**
  * @layer domain
  * @unit quick-mode
+ * @work-item-id WI-204
  *
  * ChangedFile[]をChangeClassificationに変換し、3拒否ルールを評価してQuickModeEligibilityを返すドメインサービス
  */

package/scripts/harness/setup/skill-deployer.ts

@@ -3,6 +3,7 @@
 // @work-item-id WI-086 / WI-087
 // @work-item-id WI-127
 // @work-item-id WI-184
+// @work-item-id WI-202
 // Note: import.meta.url を使わず、呼び出し元 (main.ts) がパスを解決して渡す設計。
 
 import { promises as fs } from "node:fs";

package/skills/phasegate-config-doctor/SKILL.md

@@ -131,7 +131,7 @@ product-architect で Unit を作り、いくつかの logical_design を書い
 - `repairHint` がある mechanical finding → 原則として hint のコマンドを優先し、実行前に対象ファイルと manifest の差分を確認
 - manifest parse error → `.phasegate/manifest.json` を手で修復する前に backup / uninstall / reinstall の選択肢を提示
 - reconcile / uninstall が refuse → user modified managed target として扱い、`--force` のリスクと backup path を説明して承認を取る
-- Codex の `codex_hooks` feature flag は user-level setting。project-local `install` では変更されないため、必要なら `codex features enable codex_hooks` を案内
+- Codex の `hooks` feature flag は user-level setting。project-local `install` では変更されないため、必要なら `codex features enable hooks` を案内。`codex_hooks` は legacy alias として扱う。<!-- @work-item-id WI-205 -->
 - Codex native `apply_patch` bypass は hook で完全捕捉できない。`.husky/pre-commit` の `phasegate pre-commit` が backstop になるため、Husky 配線を診断対象に含める
 - 初回 setup / retrofit / CI-only / agent-hooks の判断が曖昧な場合は `npx phasegate setup:agent --dry-run --json` を先に使い、検出済み状態、質問、変更案、rollback、validation を根拠として提案する。<!-- @work-item-id WI-172 -->
 - Claude Code setup 相談では `npx phasegate setup:agent --agent claude --dry-run --json` を先に使い、`plan.agentReadiness` の `claude` / `shared` が `configured` なら setup 修復ではなく WI 起票、inception 計画、product reflection、validation の順で作業開始を案内する。`setup:agent --apply --json` または `install --apply --json` の structured `error` がある場合は、`target`, `operation`, `code`, `likelyCause`, `recovery`, `partialChanges` を読み、`.claude` が file として存在する path conflict、sandbox/permission denial、PhaseGate managed target hash mismatch を区別して説明する。<!-- @work-item-id WI-177 -->

package/skills/story-implementor/SKILL.md

@@ -263,6 +263,23 @@ TDD実装の順序・スコープ・不明点を整理し、人間の承認を
 ### 開始条件
 - 人間がPhase 1の計画を承認した
 - QAセクションの全[Question]に[Answer]が記入されている（QAがある場合）
+- Quick Mode の許可カテゴリ外（domain/application/infrastructure/presentation/config）を変更する場合、実装前に hook-visible Full Mode session を開始している
+
+### Full Mode session
+
+Quick Mode の許可カテゴリ外を変更する Phase 2 では、手作業で `quickMode.allowedCategories` を広げない。以下の CLI で対象 Unit / WI に限定した一時 session を作成し、実装完了時に終了する。
+
+```bash
+phasegate session begin --mode full --unit <unit> --work-item <WI-XXX> --reason "story-implementor Phase 2" --duration 1h
+```
+
+実装完了または中断時:
+
+```bash
+phasegate session end --work-item <WI-XXX>
+```
+
+PreToolUse hook は `.phasegate/session.json` の TTL・unit・カテゴリを検証する。スキル名だけでは hook 通過の根拠にならない。
 
 ### ワークフロー