fix: spec v3.1 conformance (tool optional, comma quoting, attachment fixes)

- tool field optional in graph profile header (v3.1)
- Quote strings containing commas in needs_quote
- Decode v2-format indented attachments in tabular rows
- Reject duplicate attachments on the same row

Author: blackwell-systems

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v2.1.0 (2026-06-14)
+
+### Spec v3.1
+
+- `tool` field in graph profile header is now optional (SHOULD be present for MCP, not required)
+
+### Bug Fixes
+
+- Quote strings containing commas (conformance: `inline-schema/006_inline_with_quoted_values`)
+- Decode v2-format indented attachments in tabular rows (conformance: `decode/002_attachment`)
+- Reject duplicate attachments on the same row (conformance: `errors-v2/027_duplicate_attachment`)
+
 ## v2.0.0 (2026-06-12)
 
 ### Breaking Changes

src/gcf/decode.py

@@ -34,8 +34,7 @@ def decode(input_text: str) -> Payload:
         raise DecodeError(f"invalid header, expected 'GCF ...' got {header!r}")
     _parse_header(header[4:], p)
 
-    if not p.tool:
-        raise DecodeError("missing_tool: header missing required 'tool' field")
+    # v3.1: tool field is optional (SHOULD be present for MCP tool responses, not required).
 
     # Detect delta mode.
     is_delta = "delta=true" in header

src/gcf/decode_generic.py

@@ -442,6 +442,10 @@ def _parse_tabular_body(
                 if a_content is None:
                     break
 
+                # Handle v2 indented attachments: strip one extra indent level.
+                if not a_content.startswith(".") and a_content.startswith("  ."):
+                    a_content = a_content[2:]
+
                 # Line starts with ".": traditional or prefixed inline.
                 if a_content.startswith("."):
                     rest = a_content[1:]
@@ -459,6 +463,8 @@ def _parse_tabular_body(
                             p = parse_scalar(inline_vals[k], tabular_context=True)
                             if p is not MISSING:
                                 obj[inf] = p
+                        if att_name in attachment_values:
+                            raise ValueError(f"duplicate_attachment: {att_name}")
                         attachment_values[att_name] = obj
                         i += 1
                         continue
@@ -469,6 +475,8 @@ def _parse_tabular_body(
                     )
                     if not rows and parsed_fields:
                         shared_array_schemas[att_name_t] = parsed_fields
+                    if att_name_t in attachment_values:
+                        raise ValueError(f"duplicate_attachment: {att_name_t}")
                     attachment_values[att_name_t] = att_val
                     i += consumed
                     continue
@@ -503,6 +511,19 @@ def _parse_tabular_body(
                 if f not in attachment_values:
                     raise ValueError(f"missing_attachment: {f}")
 
+            # Check for extra attachment lines after all fields resolved (duplicate).
+            if i < len(lines):
+                extra_line = lines[i]
+                extra_content = ""
+                if depth == 0 or extra_line.startswith(ind):
+                    extra_content = extra_line[len(ind):] if depth > 0 else extra_line
+                if not extra_content.startswith(".") and extra_content.startswith("  ."):
+                    extra_content = extra_content[2:]
+                if extra_content.startswith("."):
+                    extra_name, _ = _parse_attachment_name(extra_content[1:])
+                    if extra_name in attachment_values:
+                        raise ValueError(f"duplicate_attachment: {extra_name}")
+
         if not row_has_id or not all_att_fields:
             att_indent = ind + "  "
             if i < len(lines) and lines[i].startswith(att_indent):

src/gcf/scalar.py

@@ -38,7 +38,7 @@ def needs_quote(s: str) -> bool:
         return True
     for c in s:
         o = ord(c)
-        if c in ('"', "\\", "|") or o < 0x20 or c in ("\n", "\r"):
+        if c in ('"', "\\", "|", ",") or o < 0x20 or c in ("\n", "\r"):
             return True
         # C1 control characters
         if 0x80 <= o <= 0x9F: