<!-- source-hash: 39498ad7a2e0f9d7ad0f6c8c114b7a36 -->
Utility module for extracting, formatting, and rendering tool call metadata — titles, command bodies, argument values, and execution results — in a human-readable form for approval and execution cards.

## Key Components

### Constants

- **`COMMAND_BODY_ARG_KEYS`** — Ordered list of argument keys (`command`, `query`, `script`, `scriptContent`, `code`) used to locate the primary command body in a tool call's argument map.

### Functions

- **`getToolCallTitle(opts)`** — Resolves a human-readable title for a tool call. Falls through `COMMAND_BODY_ARG_KEYS` → `title` → `name` → `'Tool call'`. Shape-agnostic; works for both `PendingToolCallData` and `ToolExecutionData`.
- **`getCommandText(call)`** — Thin adapter over `getToolCallTitle` for `PendingToolCallData` objects.
- **`getCommandBody(args)`** — Returns only the raw command body (first `COMMAND_BODY_ARG_KEYS` match), with no fallback. Used by the Fae client card's expanded view.
- **`expandedJsonStringify(value)`** — Pretty-prints JSON with real newlines instead of escaped `\n` sequences in multi-line strings. Optimised for human readability, not re-parsing.
- **`formatToolArgValue(value)`** — Determines render mode for a single argument value: JSON block, text block, or inline string.
- **`formatToolResult(value)`** — Determines render mode for a tool execution result. Strips markdown code fences, then applies the same JSON/block/inline logic as `formatToolArgValue`.

### Types

- **`FormattedArgValue`** — Discriminated union: `{ kind: 'inline'; text: string }` or `{ kind: 'block'; text: string; language: 'json' | 'text' }`.

## Usage Example

```typescript
import {
  getCommandText,
  getCommandBody,
  formatToolArgValue,
  formatToolResult,
} from './tool-call-helpers'

// Resolve display title for an approval card
const title = getCommandText({
  toolName: 'bash',
  toolTitle: null,
  toolCallArguments: { command: 'ls -la /var/log' },
})
// → 'ls -la /var/log'

// Render an argument value
const formatted = formatToolArgValue('{"key": "value\nwith newline"}')
// → { kind: 'block', text: '...', language: 'json' }

// Render a tool execution result (strips fences, detects JSON)
const result = formatToolResult('```bash\n{"status": "ok"}\n```')
// → { kind: 'block', text: '{\n  "status": "ok"\n}', language: 'json' }
```

**Source:** [`tool-call-helpers.ts`](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/tool-call-helpers.ts)