@foundation0/git 1.3.1 → 1.3.2

package/mcp/src/server.ts

@@ -1,9 +1,9 @@
-import { createGitServiceApi } from '@foundation0/git'
-import type {
-  GitServiceApi,
-  GitServiceApiExecutionResult,
-  GitServiceApiFactoryOptions,
-  GitServiceApiMethod,
+import { callIssueDependenciesApi, createGitServiceApi, extractDependencyIssueNumbers } from '@foundation0/git'
+import type {
+  GitServiceApi,
+  GitServiceApiExecutionResult,
+  GitServiceApiFactoryOptions,
+  GitServiceApiMethod,
 } from '@foundation0/git'
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
@@ -16,9 +16,16 @@ type ToolInvocationPayload = {
   [key: string]: unknown
 }
 
-type McpToolOutputFormat = 'terse' | 'debug'
-
-type McpFieldSelection = string[]
+type McpToolOutputFormat = 'terse' | 'debug'
+
+type McpFieldSelection = string[]
+
+type McpCallControls = {
+  format: McpToolOutputFormat | null
+  validateOnly: boolean
+  fields: McpFieldSelection | null
+  full: boolean
+}
 
 type BatchToolCall = {
   tool: string
@@ -161,28 +168,31 @@ const parseFieldSelection = (value: unknown): McpFieldSelection | null => {
   return null
 }
 
-const extractMcpControls = (
-  payload: unknown,
-): { format: McpToolOutputFormat | null; validateOnly: boolean; fields: McpFieldSelection | null } => {
-  const normalized = normalizeArgumentPayload(payload)
-  if (!isRecord(normalized)) {
-    return { format: null, validateOnly: false, fields: null }
-  }
-
-  const topLevelFormat = parseOutputFormat(normalized.format)
-  const topLevelValidateOnly = parseBoolean(normalized.validateOnly)
-  const topLevelFields = parseFieldSelection(normalized.fields)
-  const optionsFormat = parseOutputFormat(pickRecord(normalized.options).format)
-  const optionsValidateOnly = parseBoolean(pickRecord(normalized.options).validateOnly)
-  const optionsFields = parseFieldSelection(pickRecord(normalized.options).fields)
-
-  // Support either { format:"debug" } or { options:{ format:"debug" } }.
-  return {
-    format: pickFirst(topLevelFormat, optionsFormat),
-    validateOnly: Boolean(pickFirst(topLevelValidateOnly, optionsValidateOnly)),
-    fields: pickFirst(topLevelFields, optionsFields),
-  }
-}
+const extractMcpControls = (
+  payload: unknown,
+): McpCallControls => {
+  const normalized = normalizeArgumentPayload(payload)
+  if (!isRecord(normalized)) {
+    return { format: null, validateOnly: false, fields: null, full: false }
+  }
+
+  const topLevelFormat = parseOutputFormat(normalized.format)
+  const topLevelValidateOnly = parseBoolean(normalized.validateOnly)
+  const topLevelFields = parseFieldSelection(normalized.fields)
+  const topLevelFull = parseBoolean(normalized.full)
+  const optionsFormat = parseOutputFormat(pickRecord(normalized.options).format)
+  const optionsValidateOnly = parseBoolean(pickRecord(normalized.options).validateOnly)
+  const optionsFields = parseFieldSelection(pickRecord(normalized.options).fields)
+  const optionsFull = parseBoolean(pickRecord(normalized.options).full)
+
+  // Support either { format:"debug" } or { options:{ format:"debug" } }.
+  return {
+    format: pickFirst(topLevelFormat, optionsFormat),
+    validateOnly: Boolean(pickFirst(topLevelValidateOnly, optionsValidateOnly)),
+    fields: pickFirst(topLevelFields, optionsFields),
+    full: Boolean(pickFirst(topLevelFull, optionsFull)),
+  }
+}
 
 type McpTerseOk = {
   ok: true
@@ -282,23 +292,298 @@ const buildErrorMessage = (status: number | undefined, body: unknown): string =>
   if (typeof status === 'number') {
     return `HTTP ${status}`
   }
+
+  return 'Request failed'
+}
+
+const normalizeGiteaApiBase = (host: string): string => {
+  const trimmed = host.trim().replace(/\/$/, '')
+  return trimmed.endsWith('/api/v1') ? trimmed : `${trimmed}/api/v1`
+}
+
+const safeStringify = (value: unknown): string => {
+  try {
+    return JSON.stringify(value)
+  } catch {
+    return ''
+  }
+}
+
+const blockingIssueMessagePattern = /close all issues blocking this pull request|issues blocking this pull request|blocking this pull request/i
+
+const isBlockingIssueMessage = (status: number | undefined, body: unknown): boolean => {
+  const message = buildErrorMessage(status, body)
+  if (blockingIssueMessagePattern.test(message)) {
+    return true
+  }
+
+  const bodyText = typeof body === 'string' ? body : safeStringify(body)
+  return blockingIssueMessagePattern.test(bodyText)
+}
+
+type MergeFailureClassification = {
+  code: string
+  message: string
+  retryable: boolean
+  blockedByIssues: boolean
+}
+
+const classifyMergeFailure = (status: number | undefined, body: unknown): MergeFailureClassification => {
+  const message = buildErrorMessage(status, body)
+  const blockedByIssues = isBlockingIssueMessage(status, body)
+  const retryable =
+    !blockedByIssues &&
+    (status === 429 || (typeof status === 'number' && status >= 500) || /try again later/i.test(message))
+
+  return {
+    code: blockedByIssues ? 'PR_BLOCKED_BY_ISSUES' : 'MERGE_FAILED',
+    message,
+    retryable,
+    blockedByIssues,
+  }
+}
+
+const inferHeadContainedFromCompareBody = (body: unknown): boolean | null => {
+  if (!isRecord(body)) {
+    return null
+  }
+
+  const totalCommits = Number((body as Record<string, unknown>).total_commits)
+  if (Number.isFinite(totalCommits)) {
+    return totalCommits === 0
+  }
+
+  const commits = (body as Record<string, unknown>).commits
+  if (Array.isArray(commits)) {
+    return commits.length === 0
+  }
+
+  return null
+}
 
-  return 'Request failed'
-}
-
-const toMcpEnvelope = (
-  result: GitServiceApiExecutionResult,
-  format: McpToolOutputFormat,
-): { isError: boolean; envelope: McpTerseOk | McpTerseErr } => {
-  const sanitized = redactSecretsForMcpOutput(result)
-
-  if (result.ok && result.status < 400) {
-    const envelope: McpTerseOk = {
-      ok: true,
-      data: result.body,
-      meta: {
-        status: result.status,
-      },
+const isNonEmptyString = (value: unknown): boolean => typeof value === 'string' && value.trim().length > 0
+
+const isEmptyObject = (value: unknown): boolean => isRecord(value) && Object.keys(value).length === 0
+
+const isEffectivelyEmpty = (value: unknown): boolean => {
+  if (value === null || value === undefined) return true
+  if (typeof value === 'string') return value.trim().length === 0
+  if (Array.isArray(value)) return value.length === 0
+  if (isEmptyObject(value)) return true
+  return false
+}
+
+const hasKey = (value: Record<string, unknown>, key: string): boolean =>
+  Object.prototype.hasOwnProperty.call(value, key)
+
+const isLikelyUserRecord = (value: Record<string, unknown>): boolean =>
+  (hasKey(value, 'login') || hasKey(value, 'username')) &&
+  (hasKey(value, 'avatar_url') || hasKey(value, 'html_url') || hasKey(value, 'is_admin'))
+
+const isLikelyRepoRecord = (value: Record<string, unknown>): boolean =>
+  (hasKey(value, 'full_name') || hasKey(value, 'default_branch')) &&
+  (hasKey(value, 'private') || hasKey(value, 'clone_url') || hasKey(value, 'ssh_url'))
+
+const isLikelyLabelRecord = (value: Record<string, unknown>): boolean =>
+  hasKey(value, 'name') && hasKey(value, 'color') && (hasKey(value, 'id') || hasKey(value, 'description'))
+
+const isLikelyMilestoneRecord = (value: Record<string, unknown>): boolean =>
+  hasKey(value, 'title') && hasKey(value, 'state') && (hasKey(value, 'due_on') || hasKey(value, 'closed_at'))
+
+const isLikelyBranchRefRecord = (value: Record<string, unknown>): boolean =>
+  hasKey(value, 'ref') && hasKey(value, 'sha') && hasKey(value, 'repo')
+
+const isLikelyPullRequestRecord = (value: Record<string, unknown>): boolean =>
+  hasKey(value, 'number') && (hasKey(value, 'head') || hasKey(value, 'base') || hasKey(value, 'merged'))
+
+const isLikelyIssueRecord = (value: Record<string, unknown>): boolean =>
+  hasKey(value, 'number') && hasKey(value, 'title') && hasKey(value, 'state') && !isLikelyPullRequestRecord(value)
+
+const isLikelyReviewRecord = (value: Record<string, unknown>): boolean =>
+  (hasKey(value, 'commit_id') && hasKey(value, 'state') && hasKey(value, 'user')) || hasKey(value, 'submitted_at')
+
+const compactRecordByKeys = (
+  value: Record<string, unknown>,
+  keys: string[],
+  compact: (entry: unknown, keyHint?: string) => unknown,
+): Record<string, unknown> => {
+  const next: Record<string, unknown> = {}
+
+  for (const key of keys) {
+    if (!hasKey(value, key)) continue
+    const compacted = compact(value[key], key)
+    if (isEffectivelyEmpty(compacted)) continue
+    next[key] = compacted
+  }
+
+  return next
+}
+
+const compactUserRecord = (value: Record<string, unknown>, compact: (entry: unknown, keyHint?: string) => unknown): Record<string, unknown> => {
+  const next: Record<string, unknown> = {}
+  const id = value.id
+  const login = toTrimmedString(pickFirst(value.login, value.username))
+  const fullName = toTrimmedString(value.full_name)
+  const htmlUrl = toTrimmedString(value.html_url)
+
+  if (id !== undefined && id !== null) next.id = id
+  if (login) next.login = login
+  if (fullName) next.full_name = fullName
+  if (htmlUrl) next.html_url = htmlUrl
+
+  if (Object.keys(next).length > 0) return next
+  return compactRecordByKeys(value, ['login', 'username', 'id'], compact)
+}
+
+const compactRepoRecord = (value: Record<string, unknown>, compact: (entry: unknown, keyHint?: string) => unknown): Record<string, unknown> =>
+  compactRecordByKeys(value, ['id', 'name', 'full_name', 'private', 'default_branch', 'archived', 'html_url'], compact)
+
+const compactLabelRecord = (value: Record<string, unknown>, compact: (entry: unknown, keyHint?: string) => unknown): Record<string, unknown> =>
+  compactRecordByKeys(value, ['id', 'name', 'color', 'description'], compact)
+
+const compactMilestoneRecord = (value: Record<string, unknown>, compact: (entry: unknown, keyHint?: string) => unknown): Record<string, unknown> =>
+  compactRecordByKeys(value, ['id', 'title', 'state', 'due_on', 'closed_at'], compact)
+
+const compactBranchRefRecord = (value: Record<string, unknown>, compact: (entry: unknown, keyHint?: string) => unknown): Record<string, unknown> =>
+  compactRecordByKeys(value, ['label', 'ref', 'sha', 'repo'], compact)
+
+const compactPullRequestRecord = (value: Record<string, unknown>, compact: (entry: unknown, keyHint?: string) => unknown): Record<string, unknown> =>
+  compactRecordByKeys(
+    value,
+    [
+      'id',
+      'number',
+      'title',
+      'body',
+      'state',
+      'draft',
+      'is_locked',
+      'comments',
+      'additions',
+      'deletions',
+      'changed_files',
+      'mergeable',
+      'merged',
+      'merged_at',
+      'merge_commit_sha',
+      'allow_maintainer_edit',
+      'html_url',
+      'user',
+      'labels',
+      'milestone',
+      'assignee',
+      'assignees',
+      'requested_reviewers',
+      'base',
+      'head',
+      'merge_base',
+      'created_at',
+      'updated_at',
+      'closed_at',
+    ],
+    compact,
+  )
+
+const compactIssueRecord = (value: Record<string, unknown>, compact: (entry: unknown, keyHint?: string) => unknown): Record<string, unknown> =>
+  compactRecordByKeys(
+    value,
+    [
+      'id',
+      'number',
+      'title',
+      'body',
+      'state',
+      'user',
+      'labels',
+      'milestone',
+      'assignee',
+      'assignees',
+      'comments',
+      'html_url',
+      'created_at',
+      'updated_at',
+      'closed_at',
+    ],
+    compact,
+  )
+
+const compactReviewRecord = (value: Record<string, unknown>, compact: (entry: unknown, keyHint?: string) => unknown): Record<string, unknown> =>
+  compactRecordByKeys(value, ['id', 'state', 'body', 'user', 'commit_id', 'submitted_at', 'html_url'], compact)
+
+const compactResponseDataForDefaultMode = (value: unknown, keyHint?: string): unknown => {
+  const compact = compactResponseDataForDefaultMode
+
+  if (Array.isArray(value)) {
+    const next = value
+      .map((entry) => compact(entry, keyHint))
+      .filter((entry) => !isEffectivelyEmpty(entry))
+    return next
+  }
+
+  if (!isRecord(value)) {
+    if (typeof value === 'string') {
+      const trimmed = value.trim()
+      return trimmed.length > 0 ? value : undefined
+    }
+    return value
+  }
+
+  if (isLikelyPullRequestRecord(value)) return compactPullRequestRecord(value, compact)
+  if (isLikelyIssueRecord(value)) return compactIssueRecord(value, compact)
+  if (isLikelyReviewRecord(value)) return compactReviewRecord(value, compact)
+  if (isLikelyBranchRefRecord(value)) return compactBranchRefRecord(value, compact)
+  if (isLikelyMilestoneRecord(value)) return compactMilestoneRecord(value, compact)
+  if (isLikelyLabelRecord(value)) return compactLabelRecord(value, compact)
+  if (isLikelyRepoRecord(value)) return compactRepoRecord(value, compact)
+  if (isLikelyUserRecord(value)) return compactUserRecord(value, compact)
+
+  if (keyHint === 'user' || keyHint === 'owner' || keyHint === 'assignee' || keyHint === 'merged_by') {
+    return compactUserRecord(value, compact)
+  }
+  if (keyHint === 'repo') {
+    return compactRepoRecord(value, compact)
+  }
+  if (keyHint === 'base' || keyHint === 'head') {
+    return compactBranchRefRecord(value, compact)
+  }
+  if (keyHint === 'milestone') {
+    return compactMilestoneRecord(value, compact)
+  }
+  if (keyHint === 'label') {
+    return compactLabelRecord(value, compact)
+  }
+
+  const next: Record<string, unknown> = {}
+  const hasHtmlUrl = isNonEmptyString(value.html_url)
+
+  for (const [key, entryValue] of Object.entries(value)) {
+    if (key === 'url' && hasHtmlUrl) {
+      continue
+    }
+
+    const compacted = compact(entryValue, key)
+    if (isEffectivelyEmpty(compacted)) continue
+    next[key] = compacted
+  }
+
+  return next
+}
+
+const toMcpEnvelope = (
+  result: GitServiceApiExecutionResult,
+  format: McpToolOutputFormat,
+  full: boolean,
+): { isError: boolean; envelope: McpTerseOk | McpTerseErr } => {
+  const sanitized = redactSecretsForMcpOutput(result)
+  const body = full ? result.body : compactResponseDataForDefaultMode(result.body)
+
+  if (result.ok && result.status < 400) {
+    const envelope: McpTerseOk = {
+      ok: true,
+      data: body,
+      meta: {
+        status: result.status,
+      },
       ...(format === 'debug' ? { debug: sanitized } : {}),
     }
 
@@ -309,16 +594,16 @@ const toMcpEnvelope = (
   const message = buildErrorMessage(status, result.body)
   const retryable = status >= 500 || status === 429 || /try again later/i.test(message)
 
-  const envelope: McpTerseErr = {
-    ok: false,
-    error: {
-      code: httpErrorCodeForStatus(status),
-      status,
-      message,
-      details: result.body,
-      retryable,
-    },
-    meta: {
+  const envelope: McpTerseErr = {
+    ok: false,
+    error: {
+      code: httpErrorCodeForStatus(status),
+      status,
+      message,
+      details: body,
+      retryable,
+    },
+    meta: {
       status,
     },
     ...(format === 'debug' ? { debug: sanitized } : {}),
@@ -387,7 +672,7 @@ const normalizePayload = (payload: unknown): { args: string[]; options: Record<s
   }
 }
 
-const OMITTED_OPTION_KEYS = new Set(['format', 'fields', 'validateOnly'])
+const OMITTED_OPTION_KEYS = new Set(['format', 'fields', 'validateOnly', 'full'])
 
 const stripMcpOnlyOptions = (options: Record<string, unknown>): Record<string, unknown> => {
   const next: Record<string, unknown> = {}
@@ -610,15 +895,19 @@ const buildGenericToolSchema = (): Record<string, unknown> => ({
       additionalProperties: true,
       description: 'Method options (query/headers/body payload). Extra top-level keys are merged into options.',
     },
-    validateOnly: {
-      type: 'boolean',
-      description:
-        'If true, do not execute the underlying HTTP request. Returns the normalized call payload (args/options) that would be sent.',
-    },
-    fields: {
-      description:
-        'Optional field selection for the response body to reduce token usage. Accepts a string[] or a comma-separated string of dot-paths.',
-      anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
+    validateOnly: {
+      type: 'boolean',
+      description:
+        'If true, do not execute the underlying HTTP request. Returns the normalized call payload (args/options) that would be sent.',
+    },
+    full: {
+      type: 'boolean',
+      description: 'If true, return the unfiltered upstream response body.',
+    },
+    fields: {
+      description:
+        'Optional field selection for the response body to reduce token usage. Accepts a string[] or a comma-separated string of dot-paths.',
+      anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
     },
     format: {
       type: 'string',
@@ -648,12 +937,16 @@ const buildArtifactsByRunSchema = (): Record<string, unknown> => ({
       description: 'Alias for runId.',
       anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }],
     },
-    format: {
-      type: 'string',
-      enum: ['terse', 'debug'],
-      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
-    },
-    // Legacy positional forms:
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+    full: {
+      type: 'boolean',
+      description: 'If true, return the unfiltered upstream response body.',
+    },
+    // Legacy positional forms:
     // - Preferred by humans/LLMs: [owner, repo, runId]
     // - Back-compat with the underlying helper signature: [runId, owner, repo]
     args: {
@@ -716,11 +1009,15 @@ const buildLogsForRunTailSchema = (): Record<string, unknown> => ({
       type: 'string',
       description: 'If set, only return log lines containing this substring.',
     },
-    format: {
-      type: 'string',
-      enum: ['terse', 'debug'],
-      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
-    },
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+    full: {
+      type: 'boolean',
+      description: 'If true, return the unfiltered upstream response body.',
+    },
 
     // Legacy / compatibility: allow calling with positional args.
     args: {
@@ -779,12 +1076,16 @@ const buildDiagnoseLatestFailureSchema = (): Record<string, unknown> => ({
       type: 'string',
       description: 'If set, only return log lines containing this substring.',
     },
-    format: {
-      type: 'string',
-      enum: ['terse', 'debug'],
-      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
-    },
-    args: {
+    format: {
+      type: 'string',
+      enum: ['terse', 'debug'],
+      description: 'Output format. Default: "terse". Use "debug" to include request/mapping/headers.',
+    },
+    full: {
+      type: 'boolean',
+      description: 'If true, return the unfiltered upstream response body.',
+    },
+    args: {
       type: 'array',
       items: { type: 'string' },
       description: 'Legacy positional form: [owner, repo] plus options.workflowName/maxLines/etc.',
@@ -847,14 +1148,18 @@ const buildToolList = (
                 additionalProperties: true,
                 description: 'Tool invocation options',
               },
-              validateOnly: {
-                type: 'boolean',
-                description: 'If true, validate and normalize without executing the underlying request.',
-              },
-              fields: {
-                description:
-                  'Optional field selection for the response body (reduces token usage). Accepts a string[] or comma-separated string.',
-                anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
+              validateOnly: {
+                type: 'boolean',
+                description: 'If true, validate and normalize without executing the underlying request.',
+              },
+              full: {
+                type: 'boolean',
+                description: 'If true, return the unfiltered upstream response body for this call.',
+              },
+              fields: {
+                description:
+                  'Optional field selection for the response body (reduces token usage). Accepts a string[] or comma-separated string.',
+                anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
               },
               format: {
                 type: 'string',
@@ -876,14 +1181,18 @@ const buildToolList = (
           enum: ['terse', 'debug'],
           description: 'Default output format for calls that do not specify one (default: "terse").',
         },
-        validateOnly: {
-          type: 'boolean',
-          description: 'If true, validate and normalize calls without executing them.',
-        },
-        fields: {
-          description:
-            'Default field selection for calls that do not specify one. Accepts a string[] or comma-separated string.',
-          anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
+        validateOnly: {
+          type: 'boolean',
+          description: 'If true, validate and normalize calls without executing them.',
+        },
+        full: {
+          type: 'boolean',
+          description: 'Default response mode for calls that do not specify one. If true, return unfiltered bodies.',
+        },
+        fields: {
+          description:
+            'Default field selection for calls that do not specify one. Accepts a string[] or comma-separated string.',
+          anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
         },
       },
       required: ['calls'],
@@ -1091,16 +1400,148 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
     return { owner, repo }
   }
 
-  const resolvePrNumber = (args: string[], options: Record<string, unknown>): string => {
-    const fromArgs = args.length >= 1 ? toTrimmedString(args[0]) : ''
-    const fromNamed = toTrimmedString(pickFirst(options.number, (options as Record<string, unknown>).prNumber, options.index))
-    return fromArgs || fromNamed
-  }
-
-  const normalizePayloadWithContext = (
-    tool: ToolDefinition,
-    payload: unknown,
-  ): { args: string[]; options: Record<string, unknown> } => {
+  const resolvePrNumber = (args: string[], options: Record<string, unknown>): string => {
+    const fromArgs = args.length >= 1 ? toTrimmedString(args[0]) : ''
+    const fromNamed = toTrimmedString(pickFirst(options.number, (options as Record<string, unknown>).prNumber, options.index))
+    return fromArgs || fromNamed
+  }
+
+  const resolvedConfig = pickRecord(options.config)
+  const giteaHost = toTrimmedString(pickFirst(resolvedConfig.giteaHost, process.env.GITEA_HOST)) || ''
+  const giteaToken = toTrimmedString(pickFirst(resolvedConfig.giteaToken, process.env.GITEA_TOKEN)) || ''
+  const giteaApiBase = giteaHost ? normalizeGiteaApiBase(giteaHost) : ''
+
+  const checkPrBlockingIssues = async (
+    owner: string | undefined,
+    repo: string | undefined,
+    prNumber: string,
+  ): Promise<{
+    attempted: boolean
+    ok: boolean
+    status?: number
+    blockingIssueNumbers: number[]
+    details?: unknown
+    reason?: string
+  }> => {
+    const issueNumber = toPositiveInteger(prNumber)
+    if (!owner || !repo || !issueNumber) {
+      return {
+        attempted: false,
+        ok: false,
+        blockingIssueNumbers: [],
+        reason: 'owner/repo/number is required',
+      }
+    }
+
+    try {
+      const result = await callIssueDependenciesApi(
+        'GET',
+        owner,
+        repo,
+        issueNumber,
+        giteaHost || undefined,
+        giteaToken || undefined,
+      )
+
+      return {
+        attempted: true,
+        ok: result.ok,
+        status: result.status,
+        blockingIssueNumbers: result.ok ? extractDependencyIssueNumbers(result.body) : [],
+        details: result.body,
+      }
+    } catch (error) {
+      return {
+        attempted: true,
+        ok: false,
+        blockingIssueNumbers: [],
+        reason: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  const checkPrHeadContainedInBase = async (
+    owner: string | undefined,
+    repo: string | undefined,
+    baseRef: string,
+    headSha: string,
+  ): Promise<{
+    attempted: boolean
+    ok: boolean
+    status?: number
+    contained: boolean | null
+    details?: unknown
+    reason?: string
+  }> => {
+    if (!owner || !repo || !baseRef || !headSha) {
+      return {
+        attempted: false,
+        ok: false,
+        contained: null,
+        reason: 'owner/repo/baseRef/headSha is required',
+      }
+    }
+
+    if (!giteaApiBase) {
+      return {
+        attempted: false,
+        ok: false,
+        contained: null,
+        reason: 'Gitea API base is not configured',
+      }
+    }
+
+    const basehead = `${baseRef}...${headSha}`
+    const requestUrl = `${giteaApiBase}/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/compare/${encodeURIComponent(basehead)}`
+    const headers: Record<string, string> = {
+      Accept: 'application/json',
+    }
+    if (giteaToken) {
+      headers.Authorization = `token ${giteaToken}`
+    }
+
+    try {
+      const response = await fetch(requestUrl, { method: 'GET', headers })
+      const responseText = await response.text()
+      let parsedBody: unknown = responseText
+      try {
+        parsedBody = JSON.parse(responseText)
+      } catch {
+        parsedBody = responseText
+      }
+
+      if (!response.ok) {
+        return {
+          attempted: true,
+          ok: false,
+          status: response.status,
+          contained: null,
+          details: parsedBody,
+          reason: buildErrorMessage(response.status, parsedBody),
+        }
+      }
+
+      return {
+        attempted: true,
+        ok: true,
+        status: response.status,
+        contained: inferHeadContainedFromCompareBody(parsedBody),
+        details: parsedBody,
+      }
+    } catch (error) {
+      return {
+        attempted: true,
+        ok: false,
+        contained: null,
+        reason: error instanceof Error ? error.message : String(error),
+      }
+    }
+  }
+
+  const normalizePayloadWithContext = (
+    tool: ToolDefinition,
+    payload: unknown,
+  ): { args: string[]; options: Record<string, unknown> } => {
     const normalized = normalizePayload(payload)
     const optionsWithDefaults = { ...normalized.options }
     const { owner, repo } = resolveOwnerRepo(optionsWithDefaults)
@@ -1137,32 +1578,44 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
             items: { type: 'string' },
             description: 'Legacy positional form: [owner, repo]',
           },
-          format: {
-            type: 'string',
-            enum: ['terse', 'debug'],
-            description: 'Output format. Default: "terse".',
-          },
-        },
-      },
-    },
-    {
-      name: contextGetToolName,
-      description: 'Get the current default {owner, repo} for this session.',
-      inputSchema: { type: 'object', additionalProperties: true, properties: {} },
-    },
+          format: {
+            type: 'string',
+            enum: ['terse', 'debug'],
+            description: 'Output format. Default: "terse".',
+          },
+          full: {
+            type: 'boolean',
+            description: 'If true, return unfiltered helper payloads.',
+          },
+        },
+      },
+    },
+    {
+      name: contextGetToolName,
+      description: 'Get the current default {owner, repo} for this session.',
+      inputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          format: { type: 'string', enum: ['terse', 'debug'] },
+          full: { type: 'boolean', description: 'If true, return unfiltered helper payloads.' },
+        },
+      },
+    },
     {
       name: searchToolsToolName,
       description: 'Search available git MCP tools by substring (returns names + descriptions).',
-      inputSchema: {
-        type: 'object',
-        additionalProperties: true,
-        properties: {
-          query: { type: 'string', description: 'Search query (substring match on tool name/path)' },
-          limit: { type: 'integer', minimum: 1, description: 'Max matches to return (default: 20)' },
-          format: { type: 'string', enum: ['terse', 'debug'] },
-        },
-        required: ['query'],
-      },
+      inputSchema: {
+        type: 'object',
+        additionalProperties: true,
+        properties: {
+          query: { type: 'string', description: 'Search query (substring match on tool name/path)' },
+          limit: { type: 'integer', minimum: 1, description: 'Max matches to return (default: 20)' },
+          format: { type: 'string', enum: ['terse', 'debug'] },
+          full: { type: 'boolean', description: 'If true, return unfiltered helper payloads.' },
+        },
+        required: ['query'],
+      },
     },
     {
       name: prPreflightToolName,
@@ -1171,15 +1624,20 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
         type: 'object',
         additionalProperties: true,
         properties: {
-          owner: { type: 'string', description: 'Repository owner/org (optional if context/defaults set)' },
-          repo: { type: 'string', description: 'Repository name (optional if context/defaults set)' },
-          number: { anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }], description: 'PR number' },
-          includeIssues: { type: 'boolean', description: 'If true, fetch referenced issues mentioned as "Fixes #123".' },
-          validateOnly: { type: 'boolean', description: 'Validate and normalize without executing HTTP calls.' },
-          fields: {
-            description: 'Optional field selection applied to pr/checks/review bodies.',
-            anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
-          },
+          owner: { type: 'string', description: 'Repository owner/org (optional if context/defaults set)' },
+          repo: { type: 'string', description: 'Repository name (optional if context/defaults set)' },
+          number: { anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }], description: 'PR number' },
+          includeIssues: { type: 'boolean', description: 'If true, fetch referenced issues mentioned as "Fixes #123".' },
+          checkBlockingIssues: {
+            type: 'boolean',
+            description: 'If true (default), detect issue dependencies that block this PR from being merged.',
+          },
+          validateOnly: { type: 'boolean', description: 'Validate and normalize without executing HTTP calls.' },
+          full: { type: 'boolean', description: 'If true, return unfiltered PR/check/review payloads.' },
+          fields: {
+            description: 'Optional field selection applied to pr/checks/review bodies.',
+            anyOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
+          },
           format: { type: 'string', enum: ['terse', 'debug'] },
         },
         anyOf: [{ required: ['number'] }, { required: ['args'] }],
@@ -1195,14 +1653,23 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
           owner: { type: 'string', description: 'Repository owner/org (optional if context/defaults set)' },
           repo: { type: 'string', description: 'Repository name (optional if context/defaults set)' },
           number: { anyOf: [{ type: 'integer', minimum: 1 }, { type: 'string' }], description: 'PR number' },
-          mergeMethod: { type: 'string', description: 'Merge method. Maps to Gitea merge Do field (default: "merge").' },
-          maxAttempts: { type: 'integer', minimum: 1, description: 'Max poll attempts (default: 6)' },
-          delayMs: { type: 'integer', minimum: 0, description: 'Delay between polls in ms (default: 1000)' },
-          validateOnly: { type: 'boolean', description: 'Validate and normalize without executing HTTP calls.' },
-          format: { type: 'string', enum: ['terse', 'debug'] },
-        },
-        anyOf: [{ required: ['number'] }, { required: ['args'] }],
-      },
+          mergeMethod: { type: 'string', description: 'Merge method. Maps to Gitea merge Do field (default: "merge").' },
+          maxAttempts: { type: 'integer', minimum: 1, description: 'Max poll attempts (default: 6)' },
+          delayMs: { type: 'integer', minimum: 0, description: 'Delay between polls in ms (default: 1000)' },
+          allowManualFinalize: {
+            type: 'boolean',
+            description: 'If true, attempt a manual metadata finalization when normal merge fails.',
+          },
+          manualMergeCommitSha: {
+            type: 'string',
+            description: 'Optional merge commit SHA used when finalizing with Do="manually-merged".',
+          },
+          validateOnly: { type: 'boolean', description: 'Validate and normalize without executing HTTP calls.' },
+          full: { type: 'boolean', description: 'If true, return unfiltered merge/PR payloads.' },
+          format: { type: 'string', enum: ['terse', 'debug'] },
+        },
+        anyOf: [{ required: ['number'] }, { required: ['args'] }],
+      },
     },
   ]
 
@@ -1213,13 +1680,20 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
     await new Promise<void>((resolve) => setTimeout(resolve, ms))
   }
 
-  const toOk = (data: unknown, format: McpToolOutputFormat, debug?: unknown, status: number = 0): McpTerseOk => {
-    const envelope: McpTerseOk = {
-      ok: true,
-      data,
-      meta: {
-        status,
-      },
+  const toOk = (
+    data: unknown,
+    format: McpToolOutputFormat,
+    debug?: unknown,
+    status: number = 0,
+    full: boolean = true,
+  ): McpTerseOk => {
+    const outputData = full ? data : compactResponseDataForDefaultMode(data)
+    const envelope: McpTerseOk = {
+      ok: true,
+      data: outputData,
+      meta: {
+        status,
+      },
       ...(format === 'debug' && debug !== undefined ? { debug } : {}),
     }
 
@@ -1234,16 +1708,19 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
     return redactSecretsForMcpOutput(enriched) as McpTerseErr
   }
 
-  const invokeCustomTool = async (
-    toolName: string,
-    payload: unknown,
-    controls: { format: McpToolOutputFormat | null; validateOnly: boolean; fields: McpFieldSelection | null },
-  ): Promise<{ isError: boolean; envelope: McpTerseOk | McpTerseErr }> => {
-    const format = controls.format ?? 'terse'
-
-    if (toolName === contextGetToolName) {
-      return { isError: false, envelope: toOk({ owner: context.owner ?? null, repo: context.repo ?? null }, format) }
-    }
+  const invokeCustomTool = async (
+    toolName: string,
+    payload: unknown,
+    controls: McpCallControls,
+  ): Promise<{ isError: boolean; envelope: McpTerseOk | McpTerseErr }> => {
+    const format = controls.format ?? 'terse'
+
+    if (toolName === contextGetToolName) {
+      return {
+        isError: false,
+        envelope: toOk({ owner: context.owner ?? null, repo: context.repo ?? null }, format, undefined, 0, true),
+      }
+    }
 
     if (toolName === contextSetToolName) {
       const normalized = normalizePayload(payload)
@@ -1256,8 +1733,11 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
       context.owner = owner || undefined
       context.repo = repo || undefined
 
-      return { isError: false, envelope: toOk({ owner: context.owner ?? null, repo: context.repo ?? null }, format) }
-    }
+      return {
+        isError: false,
+        envelope: toOk({ owner: context.owner ?? null, repo: context.repo ?? null }, format, undefined, 0, true),
+      }
+    }
 
     if (toolName === searchToolsToolName) {
       const normalized = normalizePayload(payload)
@@ -1299,8 +1779,8 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
           return meta
         })
 
-      return { isError: false, envelope: toOk({ matches }, format) }
-    }
+      return { isError: false, envelope: toOk({ matches }, format, undefined, 0, true) }
+    }
 
     if (toolName === prPreflightToolName) {
       const normalized = normalizePayload(payload)
@@ -1327,36 +1807,43 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
         }
       }
 
-      const includeIssues = Boolean((optionsWithDefaults as Record<string, unknown>).includeIssues)
+      const includeIssues = Boolean((optionsWithDefaults as Record<string, unknown>).includeIssues)
+      const checkBlockingIssues =
+        parseBoolean((optionsWithDefaults as Record<string, unknown>).checkBlockingIssues) ?? true
 
       if (controls.validateOnly) {
         const toolPrefix = prefix ? `${prefix}.` : ''
         return {
           isError: false,
           envelope: toOk(
-            {
-              valid: true,
-              owner: owner ?? null,
+            {
+              valid: true,
+              owner: owner ?? null,
               repo: repo ?? null,
               number,
-              calls: [
-                { tool: `${toolPrefix}repo.pr.view`, args: [number], options: { owner, repo } },
-                { tool: `${toolPrefix}repo.pr.checks`, args: [number], options: { owner, repo } },
-                { tool: `${toolPrefix}repo.pr.review`, args: [number], options: { owner, repo, method: 'GET' } },
-              ],
-              includeIssues,
-            },
-            format,
-          ),
-        }
-      }
+              calls: [
+                { tool: `${toolPrefix}repo.pr.view`, args: [number], options: { owner, repo } },
+                { tool: `${toolPrefix}repo.pr.checks`, args: [number], options: { owner, repo } },
+                { tool: `${toolPrefix}repo.pr.review`, args: [number], options: { owner, repo, method: 'GET' } },
+              ],
+              includeIssues,
+              checkBlockingIssues,
+            },
+            format,
+            undefined,
+            0,
+            true,
+          ),
+        }
+      }
 
       const callOptionsBase = stripMcpOnlyOptions(optionsWithDefaults)
-      const callOptions: Record<string, unknown> = { ...callOptionsBase }
-      delete (callOptions as any).includeIssues
-      delete (callOptions as any).number
-      delete (callOptions as any).prNumber
-      delete (callOptions as any).index
+      const callOptions: Record<string, unknown> = { ...callOptionsBase }
+      delete (callOptions as any).includeIssues
+      delete (callOptions as any).checkBlockingIssues
+      delete (callOptions as any).number
+      delete (callOptions as any).prNumber
+      delete (callOptions as any).index
 
       const pr = await (api as any).repo.pr.view(number, callOptions)
       const checks = await (api as any).repo.pr.checks(number, callOptions)
@@ -1374,24 +1861,55 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
 
       const uniqueReferenced = Array.from(new Set(referencedIssueNumbers))
       const issues: unknown[] = []
-      if (includeIssues && uniqueReferenced.length > 0) {
-        for (const n of uniqueReferenced) {
-          try {
-            const issue = await (api as any).repo.issue.view(String(n), callOptions)
-            issues.push(issue.body)
+      if (includeIssues && uniqueReferenced.length > 0) {
+        for (const n of uniqueReferenced) {
+          try {
+            const issue = await (api as any).repo.issue.view(String(n), callOptions)
+            issues.push(issue.body)
           } catch {
             // best effort
-          }
-        }
-      }
-
-      const data = {
-        pr: applyFieldSelection(pr.body, controls.fields),
-        checks: applyFieldSelection(checks.body, controls.fields),
-        review: applyFieldSelection(review.body, controls.fields),
-        referencedIssueNumbers: uniqueReferenced,
-        ...(includeIssues ? { issues } : {}),
-      }
+          }
+        }
+      }
+
+      const blockerCheck = checkBlockingIssues ? await checkPrBlockingIssues(owner, repo, number) : null
+      const blockingIssueNumbers = blockerCheck ? blockerCheck.blockingIssueNumbers : []
+
+      if (blockingIssueNumbers.length > 0) {
+        return {
+          isError: true,
+          envelope: toErr(
+            {
+              ok: false,
+              error: {
+                code: 'PR_BLOCKED_BY_ISSUES',
+                message: 'Pull request is blocked by issue dependencies. Close all blocking issues before merging.',
+                details: {
+                  blockingIssueNumbers,
+                  blockerCheck: {
+                    attempted: blockerCheck?.attempted ?? false,
+                    ok: blockerCheck?.ok ?? false,
+                    status: blockerCheck?.status,
+                  },
+                },
+                retryable: false,
+              },
+            },
+            format,
+            { pr, checks, review, blockerCheck },
+          ),
+        }
+      }
+
+      const data = {
+        pr: applyFieldSelection(pr.body, controls.fields),
+        checks: applyFieldSelection(checks.body, controls.fields),
+        review: applyFieldSelection(review.body, controls.fields),
+        referencedIssueNumbers: uniqueReferenced,
+        ...(checkBlockingIssues ? { blockingIssueNumbers } : {}),
+        ...(includeIssues ? { issues } : {}),
+      }
+      const full = controls.full || Boolean(controls.fields)
 
       const allOk = pr.ok && checks.ok && review.ok
       if (!allOk) {
@@ -1403,22 +1921,31 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
               error: {
                 code: 'PREFLIGHT_FAILED',
                 message: 'One or more preflight calls failed. See details.',
-                details: {
-                  pr: { ok: pr.ok, status: pr.status },
-                  checks: { ok: checks.ok, status: checks.status },
-                  review: { ok: review.ok, status: review.status },
-                },
-                retryable: false,
-              },
-            },
-            format,
-            { pr, checks, review },
-          ),
-        }
-      }
-
-      return { isError: false, envelope: toOk(data, format, { pr, checks, review }, 200) }
-    }
+                details: {
+                  pr: { ok: pr.ok, status: pr.status },
+                  checks: { ok: checks.ok, status: checks.status },
+                  review: { ok: review.ok, status: review.status },
+                  ...(checkBlockingIssues
+                    ? {
+                        blockerCheck: {
+                          attempted: blockerCheck?.attempted ?? false,
+                          ok: blockerCheck?.ok ?? false,
+                          status: blockerCheck?.status,
+                        },
+                      }
+                    : {}),
+                },
+                retryable: false,
+              },
+            },
+            format,
+            { pr, checks, review, blockerCheck },
+          ),
+        }
+      }
+
+      return { isError: false, envelope: toOk(data, format, { pr, checks, review, blockerCheck }, 200, full) }
+    }
 
     if (toolName === prMergeAndVerifyToolName) {
       const normalized = normalizePayload(payload)
@@ -1445,75 +1972,201 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
         }
       }
 
-      const maxAttempts = toPositiveInteger((optionsWithDefaults as Record<string, unknown>).maxAttempts) ?? 6
-      const delayMs = toNonNegativeInteger((optionsWithDefaults as Record<string, unknown>).delayMs) ?? 1000
-      const mergeMethod = toTrimmedString((optionsWithDefaults as Record<string, unknown>).mergeMethod) || 'merge'
+      const maxAttempts = toPositiveInteger((optionsWithDefaults as Record<string, unknown>).maxAttempts) ?? 6
+      const delayMs = toNonNegativeInteger((optionsWithDefaults as Record<string, unknown>).delayMs) ?? 1000
+      const mergeMethod = toTrimmedString((optionsWithDefaults as Record<string, unknown>).mergeMethod) || 'merge'
+      const allowManualFinalize = Boolean((optionsWithDefaults as Record<string, unknown>).allowManualFinalize)
+      const manualMergeCommitSha =
+        toTrimmedString(
+          pickFirst(
+            (optionsWithDefaults as Record<string, unknown>).manualMergeCommitSha,
+            (optionsWithDefaults as Record<string, unknown>).mergeCommitSha,
+          ),
+        ) || ''
 
       if (controls.validateOnly) {
         return {
           isError: false,
           envelope: toOk(
-            {
-              valid: true,
-              owner: owner ?? null,
+            {
+              valid: true,
+              owner: owner ?? null,
               repo: repo ?? null,
-              number,
-              mergeMethod,
-              maxAttempts,
-              delayMs,
-            },
-            format,
-          ),
-        }
-      }
+              number,
+              mergeMethod,
+              maxAttempts,
+              delayMs,
+              allowManualFinalize,
+              manualMergeCommitSha: manualMergeCommitSha || null,
+            },
+            format,
+            undefined,
+            0,
+            true,
+          ),
+        }
+      }
 
       const callOptionsBase = stripMcpOnlyOptions(optionsWithDefaults)
       const callOptions: Record<string, unknown> = { ...callOptionsBase }
       delete (callOptions as any).maxAttempts
       delete (callOptions as any).delayMs
