codebuff-agent 2.1.74__py3-none-any.whl

codebuff_core/services/context_condenser.py

@@ -0,0 +1,306 @@
+"""
+Context Condenser for intelligent context compression.
+
+Provides token-aware context management with multiple compression strategies
+to optimize LLM input while preserving important information.
+"""
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from typing import Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+
+class CompressionStrategy(Enum):
+    """Available compression strategies."""
+
+    TRUNCATE = "truncate"  # Keep only recent messages
+    SUMMARIZE = "summarize"  # Summarize old messages, keep recent
+    ADAPTIVE = "adaptive"  # Auto-select based on context size
+
+
+@dataclass
+class CompressionStats:
+    """Statistics from a compression operation."""
+
+    original_tokens: int
+    compressed_tokens: int
+    compression_ratio: float
+    strategy_used: str
+    messages_kept: int
+    messages_removed: int
+
+
+class ContextCondenser:
+    """
+    Context compressor - optimizes conversation context within token budget.
+
+    Supports multiple LLM providers with different token limits.
+    Uses rule-based compression without additional LLM calls.
+    """
+
+    # Provider-specific token limits for context
+    TOKEN_LIMITS = {
+        "vllm": 8000,
+        "default": 4000,
+    }
+
+    # Token estimation: average tokens per word (conservative)
+    TOKENS_PER_WORD = 1.3
+
+    def __init__(self, provider: str = "default"):
+        """Initialize condenser with provider-specific settings.
+
+        Args:
+            provider: LLM provider name for token limit selection
+        """
+        self._provider = provider
+        self._stats_history: List[CompressionStats] = []
+
+    @property
+    def provider(self) -> str:
+        """Current LLM provider."""
+        return self._provider
+
+    @provider.setter
+    def provider(self, value: str) -> None:
+        """Update LLM provider."""
+        self._provider = value
+
+    def estimate_tokens(self, text: str) -> int:
+        """Estimate token count for text.
+
+        Uses word count with a conservative multiplier.
+        More accurate than character count for most text.
+
+        Args:
+            text: Input text to estimate
+
+        Returns:
+            Estimated token count
+        """
+        if not text:
+            return 0
+        words = len(text.split())
+        return int(words * self.TOKENS_PER_WORD)
+
+    def get_token_limit(self) -> int:
+        """Get token limit for current provider.
+
+        Returns:
+            Maximum tokens for context
+        """
+        return self.TOKEN_LIMITS.get(self._provider, self.TOKEN_LIMITS["default"])
+
+    def condense(
+        self,
+        messages: List[Dict[str, str]],
+        target_tokens: Optional[int] = None,
+        strategy: CompressionStrategy = CompressionStrategy.ADAPTIVE,
+    ) -> Tuple[List[Dict[str, str]], CompressionStats]:
+        """Compress message list to fit within token budget.
+
+        Args:
+            messages: List of message dicts with 'role' and 'content' keys
+            target_tokens: Target token count (default: 50% of provider limit)
+            strategy: Compression strategy to use
+
+        Returns:
+            Tuple of (compressed_messages, compression_stats)
+        """
+        if not messages:
+            return [], CompressionStats(0, 0, 1.0, "none", 0, 0)
+
+        target = target_tokens or (self.get_token_limit() // 2)
+        original_tokens = sum(
+            self.estimate_tokens(m.get("content", "")) for m in messages
+        )
+
+        # Already within budget - no compression needed
+        if original_tokens <= target:
+            stats = CompressionStats(
+                original_tokens=original_tokens,
+                compressed_tokens=original_tokens,
+                compression_ratio=1.0,
+                strategy_used="none",
+                messages_kept=len(messages),
+                messages_removed=0,
+            )
+            return messages, stats
+
+        # Select strategy if adaptive
+        if strategy == CompressionStrategy.ADAPTIVE:
+            strategy = self._select_strategy(original_tokens, target)
+
+        # Apply selected strategy
+        if strategy == CompressionStrategy.TRUNCATE:
+            compressed, stats = self._truncate(messages, target)
+        elif strategy == CompressionStrategy.SUMMARIZE:
+            compressed, stats = self._summarize(messages, target)
+        else:
+            compressed, stats = self._truncate(messages, target)
+
+        self._stats_history.append(stats)
+        logger.info(
+            f"Context compressed: {stats.original_tokens} → {stats.compressed_tokens} "
+            f"tokens ({stats.compression_ratio:.1%}), strategy={stats.strategy_used}"
+        )
+        return compressed, stats
+
+    def _select_strategy(self, original: int, target: int) -> CompressionStrategy:
+        """Select best compression strategy based on reduction needed.
+
+        Args:
+            original: Original token count
+            target: Target token count
+
+        Returns:
+            Selected compression strategy
+        """
+        ratio = target / original
+        # If we need to keep more than 50%, simple truncation works
+        if ratio >= 0.5:
+            return CompressionStrategy.TRUNCATE
+        # For more aggressive compression, use summarization
+        return CompressionStrategy.SUMMARIZE
+
+    def _truncate(
+        self, messages: List[Dict[str, str]], target: int
+    ) -> Tuple[List[Dict[str, str]], CompressionStats]:
+        """Keep only recent messages within token budget.
+
+        Preserves most recent messages, dropping oldest first.
+
+        Args:
+            messages: Original messages
+            target: Target token count
+
+        Returns:
+            Tuple of (truncated_messages, stats)
+        """
+        original_tokens = sum(
+            self.estimate_tokens(m.get("content", "")) for m in messages
+        )
+
+        # Keep messages from the end (most recent)
+        kept: List[Dict[str, str]] = []
+        current_tokens = 0
+
+        for msg in reversed(messages):
+            msg_tokens = self.estimate_tokens(msg.get("content", ""))
+            if current_tokens + msg_tokens <= target:
+                kept.insert(0, msg)
+                current_tokens += msg_tokens
+            else:
+                break
+
+        return kept, CompressionStats(
+            original_tokens=original_tokens,
+            compressed_tokens=current_tokens,
+            compression_ratio=(
+                current_tokens / original_tokens if original_tokens else 1.0
+            ),
+            strategy_used="truncate",
+            messages_kept=len(kept),
+            messages_removed=len(messages) - len(kept),
+        )
+
+    def _summarize(
+        self, messages: List[Dict[str, str]], target: int
+    ) -> Tuple[List[Dict[str, str]], CompressionStats]:
+        """Summarize old messages, keep recent ones intact.
+
+        Rule-based summarization without LLM calls.
+        Extracts first sentence from each old message.
+
+        Args:
+            messages: Original messages
+            target: Target token count
+
+        Returns:
+            Tuple of (summary + recent_messages, stats)
+        """
+        original_tokens = sum(
+            self.estimate_tokens(m.get("content", "")) for m in messages
+        )
+
+        # Keep last 3 messages intact
+        recent_count = min(3, len(messages))
+        recent = messages[-recent_count:]
+        old = messages[:-recent_count] if len(messages) > recent_count else []
+
+        recent_tokens = sum(self.estimate_tokens(m.get("content", "")) for m in recent)
+        remaining = target - recent_tokens
+
+        # If recent messages already exceed budget, fallback to truncate
+        if remaining <= 0 or not old:
+            return self._truncate(messages, target)
+
+        # Summarize old messages (extract first sentence, max 100 chars)
+        summary_parts = []
+        for msg in old:
+            content = msg.get("content", "")
+            # Get first sentence or first 100 chars
+            first_sentence = content.split(".")[0][:100]
+            if first_sentence:
+                role = "User" if msg.get("role") == "user" else "Assistant"
+                summary_parts.append(f"[{role}]: {first_sentence}...")
+
+        summary_text = "\n".join(summary_parts)
+        summary_tokens = self.estimate_tokens(summary_text)
+
+        # If summary exceeds remaining budget, fallback to truncate
+        if summary_tokens > remaining:
+            return self._truncate(messages, target)
+
+        # Combine summary with recent messages
+        summary_msg = {
+            "role": "system",
+            "content": f"[Previous conversation summary]\n{summary_text}",
+        }
+        result = [summary_msg] + recent
+
+        total_tokens = summary_tokens + recent_tokens
+        return result, CompressionStats(
+            original_tokens=original_tokens,
+            compressed_tokens=total_tokens,
+            compression_ratio=total_tokens / original_tokens
+            if original_tokens
+            else 1.0,
+            strategy_used="summarize",
+            messages_kept=len(recent),
+            messages_removed=len(old),
+        )
+
+    def get_stats_history(self) -> List[CompressionStats]:
+        """Get history of compression operations.
+
+        Returns:
+            List of CompressionStats from previous operations
+        """
+        return self._stats_history.copy()
+
+    def clear_stats_history(self) -> None:
+        """Clear compression statistics history."""
+        self._stats_history.clear()
+
+
+# Singleton accessor
+_context_condenser: Optional[ContextCondenser] = None
+
+
+def get_context_condenser(provider: str = "default") -> ContextCondenser:
+    """Get or create singleton ContextCondenser instance.
+
+    Args:
+        provider: LLM provider name (only used on first call)
+
+    Returns:
+        Singleton ContextCondenser instance
+    """
+    global _context_condenser
+    if _context_condenser is None:
+        _context_condenser = ContextCondenser(provider)
+    return _context_condenser

codebuff_core/services/pii_guardrail.py

@@ -0,0 +1,393 @@
+"""PII Guardrail — 사용자 입력에서 PII 14종을 정규식+체크섬으로 검출 후 마스킹.
+
+설계 원칙:
+- specific → generic 우선순위로 순차 in-place 마스킹 (충돌 자동 회피)
+- 매칭된 substring을 동일 길이 '*'로 교체 → 다음 패턴은 '*'를 매칭 못 함
+- 체크섬 검증으로 false positive 최소화 (Luhn / 가중치 합 체크섬)
+- 원본 PII는 로깅/저장 금지. label만 노출
+
+Reference: docs/superpowers/refs/2026-06-10-pii-regex-reference.md
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Callable, Optional
+
+
+@dataclass
+class PIIMatch:
+    """단일 PII 매치 정보."""
+
+    type_label: str
+    start: int
+    end: int
+    original: str  # debug-only, 외부 로깅 금지
+
+
+@dataclass
+class MaskResult:
+    """mask_pii 결과."""
+
+    masked_text: str
+    detected_types: list[str] = field(default_factory=list)
+    matches: list[PIIMatch] = field(default_factory=list)
+
+    @property
+    def has_pii(self) -> bool:
+        return bool(self.matches)
+
+
+# ---------------------------------------------------------------------------
+# 정규식 패턴
+# ---------------------------------------------------------------------------
+
+# 이메일 (HTML5 input validation, RFC 5322 lite)
+_EMAIL_RE = re.compile(
+    r"\b[A-Za-z0-9._%+\-]+"
+    r"@[A-Za-z0-9](?:[A-Za-z0-9\-]{0,61}[A-Za-z0-9])?"
+    r"(?:\.[A-Za-z0-9](?:[A-Za-z0-9\-]{0,61}[A-Za-z0-9])?)+\b"
+)
+
+# IPv6 — RFC 4291. dual notation 포함
+_IPV6_RE = re.compile(
+    r"(?:"
+    # full + zero-compressed
+    r"(?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}"
+    r"|(?:[0-9A-Fa-f]{1,4}:){1,7}:"
+    r"|(?:[0-9A-Fa-f]{1,4}:){1,6}:[0-9A-Fa-f]{1,4}"
+    r"|(?:[0-9A-Fa-f]{1,4}:){1,5}(?::[0-9A-Fa-f]{1,4}){1,2}"
+    r"|(?:[0-9A-Fa-f]{1,4}:){1,4}(?::[0-9A-Fa-f]{1,4}){1,3}"
+    r"|(?:[0-9A-Fa-f]{1,4}:){1,3}(?::[0-9A-Fa-f]{1,4}){1,4}"
+    r"|(?:[0-9A-Fa-f]{1,4}:){1,2}(?::[0-9A-Fa-f]{1,4}){1,5}"
+    r"|[0-9A-Fa-f]{1,4}:(?::[0-9A-Fa-f]{1,4}){1,6}"
+    r"|:(?:(?::[0-9A-Fa-f]{1,4}){1,7}|:)"
+    # dual notation (IPv4-mapped)
+    r"|::(?:[Ff]{4}(?::0{1,4})?:)?"
+    r"(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}"
+    r"(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)"
+    r"|(?:[0-9A-Fa-f]{1,4}:){1,4}:"
+    r"(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}"
+    r"(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)"
+    r")"
+)
+
+# IPv4 strict (no leading zeros) — RFC 5321 / CVE-2021-29921
+_IPV4_RE = re.compile(
+    r"\b(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}"
+    r"(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\b"
+)
+
+# MAC 주소 — IEEE 802 (콜론/하이픈) 또는 Cisco dotted
+_MAC_RE = re.compile(
+    r"\b(?:[0-9A-Fa-f]{2}[:\-]){5}[0-9A-Fa-f]{2}\b"
+    r"|\b(?:[0-9A-Fa-f]{4}\.){2}[0-9A-Fa-f]{4}\b"
+)
+
+# 한국 여권 — [MSROD] + 8 digits OR + 3 digits + letter + 4 digits
+_PASSPORT_RE = re.compile(r"\b[MSROD](?:\d{8}|\d{3}[A-Z]\d{4})\b")
+
+# 운전면허 12자리 (지역코드)
+_DL_12_RE = re.compile(r"\b(?:1[1-9]|2[0-6]|28)[\- ]\d{2}[\- ]\d{6}[\- ]\d{2}\b")
+
+# 운전면허 10자리 (2-6-2)
+_DL_10_RE = re.compile(r"\b\d{2}[\- ]\d{6}[\- ]\d{2}\b")
+
+# 신용카드 — 13~19 digits (with optional space/dash). Luhn 필수.
+_CC_RE = re.compile(r"\b\d(?:[ \-]?\d){12,18}\b")
+
+# 주민/외국인/법인등록 — 13자리 dash 형식 (validator로 disambiguate)
+_RRN_FRN_CRN_RE = re.compile(r"\b\d{6}[\- ]?\d{7}\b")
+
+# 사업자등록 — 3-2-5 dash 형식
+_BIZ_RE = re.compile(r"\b\d{3}[\- ]\d{2}[\- ]\d{5}\b")
+
+# 한국 전화번호
+# 일반: 휴대폰(010-XXXX-XXXX) / 지역(02-XXXX-XXXX, 031-XXX-XXXX) / 인터넷전화(070-XXXX-XXXX)
+# 대표번호: 1588-1234 형식 (prefix + 4-4)
+_PHONE_RE = re.compile(
+    r"\b(?:"
+    # 대표번호 (1577/1588/1599/1644 등) — prefix 4 + 4
+    r"1[5-9]\d{2}[\- ]?\d{4}"
+    # 일반 (국제 +82 옵션) — prefix + 3-4 + 4
+    r"|(?:\+?82[\- ]?)?"
+    r"(?:0?1[016789]|02|0[3-6]\d|070|050\d)"
+    r"[\- ]?\d{3,4}[\- ]?\d{4}"
+    r")\b"
+)
+
+# 건강보험 — 11자리 + 1로 시작 (low confidence)
+_HEALTH_RE = re.compile(r"\b1\d{10}\b")
+
+# 계좌번호 — dash 형식만 (last resort)
+_ACCOUNT_RE = re.compile(r"\b\d{2,6}[\- ]\d{2,6}[\- ]\d{2,6}(?:[\- ]\d{2,6})?\b")
+
+
+# ---------------------------------------------------------------------------
+# 체크섬 / 검증 함수
+# ---------------------------------------------------------------------------
+
+
+def luhn_valid(s: str) -> bool:
+    """Luhn 알고리즘 검증 (신용카드)."""
+    digits = [int(c) for c in s if c.isdigit()]
+    if not 13 <= len(digits) <= 19:
+        return False
+    checksum = 0
+    parity = len(digits) % 2
+    for i, d in enumerate(digits):
+        if i % 2 == parity:
+            d *= 2
+            if d > 9:
+                d -= 9
+        checksum += d
+    return checksum % 10 == 0
+
+
+def _valid_date(yy: int, mm: int, dd: int) -> bool:
+    """YYMMDD 기초 유효성 (월 1~12, 일 1~31). 윤년 등은 엄격 X."""
+    return 1 <= mm <= 12 and 1 <= dd <= 31
+
+
+def _rrn_frn_checksum(digits: list[int]) -> bool:
+    """주민/외국인등록 동일 체크섬 (가중치 [2,3,4,5,6,7,8,9,2,3,4,5] mod 11)."""
+    weights = [2, 3, 4, 5, 6, 7, 8, 9, 2, 3, 4, 5]
+    s_sum = sum(d * w for d, w in zip(digits[:12], weights))
+    check = (11 - s_sum % 11) % 10
+    return check == digits[12]
+
+
+def rrn_valid(s: str) -> bool:
+    """주민등록번호: 13자리 + 날짜 유효 + 7번째 자리 0/1/2/3/4/9 + 체크섬."""
+    digits = [int(c) for c in s if c.isdigit()]
+    if len(digits) != 13:
+        return False
+    yy = digits[0] * 10 + digits[1]
+    mm = digits[2] * 10 + digits[3]
+    dd = digits[4] * 10 + digits[5]
+    if not _valid_date(yy, mm, dd):
+        return False
+    # 한국인: 1/2 (1900s), 3/4 (2000s), 9/0 (1800s)
+    if digits[6] not in (0, 1, 2, 3, 4, 9):
+        return False
+    return _rrn_frn_checksum(digits)
+
+
+def frn_valid(s: str) -> bool:
+    """외국인등록번호: 7번째 자리 5/6/7/8 + 체크섬 (RRN과 동일)."""
+    digits = [int(c) for c in s if c.isdigit()]
+    if len(digits) != 13:
+        return False
+    yy = digits[0] * 10 + digits[1]
+    mm = digits[2] * 10 + digits[3]
+    dd = digits[4] * 10 + digits[5]
+    if not _valid_date(yy, mm, dd):
+        return False
+    if digits[6] not in (5, 6, 7, 8):
+        return False
+    return _rrn_frn_checksum(digits)
+
+
+def crn_valid(s: str) -> bool:
+    """법인등록번호: 13자리 + RRN/FRN 모두 fail (둘 다 형식 동일)."""
+    digits = [int(c) for c in s if c.isdigit()]
+    if len(digits) != 13:
+        return False
+    # RRN/FRN로 분류 가능하면 CRN 아님
+    if rrn_valid(s) or frn_valid(s):
+        return False
+    # 폴백: 13자리 dash 형식이면 CRN으로 분류
+    return True
+
+
+def biz_no_valid(s: str) -> bool:
+    """사업자등록번호 체크섬 (egovframe 알고리즘, 가중치 [1,3,7,1,3,7,1,3,5])."""
+    digits = [int(c) for c in s if c.isdigit()]
+    if len(digits) != 10:
+        return False
+    weights = [1, 3, 7, 1, 3, 7, 1, 3, 5]
+    s_sum = sum(d * w for d, w in zip(digits[:9], weights))
+    s_sum += (digits[8] * 5) // 10  # 9번째 × 5의 십의 자리
+    check = (10 - s_sum % 10) % 10
+    return check == digits[9]
+
+
+def account_valid(s: str) -> bool:
+    """계좌번호 후보 검증 — 날짜(YYYY-MM-DD)로 보이면 계좌번호 아님(오탐 방지).
+
+    계좌 정규식은 dash 구분 숫자(2~6자리 그룹)를 잡는 last-resort 패턴이라
+    '2026-07-23' 같은 날짜를 계좌번호로 오탐한다. 앞 3그룹이 유효한 연/월/일이면
+    계좌번호에서 제외한다. 뒤에 시각(예: '2026-07-20 03')이 붙어 4그룹이 돼도
+    날짜로 시작하면 제외한다(타임스탬프 오탐 방지).
+    """
+    parts = re.split(r"[\- ]", s.strip())
+    if len(parts) >= 3 and len(parts[0]) == 4 and parts[0].isdigit():
+        try:
+            y, mo, d = int(parts[0]), int(parts[1]), int(parts[2])
+        except ValueError:
+            return True
+        if 1900 <= y <= 2999 and 1 <= mo <= 12 and 1 <= d <= 31:
+            return False  # 날짜/타임스탬프 → 계좌 아님
+    return True
+
+
+# ---------------------------------------------------------------------------
+# 우선순위 (specific → generic)
+# ---------------------------------------------------------------------------
+
+_PATTERNS: list[tuple[str, re.Pattern, Optional[Callable[[str], bool]]]] = [
+    ("이메일", _EMAIL_RE, None),
+    ("IPv6", _IPV6_RE, None),
+    ("IPv4", _IPV4_RE, None),
+    ("MAC", _MAC_RE, None),
+    ("여권", _PASSPORT_RE, None),
+    ("운전면허", _DL_12_RE, None),  # 12자리 먼저 (longest match)
+    ("운전면허", _DL_10_RE, None),  # 10자리 폴백
+    # 13자리 dash 형식 → 신용카드(13~19 digit Luhn pass)와 우연히 겹칠 수 있어
+    # 주민/외국인/법인등록을 신용카드보다 먼저 적용 (체크섬 + 7번째 자리로 정확히 disambiguate)
+    ("주민등록번호", _RRN_FRN_CRN_RE, rrn_valid),
+    ("외국인등록번호", _RRN_FRN_CRN_RE, frn_valid),
+    ("법인등록번호", _RRN_FRN_CRN_RE, crn_valid),
+    ("신용카드", _CC_RE, luhn_valid),
+    ("사업자등록번호", _BIZ_RE, biz_no_valid),
+    ("전화번호", _PHONE_RE, None),
+    ("건강보험", _HEALTH_RE, None),
+    ("계좌번호", _ACCOUNT_RE, account_valid),
+]
+
+
+# ---------------------------------------------------------------------------
+# 도구 결과 모드 — 문맥 검증 (이슈 #155)
+# ---------------------------------------------------------------------------
+#
+# 도구 결과(파일 내용·명령 출력·쿼리 결과)에는 식별자 숫자가 흔하다. 체크섬이 없는
+# 건강보험(11자리)은 그런 숫자를 전부 잡고, 19자리 snapshot_id 는 10% 확률로 Luhn 을
+# 통과한다. 그래서 도구 결과에서만 두 유형에 문맥 조건을 더한다. 사용자 입력은
+# 기본 모드 그대로다 — 사람이 직접 친 번호는 문맥 없이도 가린다.
+
+# 문맥을 보는 범위 — 같은 줄의 앞뒤 이만큼
+_CONTEXT_CHARS = 40
+_CARD_CONTEXT_RE = re.compile(
+    # `pan_no`·`PAN_ID` 도 잡도록 `_` 를 낱말 경계로 본다 (`\b` 는 `_` 를 낱말로 본다)
+    r"카드|신용|결제|card|credit|(?<![a-z])pan(?![a-z])|(?<![a-z])cc_?(?:no|num)",
+    re.I,
+)
+_HEALTH_CONTEXT_RE = re.compile(r"건강보험|건보|보험증|증번호|nhis|health|insur", re.I)
+# 이 낱말로 끝나는 키 바로 뒤의 숫자는 식별자다 (`snapshot_id": `, `seq=`)
+_ID_KEY_WORDS = frozenset(
+    {
+        "id",
+        "ids",
+        "snapshot",
+        "seq",
+        "sequence",
+        "offset",
+        "timestamp",
+        "ts",
+        "epoch",
+        "version",
+        "hash",
+        "nonce",
+        "trace",
+        "span",
+        "commit",
+    }
+)
+_KEY_BEFORE_VALUE_RE = re.compile(r"([A-Za-z][A-Za-z0-9_]*)[\"']?\s*[:=]\s*[\"']?$")
+
+
+def _context(text: str, start: int, end: int) -> tuple[str, str]:
+    """매치 앞뒤로 같은 줄 안의 `_CONTEXT_CHARS` 글자."""
+    line_start = text.rfind("\n", 0, start) + 1
+    line_end = text.find("\n", end)
+    if line_end < 0:
+        line_end = len(text)
+    before = text[max(line_start, start - _CONTEXT_CHARS) : start]
+    after = text[end : min(line_end, end + _CONTEXT_CHARS)]
+    return before, after
+
+
+def _after_id_key(before: str) -> bool:
+    m = _KEY_BEFORE_VALUE_RE.search(before)
+    if not m:
+        return False
+    key = re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", m.group(1)).lower()
+    return any(part in _ID_KEY_WORDS for part in key.split("_"))
+
+
+def _tool_output_skip(label: str, text: str, start: int, end: int) -> bool:
+    """도구 결과에서 이 매치를 PII 로 보지 않을 것인가."""
+    if label not in ("신용카드", "건강보험"):
+        return False
+    before, after = _context(text, start, end)
+    if label == "건강보험":
+        # 체크섬이 없다 — 건강보험 문맥이 있을 때만 가린다
+        return not (
+            _HEALTH_CONTEXT_RE.search(before) or _HEALTH_CONTEXT_RE.search(after)
+        )
+    if _CARD_CONTEXT_RE.search(before) or _CARD_CONTEXT_RE.search(after):
+        return False
+    digits = text[start:end]
+    if not digits.isdigit():
+        return False  # 구분자(공백·대시)로 끊어 쓴 번호는 카드 표기다
+    # 구분자 없는 17~19자리는 카드보다 식별자(int64 등)가 흔하다
+    return len(digits) >= 17 or _after_id_key(before)
+
+
+# ---------------------------------------------------------------------------
+# Main API
+# ---------------------------------------------------------------------------
+
+
+def mask_pii(text: str, tool_output: bool = False) -> MaskResult:
+    """텍스트에서 PII를 검출하여 동일 길이 '*'로 마스킹한 결과 반환.
+
+    우선순위 순서대로 정규식 + 체크섬 적용. 한 패턴이 매칭하면 그 substring을
+    즉시 '*'로 치환 → 다음 패턴은 그 자리를 재매칭 못 함.
+
+    Args:
+        text: 입력 텍스트
+        tool_output: 도구 결과(파일·명령 출력)면 True. 카드·건강보험에 문맥 조건을
+            더해 식별자 숫자 오탐을 줄인다 (`_tool_output_skip`, 이슈 #155)
+
+    Returns:
+        MaskResult(masked_text, detected_types, matches)
+    """
+    if not text or not text.strip():
+        return MaskResult(masked_text=text)
+
+    buf = list(text)
+    matches: list[PIIMatch] = []
+    seen_labels: list[str] = []
+
+    for label, regex, validator in _PATTERNS:
+        current = "".join(buf)
+        for m in regex.finditer(current):
+            substr = m.group(0)
+            if validator is not None and not validator(substr):
+                continue
+            start, end = m.start(), m.end()
+            if tool_output and _tool_output_skip(label, current, start, end):
+                continue
+            # 이미 마스킹된 영역은 skip (방어)
+            if all(buf[i] == "*" for i in range(start, end)):
+                continue
+            for i in range(start, end):
+                buf[i] = "*"
+            matches.append(
+                PIIMatch(
+                    type_label=label,
+                    start=start,
+                    end=end,
+                    original=substr,
+                )
+            )
+            if label not in seen_labels:
+                seen_labels.append(label)
+
+    return MaskResult(
+        masked_text="".join(buf),
+        detected_types=seen_labels,
+        matches=matches,
+    )