Agent Semantic Protocols

Agent Semantic Protocols

[!IMPORTANT] Generated by asp hook install from the repository root SKILL.md template and the current provider activation. Do not edit this installed copy. Edit root SKILL.md or asp.toml, then rerun asp hook install --client <client> ..

ASP Explorer Subagent

When a hook deny message or search pipe output points to asp-explorer, Codex should reuse the ASP search agent thread already opened for the current main task. If no such thread exists, call spawn_agent with fork_turns="none" and include a self-contained ASP Explorer branch prompt plus the safe ASP command group in the message. Keep model, reasoning, and agent-type defaults in Codex config, not in the prompt. Spawn one read-only instance per independent actionFrontier or targetActions branch, and require a compact [asp-search-subagent] role=... action=... evidence=... missing=... next=... risk=... receipt.

Keep reasoning state in the parent. asp-explorer workers receive only the explicit branch prompt through fork_turns="none", do not share sibling context, must not edit files, and must not spawn child subagents. If the custom subagent remains open, reuse it with send_input so it keeps its own thread history. If the custom subagent is unavailable, run the same ASP routes sequentially and synthesize the receipts in the parent.

asp hook install --client codex . registers the role in project Codex config, but a thread that was already running before install may need a reload or new thread before spawn_agent lists asp_explorer.

Provider Activation

This root SKILL.md is the embedded template source used by asp hook install. The installed copy under .agents/skills/agent-semantic-protocols/SKILL.md is rendered from this template plus the current hook activation. Do not hard-code the active language list here: activation is owned by provider binary detection and asp.toml.

Active Providers

Detected from provider binaries plus asp.toml; only activated languages are listed.

Start with asp <language> guide . when a task needs the provider-owned tool map. Use asp providers or asp doctor when the active language or provider binary is unclear. The root asp search and asp query forms are thin routers: use --language <id> when the project root is ambiguous, or pass an owner/selector path or project root that matches one active provider's activation coverage so the root facade can route to the same asp <language> search|query boundary.

Document languages use the same facade shape but are not policy harnesses: asp org <guide|search|query> ... and asp md <guide|search|query> ... run the native orgize document provider inside asp. Use them for parser-owned document elements and metadata navigation. Normal document query must be explicit and element-oriented, such as --term or --selector with --view metadata; use --kind and --field to narrow parser-owned elements without post-processing. Add --content only when the same explicit query should print the matched element content instead of metadata. Source-preserved document reads are only a hook recovery surface through --from-hook direct-source-read. check, ast-patch, and evidence are intentionally unsupported for document files.

Rules

• Use the asp <language> facade for agent exploration; provider binaries are implementation/debug surfaces.
• Do not move language path-context resolution into asp. The facade may locate a provider project hint from that language's marker file, such as Cargo.toml, tsconfig.json, package.json, pyproject.toml, or Project.toml, but it must not parse package membership, project references, virtual environments, source/test roots, or language layout. Cargo context resolution belongs to rs-harness; TypeScript, Python, and Julia path context resolution belongs to their provider binaries. PRJ_CACHE_HOME and git toplevel .cache only select state storage.
• Do not add --json during agent exploration. --json is for schema tests, validators, receipts, and IDE integrations.
• When a search/query term contains shell metacharacters copied from docs or code, such as backticks, pipes, $, globs, braces, or spaces, pass it as a single-quoted argv literal. If the text itself contains single quotes, narrow it into separate safe terms or use a provider-documented file/stdin surface; do not interpolate raw prose into a shell command.
• asp hook install --client codex . installs hooks, provider activation, and the rendered skill for the detected providers.
• Search and non-code query are discovery surfaces and should not inline source code.
• Direct source reads are last-mile transport for exact, source-preserved text after a parser-owned frontier has selected the locator. Do not use direct-source-read for discovery, owner mapping, import scanning, symbol search, or "show me this file" habits.
• --view metadata is document-only and only valid for asp org query and asp md query. Do not use it with code providers such as Python, Rust, TypeScript, or Julia; use search ... --view seeds for discovery and query <owner-path> --term <symbol> --code or --names-only for code extraction.
• Query with --code is for exact or unique code extraction.
• Tree-sitter-compatible query is the syntax base; native parser facts enrich the capture/frontier. When syntax shape matters, use the tree-sitter guide and locator query before falling back to source-preserved direct read.
• Hook config may disable provider ast-patch; when disabled, patch with apply_patch after exact locator/code evidence.

Complex Flows

Command Selection Ladder

For code tasks, keep the command order structural-first:

asp search --language <language> prime --workspace <workspace-root> --view seeds
asp query --language <language> --treesitter-query '<pattern>' .
asp <language> search prime --workspace <workspace-root> --view seeds
asp <language> search pipe '<question-or-feature-term>' --workspace <workspace-root> --view seeds
asp <language> search fzf '<term-or-error>' owner tests --view seeds .
asp fd -query '<owner-or-path-term-a|term-b|term-c>' <scope>
asp rg -query '<content-or-error-term-a|term-b|term-c>' <scope>
asp <language> search owner <owner-path> items --query '<symbol-or-a|b|c>' --view seeds .
asp <language> query --selector <path:start-end> --workspace <workspace-root> --code

For a concrete deep question, bug, feature, or API-usage task, use search prime once to establish the project graph context, then use search pipe with an LLM-generated question-or-feature-term and read its queryPack, queryTerms, globalCoverage, pathCoverage, declarationCoverage, strongCoverage, symbolTextCoverage, clauseCoverage, ownerCoverage, packageCohesion, queryQuality, handles, rankedEvidence, evidenceFrontier, commandHandles, treeSitterHandles, optional fdPreview, actionRank, actionFrontier, recommendedNext, optional subagentHint, nextCommand, nextClasses, and avoid lines. --source changes only candidate acquisition: auto is the default, provider avoids finder, finder uses bounded lexical recall, and ingest normalizes stdin candidates. ASP does not model-expand the seed query. When more owner/path recall is needed, low-quality pipe output may include bounded fdPreview rows with ownerCandidates, packageClusters, parserIndexNext, and rgScopeNext; use those preview facts before running a separate asp fd -query. Use owner-local item queries and tree-sitter locator output only when the pipe action frontier asks for them. Do not follow a code selector when queryQuality=low or the output says query-selector-low-confidence; use recommendedNext and the ranked A* action rows, normally owner-items, rg-query, treesitter-query, or query-pack refinement, instead. When subagentHint is present it is advisory: client runtimes with subagents may delegate the named targetActions to a read-only explorer, while runtimes without subagents should follow the same recommendedNext sequentially. A single broad clause can have strong declaration coverage while still being low quality; split it into 2-4 short clauses before reading code. Only after an exact selector is known and the frontier permits query-selector should stdout become source text through query --selector ... --code.

Hook Recovery

When a hook blocks a raw source read or broad raw search, follow the recovery route printed in the hook message. Do not retry Read, cat, sed, rg, or source-dump commands on the same matched source. Treat any direct-source-read route as a bounded fallback, not the default next step. First try the structural recovery path that matches the blocked intent:

asp <language> search pipe '<blocked question-or-feature-term>' --workspace <workspace-root> --source finder --view seeds
asp <language> search fzf '<term-or-error>' owner tests --view seeds .
asp fd -query '<owner-or-path-term-a|term-b|term-c>' <scope>
asp rg -query '<content-or-error-term-a|term-b|term-c>' <scope>
asp <language> search owner <owner-path> items --query '<symbol-or-a|b|c>' --view seeds .
asp <language> query <owner-path> --term '<candidate>' --names-only .
asp <language> query --treesitter-query '<pattern>' .
asp <language> query --selector <exact-path-or-range> --treesitter-query '<narrow-pattern>' --workspace <workspace-root> --code
asp <language> query --from-hook direct-source-read --selector <exact-path-or-range> --workspace <workspace-root> --code
asp org query --from-hook direct-source-read --selector <path-or-range> .
asp md query --from-hook direct-source-read --selector <path-or-range> .

Use direct-source-read --code only when the exact selector is already known and source preservation matters, such as a small file-header import window, staged/index/head source-version inspection, or a provider-selected read-plan frontier that cannot be expressed as a syntax query. If the selector is a whole file, glob, package root, or broad line range, ask the provider for owner items, tree-sitter locator output, or a read-plan frontier instead of printing code.

For document languages, do not add --content to direct-source-read. Use query --content only as a filtered element-content projection with --selector, --term, --kind, or --field; use direct-source-read only after an exact selector is known and source-preserved text is required.

Search Before Code

asp search --language <language> prime --workspace <workspace-root> --view seeds
asp <language> search prime --workspace <workspace-root> --view seeds
asp <language> search pipe '<seed-query>' --workspace <workspace-root> --view seeds
asp fd -query '<term1|term2|term3>' .
asp rg -query '<term1|term2|term3>' .
asp <language> search owner <owner-path> items --query '<seed-query>' --view seeds .
asp <language> query <owner-path> --term <candidate> --names-only .
asp <language> query --treesitter-query '<pattern>' .
asp <language> query <owner-path> --term <candidate> --code .

Use --names-only for broad owner-local prefixes before requesting code. Within one task session, do not repeat asp <language> search pipe ... for the same concrete term or asp <language> search prime --workspace <workspace-root> --view seeds for the same language/root after a fresh frontier is already available. Reuse that frontier and move to the emitted selector, owner, tests, read-plan, fd -query, rg -query, or query-code action unless the project root, language provider state, search scope, or requested --source has changed.

Reasoning Search Profiles

Use asp <language> search guide . as the source of truth for current reasoning profiles. Its command= rows are executable shapes. Do not reconstruct reasoning commands from entries= text as positional arguments.

When search prime or search fzf exposes a reasoning frontier, run the matching profile with explicit flags before falling back to broad query or direct-source-read:

asp <language> search reasoning owner-query --owner <owner-path> --query '<term>' --view seeds .
asp <language> search reasoning owner-tests --owner <owner-path> --view seeds .
asp <language> search reasoning query-deps --query '<term>' --dependency '<pkg>' --view seeds .
asp <language> search reasoning finding-frontier --query '<finding-term>' --owner <owner-path> --view seeds .
asp <language> search reasoning feature-cfg --query '<feature-name>' --view seeds .

Invalid shapes such as search reasoning owner-query <path> <term> or search reasoning owner-query --owner <path> waste turns. If the required flags are unclear, ask search guide for the profile command instead of guessing.

Failure Frontier Search

When a check or test failure has already produced a compact failure transcript, project it into hot selectors before reading code:

asp <language> check changed --view seeds .
asp <language> check --changed --view seeds .
asp <language> search failure --message '<failure text>' --view seeds .
asp <language> search failure --from-last-check --view seeds .
asp <language> search failure --message '<failure text>' --view graph-turbo-request .
asp <language> query --selector <hot-block-selector> --code .

search failure stdout is a search surface, not a source surface. It should start with [search-failure] and return failure facts, candidate owners, hot blocks, query profiles, frontier actions, and avoid guidance. Follow only the hot block selectors in frontierActions for code reads. check ... --view seeds is the same failure-frontier projection after a failing provider check; it strips ASP projection flags before provider execution and then renders the last-check transcript through asp-graph-turbo with profile=failure-frontier. Use --view graph-turbo-request only to debug the typed request packet sent to the ranking engine. Do not recover a failure by manually scanning repeated 100-line windows.

Document Element Search

Start from the document guide when you need the element and field vocabulary:

asp org guide .
asp org query guide .
asp md guide .
asp md query guide .

asp org search prime --view seeds .
asp org search toc .
asp org query --term <heading-property-task-or-table-term> --view metadata .
asp org query --term <heading-property-task-or-table-term> --content .
asp org query --kind <element-kind> --view metadata .
asp org query --field <key=value> --view metadata .
asp org query --selector <path:start-end> --view metadata .
asp md search prime --view seeds .
asp md search toc .
asp md query --term <heading-paragraph-task-link-or-table-term> --view metadata .
asp md query --term <heading-paragraph-task-link-or-table-term> --content .
asp md query --kind paragraph --view metadata .
asp md query --field <key=value> --view metadata .
asp md query --selector <path:start-end> --view metadata .

Document search and query return parser-owned element facts: headings, paragraphs, properties, planning rows, tables, blocks, lists, tasks, links, and images. Use search toc as the repository documentation entrypoint: it returns only document heading outlines grouped by file, with level, title, range locators, and selector-query next actions. Use selector query for the element frontier inside a known range. Use --content when stdout should be only the matched element content. Use direct-source-read only when source-preserved document text is required after that range is known.

Document query is an intersection of explicit axes:

• --term <term> searches element kind, source kind, path, text/content, field keys, and field values.
• --selector <path:start-end> narrows to elements overlapping a known range.
• --kind <element-kind> narrows to an exact element kind.
• --field <key> or --field <key=value> narrows to parser-owned fields; the value match is substring-based.

Org element fields are parser-owned by orgize:

• heading: level, title, todo, todoType, priority, tag
• property: key, value
• planning: scheduled, deadline, closed
• table: header
• block: kind=source|export, lang, backend
• list: listKind, descriptive
• listItem: bullet, indent, counter, tag
• task: bullet, indent, checkbox, checked, tag
• link / image: target, description

Useful Org query shapes:

asp org query --kind heading --field todo=TODO --view metadata .
asp org query --kind task --field checked=true --view metadata .
asp org query --kind property --field key=CUSTOM_ID --view metadata .
asp org query --kind block --field kind=source --field lang=rust --view metadata .
asp org query --kind paragraph --term <term> --content .

Tree-sitter Locate Then Code

asp <language> query guide treesitter .
asp <language> query --treesitter-query '<pattern>' .
asp <language> query --selector <path-or-range> --treesitter-query '<narrow-pattern>' --workspace <workspace-root> --code

Without --code, tree-sitter query output is a capture/frontier locator. Use it to pick the owner, symbol, import, call, attribute, decorator, or test window. With --code, stdout should be pure source for an exact selector or unique match. If the provider cannot compile the pattern or reports unsupported captures, record that reason and fall back to owner items or a bounded direct-source-read instead of silently widening the read.

Verification

asp <language> check --changed .
asp <language> ast-patch dry-run --packet <semantic-ast-patch.json> .

Use provider ast-patch only for structural/mechanical edits after a dry-run receipt and only when hook config enables that path.