Log the turn to history
log_interactionRecords each completed turn with the exact final answer, verbatim user request, workspace, and persona attribution to history and Langfuse tracing sinks.
Instructions
End-of-turn logger. Compose the answer including its footer, call this tool with that exact response_content, then deliver the final answer. Pass the current user request verbatim as query, without paraphrasing or substituting a conversation summary, and workspace, your working directory.
persona: the `persona` object of the last SUCCESS/NO_CHANGE, copied verbatim
with all 7 keys (agent, activation_id, bundle_revision, scope, skills_loaded,
implants_loaded, rules_loaded); persona_action (keep/switch/refresh/restore)
only together with it. Compact subagents return their data envelope without
calling this tool. Other callers without a retained descriptor omit both and
add no footer; this does not waive initial activation. files/tags are JSON arrays.
Persona and persona_action are client-reported attribution, not proof of
instruction compliance. A partial, malformed or mismatching persona never
costs the turn: it is written marked ``unverified`` or ``mismatch`` and the
response carries ``warnings``. Do not retry such a call.
Two sinks, independent of each other:
* **history.md** — written via ``HistoryWriter`` (append-only, content-hash
deduped; the persona line is not part of the hash). Defaults:
``intent=query``, ``action="Agent: {agent_name}"``, ``outcome=response_content``.
Pass ``intent``/``action``/``outcome``/``files``/``tags`` to curate the entry.
* **Langfuse** — generation trace recorded only when ``LANGFUSE_PUBLIC_KEY`` /
``LANGFUSE_SECRET_KEY`` are configured; otherwise the call is a no-op via
``langfuse_compat``.
Returns at once, before either sink is written:
``{request_id, timestamp, langfuse: {status: "queued"}, history: {status: "queued"}}``
plus ``workspace`` (``root``, ``source``), ``pid``, ``history_last_error``
(``code``, ``errno``, ``path``, ``at``; only after an earlier history write
failed) and the attribution (with ``warnings`` and an ``instruction`` when it
was incomplete). While retrieval is still warming up, ``langfuse`` is
``{status: "skipped", reason: "warming_up"}`` and no trace is recorded. ``timestamp`` is the server's local time
(``YYYY.MM.DD HH:MM:SS``); the final answer starts with it on its own line,
and it is not part of ``response_content``. The sinks are written in the
background with that timestamp and do not prevent each other; a full queue
can also drop a write. A failed history write is logged once per path and
errno (WARNING, ``code=history_unwritable``) and reported on the next result
as ``history_last_error``; Langfuse failures are only logged. When no project
resolves, the turn goes to the installation's fallback journal (#292):
``workspace`` is ``{root: null, source: "fallback", claimed, reason, journal}``,
``claimed`` the directory the client named (recorded, never written), and the
``instruction`` says to mention it once. The only request-level rejection left
is a stdio client with MCP roots that named no workspace, asked to retry once
with it, or a fallback journal directory that cannot be created (a later write
failure shows as ``history_last_error``): a protocol ERROR without
``timestamp``, over stdio with ``pid`` and ``workspace_inputs`` (``cwd``,
``claude_project_dir``, ``agents_client_repo_root``, ``client``, ``roots``).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional tags, as a JSON array of strings, e.g. ["bug", "fix"]. | |
| files | No | Optional files touched, as a JSON array of paths, e.g. ["src/a.py"]. | |
| query | Yes | The current user request, verbatim. | |
| action | No | Optional curated action; defaults to the agent name. | |
| intent | No | Optional curated intent; defaults to query. | |
| outcome | No | Optional curated outcome; defaults to response_content. | |
| persona | No | The `persona` object of the last SUCCESS/NO_CHANGE, copied verbatim, with all 7 keys: agent, activation_id, bundle_revision (64 hex characters), scope, skills_loaded, implants_loaded, rules_loaded. Without a retained descriptor omit both persona and persona_action. Incomplete values are still logged, marked unverified. | |
| reasoning | No | Optional short reason for the selection. | |
| workspace | No | Absolute path of your working directory, the project this session works in. Pass it whenever you have one: one server can serve several sessions. | |
| agent_name | Yes | Canonical name of the active agent. | |
| request_id | No | Optional request id for correlation. | |
| persona_action | No | One of keep, switch, refresh, restore; send it only together with persona. | |
| response_content | Yes | The exact final answer text, without any time line. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |