diff --git a/packages/cli/src/config/settingsSchema.ts b/packages/cli/src/config/settingsSchema.ts
index 3ee6575f3..4e6fd7c1a 100644
--- a/packages/cli/src/config/settingsSchema.ts
+++ b/packages/cli/src/config/settingsSchema.ts
@@ -1408,7 +1408,7 @@ const SETTINGS_SCHEMA = {
     type: 'boolean',
     label: 'Disable All Hooks',
     category: 'Advanced',
-    requiresRestart: true,
+    requiresRestart: true, // Future enhancement: consider supporting mid-session toggle for better UX
     default: false,
     description:
       'Temporarily disable all hooks without deleting configurations. Default is false (hooks enabled).',
diff --git a/packages/cli/src/ui/components/hooks/HooksDisabledStep.tsx b/packages/cli/src/ui/components/hooks/HooksDisabledStep.tsx
index 84045f83f..fb0e0695e 100644
--- a/packages/cli/src/ui/components/hooks/HooksDisabledStep.tsx
+++ b/packages/cli/src/ui/components/hooks/HooksDisabledStep.tsx
@@ -15,7 +15,9 @@ interface HooksDisabledStepProps {
 export function HooksDisabledStep({
   configuredHooksCount,
 }: HooksDisabledStepProps): React.JSX.Element {
-  // Get the correct plural/singular form
+  // Note: The i18n t() function expects string parameters (Record<string, string>).
+  // Pluralization is handled manually by selecting the appropriate translation key
+  // based on the count, since the i18n system doesn't support ICU MessageFormat.
   const hooksText =
     configuredHooksCount === 1
       ? t('{{count}} configured hook', { count: String(configuredHooksCount) })
@@ -49,6 +51,9 @@ export function HooksDisabledStep({
         <Text bold color={theme.text.primary}>
           {t('When hooks are disabled:')}
         </Text>
+        {/* Note: Using middle dot (·) as bullet character. This is consistent with
+            other CLI components. If a design system evolves, consider extracting
+            to a shared constant or using a BulletList component. */}
         <Box>
           <Text color={theme.text.secondary}>
             {`  · ${t('No hook commands will execute')}`}
diff --git a/packages/cli/src/ui/components/hooks/HooksManagementDialog.tsx b/packages/cli/src/ui/components/hooks/HooksManagementDialog.tsx
index ef1909ab6..837d116e9 100644
--- a/packages/cli/src/ui/components/hooks/HooksManagementDialog.tsx
+++ b/packages/cli/src/ui/components/hooks/HooksManagementDialog.tsx
@@ -113,6 +113,10 @@ export function HooksManagementDialog({
   const boxWidth = width - 4;
 
   // Check if hooks are disabled
+  // Note: This value is captured at dialog open time. If disableAllHooks
+  // changes while the dialog is open (e.g., via settings.json edit),
+  // the dialog will not react to the change until it's closed and reopened.
+  // This is intentional - the dialog represents a snapshot of the current state.
   const disableAllHooks = config?.getDisableAllHooks() ?? false;
 
   const [navigationStack, setNavigationStack] = useState<string[]>([
diff --git a/packages/cli/src/ui/components/hooks/constants.ts b/packages/cli/src/ui/components/hooks/constants.ts
index d0d1bd751..2a5b1011f 100644
--- a/packages/cli/src/ui/components/hooks/constants.ts
+++ b/packages/cli/src/ui/components/hooks/constants.ts
@@ -185,7 +185,10 @@ export function getTranslatedSourceDisplayMap(): Record<
 
 /**
  * List of hook events to display in the UI
- * Automatically synced with HookEventName enum from core
+ * Automatically synced with HookEventName enum from core.
+ * Note: Order follows the enum definition order. If UI presentation order
+ * needs to be different (e.g., grouped by lifecycle phase), consider using
+ * an explicit sorted array instead. Current enum order is acceptable for display.
  */
 export const DISPLAY_HOOK_EVENTS: HookEventName[] =
   Object.values(HookEventName);
diff --git a/packages/core/src/config/config.ts b/packages/core/src/config/config.ts
index 68e609bbd..d11671af0 100644
--- a/packages/core/src/config/config.ts
+++ b/packages/core/src/config/config.ts
@@ -418,7 +418,12 @@ export interface ConfigParameters {
   modelProvidersConfig?: ModelProvidersConfig;
   /** Multi-agent collaboration settings (Arena, Team, Swarm) */
   agents?: AgentsCollabSettings;
-  /** Disable all hooks (default: false, hooks enabled) */
+  /**
+   * Disable all hooks (default: false, hooks enabled).
+   * Migration note: This replaces the deprecated hooksConfig.enabled setting.
+   * Users with old settings.json containing hooksConfig.enabled should migrate
+   * to use disableAllHooks instead (note: inverted logic - enabled:true → disableAllHooks:false).
+   */
   disableAllHooks?: boolean;
   /** Hooks configuration from settings */
   hooks?: Record<string, unknown>;