Align Go/JS tool-call parsing semantics and compat fixtures

docs/toolcall-semantics.md

@@ -0,0 +1,40 @@
+# Tool call parsing semantics (Go canonical spec)
+
+This document defines the cross-runtime contract for `ParseToolCallsDetailed` / `parseToolCallsDetailed`.
+
+## Output contract
+
+- `calls`: accepted tool calls with normalized tool names.
+- `sawToolCallSyntax`: true when tool-call-like syntax is detected (`tool_calls`, `<tool_call>`, `<function_call>`, `<invoke>`) or a valid call is parsed.
+- `rejectedByPolicy`: true when parser extracted call syntax but all calls are rejected by allow-list policy.
+- `rejectedToolNames`: de-duplicated rejected tool names in first-seen order.
+
+## Parse pipeline
+
+1. Strip fenced code blocks for non-standalone parsing.
+2. Build candidates from:
+   - full text,
+   - fenced JSON snippets,
+   - extracted JSON objects around `tool_calls`,
+   - first `{` to last `}` object slice.
+3. Parse each candidate in order:
+   - JSON payload parser (`tool_calls`, list, single call object),
+   - markup parser (`<tool_call>`, `<function_call>`, `<invoke>`; supports attributes + nested fields).
+4. Stop at first candidate that yields at least one call.
+
+## Name normalization policy
+
+When matching parsed names against configured tools:
+
+1. exact match,
+2. case-insensitive match,
+3. namespace tail match (`a.b.c` => `c`),
+4. loose alnum match (remove non `[a-z0-9]`, compare).
+
+## Standalone mode
+
+Standalone mode (`ParseStandaloneToolCallsDetailed`) parses the whole input directly (no candidate slicing), while still applying:
+
+- example-context guard,
+- JSON then markup fallback,
+- the same allow-list normalization policy.