-      delete (callOptions as any).number
-      delete (callOptions as any).prNumber
-      delete (callOptions as any).index
-      delete (callOptions as any).mergeMethod
-
-      let mergeResult: GitServiceApiExecutionResult | null = null
-      let lastMergeError: unknown = null
-
-      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      delete (callOptions as any).number
+      delete (callOptions as any).prNumber
+      delete (callOptions as any).index
+      delete (callOptions as any).mergeMethod
+      delete (callOptions as any).allowManualFinalize
+      delete (callOptions as any).manualMergeCommitSha
+      delete (callOptions as any).mergeCommitSha
+
+      let mergeResult: GitServiceApiExecutionResult | null = null
+      let lastMergeError: unknown = null
+      let lastFailure: MergeFailureClassification | null = null
+      let manualFinalize: Record<string, unknown> | null = null
+
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
         mergeResult = await (api as any).repo.pr.merge(number, { ...callOptions, mergeMethod })
         if (mergeResult.ok && mergeResult.status < 400) {
           break
-        }
-
-        lastMergeError = mergeResult.body
-        const message = buildErrorMessage(mergeResult.status, mergeResult.body)
-        if (!/try again later/i.test(message) && mergeResult.status !== 429 && mergeResult.status < 500) {
-          break
-        }
+        }
+
+        lastMergeError = mergeResult.body
+        lastFailure = classifyMergeFailure(mergeResult.status, mergeResult.body)
+        if (!lastFailure.retryable) {
+          break
+        }
 
         await sleep(delayMs)
       }
 
-      if (!mergeResult || !mergeResult.ok || mergeResult.status >= 400) {
-        return {
-          isError: true,
-          envelope: toErr(
-            {
-              ok: false,
-              error: {
-                code: 'MERGE_FAILED',
-                status: mergeResult?.status,
-                message: buildErrorMessage(mergeResult?.status, mergeResult?.body ?? lastMergeError),
-                details: mergeResult?.body ?? lastMergeError,
-                retryable: true,
-              },
-              meta: mergeResult?.status ? { status: mergeResult.status } : undefined,
-            },
-            format,
-            { mergeResult },
-          ),
-        }
-      }
+      if (!mergeResult || !mergeResult.ok || mergeResult.status >= 400) {
+        const failure = classifyMergeFailure(mergeResult?.status, mergeResult?.body ?? lastMergeError)
+
+        if (failure.blockedByIssues) {
+          return {
+            isError: true,
+            envelope: toErr(
+              {
+                ok: false,
+                error: {
+                  code: 'PR_BLOCKED_BY_ISSUES',
+                  status: mergeResult?.status,
+                  message: failure.message,
+                  details: mergeResult?.body ?? lastMergeError,
+                  retryable: false,
+                },
+                meta: mergeResult?.status ? { status: mergeResult.status } : undefined,
+              },
+              format,
+              { mergeResult, lastFailure },
+            ),
+          }
+        }
+
+        if (allowManualFinalize) {
+          const prBeforeFinalize = await (api as any).repo.pr.view(number, callOptions)
+          const prBody = isRecord(prBeforeFinalize.body) ? (prBeforeFinalize.body as Record<string, unknown>) : null
+          const baseRef = prBody && isRecord(prBody.base) ? toTrimmedString((prBody.base as Record<string, unknown>).ref) : ''
+          const headSha = prBody && isRecord(prBody.head) ? toTrimmedString((prBody.head as Record<string, unknown>).sha) : ''
+
+          const containmentCheck = manualMergeCommitSha
+            ? {
+                attempted: false,
+                ok: true,
+                contained: true,
+                reason: 'manualMergeCommitSha provided by caller',
+              }
+            : await checkPrHeadContainedInBase(owner, repo, baseRef, headSha)
+
+          const canFinalize = manualMergeCommitSha.length > 0 || containmentCheck.contained === true
+          manualFinalize = {
+            attempted: true,
+            canFinalize,
+            manualMergeCommitSha: manualMergeCommitSha || null,
+            baseRef: baseRef || null,
+            headSha: headSha || null,
+            containmentCheck,
+          }
+
+          if (canFinalize) {
+            const finalizeBody: Record<string, unknown> = {
+              Do: 'manually-merged',
+            }
+            if (manualMergeCommitSha) {
+              finalizeBody.MergeCommitID = manualMergeCommitSha
+            }
+
+            const manualMergeResult = await (api as any).repo.pr.merge(number, {
+              ...callOptions,
+              mergeMethod: 'manually-merged',
+              requestBody: finalizeBody,
+            })
+
+            if (manualMergeResult.ok && manualMergeResult.status < 400) {
+              mergeResult = manualMergeResult
+              manualFinalize = {
+                ...manualFinalize,
+                mode: 'manually-merged',
+                status: manualMergeResult.status,
+                ok: true,
+              }
+            } else {
+              const finalizeFailure = classifyMergeFailure(manualMergeResult.status, manualMergeResult.body)
+              return {
+                isError: true,
+                envelope: toErr(
+                  {
+                    ok: false,
+                    error: {
+                      code: finalizeFailure.blockedByIssues ? 'PR_BLOCKED_BY_ISSUES' : 'MERGE_FINALIZE_FAILED',
+                      status: manualMergeResult.status,
+                      message: finalizeFailure.message,
+                      details: {
+                        merge: manualMergeResult.body,
+                        manualFinalize,
+                      },
+                      retryable: finalizeFailure.retryable,
+                    },
+                    meta: manualMergeResult.status ? { status: manualMergeResult.status } : undefined,
+                  },
+                  format,
+                  { mergeResult, manualMergeResult, manualFinalize, prBeforeFinalize },
+                ),
+              }
+            }
+          }
+        }
+
+        if (!mergeResult || !mergeResult.ok || mergeResult.status >= 400) {
+          return {
+            isError: true,
+            envelope: toErr(
+              {
+                ok: false,
+                error: {
+                  code: failure.code,
+                  status: mergeResult?.status,
+                  message: failure.message,
+                  details: {
+                    merge: mergeResult?.body ?? lastMergeError,
+                    manualFinalize,
+                  },
+                  hint:
+                    allowManualFinalize && !manualMergeCommitSha
+                      ? 'Set allowManualFinalize=true and provide manualMergeCommitSha when the PR is already merged outside the API.'
+                      : undefined,
+                  retryable: failure.retryable,
+                },
+                meta: mergeResult?.status ? { status: mergeResult.status } : undefined,
+              },
+              format,
+              { mergeResult, lastFailure, manualFinalize },
+            ),
+          }
+        }
+
+        lastFailure = null
+      }
 
       const views: GitServiceApiExecutionResult[] = []
       let prAfter: GitServiceApiExecutionResult | null = null
@@ -1530,12 +2183,14 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
         await sleep(delayMs)
       }
 
-      const data = {
-        merge: mergeResult.body,
-        pr: prAfter ? prAfter.body : null,
-        polled: views.length,
-      }
-
+      const data = {
+        merge: mergeResult.body,
+        pr: prAfter ? prAfter.body : null,
+        polled: views.length,
+        ...(manualFinalize ? { finalization: manualFinalize } : {}),
+      }
+      const full = controls.full
+
       const merged = prAfter && isRecord(prAfter.body) ? Boolean((prAfter.body as any).merged) : false
       const state = prAfter && isRecord(prAfter.body) && typeof (prAfter.body as any).state === 'string' ? String((prAfter.body as any).state) : ''
 
@@ -1543,23 +2198,23 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
         return {
           isError: true,
           envelope: toErr(
-            {
-              ok: false,
-              error: {
-                code: 'MERGE_VERIFY_FAILED',
-                message: 'Merge request succeeded, but PR state did not transition to merged/closed within polling window.',
-                details: { merged, state },
-                retryable: true,
-              },
-            },
-            format,
-            { mergeResult, prAfter, views },
-          ),
-        }
-      }
-
-      return { isError: false, envelope: toOk(data, format, { mergeResult, prAfter, views }, 200) }
-    }
+            {
+              ok: false,
+              error: {
+                code: 'MERGE_VERIFY_FAILED',
+                message: 'Merge request succeeded, but PR state did not transition to merged/closed within polling window.',
+                details: { merged, state },
+                retryable: true,
+              },
+            },
+            format,
+            { mergeResult, prAfter, views, manualFinalize },
+          ),
+        }
+      }
+
+      return { isError: false, envelope: toOk(data, format, { mergeResult, prAfter, views, manualFinalize }, 200, full) }
+    }
 
     return {
       isError: true,
@@ -1606,12 +2261,13 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
           if (customToolMetaByName.has(tool)) {
             const mergedPayload = { args, options }
             const callControls = extractMcpControls(mergedPayload)
-            const effectiveControls = {
-              ...callControls,
-              format: callControls.format ?? batchControls.format ?? null,
-              fields: callControls.fields ?? batchControls.fields ?? null,
-              validateOnly: callControls.validateOnly || batchControls.validateOnly,
-            }
+            const effectiveControls = {
+              ...callControls,
+              format: callControls.format ?? batchControls.format ?? null,
+              fields: callControls.fields ?? batchControls.fields ?? null,
+              validateOnly: callControls.validateOnly || batchControls.validateOnly,
+              full: callControls.full || batchControls.full,
+            }
 
             try {
               const { isError, envelope } = await invokeCustomTool(tool, mergedPayload, effectiveControls)
@@ -1653,13 +2309,14 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
 
           try {
             const mergedPayload = { args, options }
-            const callControls = extractMcpControls(mergedPayload)
-            const effectiveFormat = callControls.format ?? batchControls.format ?? 'terse'
-            const effectiveFields = callControls.fields ?? batchControls.fields ?? null
-            const validateOnly = callControls.validateOnly || batchControls.validateOnly
-
-            if (validateOnly) {
-              const normalized = normalizePayloadWithContext(toolDefinition, mergedPayload)
+            const callControls = extractMcpControls(mergedPayload)
+            const effectiveFormat = callControls.format ?? batchControls.format ?? 'terse'
+            const effectiveFields = callControls.fields ?? batchControls.fields ?? null
+            const validateOnly = callControls.validateOnly || batchControls.validateOnly
+            const full = callControls.full || batchControls.full
+
+            if (validateOnly) {
+              const normalized = normalizePayloadWithContext(toolDefinition, mergedPayload)
               const envelope: McpTerseOk = {
                 ok: true,
                 data: {
@@ -1688,13 +2345,14 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
               ? invokeLogsForRunTailTool(toolDefinition, normalizedPayload)
               : isArtifactsByRunTool(toolDefinition.name)
                 ? invokeArtifactsByRunTool(toolDefinition, normalizedPayload)
-              : invokeTool(toolDefinition, normalizedPayload))
-
-            const selected = effectiveFields ? { ...data, body: applyFieldSelection(data.body, effectiveFields) } : data
-            const { isError, envelope } = toMcpEnvelope(selected, effectiveFormat)
-            return {
-              index,
-              tool,
+              : invokeTool(toolDefinition, normalizedPayload))
+
+            const selected = effectiveFields ? { ...data, body: applyFieldSelection(data.body, effectiveFields) } : data
+            const shouldReturnFull = full || Boolean(effectiveFields)
+            const { isError, envelope } = toMcpEnvelope(selected, effectiveFormat, shouldReturnFull)
+            return {
+              index,
+              tool,
               isError,
               ...(envelope as McpTerseOk | McpTerseErr),
             } as BatchResult
@@ -1746,16 +2404,17 @@ export const createGitMcpServer = (options: GitMcpServerOptions = {}): GitMcpSer
     const normalized = normalizePayloadWithContext(tool, payload)
     const normalizedPayload = { args: normalized.args, options: normalized.options }
 
-    const result = await (isLogsForRunTailTool(tool.name)
-      ? invokeLogsForRunTailTool(tool, normalizedPayload)
-      : isArtifactsByRunTool(tool.name)
-        ? invokeArtifactsByRunTool(tool, normalizedPayload)
-      : invokeTool(tool, normalizedPayload))
-
-    const selected = controls.fields ? { ...result, body: applyFieldSelection(result.body, controls.fields) } : result
-    const { isError, envelope } = toMcpEnvelope(selected, controls.format ?? 'terse')
-    return { isError, text: JSON.stringify(envelope) }
-  }
+    const result = await (isLogsForRunTailTool(tool.name)
+      ? invokeLogsForRunTailTool(tool, normalizedPayload)
+      : isArtifactsByRunTool(tool.name)
+        ? invokeArtifactsByRunTool(tool, normalizedPayload)
+      : invokeTool(tool, normalizedPayload))
+
+    const selected = controls.fields ? { ...result, body: applyFieldSelection(result.body, controls.fields) } : result
+    const shouldReturnFull = controls.full || Boolean(controls.fields)
+    const { isError, envelope } = toMcpEnvelope(selected, controls.format ?? 'terse', shouldReturnFull)
+    return { isError, text: JSON.stringify(envelope) }
+  }
 
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: listTools(),