agentgrep(feat[mcp]): Add a human filter to the MCP search tool

why: The human: distinction was queryable from the CLI but not over MCP — the
search tool had no way to keep user-typed prompts or isolate tool output.

what:
- Add an optional human ("true"|"false") parameter to the MCP search tool and
  SearchRequestModel; "true" keeps user-typed turns, "false" keeps tool/agent
  output, omitted keeps both.
- Thread it through the page cursor so paginated human-filtered searches stay
  consistent.

Author: tony

src/agentgrep/mcp/models.py

@@ -227,6 +227,7 @@ class SearchRequestModel(AgentGrepModel):
     cwd: str | None = None
     repo: str | None = None
     branch: str | None = None
+    human: t.Literal["true", "false"] | None = None
 
 
 class SearchToolResponse(AgentGrepModel):

src/agentgrep/mcp/refs.py

@@ -45,6 +45,7 @@ class _SearchCursorPayload(t.TypedDict):
     cwd: str | None
     repo: str | None
     branch: str | None
+    human: str | None
 
 
 class _FindCursorPayload(t.TypedDict):
@@ -79,6 +80,7 @@ class SearchCursor:
     cwd: str | None = None
     repo: str | None = None
     branch: str | None = None
+    human: str | None = None
 
 
 @dataclasses.dataclass(frozen=True, slots=True)
@@ -245,6 +247,7 @@ def make_search_cursor(
     cwd: str | None = None,
     repo: str | None = None,
     branch: str | None = None,
+    human: str | None = None,
 ) -> str:
     """Build an opaque cursor for the next search page."""
     return _encode_token(
@@ -263,6 +266,7 @@ def make_search_cursor(
                 cwd=cwd,
                 repo=repo,
                 branch=branch,
+                human=human,
             ),
         ),
     )
@@ -313,6 +317,8 @@ def parse_search_cursor(cursor: str) -> SearchCursor:
     if branch is not None and not isinstance(branch, str):
         msg = "cursor branch must be a string or null"
         raise McpTokenError(msg)
+    human_raw = payload.get("human")
+    human = human_raw if human_raw in ("true", "false") else None
     return SearchCursor(
         offset=offset,
         terms=t.cast("list[str]", terms),
@@ -323,6 +329,7 @@ def parse_search_cursor(cursor: str) -> SearchCursor:
         cwd=cwd,
         repo=repo,
         branch=branch,
+        human=t.cast("str | None", human),
     )
 
 

src/agentgrep/mcp/tools/search_tools.py

@@ -86,6 +86,7 @@ def _request_from_cursor(request: SearchRequestModel) -> tuple[SearchRequestMode
             cwd=cursor.cwd,
             repo=cursor.repo,
             branch=cursor.branch,
+            human=t.cast("t.Literal['true', 'false'] | None", cursor.human),
         ),
         cursor.offset,
     )
@@ -193,6 +194,16 @@ async def _search_async(
             records.append(t.cast("SearchRecordLike", event.record))
         elif isinstance(event, ag_events.SearchFinished):
             matched = max(matched, event.match_count)
+    if effective_request.human is not None:
+        # Adapters tag tool/assistant output with human_typed=False; a missing
+        # tag means a user-typed turn (the same rule the ``human:`` query field uses).
+        want_human = effective_request.human == "true"
+        records = [
+            record
+            for record in records
+            if ((getattr(record, "metadata", None) or {}).get("human_typed", True) is not False)
+            == want_human
+        ]
     # The inline execution driver emits records per source, not in final
     # result order; restore the newest-first contract the list-returning
     # search path guarantees before building the response.
@@ -214,6 +225,7 @@ async def _search_async(
                 cwd=effective_request.cwd,
                 repo=effective_request.repo,
                 branch=effective_request.branch,
+                human=effective_request.human,
             )
             if has_more
             else None
@@ -331,6 +343,16 @@ async def search_tool(
                 description="Only return records whose recorded git branch matches this name.",
             ),
         ] = None,
+        human: t.Annotated[
+            t.Literal["true", "false"] | None,
+            Field(
+                default=None,
+                description=(
+                    "Filter by who authored the turn: 'true' keeps user-typed prompts, "
+                    "'false' keeps tool/assistant output. Omit to keep both."
+                ),
+            ),
+        ] = None,
     ) -> SearchToolResponse:
         request = SearchRequestModel(
             terms=terms or [],
@@ -342,6 +364,7 @@ async def search_tool(
             cwd=cwd,
             repo=repo,
             branch=branch,
+            human=human,
         )
         return await _search_async(request, runtime=runtime)
 

tests/test_agentgrep_mcp.py

@@ -590,6 +590,61 @@ async def test_mcp_search_rejects_invalid_query() -> None:
     assert "agent" in error_message
 
 
+async def test_mcp_search_tool_human_filter(
+    tmp_path: pathlib.Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """The MCP search ``human`` filter keeps user-typed prompts vs tool/agent output."""
+    agentgrep_mcp = load_agentgrep_mcp_module()
+    home = tmp_path / "home"
+    monkeypatch.setenv("HOME", str(home))
+
+    session_path = home / ".codex" / "sessions" / "2026" / "01" / "01" / "rollout.jsonl"
+    write_jsonl(
+        session_path,
+        [
+            {
+                "timestamp": "2026-01-01T00:00:00Z",
+                "type": "session_meta",
+                "payload": {"id": "session-h", "model_provider": "openai"},
+            },
+            {
+                "timestamp": "2026-01-01T00:00:01Z",
+                "type": "response_item",
+                "payload": {
+                    "type": "message",
+                    "role": "user",
+                    "content": [{"type": "input_text", "text": "deploy the widget service"}],
+                },
+            },
+            {
+                "timestamp": "2026-01-01T00:00:02Z",
+                "type": "response_item",
+                "payload": {
+                    "type": "function_call_output",
+                    "output": "widget service: installed 11 packages",
+                },
+            },
+        ],
+    )
+
+    async with Client(agentgrep_mcp.build_mcp_server()) as client:
+        kept = await client.call_tool(
+            "search",
+            {"terms": ["widget"], "agent": "codex", "scope": "all", "human": "true", "limit": 5},
+        )
+        dropped = await client.call_tool(
+            "search",
+            {"terms": ["widget"], "agent": "codex", "scope": "all", "human": "false", "limit": 5},
+        )
+
+    human_data = t.cast("SearchToolDataLike", kept.data)
+    tool_data = t.cast("SearchToolDataLike", dropped.data)
+    # human:true keeps the typed prompt; human:false excludes it.
+    assert any("deploy the widget service" in r.text for r in human_data.results)
+    assert all("deploy the widget service" not in r.text for r in tool_data.results)
+
+
 async def test_mcp_search_tool_sorts_records_across_sources(
     tmp_path: pathlib.Path,
     monkeypatch: pytest.MonkeyPatch,